使用说明
KB桥
用于智能知识库搜索和检索的模型上下文协议（MCP）服务器，支持多个后端提供商。
安装
pip install kbbridge
快速开始
配置
创建 .env 包含检索后端凭据的文件：
# Required - Retrieval Backend Configuration
RETRIEVAL_ENDPOINT=https://api.dify.ai/v1 # Example: Dify endpoint
RETRIEVAL_API_KEY=your-retrieval-api-key
LLM_API_URL=https://your-llm-service.com/v1
LLM_MODEL=gpt-4o
LLM_API_TOKEN=your-token-here
# Optional
RERANK_URL=https://your-rerank-api.com
RERANK_MODEL=your-rerank-model
支持的后端：
| 后端 | 状态 | 备注 |
|---|---|---|
| Dify | 支持 | 当前可用 |
| 其他 | 计划中 | 其他后端即将推出 |
看 env.example 对于所有可用的配置选项。
运行服务器
# Start server
python -m kbbridge.server --host 0.0.0.0 --port 5210
# Or using Makefile (if available)
make start
服务器在上运行 http://0.0.0.0:5210 MCP端点位于 http://0.0.0.0:5210/mcp.
部署选项
选项1:Docker（本地开发/简单部署）
对于本地开发或简单的单容器部署：
# Build the image
docker build -t kbbridge:latest .
# Run with environment variables
docker run -d \
--name kbbridge \
-p 5210:5210 \
--env-file .env \
kbbridge:latest
对于生产部署，使用Kubernetes等容器编排平台和您首选的部署方法。
特性
- 后端集成：支持多个检索后端的可扩展架构
- 多种搜索方法：混合搜索、语义搜索、关键字搜索和全文搜索
- 质量反思：自动评估和优化答案质量
- 自定义指令：特定领域查询指南
工作流程
KB Bridge遵循多阶段流程，以确保高质量的答案：
flowchart LR
Start([User Query]) --> Preprocess[Query Preprocessing<br/>Rewriting & Understanding]
Preprocess --> FileDiscovery[File Discovery<br/>Find Relevant Files]
FileDiscovery --> Search[Search Stages]
Search --> Direct[Direct Approach<br/>Simple Retrieval]
Search --> Advanced[Advanced Approach<br/>File-level Processing]
Direct --> Candidates
Advanced --> Candidates[Collect Candidates]
Candidates --> Synthesis[Answer Synthesis<br/>Rerank & Format]
Synthesis --> Reflection{Reflection<br/>Enabled?}
Reflection -->|Yes| Reflect[Quality Check<br/>& Refinement]
Reflection -->|No| Final
Reflect --> Final([Final Answer])
style Start fill:#e1f5ff
style Final fill:#c8e6c9
style FileDiscovery fill:#fff9c4
style Direct fill:#fff9c4
style Advanced fill:#fff9c4
style Reflect fill:#ffccbc
style Synthesis fill:#e1bee7
舞台细节
查询预处理 （可选）
- 查询重写：基于LLM的扩展/放宽以提高召回率
- 查询理解：提取意图并分解复杂查询
文件发现
- 语义搜索以识别相关文件（以回忆为重点）
- 如果质量低，可选择自动搜索扩展的质量评估
搜索阶段 （平行）
- 直接方法：简单查询→ 检索→ 答案提取（回退）
- 高级方法：文件级处理，内容增强以提高精度
答案综合
- 按相关性对候选人进行重新排名（如果提供重新排名服务）
- 使用LLM进行合并和重复数据消除
质量反思 （可选）
- 评估答案质量，并在需要时进行优化（最多max_reditions）
实施状态
编排者(DatasetProcessor)目前实施阶段1-3、5-8。文件发现质量评估（第4阶段）已实施，但尚未集成到管道中。看 .doc/FILE_DISCOVERY_EVALUATION_CONFIG.md 了解详情。
可用工具
assistant：从知识库中智能搜索和答案提取file_discover：使用检索器+可选的重新排序发现相关文件file_lister：列出知识库数据集中的文件keyword_generator：使用LLM生成搜索关键字retriever：使用各种搜索方法检索信息file_count：获取知识库数据集中的文件计数
使用示例
基本查询
import asyncio
from fastmcp import Client
async def main():
async with Client("http://localhost:5210/mcp") as client:
result = await client.call_tool(
"assistant",
{
"resource_id": "resource-id",
"query": "What are the safety protocols?",
},
)
print(result.content[0].text)
asyncio.run(main())
使用自定义说明
await client.call_tool("assistant", {
"resource_id": "hr_dataset",
"query": "What is the maternity leave policy?",
"custom_instructions": "Focus on HR compliance and legal requirements."
})
使用查询重写
await client.call_tool("assistant", {
"resource_id": "resource-id",
"query": "What are the safety protocols?",
"enable_query_rewriting": True # Enables LLM-based query expansion/relaxation
})
使用文档筛选
await client.call_tool("assistant", {
"resource_id": "resource-id",
"query": "What are the safety protocols?",
"document_name": "safety_manual.pdf" # Limit search to specific document
})
与Dify集成
您可以将KB Bridge插入Dify Agent工作流，而不是直接调用MCP工具：
- 配置MCP连接
- MCP服务器URL:
http://localhost:5210/mcp - 添加身份验证标头：
X-RETRIEVAL-ENDPOINT,X-RETRIEVAL-API-KEY,X-LLM-API-URL,X-LLM-MODEL
- MCP服务器URL:
- 创建代理工作流
- 添加“MCP工具”节点
- 选择工具：
assistant - 将工作流变量映射到
resource_id,query，以及其他工具参数
- 运行查询
- 用户输入→ 代理→ MCP
assistanttool → 带引用的结构化答案
- 用户输入→ 代理→ MCP
发展
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/
# Format code
black kbbridge/ tests/
# Lint code
ruff check kbbridge/ tests/
许可证
阿帕奇-2.0
