使用说明

MCP演示

🚀 快速开始

先决条件

运行此项目之前，请确保已安装以下内容：你应该有

Docker已安装
python 3.11 和git

2.设置环境变量

创建虚拟环境以安装库

python 3.11-m venv env11 如果您使用的是MacOS：要激活：source env11/bin/activate 在Windows上：env11\Scripts\activate

创建 .env 我们需要OpenAI api密钥。

（无需更改litellm密钥。这是我们在系统中设置的密钥）


OPENAI_API_KEY= actual_api_key
LITELLM_MASTER_KEY=demo-key-123
HUGGINGFACE_API_KEY=HF_key

3.安装Python依赖项

pip install -r requirements.txt

4.启动Docker服务

docker-compose up -d

这将开始：

开放搜索 （端口9200）
OpenSearch仪表板 （端口5601）
奥拉玛 （端口11434）
LiteLLM代理 （端口4000）

4.等待服务初始化

等待大约2-3分钟，让所有服务完全启动。您可以通过以下方式检查状态：

docker-compose ps

所有服务都应显示“Up”状态。

5.索引示例PDF

python indexer.py

这将：

从纸张/PDF中读取文件
处理和分组文档
使用HuggingFace BGE模型生成嵌入
索引OpenSearch中的所有内容

6.运行演示

python agno_agent.py

🎯 Demo的功能是什么

演示对索引文档执行三种类型的搜索：

BM25搜索 -基于关键字的搜索
密集矢量搜索 -基于嵌入的语义搜索
混合搜索 -结合BM25和矢量搜索

对于每种搜索类型，它：

显示结果的前300个字符
使用完整的混合搜索结果作为LLM的上下文
使用LiteLLM代理生成AI响应

🔧 配置

LLM配置

如果你打开litellm_config.yaml，HF模型会出现在注释中。如果你想使用HF，只需删除注释，在注释中创建Openai模型和api键行，并在agno_agent.py中更改模型名称

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: "your-openai-api-key"

建议是决定一个并使用它。如果你使用一个并切换到另一个，在更改litellm_config.yaml后，重新启动litellm（在终端中）：

docker编写重启litellm代理

📁 项目结构

mcp-demo/
├── agno_agent.py              # Main agent script
├── indexer.py                 # PDF processing and indexing script
├── fastmcp_server.py          # FastMCP server
├── mcp_opensearch_tool.py     # OpenSearch MCP tool
├── docker-compose.yml         # Docker services configuration
├── litellm_config.yaml        # LiteLLM proxy configuration
├── requirements.txt           # Python dependencies
└── README.md                  # This file

🛠️ 故障排除

常见问题

Docker服务未启动

# Check Docker is running
docker --version

# Restart services
docker-compose down
docker-compose up -d

内存问题
- 确保您有至少8GB的可用RAM
- 关闭其他内存密集型应用程序
- 在Docker桌面设置中增加Docker内存限制
端口冲突
- 确保端口9200、5601、11434和4000未使用
- 请检查： netstat -an | grep :9200

Python依赖关系

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

OpenSearch连接问题

# Check OpenSearch health
curl http://localhost:9200/_cluster/health

日志和调试

Docker日志: docker-compose logs [service-name]
OpenSearch日志: docker-compose logs opensearch
LiteLLM日志: docker-compose logs litellm

🔍 测试系统

1.测试OpenSearch

curl http://localhost:9200/_cluster/health

2.测试LiteLLM代理

curl -X POST http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

🔄 添加新PDF

要将新PDF添加到系统中，请执行以下操作：

将PDF放在papers目录中：

mkdir -p papers/pdfs
# Copy your PDFs to papers/pdfs/

运行索引器：
```
python3 indexer.py
```
运行代理：
```
python3 agno_agent.py
```

索引器将自动执行以下操作：

从以下位置读取PDF papers/pdfs/
从PDF中提取文本
分成块
生成嵌入
OpenSearch中的索引

🚀 高级用法

添加新PDF

将PDF文件放入 papers/ 目录
运行索引器： python opensearch_indexer.py
新文档将被自动处理和索引

🔄 停止服务

要停止所有服务，请执行以下操作：

docker-compose down

要停止并删除所有数据，请执行以下操作：

docker-compose down -v