382 lines
8.6 KiB
Markdown
382 lines
8.6 KiB
Markdown
# AI Agent 系统部署指南
|
||
|
||
## 🎯 系统架构
|
||
|
||
### 三阶段流程
|
||
|
||
```
|
||
用户输入
|
||
↓
|
||
[阶段1: 计划制定 Planning]
|
||
- LLM 分析用户需求
|
||
- 确定需要哪些工具
|
||
- 制定执行计划（steps）
|
||
↓
|
||
[阶段2: 工具执行 Execution]
|
||
- 按计划顺序调用 MCP 工具
|
||
- 收集数据
|
||
- 异常处理和重试
|
||
↓
|
||
[阶段3: 结果总结 Summarization]
|
||
- LLM 综合分析所有数据
|
||
- 生成自然语言报告
|
||
↓
|
||
输出给用户
|
||
```
|
||
|
||
## 📦 文件清单
|
||
|
||
### 后端文件
|
||
|
||
```
|
||
mcp_server.py # MCP 工具服务器（已有）
|
||
mcp_agent_system.py # Agent 系统核心逻辑（新增）
|
||
mcp_config.py # 配置文件（已有）
|
||
mcp_database.py # 数据库操作（已有）
|
||
```
|
||
|
||
### 前端文件
|
||
|
||
```
|
||
src/components/ChatBot/
|
||
├── ChatInterfaceV2.js # 新版聊天界面（漂亮）
|
||
├── PlanCard.js # 执行计划卡片
|
||
├── StepResultCard.js # 步骤结果卡片（可折叠）
|
||
├── ChatInterface.js # 旧版聊天界面（保留）
|
||
├── MessageBubble.js # 消息气泡组件（保留）
|
||
└── index.js # 统一导出
|
||
|
||
src/views/AgentChat/
|
||
└── index.js # Agent 聊天页面
|
||
```
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
# 进入项目目录
|
||
cd /home/ubuntu/vf_react
|
||
|
||
# 安装 OpenAI SDK（支持多个LLM提供商）
|
||
pip install openai
|
||
```
|
||
|
||
### 2. 获取 LLM API Key
|
||
|
||
**推荐：通义千问（便宜且中文能力强）**
|
||
|
||
1. 访问 https://dashscope.console.aliyun.com/
|
||
2. 注册/登录阿里云账号
|
||
3. 开通 DashScope 服务
|
||
4. 创建 API Key
|
||
5. 复制 API Key（格式：`sk-xxx...`）
|
||
|
||
**其他选择**：
|
||
- DeepSeek: https://platform.deepseek.com/ （最便宜）
|
||
- OpenAI: https://platform.openai.com/ （需要翻墙）
|
||
|
||
### 3. 配置环境变量
|
||
|
||
```bash
|
||
# 编辑环境变量
|
||
sudo nano /etc/environment
|
||
|
||
# 添加以下内容（选择一个）
|
||
# 方式1: 通义千问（推荐）
|
||
DASHSCOPE_API_KEY="sk-your-key-here"
|
||
|
||
# 方式2: DeepSeek（更便宜）
|
||
DEEPSEEK_API_KEY="sk-your-key-here"
|
||
|
||
# 方式3: OpenAI
|
||
OPENAI_API_KEY="sk-your-key-here"
|
||
|
||
# 保存并退出，然后重新加载
|
||
source /etc/environment
|
||
|
||
# 验证环境变量
|
||
echo $DASHSCOPE_API_KEY
|
||
```
|
||
|
||
### 4. 修改 mcp_server.py
|
||
|
||
在文件末尾（`if __name__ == "__main__":` 之前）添加：
|
||
|
||
```python
|
||
# ==================== Agent 端点 ====================
|
||
|
||
from mcp_agent_system import MCPAgent, ChatRequest, AgentResponse
|
||
|
||
# 创建 Agent 实例
|
||
agent = MCPAgent(provider="qwen") # 或 "deepseek", "openai"
|
||
|
||
@app.post("/agent/chat", response_model=AgentResponse)
|
||
async def agent_chat(request: ChatRequest):
|
||
"""智能代理对话端点"""
|
||
logger.info(f"Agent chat: {request.message}")
|
||
|
||
# 获取工具列表和处理器
|
||
tools = [tool.dict() for tool in TOOLS]
|
||
|
||
# 处理查询
|
||
response = await agent.process_query(
|
||
user_query=request.message,
|
||
tools=tools,
|
||
tool_handlers=TOOL_HANDLERS,
|
||
)
|
||
|
||
return response
|
||
```
|
||
|
||
### 5. 重启 MCP 服务
|
||
|
||
```bash
|
||
# 如果使用 systemd
|
||
sudo systemctl restart mcp-server
|
||
|
||
# 或者手动重启
|
||
pkill -f mcp_server
|
||
nohup uvicorn mcp_server:app --host 0.0.0.0 --port 8900 > mcp_server.log 2>&1 &
|
||
|
||
# 查看日志
|
||
tail -f mcp_server.log
|
||
```
|
||
|
||
### 6. 测试 Agent API
|
||
|
||
```bash
|
||
# 测试 Agent 端点
|
||
curl -X POST http://localhost:8900/agent/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"message": "全面分析贵州茅台这只股票",
|
||
"conversation_history": []
|
||
}'
|
||
|
||
# 应该返回类似这样的JSON：
|
||
# {
|
||
# "success": true,
|
||
# "message": "根据分析，贵州茅台...",
|
||
# "plan": {
|
||
# "goal": "全面分析贵州茅台",
|
||
# "steps": [...]
|
||
# },
|
||
# "step_results": [...],
|
||
# "metadata": {...}
|
||
# }
|
||
```
|
||
|
||
### 7. 部署前端
|
||
|
||
```bash
|
||
# 在本地构建
|
||
npm run build
|
||
|
||
# 上传到服务器
|
||
scp -r build/* ubuntu@your-server:/var/www/valuefrontier.cn/
|
||
|
||
# 或者在服务器上构建
|
||
cd /home/ubuntu/vf_react
|
||
npm run build
|
||
sudo cp -r build/* /var/www/valuefrontier.cn/
|
||
```
|
||
|
||
### 8. 重启 Nginx
|
||
|
||
```bash
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
## ✅ 验证部署
|
||
|
||
### 1. 测试后端 API
|
||
|
||
```bash
|
||
# 测试工具列表
|
||
curl https://valuefrontier.cn/mcp/tools
|
||
|
||
# 测试 Agent
|
||
curl -X POST https://valuefrontier.cn/mcp/agent/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"message": "今日涨停股票有哪些",
|
||
"conversation_history": []
|
||
}'
|
||
```
|
||
|
||
### 2. 测试前端
|
||
|
||
1. 访问 https://valuefrontier.cn/agent-chat
|
||
2. 输入问题："全面分析贵州茅台这只股票"
|
||
3. 观察：
|
||
- ✓ 是否显示执行计划卡片
|
||
- ✓ 是否显示步骤执行过程
|
||
- ✓ 是否显示最终总结
|
||
- ✓ 步骤结果卡片是否可折叠
|
||
|
||
### 3. 测试用例
|
||
|
||
```
|
||
测试1: 简单查询
|
||
输入：查询贵州茅台的股票信息
|
||
预期：调用 get_stock_basic_info，返回基本信息
|
||
|
||
测试2: 深度分析（推荐）
|
||
输入：全面分析贵州茅台这只股票
|
||
预期：
|
||
- 步骤1: get_stock_basic_info
|
||
- 步骤2: get_stock_financial_index
|
||
- 步骤3: get_stock_trade_data
|
||
- 步骤4: search_china_news
|
||
- 步骤5: summarize_with_llm
|
||
|
||
测试3: 市场热点
|
||
输入：今日涨停股票有哪些亮点
|
||
预期：
|
||
- 步骤1: search_limit_up_stocks
|
||
- 步骤2: get_concept_statistics
|
||
- 步骤3: summarize_with_llm
|
||
|
||
测试4: 概念分析
|
||
输入：新能源概念板块的投资机会
|
||
预期：
|
||
- 步骤1: search_concepts（新能源）
|
||
- 步骤2: search_china_news（新能源）
|
||
- 步骤3: summarize_with_llm
|
||
```
|
||
|
||
## 🐛 故障排查
|
||
|
||
### 问题1: Agent 返回 "Provider not configured"
|
||
|
||
**原因**: 环境变量未设置
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查环境变量
|
||
echo $DASHSCOPE_API_KEY
|
||
|
||
# 如果为空，重新设置
|
||
export DASHSCOPE_API_KEY="sk-xxx..."
|
||
|
||
# 重启服务
|
||
sudo systemctl restart mcp-server
|
||
```
|
||
|
||
### 问题2: Agent 返回 JSON 解析错误
|
||
|
||
**原因**: LLM 没有返回正确的 JSON 格式
|
||
|
||
**解决**: 在 `mcp_agent_system.py` 中已经处理了代码块标记清理，如果还有问题：
|
||
1. 检查 LLM 的 temperature 参数（建议 0.3）
|
||
2. 检查 prompt 是否清晰
|
||
3. 尝试不同的 LLM 提供商
|
||
|
||
### 问题3: 前端显示 "查询失败"
|
||
|
||
**原因**: 后端 API 未正确配置或 Nginx 代理问题
|
||
|
||
**解决**:
|
||
```bash
|
||
# 1. 检查 MCP 服务是否运行
|
||
ps aux | grep mcp_server
|
||
|
||
# 2. 检查 Nginx 配置
|
||
sudo nginx -t
|
||
|
||
# 3. 查看错误日志
|
||
sudo tail -f /var/log/nginx/error.log
|
||
tail -f /home/ubuntu/vf_react/mcp_server.log
|
||
```
|
||
|
||
### 问题4: 执行步骤失败
|
||
|
||
**原因**: 某个 MCP 工具调用失败
|
||
|
||
**解决**: 查看步骤结果卡片中的错误信息，通常是：
|
||
- API 超时：增加 timeout
|
||
- 参数错误：检查工具定义
|
||
- 数据库连接失败：检查数据库连接
|
||
|
||
## 💰 成本估算
|
||
|
||
### 使用通义千问（qwen-plus）
|
||
|
||
**价格**: ¥0.004/1000 tokens
|
||
|
||
**典型对话消耗**:
|
||
- 简单查询（1步）: ~500 tokens = ¥0.002
|
||
- 深度分析（5步）: ~3000 tokens = ¥0.012
|
||
- 平均每次对话: ¥0.005
|
||
|
||
**月度成本**（1000次深度分析）:
|
||
- 1000次 × ¥0.012 = ¥12
|
||
|
||
**结论**: 非常便宜！1000次深度分析只需要12元。
|
||
|
||
### 使用 DeepSeek（更便宜）
|
||
|
||
**价格**: ¥0.001/1000 tokens（比通义千问便宜4倍）
|
||
|
||
**月度成本**（1000次深度分析）:
|
||
- 1000次 × ¥0.003 = ¥3
|
||
|
||
## 📊 监控和优化
|
||
|
||
### 1. 添加日志监控
|
||
|
||
```bash
|
||
# 实时查看 Agent 日志
|
||
tail -f mcp_server.log | grep -E "\[Agent\]|\[Planning\]|\[Execution\]|\[Summary\]"
|
||
```
|
||
|
||
### 2. 性能优化建议
|
||
|
||
1. **缓存计划**: 相似的问题可以复用执行计划
|
||
2. **并行执行**: 独立的工具调用可以并行执行
|
||
3. **流式输出**: 使用 Server-Sent Events 实时返回进度
|
||
4. **结果缓存**: 相同的工具调用结果可以缓存
|
||
|
||
### 3. 添加统计分析
|
||
|
||
在 `mcp_server.py` 中添加：
|
||
|
||
```python
|
||
from datetime import datetime
|
||
import json
|
||
|
||
# 记录每次 Agent 调用
|
||
@app.post("/agent/chat")
|
||
async def agent_chat(request: ChatRequest):
|
||
start_time = datetime.now()
|
||
|
||
response = await agent.process_query(...)
|
||
|
||
duration = (datetime.now() - start_time).total_seconds()
|
||
|
||
# 记录到日志
|
||
logger.info(f"Agent query completed in {duration:.2f}s", extra={
|
||
"query": request.message,
|
||
"steps": len(response.plan.steps) if response.plan else 0,
|
||
"success": response.success,
|
||
"duration": duration,
|
||
})
|
||
|
||
return response
|
||
```
|
||
|
||
## 🎉 完成！
|
||
|
||
现在你的 AI Agent 系统已经部署完成！
|
||
|
||
访问 https://valuefrontier.cn/agent-chat 开始使用。
|
||
|
||
**特点**:
|
||
- ✅ 三阶段智能分析（计划-执行-总结）
|
||
- ✅ 漂亮的UI界面（卡片式展示）
|
||
- ✅ 步骤结果可折叠查看
|
||
- ✅ 实时进度反馈
|
||
- ✅ 异常处理和重试
|
||
- ✅ 成本低廉（¥3-12/月）
|