AI导哈

检索增强生成服务

基于FastMCP框架的检索增强生成服务，通过Model Context Protocol提供文档检索工具，支持Google Firestore文档源和Qdrant向量数据库相似性搜索。

  • by gokulnathan66
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 gokulnathan66/rag_mcp

使用说明

RAG MCP 服务器

这个仓库包含了基于RAG（检索增强生成）的MCP服务器：一个基于FastMCP的服务，通过模型上下文协议提供文档检索工具。该系统从Google Firestore接收文档，使用FastEmbed（ONNX运行时）生成嵌入表示，并利用Qdrant进行相似度搜索。

内容

  • 设计概述与架构
  • 要求和验收标准
  • 数据模型和错误处理策略
  • 部署说明（Docker Compose）

本README文件汇总了位于（此处）的设计和需求文档 .kiro/specs/rag-mcp-server/。

概述

RAG MCP服务器是一个即开即用的检索增强生成系统，它集成了Google Firestore作为文档来源，并使用Qdrant向量数据库进行相似度搜索。该系统基于FastMCP框架构建，通过模型上下文协议提供实时文档同步和高性能查询能力。

高级架构

组件：

  • MCP 客户端 -> FastMCP 服务器
  • FastMCP 服务器 -> LangGraph 调度器
  • LangGraph -> Firestore 客户端，FastEmbed，Qdrant 客户端
  • Firestore 存储文档；Qdrant 存储向量
  • FastEmbed 使用 ONNX 运行时进行嵌入生成

横切关注点：Pydantic 验证和 Logfire 监控。

组件职责

  1. FastMCP 服务器
    • 处理MCP（JSON-RPC 2.0）通信并暴露RAG工具。
    • 示例工具接口：
@mcp.tool
async def query_documents(query: str, max_results: int = 10) -> List[DocumentResult]

@mcp.tool
async def ingest_firestore_collection(collection_name: str, filters: Optional[Dict] = None) -> IngestionResult

@mcp.tool
async def get_server_status() -> ServerStatus

  1. LangGraph 任务调度器

    • 协调多步骤的RAG（检索增强生成）工作流程（查询解析、提取、分块、嵌入、存储、搜索、组装）。
    • 管理状态、重试和并发操作。

  2. Firestore 集成

    • 使用服务账户凭据连接到 Google Firestore。
    • 支持异步操作、集合组查询以及实时监听器以实现同步。

  3. FastEmbed 处理

    • 使用ONNX优化模型生成嵌入（默认： sentence-transformers/all-MiniLM-L6-v2）。
    • 支持批处理和可选的稀疏模型。

  4. Qdrant 向量数据库

    • 存储索引向量和有效载荷元数据，支持混合搜索和持久化存储。

数据模型（Pydantic）

关键模型：

  • Firestore文档：文档ID、集合路径、内容、创建时间、更新时间、文档类型
  • 文档块：块ID，父文档ID，内容，块索引，元数据
  • 文档嵌入：块ID，向量，模型名称，嵌入类型
  • 查询结果：文档ID，片段ID，内容，相似度分数，元数据，Firestore元数据

QdrantPoint的有效载荷包括document_id（文档ID）、collection_path（集合路径）、content（内容）、chunk_index（块索引）、create_time（创建时间）、update_time（更新时间）和embedding_model（嵌入模型）。

错误处理

类别和策略：

  • 连接错误：使用指数退避重试，Qdrant的断路器机制
  • 处理错误：回退模型，跳过无效文档，重试
  • 验证错误：Pydantic验证与结构化错误响应
  • 资源错误：减少批处理大小，对磁盘/内存问题发出警报

错误响应格式：

class ErrorResponse(BaseModel):
		error_code: str
		error_message: str
		error_details: Optional[Dict[str, Any]]
		retry_after: Optional[int]
		correlation_id: str

要求（概要）

服务器必须支持：

  • 自然语言查询 -> 查询嵌入 -> 在Qdrant中进行相似度搜索 -> 返回带有相似度分数和Firestore元数据的排序文档（可配置结果限制）。
  • 处理Firestore集合：提取文档，对大文档进行分块，生成嵌入向量，将向量和负载存储在Qdrant中。
  • MCP协议支持：将检索功能作为MCP工具暴露出来，并返回有效的MCP响应。
  • 配置：FastEmbed模型选择、Qdrant连接、Firestore凭据/过滤器、LangGraph分块策略。
  • 实时同步：通过监听器检测 Firestore 的创建/更新/删除操作，并保持 Qdrant 与之同步。
  • 通过 Pydantic/Logfire 实现优雅的错误处理和监控。

验收标准已全部列出在 .kiro/specs/rag-mcp-server/requirements.md 在执行测试和持续集成（CI）检查时应使用它。

测试策略

  • 针对MCP工具、LangGraph节点、Firestore客户端、嵌入生成以及Qdrant操作的单元测试。
  • 使用 Firestore 模拟器和容器化的 Qdrant 测试实例进行集成测试。
  • 针对数据摄入和查询管道进行端到端测试，包括实时同步和错误场景测试。

部署

示例 Docker Compose（见 .kiro/specs/rag-mcp-server/design.md):

version: '3.8'
services:
	qdrant:
		image: qdrant/qdrant:latest
		ports:
			- "6333:6333"
			- "6334:6334"
		volumes:
			- ./qdrant_storage:/qdrant/storage

	rag-mcp-server:
		build: .
		ports:
			- "8000:8000"
		environment:
			- FIRESTORE_PROJECT_ID=${FIRESTORE_PROJECT_ID}
			- FIRESTORE_CREDENTIALS_PATH=/app/credentials.json
			- QDRANT_URL=http://qdrant:6333
		volumes:
			- ./credentials.json:/app/credentials.json:ro
		depends_on:
			- qdrant

配置

示例配置模型：

class ServerConfig(BaseModel):
		mcp_server_name: str = "rag-server"
		mcp_version: str = "1.0.0"
		firestore_project_id: str
		firestore_credentials_path: str
		firestore_database_id: str = "(default)"
		qdrant_url: str = "http://localhost:6333"
		qdrant_api_key: Optional[str] = None
		qdrant_collection_name: str = "firestore_documents"
		embedding_model_name: str = "sentence-transformers/all-MiniLM-L6-v2"
		embedding_batch_size: int = 32
		enable_sparse_embeddings: bool = False
		max_chunk_size: int = 1000
		chunk_overlap: int = 200
		max_concurrent_requests: int = 10
		enable_logfire: bool = True
		log_level: str = "INFO"

实时同步

Firestore 监听器应实现对创建、更新和删除文档的回调处理。应跟踪 Qdrant 有效载荷元数据中的同步状态，并使用最后写入覆盖的方式解决冲突。

Web用户界面（或Web界面）

提供了一个简单的网页界面，用于上传CSV文件和查询文档：

# Start Qdrant
docker-compose up -d qdrant

# Run web UI
make web-ui
# or
python -m app.web_server

在您的浏览器中打开 http://localhost:8000。

特点：

  • 通过浏览器上传CSV文件
  • 使用自然语言查询文档
  • 查看摄入统计信息和结果
  • 监控系统健康状况

看 QUICKSTART_WEB_UI.md 翻译为中文是：快速启动_网页界面指南.md 以获取详细说明。

下一步行动及建议

  • 使用工具实现FastMCP服务器的框架 query_documents， ingest_firestore_collection，和 get_server_status。
  • 添加测试以及一个基于docker-compose的最小化本地开发环境设置（Firestore 模拟器 + Qdrant）。
  • 添加CI检查以使用模拟器/容器运行单元测试和集成测试。

文件

  • .kiro/specs/rag-mcp-server/design.md — 设计文档（源文件）
  • .kiro/specs/rag-mcp-server/requirements.md — 要求和验收标准（来源）

许可证

添加您偏好的许可证。

更新后的README：合并了设计+需求，以便更轻松地上手和实施。

相关 MCP