本体论-MCP服务器-强化学习-稳定基线3

Name: 本体论-MCP服务器-强化学习-稳定基线3
Author: shark8848

作者：shark88482 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

Ontology RL Commerce Agent

English | 简体中文

🛍️ Ontology RL Commerce Agent（原名“Ontology MCP Server”）突出了最新的强化学习驱动的闭环系统。该系统仍然依赖于模型上下文协议（MCP）来结合本体推理、电子商务业务逻辑、记忆以及一个Gradio用户界面，以便您可以从头到尾地重现完整的购物助手体验。

🤖 强化学习驱动的代理：Stable Baselines3 PPO训练流水线内置在树中。它涵盖了从数据 → 训练 → 评估 → 部署的整个流程，使代理能够不断从真实的对话记录和工具日志中学习，从而自动发现更安全、更高效的工具链策略。

🚀 快速开始

选项A：Docker（推荐）

需求

Docker 20.10+
Docker Compose 2.0+
8GB+ 内存
20GB 磁盘空间

一键启动

# 1. 克隆仓库
git clone <repository-url>
cd ontology-mcp-server-RL-Stable-Baselines3

# 2. 配置环境变量
cp .env.example .env
nano .env  # 填写LLM API密钥

# 3. 启动所有服务
docker-compose up -d

# 4. 尾随日志
docker-compose logs -f

# 5. 停止服务
docker-compose down

服务端点

MCP服务器：http://localhost:8000
代理UI：http://localhost:7860
训练仪表板：http://localhost:7861

常见命令

# 重启单个服务
docker-compose restart agent-ui

# 进入容器进行调试
docker exec -it ontology-agent-ui bash

# 检查状态
docker-compose ps

# 清理并重建（谨慎使用）
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d

GPU支持（可选）

安装nvidia-docker，然后取消注释docker-compose.yml中的GPU块。

distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

选项B：本地开发

1. 环境准备

需求

Python 3.10+
8GB+ 内存用于推理/演示（32GB+ 用于RL训练）
Linux/macOS/WSL2
可选GPU（建议≥12GB VRAM NVIDIA）
40GB磁盘（数据库、Chroma向量、RL检查点）

安装依赖项

git clone <repository-url>
cd ontology-mcp-server-RL-Stable-Baselines3
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

2. 初始化数据库

Docker部署会在首次启动时自动运行这些步骤。手动步骤仅适用于本地开发。

export ONTOLOGY_DATA_DIR="$(pwd)/data"
python scripts/init_database.py        # 创建表
python scripts/seed_data.py            # 种子基础用户/产品
python scripts/add_bulk_products.py    # 可选：+1000产品
python scripts/add_bulk_users.py       # 可选：+200用户
python scripts/update_demo_user_names.py --seed 2025

示例用户

用户ID	名称	邮箱	级别	终身消费
1	张三	zhangsan@example.com	普通	¥0
2	李四	lisi@example.com	VIP	¥6,500
3	王五	wangwu@example.com	SVIP	¥12,000

示例产品

iPhone 15 Pro Max (¥9,999)
iPhone 15 Pro (¥8,999)
iPhone 15 (¥5,999)
AirPods Pro 2 (¥1,899)
配件等

3. 配置LLM

src/agent/config.yaml 支持DeepSeek、OpenAI兼容API或本地Ollama：

llm:
  provider: "deepseek"
  api_url: "https://api.deepseek.com/v1"
  api_key: "your-api-key-here"
  model: "deepseek-chat"
  temperature: 0.7
  max_tokens: 2000

或者通过环境变量：

export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"

# 本地Ollama（qwen3:8b示例）
export LLM_PROVIDER="ollama"
export OLLAMA_API_URL="http://localhost:11434/v1"
export OLLAMA_MODEL="qwen3:8b"
export OLLAMA_API_KEY="ollama"  # Ollama忽略此值

3.1 配置MCP基础URL

训练脚本（train_rl_agent.py）和Gradio代理都通过HTTP调用MCP。如果需要覆盖MCP_BASE_URL：

# 本地/开发
export MCP_BASE_URL="http://127.0.0.1:8000"

# Docker/生产（容器间通信）
export MCP_BASE_URL="http://ontology-mcp-server:8000"

4. 启动服务

选项1：start_all.sh（推荐）

./scripts/start_all.sh
# 日志流至logs/<service>_yyyyMMdd_HHmmss.log
tail -f logs/server_*.log

停止所有服务：

./scripts/stop_all.sh

选项2：单独启动

./scripts/run_server.sh
./scripts/run_agent.sh
./scripts/run_training_dashboard.sh
./scripts/run_tensorboard.sh

选项3：手动命令

# 终端1：MCP服务器（FastAPI）
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
uvicorn ontology_mcp_server.server:app --host 0.0.0.0 --port 8000

# 终端2：Gradio UI
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://127.0.0.1:8000"
python -m agent.gradio_ui

# 终端3：RL训练仪表板
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://127.0.0.1:8000"
python scripts/run_training_dashboard.py

# 终端4：TensorBoard
source .venv/bin/activate
tensorboard --logdir data/rl_training/logs/tensorboard --host 0.0.0.0 --port 6006

要更改Gradio绑定地址/端口，请在启动前设置GRADIO_SERVER_NAME和GRADIO_SERVER_PORT。run_agent.sh / run_training_dashboard.sh接受AGENT_HOST/PORT和TRAINING_DASHBOARD_HOST/PORT；它们将值转发给Gradio环境变量以保持端口7860/7861独立。

5. 访问UI

访问**http://127.0.0.1:7860**。

标签页：

💬 计划：聊天界面 + 推理计划
🔧 工具调用：实时工具调用日志
🧠 记忆：对话记忆（ChromaDB）
🛍️ 商业分析：质量评分、意图追踪器、对话状态、推荐引擎
📋 执行日志：完整的LLM输入/输出和工具跟踪

记忆流程（Mermaid）

flowchart LR
  subgraph Ingest[Ingest & Store]
    direction TB
    U(User input)
    U --> AT(ChromaMemory.add_turn)
    AT --> SUM(generate_summary)
    SUM --> DB((ChromaDB collection))
    AT --> DB
  end

  subgraph Extract[Extraction]
    direction TB
    AT --> EX(UserContextExtractor)
    EX --> UM(UserContextManager)
  end

  subgraph Retrieval[Retrieval & Injection]
    direction TB
    UM --> CTX(get_context_for_prompt)
    CTX --> NOTE_CTX(Inject context + history)
    NOTE_CTX --> AGT(Agent / LLM)
  end

  AGT --> TC(Tool calls)
  TC --> AT
  TC -->|create_order yields ORD...| UM

6. 示例对话

用户：你好
AI：你好！欢迎...（意图：问候）

用户：推荐一部手机？
AI：[commerce.search_products] 返回4款iPhone型号...

用户：iPhone 15 Pro Max有货吗？
AI：[commerce.check_stock] 有货，50台...

用户：加入购物车
AI：[commerce.add_to_cart] 已添加...（状态：浏览 → 购物车）

7. 可选RL循环

使用scripts/generate_dialogue_corpus.py生成最新的200个完全真实的场景
使用python test_rl_modules.py检查RL模块
使用python train_rl_agent.py --timesteps ...启动PPO训练
详情见🧠 强化学习（阶段6）

🔧 MCP服务器API

MCP服务器暴露HTTP端点。

健康检查

curl http://localhost:8000/health

能力列表

curl http://localhost:8000/capabilities

调用工具

curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "commerce.search_products",
    "params": {
      "available_only": true,
      "limit": 5
    }
  }'

21个工具

本体工具（3个）

ontology.explain_discount
ontology.normalize_product
ontology.validate_order

商业工具（18个） 4. commerce.search_products 5. commerce.get_product_detail 6. commerce.check_stock 7. commerce.get_product_recommendations 8. commerce.get_product_reviews 9. commerce.add_to_cart 10. commerce.view_cart 11. commerce.remove_from_cart 12. commerce.create_order 13. commerce.get_order_detail 14. commerce.cancel_order 15. commerce.get_user_orders 16. commerce.process_payment 17. commerce.track_shipment 18. commerce.get_shipment_status 19. commerce.create_support_ticket 20. commerce.process_return 21. commerce.get_user_profile

🧠 代理架构

核心组件

ReAct代理（react_agent.py）
- LangChain ReAct工作流（推理 + 行动）
- 自动工具选择和推理轨迹
- 多轮对话意识
对话状态（conversation_state.py）
- 8个阶段：问候 → 浏览 → 选择 → 购物车 → 结算 → 跟踪 → 服务 → 空闲
- 跟踪VIP状态、购物车状态、浏览历史
- 通过关键词和工具使用自动检测转换
系统提示（prompts.py）
- 电商角色：专业友好的购物顾问
- 中文提示使用“您”的语气，避免系统术语
- 确认风险操作（支付、取消）
- 鼓励澄清问题而不是立即拒绝
对话记忆（chroma_memory.py）
- 后端：ChromaDB
- 检索模式：recent，similarity，hybrid
- 每轮自动总结
- 持久化在data/chroma_memory/
质量跟踪（quality_metrics.py）
- 对话质量评分（0-1）
- 用户满意度估计
- 工具效率及延迟跟踪
意图追踪器（intent_tracker.py）
- 14种意图（问候、搜索、查看购物车、结算、跟踪订单等）
- 置信度分数 + 历史
推荐引擎（recommendation_engine.py）
- 个性化产品推荐
- 使用浏览/购物车历史及会员等级

🧠 强化学习（阶段6）

硬件提示：PPO训练受益于≥8核CPU，≥32GB内存，和≥1个具有≥12GB VRAM的GPU（如RTX 3080/4090/A6000）。仅使用CPU是可能的，但10万步可能需要5-8小时；GPU将其缩短到约1小时。预留≥15GB用于data/rl_training/。

目标与优势

让ReAct代理通过Stable Baselines3 PPO自我改进。
编码用户上下文/意图/工具使用/产品信息到128维状态。
多目标奖励（任务成功、效率、满意度、安全性）。
Gymnasium环境重用LangChain代理而不重新实现业务逻辑。

模块概述（`src/agent/rl_agent/`）

文件	角色	备注
`state_extractor.py`	将多源对话编码成128维向量	处理嵌入/简单特征，容忍字符串/对象意图
`reward_calculator.py`	多目标奖励	`任务/效率/满意度/安全性` + 回合聚合
`gym_env.py`	`EcommerceGymEnv`	22个离散动作（21个工具 + 直接回复）
`ppo_trainer.py`	训练编排	DummyVecEnv + 评估/检查点回调 + TensorBoard
`train_rl_agent.py`	CLI入口	可配置步数、评估频率、检查点、嵌入

场景语料库 data/training_scenarios/sample_dialogues.json 包含200个真实对话，涉及真实用户/订单/产品的5个场景类别。

闭环：数据 → 训练 → 应用

数据阶段
- 确保数据库已填充：add_bulk_products.py，add_bulk_users.py，update_demo_user_names.py --seed 2025。
- 生成200个真实场景：python scripts/generate_dialogue_corpus.py。
- 可选验证片段（类别计数）显示在README.zh.md中。
训练

source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://localhost:8000"
export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"
export TRAIN_DEVICE="gpu"  # 回退到cpu
python test_rl_modules.py
python train_rl_agent.py \
  --timesteps 100000 \
  --eval-freq 2000 \
  --checkpoint-freq 20000 \
  --output-dir data/rl_training \
  --max-steps-per-episode 12 \
  --scenario-file data/training_scenarios/sample_dialogues.json \
  --device "${TRAIN_DEVICE:-gpu}"

日志流至data/rl_training/logs/tensorboard/。

评估与工件

最佳模型：data/rl_training/best_model/best_model.zip
最终模型：data/rl_training/models/ppo_ecommerce_final.zip
检查点：data/rl_training/checkpoints/ppo_ecommerce_step_*.zip
回合统计：data/rl_training/logs/training_log.json

部署

python - <<'PY'
from agent.react_agent import LangChainAgent
from agent.rl_agent.ppo_trainer import PPOTrainer

agent = LangChainAgent(max_iterations=6)
trainer = PPOTrainer(agent, output_dir="data/rl_training")
trainer.create_env(max_steps_per_episode=10)
trainer.load_model("data/rl_training/best_model/best_model.zip")

query = "我需要十部旗舰华为手机，预算大约7000"
action_idx, action_name, _ = trainer.predict(query)
print("RL建议的操作：", action_idx, action_name)

result = agent.run(query)
print(result["final_answer"])
PY

RL仪表板（Gradio）

src/training_dashboard/ 提供了一个自包含的控制台，包括语料库汇总、训练编排、指标可视化、模型注册表和热重载：

复制config/training_dashboard.example.yaml → config/training_dashboard.yaml并调整路径。
通过PYTHONPATH=src python scripts/run_training_dashboard.py启动。
标签页：概览（