使用说明
FastMCP RAG模板
生产准备就绪 FastMCP+LangChain RAG（检索增强生成） 具有多提供商LLM支持、智能自动检测和灵活架构的模板。
特征：
多提供商LLM支持
- 开放人工智能 （GPT-5、O1 Pro、GPT-4o）
- Anthropic （克劳德4.5作品/十四行诗/俳句）
- 谷歌双子座 （Gemini 3.0 Pro、2.5 Pro/Flash）
- 基于可用API密钥的自动提供程序检测
- 在提供商之间进行热交换而不会丢失数据
灵活嵌入
- 供应商特定：OpenAI、谷歌Gemini嵌入
- 第三方：Voyage AI
- 免费替代品：拥抱脸（当地），奥利马（当地）
- 混合搭配LLM和嵌入提供商
文档管理
- 对……的支持
.txt,.pdf,.md,.docx文件 - 可配置的组块策略
- 带有错误处理的批处理文档
- 自定义元数据支持
- 动态文档添加/删除
高级检索
- 相似性搜索 -查找语义相似的内容
- MMR（最大边际相关性） -多样化的结果
- 分数阈值过滤 -只有高信心的比赛
- 对话记忆和聊天记录
- 每次回复的来源引用
MCP工具
| 工具 | 说明 |
|---|---|
setup_rag() |
使用自动提供程序检测进行初始化 |
query() |
支持对话历史记录的查询 |
add_documents() |
批量文档添加 |
search() |
语义+关键字混合搜索 |
get_config() |
显示当前配置 |
switch_provider() |
提供商之间的热交换 |
clear_index() |
重置矢量存储 |
监控和分析
- 每次查询的成本跟踪
- 性能指标（延迟、令牌）
- 提供商比较分析
- 查询历史跟踪
快速入门：
先决条件
- Python 3.10或更高版本
- 紫外线 包管理器
- 至少一个提供商（OpenAI、Anthropic或Google）的API密钥
安装
-
克隆存储库
git clone <repository-url> cd mcp-chain-template -
使用uv安装依赖项
# Install base dependencies uv pip install -e . # Or install with all providers uv pip install -e ".[all]" # Or install specific providers uv pip install -e ".[openai,anthropic]" -
配置环境变量
cp .env.example .env # Edit .env and add your API keys -
运行MCP服务器
uv run server.py -
测试您的设置 （可选但推荐）
# Run the production test to verify everything works uv run test_production.py备注：如果您达到API配额限制，请切换到免费的HuggingFace嵌入：
echo "PREFERRED_EMBEDDING_PROVIDER=huggingface" >> .env uv pip install -e ".[embeddings-hf]" uv run test_production.py
提供商设置指南：
OpenAI设置
- 从获取API密钥 OpenAI平台
- 增添
.env:OPENAI_API_KEY=sk-... OPENAI_MODEL=gpt-5 - 安装：
uv pip install -e ".[openai]"
支持的型号: gpt-5, gpt-5-mini, o1-pro, gpt-4o
人物（克劳德）设置
- 从获取API密钥 拟人控制台
- 增添
.env:ANTHROPIC_API_KEY=sk-ant-... ANTHROPIC_MODEL=claude-4-5-sonnet-20250929 - 安装：
uv pip install -e ".[anthropic]"
支持的型号: claude-4-5-opus-20251124, claude-4-5-sonnet-20250929, claude-4-5-haiku-20251015
谷歌Gemini设置
- 从获取API密钥 谷歌AI工作室
- 增添
.env:GOOGLE_API_KEY=AIza... GEMINI_MODEL=gemini-2.5-pro - 安装：
uv pip install -e ".[gemini]"
支持的型号: gemini-3.0-pro, gemini-2.5-pro, gemini-2.5-flash
嵌入提供者
拥抱脸（免费，本地）
uv pip install -e ".[embeddings-hf]"
不需要API密钥！使用本地模型。
Voyage AI
# Add to .env
VOYAGE_API_KEY=pa-...
# Install
uv pip install -e ".[embeddings-voyage]"
Ollama（免费，当地）
# Install Ollama first: https://ollama.ai
# Pull a model: ollama pull llama2
uv pip install -e ".[embeddings-ollama]"
💡 使用示例
基本RAG查询
# Through MCP protocol
{
"tool": "setup_rag",
"arguments": {} # Auto-detects available provider
}
{
"tool": "add_documents",
"arguments": {
"file_paths": ["documents/sample.md", "documents/sample.txt"]
}
}
{
"tool": "query",
"arguments": {
"question": "What is machine learning?"
}
}
答复：
{
"status": "success",
"answer": "Machine learning is a subset of AI that enables systems to learn...",
"sources": [
{
"content": "Machine learning is...",
"metadata": {"source": "documents/sample.md", "page": 1}
}
],
"metrics": {
"latency_ms": 1234,
"total_tokens": 256,
"cost_usd": 0.0023
}
}
提供商切换
# Start with OpenAI
setup_rag(provider="openai")
# Switch to Claude mid-conversation
switch_provider(provider="anthropic", model="claude-3-sonnet-20240229")
# Switch to Gemini
switch_provider(provider="gemini")
矢量存储和文档在提供程序交换机之间保持不变！
与记忆对话
# First query
result1 = query(question="What is supervised learning?")
# Follow-up (maintains context)
result2 = query(
question="Can you give me examples?",
chat_history=[
{"role": "user", "content": "What is supervised learning?"},
{"role": "assistant", "content": result1["answer"]}
]
)
高级搜索
# Similarity search
search(query="machine learning applications", top_k=5, search_type="similarity")
# MMR for diverse results
search(query="Python features", search_type="mmr")
# High-confidence matches only
search(query="neural networks", search_type="similarity_score_threshold")
成本跟踪
config = get_config()
print(f"Total queries: {config['metrics']['total_queries']}")
print(f"Total cost: ${config['metrics']['total_cost_usd']}")
print(f"Average latency: {config['metrics']['avg_latency_ms']}ms")
🎛️ 配置
环境变量
看 .env.example 对于所有配置选项。
关键设置：
# Provider Priority
PREFERRED_LLM_PROVIDER=openai # or anthropic, gemini
# Chunking Strategy
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
# Retrieval Settings
TOP_K=4
SEARCH_TYPE=similarity # or mmr, similarity_score_threshold
# Vector Store
VECTOR_STORE=faiss # or chroma, pinecone
# Features
ENABLE_STREAMING=false
ENABLE_COST_TRACKING=true
MEMORY_TYPE=buffer # or summary, none
分块策略
| 策略 | 最适合 | 配置 |
|---|---|---|
| 递归 | 常规文本 | 默认 |
| 角色 | 简单拆分 | 设置 splitter_type=character |
| Markdown | .md文件 | 设置 splitter_type=markdown |
矢量存储
| 商店 | 类型 | 最适合 |
|---|---|---|
| FAISS | 本地 | 开发，单机 |
| Chroma | 本地/云 | 持久性，元数据过滤 |
| 松果 | 云 | 生产、规模 |
📁 项目结构
fastmcp-rag-template/
├── server.py # Main FastMCP server
├── config.py # Configuration management
├── document_manager.py # Document loading & chunking
├── vector_store.py # Vector store management
├── metrics.py # Cost & performance tracking
├── test_production.py # Production test suite
├── providers/ # Provider implementations
│ ├── __init__.py
│ ├── base.py # Abstract provider interface
│ ├── openai.py # OpenAI implementation
│ ├── anthropic.py # Anthropic implementation
│ ├── gemini.py # Google Gemini implementation
│ └── registry.py # Provider factory
├── documents/ # Your documents go here
│ ├── sample.md
│ └── sample.txt
├── pyproject.toml # Dependencies & config
├── .env.example # Environment template
└── README.md # This file
🔧 故障排除
没有可用的LLM提供程序
错误： No LLM provider available. Please set at least one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY
解决方案： 将至少一个API密钥添加到您的 .env 文件。
提供程序导入错误
错误： ImportError: Anthropic provider requires langchain-anthropic
解决方案： 安装提供程序依赖项：
uv pip install -e ".[anthropic]"
未找到矢量存储
错误： 矢量存储未初始化
解决方案： 先添加文档：
add_documents(file_paths=["path/to/document.txt"])
不支持的文件格式
错误： Unsupported file format: .xlsx
解决方案： 目前支持的格式有 .txt, .pdf, .md, .docx。转换文件或实现自定义加载器。
🏗️ 建筑
自动检测流程
graph TD
A[setup_rag called] --> B{Preferred provider set?}
B -->|Yes| C{Provider available?}
C -->|Yes| D[Use preferred provider]
C -->|No| E[Fallback to auto-detect]
B -->|No| E
E --> F{OpenAI available?}
F -->|Yes| G[Use OpenAI]
F -->|No| H{Anthropic available?}
H -->|Yes| I[Use Anthropic]
H -->|No| J{Gemini available?}
J -->|Yes| K[Use Gemini]
J -->|No| L[Error: No provider]
RAG查询流
graph LR
A[User Query] --> B[Embedding]
B --> C[Vector Search]
C --> D[Retrieve Docs]
D --> E[Context + Query]
E --> F[LLM]
F --> G[Answer + Sources]
G --> H[Track Metrics]
🎯 最佳实践
1.供应商选择
- 注重成本：使用Gemini或GPT-3.5涡轮增压
- 最佳质量：GPT-4或克劳德3作品集
- 平衡的：克劳德三重奏或GPT-4涡轮
2.嵌入策略
- 省钱：拥抱脸（免费，本地）
- 最佳质量：OpenAI文本嵌入-3大
- 本地/私人：Ollama嵌入件
3.堵塞
- 技术文档：较大的区块（1500-2000个代币）
- 问答：较小的区块（500-800个代币）
- 混合内容：默认值（1000个令牌）
4.搜索类型
- 具体问题:
similarity - 探索性:
mmr - 高精度:
similarity_score_threshold
🤝 贡献
欢迎投稿！需要改进的地方：
- 其他法学硕士提供者（Cohere、Mistral等）
- 更多矢量存储（Weaviate、Qdrant）
- 重新排序实施
- 流媒体响应支持
- 高级检索策略
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件
🙏 致谢
内置：
📞 支持
RAG大楼快乐！ 🚀
