项目描述
本项目实现了一个基于 模型上下文协议 (FastMCP) 的检索增强生成 (RAG) 系统，专门用于服务 Solidity 文档查询。
系统利用本地向量数据库 (Milvus Lite) 和 Hugging Face 嵌入模型对 Markdown 文件进行索引，为 LLM 提供语义模糊搜索和文档全文获取功能。
系统要求
- Python 3.10 或更高版本
- pip (Python 包管理器)
- 足够的系统内存以加载嵌入模型 (建议剩余内存 >= 4GB)
目录结构
project/
├── main.py # 程序入口 & MCP 工具定义
├── manager.py # 业务逻辑管理器 (Facade 外观模式)
├── config.py # 全局配置类
├── utils.py # 文件 I/O 与哈希计算工具
├── interfaces.py # 抽象接口定义 (Strategy 策略接口)
├── strategies/ # 策略具体实现包
│ ├── __init__.py
│ ├── embedding.py # SentenceTransformer 嵌入实现
│ └── vector_store.py # Milvus 数据库操作实现
├── segments/ # (必须) 存放源 .md 文档的目录
└── requirements.txt # 项目依赖列表安装步骤
- 克隆或解压项目代码
- 创建虚拟环境 (推荐)
python3 -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows- 安装依赖
pip install -r requirements.txt- 准备数据
请确保项目根目录下存在 segments 文件夹，并将需要索引的 Solidity Markdown (.md) 文档放入其中。
配置说明
所有可配置项均位于 config.py 文件中，你可以根据需要进行修改：
segments_dir: 文档源目录路径 (默认:./segments)db_file: 本地 Milvus 数据库文件路径 (默认:./milvus_solidity_docs.db)collection_name: 向量集合名称embedding_model: HuggingFace 模型 ID (默认:BAAI/bge-m3)embedding_dim: 向量维度 (需与模型匹配，默认: 1024)
运行与使用
在终端中运行主程序：
fastmcp run main.py:mcp --transport http --port 8000 --host 0.0.0.0或
chmod +x run.sh
./run.sh- 首次运行: 系统会计算
segments/目录下文件的哈希值，下载嵌入模型，并建立向量索引。这可能需要几分钟。 - 后续运行: 系统会自动对比文件哈希。如果源文件未发生变更，将跳过索引重建过程，直接启动服务。
提供的工具 (Tools)
服务端向 MCP 客户端暴露以下两个工具：
- fuzzy_search(query, limit)
* 描述: 对已索引的文档执行语义向量搜索。 * 参数: query (查询语句), limit (返回结果数量)。 * 返回: 包含文档 ID、相似度评分和文本预览的 JSON 字符串。
- get_doc_by_id(doc_id)
* 描述: 获取指定文档的完整内容和元数据。 * 参数: doc_id (文件名，例如 10.md)。 * 返回: 文档全文。
故障排除
- 错误: 索引未更新
* 解决: 删除根目录下的 .lock 文件和 .db 文件，强制程序重新构建索引。