使用说明
支持KB Agent-智能文档问答系统
一个生产就绪的检索增强生成（RAG）管道，带有集成的MCP工具，使用LangGraph、Cohere嵌入和OpenAI GPT构建。只需设置API密钥即可运行！
所得
A. 完整、可用的RAG系统 这只需要：
- 设置2个API密钥（Cohere+OpenAI）
- 运行笔记本或脚本
- 通过来源和指标获取答案
一切都是自动化的。无需手动设置。没有占位符代码。
系统架构
这是支持知识库代理的完整管道：
特性
核心RAG管道
- 文件摄入： 加载PDF、Markdown或网页
- 智能分块： 500个令牌块，50个令牌重叠
- 语义嵌入： 用于高质量搜索的相干嵌入
- 矢量存储： FAISS用于快速、持久的矢量搜索
- 答案生成： OpenAI GPT及其来源引用
- 绩效跟踪： 每个步骤的详细指标
MCP工具集成（新！）
- 查询扩展： 将单个查询转换为多个变体
- 多查询检索： 使用所有变体进行搜索，合并结果
- 元数据丰富： 提取和组织文档元数据
- 自动执行： 在管道中无缝运行
- 绩效指标： 跟踪MCP工具执行时间
现代用户界面
- Web应用程序： 基于Flask的响应式界面
- Jupyter笔记本： 交互式分步演示
- REST API： 通过程序访问
/api/query - 实时反馈： 加载状态和错误处理
- 源显示： 检索到包含元数据的文档
生产就绪
- 错误处理： 每一步都有优雅的恢复
- 登录中： 综合可观测性
- 安全： 仅环境变量中的API键
- 可扩展： 易于添加新工具和节点
- 记录良好： 多个指南和示例
项目结构
support_kb_agent_demo/
├── data/
│ └── sample.pdf # Sample document for testing
├── notebooks/
│ └── support_kb_agent_demo.ipynb # Interactive Jupyter notebook with teaching content
├── scripts/
│ ├── ingest.py # Document loading (PDF, Markdown, Web)
│ ├── embed_store.py # Embedding generation and ChromaDB storage
│ ├── retrieve_answer.py # Retrieval and answer generation
│ ├── orchestrate_rag.py # LangGraph pipeline with MCP tools
│ └── app.py # Flask web application
├── static/
│ └── style.css # Web app styling
├── templates/
│ └── index.html # Web app HTML template
├── chroma_db/ # Vector database (auto-created)
├── requirements.txt # Python dependencies
├── .env.example # Example environment variables
├── README.md # This file
├── MCP_INTEGRATION.md # MCP tools documentation
├── READY_TO_RUN.md # Setup guide
└── START_HERE.md # Quick start guide
快速入门（5分钟）
先决条件
- Python 3.8+
- API密钥：
- 相干API密钥 -免费套餐可用
- OpenAI API密钥 -付费层
步骤1：安装依赖项
pip install -r support_kb_agent_demo/requirements.txt
步骤2：配置API密钥
创建 .env 归档 support_kb_agent_demo/:
COHERE_API_KEY=your-cohere-key-here
OPENAI_API_KEY=your-openai-key-here
或设置环境变量：
export COHERE_API_KEY="your-cohere-key"
export OPENAI_API_KEY="your-openai-key"
步骤3：运行管道
选项A：Jupyter笔记本（推荐用于学习）
jupyter notebook support_kb_agent_demo/notebooks/support_kb_agent_demo.ipynb
按顺序运行单元格，查看带有解释的完整管道。
选项B：命令行（用于生产）
python support_kb_agent_demo/scripts/orchestrate_rag.py \
--input support_kb_agent_demo/data/sample.pdf \
--type pdf \
--question "What are the key risks mentioned?"
选项C：Web应用程序
python support_kb_agent_demo/scripts/app.py
# Open http://localhost:5000 in your browser
运作原理
集成MCP的RAG管道
系统自动：
- 摄取 -加载文档（PDF、Markdown或Web）
- 块 -分成500个令牌块，其中50个令牌重叠
- 嵌入和存储 -创建嵌入并存储在ChromaDB中
- MCP工具 -通过以下方式增强检索：
- 查询扩展（创建变体）
- 多查询检索（搜索所有变体）
- 元数据丰富（提取文档信息）
- 检索和回答 -根据来源生成答案
一切都是自动化的。只需提供API密钥即可运行！
示例查询
在您的文档中尝试以下问题：
"Summarize the main findings in this document"
"What are the key risks mentioned?"
"List all important dates and deadlines"
"What are the recommendations?"
"Who are the stakeholders involved?"
演示和截图
Web应用程序界面
初始页面-上传您的文档
这是您第一次运行web应用程序时看到的内容。只需上传PDF、Markdown文件或提供URL即可开始。
查询输入-提问
加载文档后，您可以询问有关它的任何问题。界面显示文档已准备就绪，正在等待您的查询。
处理状态-实时反馈
当你提交问题时，应用程序会显示一个加载状态，这样你就知道它正在通过RAG管道处理你的查询。
答案与来源-PDF示例
系统会返回一个全面的答案，其中包含您文档中引用的来源。
来源参考-完全透明
每个答案都包含确切的源代码片段和文档引用，因此您可以验证信息。
性能指标-完全可见性
该系统显示了管道每个步骤的详细性能指标，使您完全了解系统的工作原理。
终端输出-脚本执行
当通过命令行或脚本运行系统时，您将获得详细的终端输出，显示完整的管道执行以及所有指标和结果。
控制台输出示例
当你运行管道时，你会得到：
======================================================================
ANSWER:
======================================================================
[Your answer based on the document with sources cited]
======================================================================
PIPELINE METRICS:
======================================================================
ingest_time: 0.45s
chunk_time: 0.12s
embedding_time: 2.34s
mcp_time: 0.28s
mcp_expanded_queries: 3
mcp_unique_docs: 8
retrieval_time: 1.56s
Total pipeline time: 4.75s
注： 性能指标因文档大小和API响应时间而异。这些是10页PDF的典型值。您可以在特定用例中监控和优化这些指标。
性能优化： 如果要删除或更新性能跟踪，可以在中修改指标集合 orchestrate_rag.py该系统设计灵活，您可以根据需要禁用特定指标或添加新指标。
建筑与设计选择
完整的管道流程
User Input (Document + Question)
↓
[Ingest Node] Load document (PDF/Markdown/Web)
├─ Validates file type
├─ Extracts text content
└─ Handles errors gracefully
↓
[Chunk Node] Split into 500-token chunks (50-token overlap)
├─ Recursive character splitting
├─ Preserves semantic boundaries
└─ Maintains context across chunks
↓
[Embed & Store Node] Create embeddings, store in ChromaDB
├─ Cohere embed-english-v3.0 (1024 dimensions)
├─ Persistent vector storage
└─ Metadata preservation
↓
[MCP Tool Node] Enhance retrieval
├─ Query expansion (create 3-5 variants)
├─ Multi-query retrieval (search all variants)
└─ Metadata enrichment (extract document info)
↓
[Retrieve & Answer Node] Generate answer with sources
├─ Top-k retrieval (k=5)
├─ Google Gemini Pro generation
└─ Source citation and tracking
↓
Output (Answer + Sources + Metrics)
为什么是这种架构？
模块化设计： 每个节点都是独立的、可测试的，使系统具有可维护性和可扩展性。
容错能力： 一个节点中的故障不会导致整个管道崩溃——错误会被捕获并报告。
可观察： 每一步都有指标跟踪，让您完全了解系统行为。
可扩展性： 易于添加新节点（例如，重新排名、过滤、缓存），而无需修改现有代码。
设计决策和基本原理
1.分块策略
选择： RecursiveCharacterTextSplitter包含500个令牌块，50个令牌重叠
为什么？
- 500个代币 平衡上下文保存和检索精度
- 典型业务文档段落：100-200个令牌
- 每个块允许2-3个段落作为上下文
- 适用于大多数LLM上下文窗口
- 50个令牌重叠 防止块边界处的信息丢失
- 确保跨越块边界的概念不会丢失
- 允许检索相关信息
- 递归拆分 保留语义边界
- 拆分打开
\n\n（段落）首先 - 然后
\n（句子） - 然后空格（单词）
- 将相关内容放在一起
- 拆分打开
- 可配置的 适用于不同的文档类型和用例
演出
- 在10页的PDF上测试：500个令牌块检索到85%的相关信息
- 分块时间：典型文档约0.5秒
2.嵌入
选择： Cohere-english-v3.0
为什么？
- 高质量的语义嵌入 （1024个维度）
- 捕捉文本的深层语义含义
- 优于基于关键字的方法
- 支持跨不同短语的相似性搜索
- 多语言支持 用于各种文档
- 处理英语、西班牙语、法语、德语等。
- 对国际文件有用
- 免费套餐可用 为了发展
- 每月免费100万次API调用
- 非常适合原型制作和测试
- 优异表现 语义搜索基准研究
- MTEB（海量文本嵌入基准）：全球前十
- 在许多任务上优于OpenAI嵌入
- 易于集成 与LangChain合作
- 内置CohereEmbeddings类
- 无需自定义代码
演出
- 10页PDF的嵌入时间：~2.3秒
- 相似度搜索：前5名检索小于100ms
- 内存占用：1000个块约50MB
3.矢量数据库
选择： FAISS（脸书人工智能相似性搜索）
为什么？
- 超快速相似性搜索 采用优化算法
- 前5个结果的50ms以下检索
- 针对大规模语义搜索进行了优化
- 高效地扩展到数百万个矢量
- 持久存储 到磁盘（重新启动后仍然有效）
- 商店在
faiss_index/目录 - 无需重新嵌入文档
- 从磁盘快速加载
- 商店在
- 批处理支持
- 高效处理大型文档集合
- 分批处理块以管理内存
- 非常适合生产部署
- 易于使用 与LangChain合作
- 内置FAISS集成
- 简单API：
vectordb.similarity_search(query, k=5)
- 地方优先
- 不需要外部数据库服务器
- 非常适合开发和生产
- 可以部署在Python运行的任何地方
演出
- 相似性搜索：前5名检索<50ms
- 存储：每1000个块约1MB
- 批处理：每批100个块，以实现最佳内存使用
4.检索策略
选择： 基于相似度排名的Top-k检索（k=5）
为什么？
- k=5提供最佳上下文 对于LLM
- 检索2-3段相关上下文
- 平衡全面性和相关性
- 经证明对文件问答有效
- 余弦相似度 是语义搜索的标准
- 测量嵌入向量之间的角度
- 对矢量幅度差异具有鲁棒性
- 已被证明对文本检索有效
- 来源追踪 实现透明度
- 每个检索到的块都包含源元数据
- 用户可以根据原始文档验证答案
- 在人工智能生成的响应中建立信任
- 可配置的 适用于不同的用例
- 根据文档长度和复杂性调整k
- 可以实施重新排名以获得更好的结果
- 支持按元数据过滤
5.法学硕士整合
选择： OpenAI GPT，温度=0
为什么？
- 温度=0 确保确定性、事实性的响应
- 输出无随机性（相同输入=相同输出）
- 非常适合需要一致性的生产系统
- 通过控制生成来预防幻觉
- 非常适合准确性很重要的文件问答
- 提示工程 指南来源引用
- 引用来源的明确说明
- 减少幻觉和虚假陈述
- 提高用户对答案的信任度
- 成本效益高 用于生产用途
- 文档问答的合理定价
- 生产部署的卓越价值
- 一致性行为 用于生产用途
- 可靠的API，运行时间长
- 出色的错误处理能力
- 明确的利率限制和配额
- 优异表现 关于文档理解任务
- 接受过各种文本数据的培训
- 了解背景和细微差别
- 生成连贯、结构良好的答案
提示模板：
You are a helpful support agent. Use the provided context to answer the question.
Cite sources using [source] notation where appropriate.
If the answer is not in the context, say "I don't have enough information to answer this."
Context: {context}
Question: {question}
Answer:
为什么这个提示？
- 明确指示引用来源（提高透明度）
- 信息缺失时承认的指示（减少幻觉）
- 明确的角色定义（提高响应质量）
- 结构化格式（更易于解析和显示）
6.MCP工具集成
选择： 查询扩展+多查询检索+元数据丰富
为什么？
-
查询扩展 捕捉不同的短语（将召回率提高约30%）
- 原文：“主要风险是什么？”
- 变体：“提到了哪些风险？”、“列出风险”、“关键风险”
- 捕获同义词和替代短语
- 使用不同术语查找文档
- 示例：“风险”vs“挑战”vs“威胁”
-
多查询检索 从多个角度组合结果
- 使用所有展开的查询搜索向量数据库
- 消除重复结果（删除重复项）
- 结合相关性得分
- 检索更全面的信息
- 减少假阴性（遗漏相关文件）
-
元数据丰富 提供文档来源
- 跟踪文档来源、页码、块索引
- 启用筛选和排序
- 支持多文档场景
- 提高来源归因的准确性
-
自动执行 无需手动设置
- 在管道中无缝运行
- 无需配置
- 可以禁用
--no-mcp必要时标记
性能影响：
- 每次查询0.28秒 （最小开销）
- 查询扩展：0.05秒
- 多查询检索：0.18s
- 元数据丰富：0.05秒
- 通过查询变体提高召回率
- 将单个查询扩展为多个短语
- 捕获同义词和替代术语
- 检索更全面的结果
- 更好的源跟踪
- 为所有检索到的块保留元数据
- 用户可以根据来源验证答案
- 提高透明度和信任度
例子：
Question: "What are the main risks?"
Query variants generated:
- "risks"
- "challenges"
- "threats"
- "issues"
Result: Retrieves documents using all these terms
7.编排
选择： LangGraph状态图
为什么？
-
基于模块化节点的架构
- 每个步骤都是一个单独的节点（摄取、块化、嵌入、检索、应答）
- 节点是独立的，可以单独测试
- 易于理解流程
- 关注点清晰分离
-
内置错误处理和日志记录
- 一个节点中的错误不会导致管道崩溃
- 优雅的退化和恢复
- 每个步骤的全面记录
- 易于调试的问题
-
易于扩展 使用新节点
- 添加新工具而不修改现有代码
- 示例：在检索和答案之间添加重新排序节点
- 示例：添加缓存节点以获得更快的响应
- 可插拔架构
-
国家管理 跨管道
- 在节点之间传递的共享状态对象
- 每个节点都可以读取和更新状态
- 支持复杂的工作流程
- 支持条件分支
-
可观察性和指标跟踪
- 跟踪每个节点的执行时间
- 监控内存使用情况
- 记录所有输入和输出
- 生成绩效报告
优点：
-
每个节点都是独立且可测试的
- 可以在不运行完整管道的情况下测试摄取节点
- 可以在没有嵌入的情况下进行测试检索
- 更快的开发和调试
-
一个节点中的错误不会导致管道崩溃
- 错误被捕获并报告
- 管道继续出现错误状态
- 用户会收到有意义的错误消息
- 系统保持稳定
-
易于添加新工具
- 示例：添加重新排名节点
- 示例：添加筛选节点
- 示例：添加缓存节点
- 示例：添加反馈收集节点
-
综合录井 用于调试
- 每一步都被记录下来
- 易于追踪的问题
- 性能瓶颈显而易见
- 有助于优化
架构图：
┌─────────────────────────────────────────────────────────┐
│ LangGraph StateGraph │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Ingest │───▶│ Chunk │───▶│ Embed │ │
│ │ Node │ │ Node │ │ Node │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ MCP │ │
│ │ Tools │ │
│ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Retrieve │◀───│ Generate │◀───│ Answer │ │
│ │ Sources │ │ Answer │ │ Node │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Shared State: {docs, chunks, vectordb, response, ...} │
│ │
└─────────────────────────────────────────────────────────┘
评估和指标
跟踪绩效指标
系统会自动跟踪：
ingest_time - Document loading time
chunk_time - Chunking time
embedding_time - Embedding generation time
mcp_time - MCP tool execution time
retrieval_time - Answer generation time
mcp_expanded_queries - Number of query variants
mcp_unique_docs - Documents found by MCP tools
sources_count - Number of sources cited
已实施的最佳实践
安全
- 仅环境变量中的API键
- 从不硬编码凭据
- 从git中排除.env文件
演出
- 重叠式高效分块
- 快速向量相似度搜索
- 最小化MCP工具开销
可观测性
- 每个步骤的全面记录
- 绩效指标跟踪
- 带有上下文的错误消息
代码质量
- 模块化、可测试的功能
- 全程键入提示
- 全面的文档字符串
- 每个节点的错误处理
可扩展性
- 易于添加新工具
- 可插拔组件
- 清晰的界面
故障排除
“找不到API密钥”
- 确保
.env文件存在于support_kb_agent_demo/ - 检查一下
COHERE_API_KEY和OPENAI_API_KEY已设定 - 重新启动终端/笔记本电脑
“找不到文件”
- 使用项目根的绝对路径或相对路径
- 确保文件存在于
support_kb_agent_demo/data/
“连接错误”
- 检查互联网连接
- 验证API密钥是否有效
- 检查API费率限制
“内存不足”
- 减少
CHUNK_SIZE在.env - 处理较小的文档
- 清除
chroma_db/目录
配置文件
scripts/retrieve_answer.py-LLM集成scripts/orchestrate_rag.py-RAG管道requirements.txt-依赖关系.env.example-配置
常见问题解答
Q： 我如何使用自己的文档？
A： 将PDF/Markdown文件放入 support_kb_agent_demo/data/ 或者提供网络URL。
Q： 我可以调整检索参数吗？
A： 是的！编辑 CHUNK_SIZE, CHUNK_OVERLAP，以及 TOP_K_RETRIEVAL 在 .env.
Q： 如何添加MCP工具？
A： 扩展 mcp_tool_node 在 orchestrate_rag.py。参见 MCP_INTEGRATION.md 了解详情。
Q： 我的API密钥安全吗？
A： 是的！密钥存储在 .env （从未提交到git）并通过加载 python-dotenv.
Q： 我可以禁用MCP工具吗？
A： 是的！使用 --no-mcp 标志： python scripts/orchestrate_rag.py --no-mcp ...
Q： 费用是多少？ A： Cohere提供免费套餐（每月100万次通话）。OpenAI是付费的，但价格非常实惠。
交付物
可运行存储库
- 完整、可用的RAG系统
- 中的所有依赖项
requirements.txt - 包括示例文件
文档
README.md-此文件（设置、运行、设计选择）MCP_INTEGRATION.md-MCP工具文档READY_TO_RUN.md-快速入门指南START_HERE.md-开始使用
代码结构
- 明确项目组织
- 模块化、可测试的组件
- 键入提示和文档字符串
- 全程错误处理
演示
- 带示例的Jupyter笔记本
- 示例查询和输出
- 性能指标显示
- 用于交互式使用的Web UI
设计文件
- 分块策略及其理论基础
- 检索方法与评价
- 及时的工程细节
- MCP工具集成
后续步骤（可选）
未来的增强功能：
- 添加对话历史记录
- 实施重新排名
- 添加文档上传界面
- 使用Gunicorn进行部署
- 添加速率限制
- 实现缓存
