KB-Bridge

<a href="https://pypi.org/project/kbbridge/"><img src="https://img.shields.io/pypi/v/kbbridge.svg?logo=pypi&label=PyPI&logoColor=silver"/></a>

一个支持多种后端提供商的智能知识库搜索和检索的模型上下文协议（MCP）服务器。

安装

pip install kbbridge

快速开始

配置

创建一个包含检索后端凭证的.env文件：

# 必需 - 检索后端配置
RETRIEVAL_ENDPOINT=https://api.dify.ai/v1  # 示例：Dify 端点
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

# 可选
RERANK_URL=https://your-rerank-api.com
RERANK_MODEL=your-rerank-model

支持的后端：

后端	状态	备注
Dify	支持	当前可用
其他	计划	将来提供更多后端

查看 env.example 获取所有可用配置选项。

运行服务器

# 启动服务器
python -m kbbridge.server --host 0.0.0.0 --port 5210

# 或者使用 Makefile（如果可用）
make start

服务器运行在 http://0.0.0.0:5210，MCP 端点位于 http://0.0.0.0:5210/mcp。

部署选项

选项 1：Docker（本地开发 / 简单部署）

对于本地开发或简单的单容器部署：

# 构建镜像
docker build -t kbbridge:latest .

# 使用环境变量运行
docker run -d \
  --name kbbridge \
  -p 5210:5210 \
  --env-file .env \
  kbbridge:latest

对于生产部署，请使用 Kubernetes 等容器编排平台以及您首选的部署方法。

功能

• 后端集成：支持多种检索后端的可扩展架构
• 多种搜索方法：混合、语义、关键词和全文搜索
• 质量反映：自动答案质量评估和改进
• 自定义指令：领域特定查询指导

可用工具

• 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": "安全规程是什么？",
            },
        )
        print(result.content[0].text)

asyncio.run(main())

带自定义指令

await client.call_tool("assistant", {
    "resource_id": "hr_dataset",
    "query": "产假政策是什么？",
    "custom_instructions": "重点考虑人力资源合规性和法律要求。",
})

带查询重写

await client.call_tool("assistant", {
    "resource_id": "resource-id",
    "query": "安全规程是什么？",
    "enable_query_rewriting": True  # 启用基于 LLM 的查询扩展/放松
})

带文档过滤

await client.call_tool("assistant", {
    "resource_id": "resource-id",
    "query": "安全规程是什么？",
    "document_name": "safety_manual.pdf"  # 限制搜索到特定文档
})

与 Dify 集成

您可以将 KB-Bridge 插入到 Dify 代理工作流中，而不是直接调用 MCP 工具：

1. 配置 MCP 连接
   • MCP 服务器 URL：http://localhost:5210/mcp
   • 添加认证头：X-RETRIEVAL-ENDPOINT，X-RETRIEVAL-API-KEY，X-LLM-API-URL，X-LLM-MODEL
2. 创建代理工作流
   • 添加“MCP 工具”节点
   • 选择工具：assistant
   • 映射工作流变量到 resource_id，query 和其他工具参数
3. 运行查询
   • 用户输入 → 代理 → MCP assistant 工具 → 结构化答案带引用

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/

# 格式化代码
black kbbridge/ tests/

# 代码检查
ruff check kbbridge/ tests/

许可证

Apache-2.0