Skip to content
BranchesTags

Repository files navigation

kb-cs-agent

CI Python

面向知识库问答的可运行 RAG Agent 原型：把文档解析、结构化分块、向量检索、Agent 编排、答案生成与来源引用串成一条完整链路。

kb-cs-agent 基于 LangGraph + Milvus + FastAPI + LiteLLM 构建，适合客服知识库、内部文档问答和轻量级 AI 助手场景。项目以 Web 入口为主，同时提供 CLI、JSON API、SSE 流式接口和带鉴权的知识库管理 API。

Important

当前项目处于“工程原型 + CI 门禁验证”阶段，适合演示、学习和内部试用，不应理解为所有消息渠道都已达到生产级交付。实际能力以 质量门禁 和测试结果为准。

目录

项目定位

这个仓库优先解决“知识库内容可以被稳定摄入、检索并解释”的工程问题：

  • 面向知识库问答：回答基于检索上下文生成，并返回来源、页码、分块和相关性信息。
  • Web 优先：开箱提供浏览器聊天页、同步对话和 SSE 对话流，不要求先接入第三方消息平台。
  • 配置驱动：LLM、Embedding、Milvus、Checkpointer、重排和高级 RAG 策略均由 RAG_ 环境变量控制。
  • 可验证：文档摄入、检索契约、API 错误、分层测试和覆盖率均纳入质量门禁。

核心能力

能力 状态 说明
文档摄入 ✅ 可用 .txt、.md、.docx、.xlsx、.xls、.pdf
文档处理 ✅ 可用 格式/解析/结构/切分质量校验；默认 section-aware + token-aware
PDF 解析 ✅ 可用 Docling 优先，缺少可选依赖时回退到 pypdf
向量检索 ✅ 可用 Milvus / Milvus Lite；新建集合默认 v6 schema，兼容读取旧 schema
检索增强 ✅ 可选 Dense、Hybrid（BM25 + Dense）、Reranker、Parent-Child
Agent 工作流 ✅ 可选 Linear、CRAG、HyDE、Multi-Query、Self-RAG
引用与降级 ✅ 可用 输出引用链路；低置信或依赖故障时返回安全的结构化结果
Web / API ✅ 可用 FastAPI、匿名签名会话、同步 JSON、SSE 流式响应
Admin 知识库管理 ✅ 可用 Token 鉴权、上传、来源/分块查看、删除和检索测试
飞书 / 钉钉 / 企微渠道 🚧 规划中 SDK extra 已预留，渠道适配器尚未全部落地

系统架构

flowchart LR
    A[文档上传或 CLI] --> B[格式/结构校验]
    B --> C[解析与 section-aware token 分块]
    C --> D[Embedding]
    D --> E[(Milvus)]

    Q[用户问题] --> F[LangGraph Agent]
    F --> G[查询变换<br/>可选 HyDE / Multi-Query]
    G --> H[Dense / Hybrid 检索]
    E --> H
    H --> I[可选 Reranker / CRAG]
    I --> J[LLM 生成]
    J --> K[引用构建与低置信降级]
    K --> L[Web / JSON / SSE]
Loading

摄入采用“先写入新版本、校验并激活、再退役旧版本”的发布协议；新版本失败时尽量保留旧版本的可检索性。

技术栈

领域 技术 用途
Agent 编排 LangGraph 状态机驱动的 RAG 节点与条件路由
LLM / Embedding LiteLLM 接入 OpenAI 兼容的模型服务
向量数据库 Milvus / Milvus Lite Dense / Hybrid 检索与版本化文档存储
Web 服务 FastAPI + SSE 聊天页面、JSON API、流式响应和 Admin API
配置 Pydantic Settings RAG_ 前缀与 __ 嵌套环境变量
CLI Typer kb-ingest 文档摄入、kb-server 服务启动
文档解析 Docling / pypdf / python-docx / openpyxl / xlrd 多格式解析与 fallback

快速开始

1. 环境要求

  • Python 3.11–3.13；Python 3.14 暂未纳入 CI 和打包支持范围。
  • 一个可用的 LLM API Key，以及一个兼容 LiteLLM 的模型接口。
  • Embedding 模型的输出维度必须与 RAG_MILVUS__DIMENSION 一致。
  • 本地开发推荐使用 Milvus Lite；安装 dev extra 后可使用仓库默认的本地 .db URI。

2. 创建环境并安装

python -m venv .venv
source .venv/bin/activate

python -m pip install -U pip
python -m pip install -e ".[dev]" -c constraints.txt

Windows PowerShell 可将激活命令替换为：

.\.venv\Scripts\Activate.ps1

可选能力：

Extra 安装命令 用途
pdf python -m pip install -e ".[pdf]" -c constraints.txt Docling 重型 PDF 解析
reranker python -m pip install -e ".[reranker]" -c constraints.txt 本地 FlagEmbedding 重排序
channels python -m pip install -e ".[channels]" -c constraints.txt 飞书 / 钉钉 / 企微 SDK
checkpointer-postgres python -m pip install -e ".[checkpointer-postgres]" -c constraints.txt PostgreSQL 会话状态持久化
checkpointer-redis python -m pip install -e ".[checkpointer-redis]" -c constraints.txt Redis 会话状态持久化

3. 配置环境变量

cp .env.example .env

至少检查并修改以下配置；不要使用示例中的占位密钥：

配置 作用
RAG_LLM__MODEL / RAG_LLM__API_KEY / RAG_LLM__API_BASE LLM 模型、凭据和兼容网关地址
RAG_EMBEDDING__MODEL Embedding 模型
RAG_MILVUS__URI / RAG_MILVUS__TOKEN 本地文件、Milvus 服务或云端连接
RAG_MILVUS__DIMENSION 向量维度，必须与 Embedding 模型匹配
RAG_SERVER__ADMIN_TOKEN Admin API 与文档上传接口的鉴权令牌

完整配置说明见 docs/config.md，可复制的模板见 .env.example。

4. 摄入文档并启动服务

# 先将文档解析、分块、向量化并写入 Milvus
kb-ingest path/to/document.md

# 启动 Web/API 服务
kb-server

kb-ingest 还支持 --embedding、--source、--no-replace-existing 等选项，可运行 kb-ingest --help 查看详情。服务启动后访问：

API 快速体验

健康检查与会话

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/ready

# 获取匿名会话令牌；后续请求可携带 response 中的 session_token
curl -X POST http://127.0.0.1:8000/session

同步对话

不携带令牌时，服务会自动签发匿名会话并在响应中返回 session_token：

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"请根据知识库介绍一下项目"}'

响应包含 answer、citations、retrieval_confidence 和 session_id 等字段。

SSE 流式对话

curl -N -X POST http://127.0.0.1:8000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message":"请总结这份文档的重点"}'

事件类型包括：

  • status：请求已接受，并返回会话信息。
  • final：最终答案、引用和检索状态。
  • error：安全错误码与用户可见消息，不包含 traceback。

Admin 上传文档

Admin API 支持以下两种鉴权头：X-Admin-Token 或 Authorization。

ADMIN_TOKEN='replace-with-your-admin-token'
curl -X POST http://127.0.0.1:8000/admin/api/kb/upload \
  -H "X-Admin-Token: ${ADMIN_TOKEN}" \
  -F "file=@path/to/document.pdf"

常用端点：

方法 路径 说明
GET / Web 对话页
POST /session 签发匿名会话
GET /health / /ready 存活与就绪检查
POST /chat 同步对话
POST /chat/stream SSE 对话流
GET /admin Admin 页面
POST /admin/api/kb/upload Admin 上传入库（需 Token）
GET /admin/api/kb/sources 来源列表（需 Token）
GET /admin/api/kb/sources/{source}/chunks 分块列表（需 Token）
DELETE /admin/api/kb/sources/{source} 删除来源（需 Token）
POST /admin/api/kb/search 检索测试（需 Token）
POST /ingest 兼容上传入口（需 Token）

检索与 Agent 策略

默认配置是简单、可观测的 Linear 流程；可按数据集和质量目标逐项打开增强能力：

配置 策略 说明
RAG_HYBRID__ENABLED=true Hybrid 融合 BM25 稀疏检索与 Dense 向量检索
RAG_RERANKER__ENABLED=true Reranker 对候选结果二次排序；本地模式需 reranker extra
RAG_CRAG__ENABLED=true CRAG 对检索结果评分，必要时改写查询并重试
RAG_QUERY_TRANSFORM__HYDE_ENABLED=true HyDE 生成假设回答并用于查询向量化
RAG_QUERY_TRANSFORM__MULTI_QUERY_ENABLED=true Multi-Query 生成多个查询变体后合并检索结果
RAG_SELF_RAG__ENABLED=true Self-RAG 对生成结果进行反思并按需重生成
RAG_CHECKPOINTER__BACKEND=sqlite 会话记忆 默认使用本地 SQLite，也支持 memory / postgres / redis

HyDE 与 Multi-Query 是互斥的查询变换策略，不要同时启用。完整节点、状态和降级路径见 docs/agent.md 与 docs/flow.md。

项目结构

src/kb_cs_agent/
  agent/          # LangGraph 状态、节点、Prompt 与图构建
  cli/            # kb-ingest / kb-server 命令入口
  config/         # Pydantic Settings 与环境变量模型
  kb/             # 解析、校验、分块、Embedding、Milvus 与检索
  server/         # FastAPI、Web UI、SSE、会话和 Admin API
  utils/          # 日志、错误体系和引用构建
  channels/       # 消息渠道适配器预留包

docs/
  architecture.md # 总体架构与技术栈
  flow.md         # 摄入、问答和 SSE 数据流
  kb.md           # 知识库、Schema、检索和摄入细节
  agent.md        # LangGraph Agent 节点与状态
  server.md       # FastAPI、鉴权、限流和降级
  config.md       # 配置项与校验规则
  QUALITY_GATE.md # CI 对齐的发布质量门禁

开发与测试

仓库已经内置了与 CI 等价的质量门禁：

ruff check src tests
ruff format --check src tests
mypy
python -m build
pytest -q tests/unit tests/integration tests/rag_quality \
  --cov=kb_cs_agent --cov-report=term-missing --cov-fail-under=60

测试默认不需要云端凭据：

层级 命令 说明
Unit pytest tests/unit/ Mock / stub 覆盖单元行为
Integration pytest tests/integration/ 使用 Milvus Lite 或 fake 的受控集成测试
RAG quality（本地） pytest tests/rag_quality/ -q 无网络、确定性黄金语料
RAG quality（provider） pytest tests/rag_quality -m rag --run-rag 需真实 Provider 凭据
External smoke pytest -m external --run-external 显式外部资源测试，默认不执行

更多约束、覆盖率要求和 schema 兼容说明见 docs/QUALITY_GATE.md。

文档导航

建议按以下顺序阅读：

  1. docs/README.md：文档索引和阅读路线
  2. docs/architecture.md：模块关系、运行模式和技术栈
  3. docs/flow.md：从摄入到问答返回的完整数据流
  4. docs/config.md：环境变量、默认值和校验规则
  5. docs/kb.md：解析、分块、Milvus Schema、检索和重排
  6. docs/agent.md：LangGraph 状态、节点和高级 RAG
  7. docs/server.md：HTTP API、会话、鉴权、限流和降级
  8. docs/learning-guide.md：初学者学习路线
  9. docs/replication-guide.md：从 MVP 到完整 RAG 的复刻指南

边界与常见问题

/ready 返回 503

检查 RAG_LLM__API_KEY、RAG_EMBEDDING__MODEL、Milvus URI/Token 和服务日志。/health 用于存活检查，/ready 才表示业务依赖已初始化。

摄入时报向量维度不匹配

确认 Embedding 模型的实际输出维度与 RAG_MILVUS__DIMENSION 相同；更换模型后不要直接复用不兼容的集合。

PDF 解析效果不理想

先安装 pdf extra 以启用 Docling；未安装时系统会使用 pypdf fallback，复杂版面可能需要额外验证。

Admin API 返回 401

确认请求使用 X-Admin-Token 或 Authorization 请求头，令牌与 .env 中的 RAG_SERVER__ADMIN_TOKEN 完全一致。

修改配置后仍使用旧行为

重启 kb-server 或重新运行 kb-ingest。配置从环境变量和 .env 加载，不会在进程运行期间自动刷新。

贡献方式

欢迎通过 Issue、Pull Request 或讨论区参与改进：

  1. Fork 本仓库并创建功能分支。
  2. 针对实现变更补充测试，针对行为变更同步更新文档。
  3. 运行上述质量门禁。
  4. 提交 PR，说明变更背景、兼容性影响和验证结果。

请勿提交真实密钥、凭据或私钥；敏感配置只应放在本地 .env 或环境变量中。

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages