基于MCP的清洁技术检索与推理代理AI系统
此存储库包含一个完全实现的 智能人工智能系统 使用 模型上下文协议（MCP） 执行 文档检索、重新排序、总结和推理 在大型清洁技术媒体语料库上。\ 与精美的学术演示不同，这个项目反映了 *真正的工程之旅* --包括工具编排、ChromaDB索引失败、调试周期、评估脚本以及实际构建的所有组件。
______________________________________________________________________
概述
该系统在四个主要功能上运行：
检索
- 20111篇清洁技术媒体文章编入 色度数据库
- 嵌入：
MiniLM-L6-v2 - 存储的元数据：id、标题、URL、日期、作者、域
重排序
- 交叉编码器：
ms-marco-MiniLM-L-6-v2 - 比纯向量搜索具有更强的相关性排序
摘要
- HuggingFace推论API
- 型号：
meta-llama/Llama-3.2-3B-Instruct:free - 使用上下文窗口进行基础摘要
推理（自定义MCP工具）
为答案生成理由：
- 支持vs.部分支持vs.弱支持
- 引用检索到的文档
- 旗帜幻觉或不受支持的声明
______________________________________________________________________
系统架构
- 色度数据库 存储20000多件带嵌入件的清洁技术产品
- MCP服务器 展示4个工具：
- retrieve_cleantech - summarize_docs - explain_answer - answer_question
- 评估管道 计算检索指标+语义答案相似度
- 离线脚本 重用相同的检索+重新排序逻辑进行大规模基准测试
架构和数据流的图表可以放在 diagrams/ 文件夹。
______________________________________________________________________
存储库结构
cleantech_mcp_agent/
│
├── mcp_server/
│ ├── server.py
│ └── __init__.py
│
├── src/
│ ├── build_index.py
│ ├── embedding_wrapper.py
│ ├── evaluate_system.py
│ ├── run_full_evaluation.py
│ ├── run_mcp_answers.py
│ │
│ ├── mcp_answers.csv
│ ├── results_retrieval.csv
│ ├── results_answers.csv
│ └── results_model_answers.json
│
├── data/
│ ├── cleantech_media_dataset_v3_2024-10-28.csv
│ ├── cleantech_rag_evaluation_data_2024-09-20.csv
│ └── CleanTech-50answers.txt
│
├── chroma_db/
│
├── diagrams/
│
├── requirements.txt
│
└── README.md______________________________________________________________________
安装
克隆仓库
安装依赖项
（可选，但推荐）
忽略向量数据库目录以避免损坏
可用工具：
| 工具 | 目的 |
|---|---|
ping | 健康检查 |
retrieve_cleantech | 矢量检索+元数据过滤器+重新排序 |
summarize_docs | 上下文构建+LLM总结 |
explain_answer | 逐步推理+支持级别 |
answer_question | 全管道编排器 |
______________________________________________________________________
评估
所有实验均遵循作业第3部分的评估方案。
运行检索+答案质量基准：
输出：
results_retrieval.csvresults_answers.csvresults_model_answers.json
检索结果（前10名）
| 度量 | 分数 |
|---|---|
| Hit@10 | 0.34 |
| Precision@10 | 0.068 |
| Recall@10 | 0.513 |
| 平均倒数排名 | 0.260 |
释义：\ 系统检索 覆盖良好 （高召回率），即使精确匹配很嘈杂。这在一个有许多重叠文章的领域是意料之中的。
答案质量
| 度量 | 分数 |
|---|---|
| 平均余弦相似性（系统与黄金答案） | 0.6586 |
这表示生成的答案是 *语义对齐* 检索成功时使用黄金参考。
______________________________________________________________________
遇到的主要挑战
本项目有意记录 真正的工程障碍，包括：
- ChromaDB模式不匹配和损坏
- 嵌入过程中的批量限制
- LangChain弃用（HFEmbeddings→ langchain拥抱脸）
- MCP stdio传输中的严格JSON格式
- 拥抱面对推理失败/回退
- 环境不一致
- MCP工具调用错误(
params.name、错误字段等）
这些塑造了最终的设计，并有助于构建更稳定的架构。
______________________________________________________________________
经验教训
技术性的
- MCP功能强大，但非常严格
- 重新排序显著提高了检索质量
- 版本固定至关重要
- 配料可防止Chroma断裂
- 推理工具早期暴露幻觉
项目级别
- 现实世界的系统从来不会在第一次尝试时工作
- 重置和重建索引有时是不可避免的
- 严格控制范围，确保项目顺利进行
______________________________________________________________________