Ontology MCP Server Rl Stable Baselines3

🚀 本體強化學習電商智能體

🛍️ 本體強化學習電商智能體（原 “本體MCP服務器”）著重展示了最新的強化學習驅動的閉環系統。該系統仍依賴模型上下文協議（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
• 智能體用戶界面：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 中 training-dashboard 下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 及以上）
• Linux/macOS/WSL2 操作系統
• 可選GPU（建議NVIDIA顯卡，顯存≥12GB）
• 40GB 以上磁盤空間（用於數據庫、Chroma向量和強化學習檢查點）

安裝依賴

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會員	6500元
3	王五	wangwu@example.com	SVIP會員	12000元

示例產品

• iPhone 15 Pro Max（9999元）
• iPhone 15 Pro（8999元）
• iPhone 15（5999元）
• AirPods Pro 2（1899元）
• 配件等

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/server.log（按日輪轉），若想恢復各腳本獨立日誌，運行前導出 DISABLE_SCRIPT_LOG_FILES=0
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用戶界面
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：啟動強化學習訓練儀表盤
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. 訪問用戶界面

訪問 http://127.0.0.1:7860。

界面標籤頁：

• 💬 計劃：聊天輸入框、AI回覆、推理計劃、即時狀態
• 🔧 工具調用：工具名稱/參數、時間戳、調用結果、錯誤信息
• 🧠 記憶：對話歷史列表、摘要、檢索控制、會話管理
• 🛍️ 電商分析：質量指標、意圖分析、對話狀態、推薦引擎
• 📋 執行日誌：完整的大語言模型輸入/輸出和工具調用跟蹤信息

記憶流程（Mermaid圖）

flowchart LR
  subgraph Ingest[攝入與存儲]
    direction TB
    U(用戶輸入)
    U --> AT(ChromaMemory.add_turn)
    AT --> SUM(生成摘要)
    SUM --> DB((ChromaDB集合))
    AT --> DB
  end

  subgraph Extract[提取]
    direction TB
    AT --> EX(用戶上下文提取器)
    EX --> UM(用戶上下文管理器)
  end

  subgraph Retrieval[檢索與注入]
    direction TB
    UM --> CTX(為提示獲取上下文)
    CTX --> NOTE_CTX(注入上下文和歷史記錄)
    NOTE_CTX --> AGT(智能體/大語言模型)
  end

  AGT --> TC(工具調用)
  TC --> AT
  TC -->|創建訂單生成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. 交互序列圖

完整對話的日誌驅動分段（推薦 → 多輪搜索 → 結賬 → 售後 → 分析）記錄在 中。每個部分都包含一個Mermaid序列圖和一個PNG快照，方便你將原始日誌、工具調用和用戶界面狀態對應起來。

8. 可選的強化學習循環

• 使用 scripts/generate_dialogue_corpus.py 生成最新的200個完全真實的場景
• 運行 python test_rl_modules.py 對強化學習模塊進行基本檢查
• 執行 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個）

1. ontology.explain_discount
2. ontology.normalize_product
3. 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

🧠 智能體架構

核心組件

1. ReAct智能體 (react_agent.py)

   • 基於LangChain的ReAct工作流（推理 + 行動）
   • 自動工具選擇和推理跟蹤
   • 支持多輪對話感知

2. 對話狀態 (conversation_state.py)

   • 8個階段：問候 → 瀏覽 → 選擇 → 購物車 → 結賬 → 跟蹤 → 服務 → 空閒
   • 跟蹤VIP狀態、購物車狀態、瀏覽歷史
   • 根據關鍵詞和工具使用情況自動檢測狀態轉換

3. 系統提示 (prompts.py)

   • 電商角色設定：專業、友好的購物顧問
   • 生成中文提示時使用禮貌的“您”語氣，避免使用系統術語
   • 確認有風險的操作（付款、取消訂單）
   • 鼓勵提出澄清問題，而非直接拒絕

4. 對話記憶 (chroma_memory.py)

   • 後端：ChromaDB
   • 檢索模式：最近、相似度、混合
   • 自動總結每一輪對話
   • 持久化存儲在 data/chroma_memory/

5. 質量跟蹤 (quality_metrics.py)

   • 對話質量評分（0 - 1）
   • 用戶滿意度估計
   • 工具效率和延遲跟蹤

6. 意圖跟蹤器 (intent_tracker.py)

   • 14種意圖（問候、搜索、查看購物車、結賬、跟蹤訂單等）
   • 置信度分數和歷史記錄

7. 推薦引擎 (recommendation_engine.py)

   • 個性化產品推薦
   • 使用瀏覽/購物車歷史和會員等級信息

🧠 強化學習（階段6）

硬件提示：PPO訓練建議使用≥8核CPU、≥32GB內存和≥1塊顯存≥12GB的GPU（如RTX 3080/4090/A6000）。僅使用CPU也可以進行訓練，但100K步可能需要5 - 8小時，而使用GPU則可將時間縮短至約1小時。請為 data/rl_training/ 預留≥15GB的磁盤空間。

目標與優勢

• 讓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	命令行入口	可配置訓練步數、評估頻率、檢查點、嵌入方式

場景語料庫 data/training_scenarios/sample_dialogues.json 包含200個真實對話，涉及5種場景類別下的真實用戶/訂單/產品。

閉環流程：數據 → 訓練 → 應用

1. 數據階段

   • 確保數據庫已填充數據：運行 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

2. 訓練

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"  # 若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/。

3. 評估與產物

• 最佳模型：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

4. 部署

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("強化學習建議的動作:", action_idx, action_name)

result = agent.run(query)
print(result["最終答案"])
PY

強化學習儀表盤（Gradio）

src/training_dashboard/ 提供了一個獨立的控制檯，支持語料庫聚合、訓練編排、指標可視化、模型管理和熱重載：

1. 將 config/training_dashboard.example.yaml 複製為 config/training_dashboard.yaml 並調整路徑
2. 運行 PYTHONPATH=src python scripts/run_training_dashboard.py 啟動儀表盤
3. 標籤頁：概述（即時狀態、獎勵/長度曲線、日誌）、語料庫管理（靜態/日誌混合）、訓練控制、模型管理

獎勵分解

• R_task：成功下單獎勵10分；缺少關鍵信息或回覆為空則扣分
• R_efficiency：工具調用次數少且延遲低則獎勵；調用次數過多則懲罰
• R_satisfaction：使用即時質量評分獎勵主動引導行為
• R_safety：初始值為+1；SHACL驗證失敗或使用不安全工具最多扣10分

調優提示

• 若資源允許，啟用 --use-text-embedding 以獲得更豐富的狀態表示
• 調整 PPOTrainer 中的 reward_weights 以平衡任務成功和安全性
• max_steps_per_episode：短回合用於頻繁評估；長回合用於完整購物流程

🏗️ 本體與架構

本體語義模型

系統定義了 12個核心業務實體，並明確了它們之間的關係和屬性：

核心交易實體

1. 用戶

   • 屬性：用戶ID、用戶名、郵箱、電話、用戶等級（普通會員/VIP會員/SVIP會員）、累計消費、信用評分
   • 操作：查詢用戶信息、用戶認證
   • 關係：創建訂單、擁有購物車商品、發起支持工單

2. 產品

   • 屬性：產品ID、產品名稱、類別、品牌、型號、價格、庫存數量、規格
   • 操作：搜索產品、獲取產品詳情、檢查庫存、獲取推薦、獲取評價
   • 關係：被購物車商品、訂單商品和評價引用

3. 購物車商品

   • 屬性：購物車ID、用戶ID、產品ID、數量、添加時間
   • 操作：添加到購物車、查看購物車、從購物車移除
   • 關係：關聯用戶和產品

4. 訂單

   • 屬性：訂單ID、訂單編號、總金額、折扣金額、最終金額、訂單狀態、支付狀態
   • 操作：創建訂單、獲取訂單詳情、取消訂單、獲取用戶訂單
   • 關係：包含訂單商品，生成支付和物流記錄
   • 本體推理：折扣金額根據用戶等級、訂單金額和首單狀態由本體規則計算得出

5. 訂單商品

   • 屬性：商品ID、訂單ID、產品ID、產品名稱、數量、單價、小計
   • 關係：訂單包含多個訂單商品，每個訂單商品引用一個產品

6. 支付

   • 屬性：支付ID、訂單ID、支付方式、支付金額、支付狀態、交易ID、支付時間
   • 操作：處理支付
   • 關係：由訂單生成
   • 注意：交易ID作為支付憑證

7. 物流

   • 屬性：物流ID、訂單ID、物流單號、承運商、當前狀態、當前位置、預計送達時間
   • 操作：跟蹤物流、獲取物流狀態
   • 關係：由訂單生成，記錄物流軌跡

8. 物流軌跡

   • 屬性：軌跡ID、物流ID、狀態、位置、描述、記錄時間
   • 關係：多個軌跡屬於一個物流記錄

客戶服務與售後實體

9. 支持工單

   • 屬性：工單ID、工單編號、用戶ID、訂單ID、類別、優先級、狀態、主題、描述
   • 操作：創建支持工單
   • 關係：用戶為訂單創建，包含支持消息

10. 支持消息

    • 屬性：消息ID、工單ID、發送者類型、發送者ID、消息內容、發送時間
    • 關係：多個消息屬於一個支持工單

11. 退貨

    • 屬性：退貨ID、退貨編號、訂單ID、用戶ID、退貨類型（退貨/換貨）、原因、狀態、退款金額
    • 操作：處理退貨
    • 關係：由訂單發起

12. 評價

    • 屬性：評價ID、產品ID、用戶ID、訂單ID、評分（1 - 5星）、內容、圖片
    • 操作：獲取產品評價
    • 關係：用戶對產品進行評價

架構圖

實體關係：

• 用戶 → 訂單 → 訂單商品 → 產品
• 訂單 → 購物車商品 → 產品
• 訂單 → 支付（支付金額、支付方式、交易ID）
• 訂單 → 物流 → 物流軌跡（位置、時間）
• 用戶/訂單 → 支持工單 → 支持消息
• 訂單 → 退貨（退貨編號、退貨類型、退款金額）
• 產品 → 評價（評分、內容）

本體推理：

• 折扣規則：VIP/SVIP會員折扣、批量折扣（≥5000/≥10000）、首單折扣
• 物流規則：滿500元免運費（或VIP/SVIP會員）、SVIP會員次日達、偏遠地區附加費
• 退貨政策：普通會員7天無理由退貨、VIP/SVIP會員15天無理由退貨、特定類別商品規則

MCP工具層：21個工具通過本體推理對12個實體進行操作 ReAct智能體：調用工具，通過強化學習（PPO模型、獎勵系統）進行優化

🎯 本體規則覆蓋情況

ontology_rules.ttl 中的規則在 ecommerce_ontology.py 中實現了100%覆蓋。

用戶等級規則（2條）

規則	觸發條件	方法
VIP升級規則	累計消費 ≥ 5000元	infer_user_level()
SVIP升級規則	累計消費 ≥ 10000元	infer_user_level()

折扣規則（5條）

規則	觸發條件	折扣	方法
VIP折扣規則	VIP用戶	95折	infer_discount()
SVIP折扣規則	SVIP用戶	9折	infer_discount()
5000元批量折扣規則	訂單金額 ≥ 5000元	95折	infer_discount()
10000元批量折扣規則	訂單金額 ≥ 10000元	9折	infer_discount()
首單折扣規則	首次購買用戶	98折	infer_discount()

會員折扣和批量折扣不疊加，取最優折扣。

物流規則（5條）

規則	觸發條件	物流費用	方法
滿500元免運費規則	訂單金額 ≥ 500元	0元標準運費	infer_shipping()
VIP/SVIP免運費規則	VIP/SVIP會員	0元標準運費	infer_shipping()
SVIP次日達規則	SVIP會員	0元次日達運費	infer_shipping()
普通會員不滿500元標準運費規則	普通會員訂單金額 < 500元	15元標準運費	infer_shipping()
偏遠地區附加費規則	偏遠地址	加收30元	infer_shipping()

退貨/換貨規則（5條）

規則	適用範圍	退貨期限	額外條件
普通會員7天無理由退貨規則	普通用戶	7天	無需理由
VIP/SVIP會員15天無理由退貨規則	VIP/SVIP會員	15天	無需理由
電子產品退貨規則	電子產品	按會員等級	設備未開封
配件退貨規則	配件	按會員等級	包裝完好
服務類商品不退貨規則	服務類商品	不適用	不可退貨

組合策略（2條）

策略	場景	行為
折扣疊加策略	存在多個折扣	選擇最優折扣
物流優先級策略	存在多種物流選項	應用優先級最高的選項

SHACL驗證

commerce_service.py 在創建訂單前調用SHACL驗證，以確保數據完整性，並記錄主要違規信息和三元組數量。

📊 Gradio用戶界面功能

• 💬 計劃：輸入框、AI回覆、推理計劃、即時狀態
• 🔧 工具調用：工具名稱/參數、時間戳、調用結果、錯誤信息
• 🧠 記憶：歷史記錄列表、摘要、檢索控制、會話管理
• 🛍️ 電商分析：質量指標、意圖分析、對話狀態、推薦引擎
• 📋 執行日誌：完整的大語言模型輸入/輸出和工具調用跟蹤信息

📚 文檔

• 階段3完成報告
• 階段4完成報告
• 記憶指南
• 記憶配置指南
• 執行日誌指南
• Gradio用戶界面指南
• 智能體使用指南

🧪 測試

source .venv/bin/activate
python test_memory_quick.py
python test_execution_log.py
python test_phase4_shopping.py
python test_phase4_advanced.py
python test_gradio_ecommerce.py
python test_rl_modules.py

pytest tests/
pytest tests/test_services.py
pytest tests/test_commerce_service.py
python train_rl_agent.py --timesteps 20000 --eval-freq 2000 --checkpoint-freq 5000

⚙️ 配置

環境變量

MCP / 數據根目錄

export ONTOLOGY_DATA_DIR="$(pwd)/data"
export APP_HOST=0.0.0.0
export APP_PORT=8000

本體開關（config.yaml）

ontology:
   use_owlready2: true  # 默認啟用，可通過 config.yaml 修改

如需在運行時臨時關閉，可設置 ONTOLOGY_USE_OWLREADY2=false 環境變量覆蓋上述配置。

智能體與大語言模型（LLM）

export MCP_BASE_URL="http://127.0.0.1:8000"
export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"
export LLM_PROVIDER="deepseek"

Gradio服務

export GRADIO_SERVER_NAME=0.0.0.0
export GRADIO_SERVER_PORT=7860
export AGENT_HOST=0.0.0.0
export AGENT_PORT=7860
export TRAINING_DASHBOARD_HOST=0.0.0.0
export TRAINING_DASHBOARD_PORT=7861
export LOG_DIR="$(pwd)/logs"
export TB_LOG_DIR="$(pwd)/data/rl_training/logs/tensorboard"
export TB_HOST=0.0.0.0
export TB_PORT=6006

# 統一日誌輸出
export ONTOLOGY_SERVER_LOG_DIR="$(pwd)/logs"   # 默認也是 repo/logs
# 設為 0 可恢復各 run_*.sh 生成單獨 log 文件
export DISABLE_SCRIPT_LOG_FILES=1

強化學習輔助配置

export TRAIN_DEVICE=gpu
export RL_OUTPUT_DIR="$(pwd)/data/rl_training"

記憶管理

export MEMORY_ENABLED=true
export MEMORY_BACKEND=chromadb
export CHROMA_PERSIST_DIR="data/chroma_memory"
export MEMORY_RETRIEVAL_MODE=recent
export MEMORY_MAX_TURNS=10

config.yaml 示例

完整配置選項見 src/agent/config.yaml（支持DeepSeek/Ollama、記憶管理、智能體開關）。

🗄️ 數據庫架構

SQLite數據庫 data/ecommerce.db 包含12個表：

• users、products、cart_items、orders、order_items
• payments、shipments、shipment_tracks
• support_tickets、support_messages、returns、reviews

🎯 使用場景

1. 搜索與推薦：commerce.search_products 結合推薦引擎
2. 完整購買流程：瀏覽 → 選擇 → 購物車 → 結賬 → 支付 → 跟蹤
3. 訂單管理：commerce.get_user_orders、取消/退貨流程
4. 本體推理：ontology.explain_discount 用於上下文相關的折扣解釋

🤝 貢獻代碼

1. Fork本項目
2. 創建新分支：git checkout -b feature/AmazingFeature
3. 提交代碼：git commit -m 'Add some AmazingFeature'
4. 推送分支：git push origin feature/AmazingFeature
5. 打開Pull Request

🏷️ 版本亮點

v1.5.3 (2025-12-01) — 確認記憶與完整工具跟蹤

• 確認模式持久化：用戶批准關鍵工具（創建訂單/支付）後，運行過程會將清理後的參數和觀察結果寫回 tool_log、記憶和對話狀態，使下一回合能看到已完成的訂單，避免再次進入結賬流程
• 驗證防護硬停止：ontology_validate_order 被標記為關鍵工具，提醒信息會阻止最終回覆，直到SHACL驗證完成，訂單確認後智能體現在會主動提示用戶繼續支付
• 端到端工具透明度：流式事件會傳輸完整的觀察負載，Gradio用戶界面不再截斷JSON數據，大大方便了審計和調試
• 新領域報告：新增 文檔，記錄與記憶相關的經驗教訓（包含英文和中文索引），幫助未來貢獻者避免迴歸問題

v1.5.2 (2025-11-29) — 流式跟蹤基線 ✅

• 真正的流式管道：react_agent.py 現在提供基於生成器的 run_stream 方法，DeepSeek適配器發出令牌增量，Gradio用戶界面逐令牌渲染思考過程和最終答案（提交記錄：505b39e → 7c99e84 → aab0956）
• 搜索準確性提升：可配置的多策略意圖跟蹤器、基於大語言模型的查詢重寫器、FTS5全文索引 + 混合回退策略（FTS5 → LIKE → 類別）顯著提高了通用查詢（如 “電子產品”）的準確性
• 可追溯性工具： 使用Mermaid圖和PNG證據記錄每個對話回合（推薦 → 多輪搜索 → 結賬 → 售後 → 分析），兩個README文件現在都指向該文檔。標籤 v1.5.2 標誌著下游強化學習實驗的新基線

v1.5.1 (2025-11-23)

• 內聯圖表（Markdown + Base64 PNG），包含意圖/用戶上下文元數據和 _filter_charts_by_intent() 隱私保護功能
• analytics_service.py 提供五個圖表數據端點和 analytics_get_chart_data MCP工具（第22個功能）
• 依賴對齊：plotly>=6.1.0,<7.0.0、kaleido==0.2.1；診斷腳本（verify_chart_fix.py、test_chart_feature.py）和數據/日誌備份
• 訓練儀表盤用戶體驗改進：點擊預覽語料庫、同步JSON視圖、多實例調試的主機/端口日誌

v1.2.3 (2025-11-15) — 重命名與致謝

• 項目更名為 本體強化學習電商智能體；記錄強化學習相關上下文
• 新增對Stable Baselines3/Gymnasium/TensorBoard等的致謝
• 工具改進：訂單ID驗證，避免 OverflowError；支持Ollama的 qwen3:8b 模型

v1.2.2 (2025-11-12) — README強化學習指南

• 在README開頭添加了強化學習閉環描述，強調數據 → 訓練 → TensorBoard → 部署流程

v1.2.0 (2025-11-11) — 動態用戶上下文系統

• 自動提取用戶ID、電話號碼、地址、訂單ID、產品ID
• 提示注入確保對話連續性；正則表達式引擎處理多語言/多寬度變體
• 基於集合的去重，嚴格的 ORD... 驗證，產品ID範圍保護
• 測試：tests/test_user_context.py

v1.2.1 (2025-11-11) — 近期訂單跟蹤熱修復

• create_order 現在強制解析有效 ORD... ID的觀察/輸入，調用 set_recent_order()

v1.1.0 (2025-11-10) — Gradio用戶界面增強

• 十個快速測試按鈕（本體和SHACL操作）
• 流式響應、主動按鈕狀態管理、生成器修復

v1.0.0 (2025-11-08) — 訂單驗證基線

• 訂單創建前自動進行SHACL驗證；詳細的違規日誌記錄
• 提示改進和100%規則覆蓋（折扣/物流/退貨/組合）

基礎版本 (2025-10)

• 完成階段1 - 5：ORM、本體、21個工具、ReAct智能體、Gradio用戶界面

📦 版本歷史

版本	日期	亮點	下載
v1.5.3	2025-12-01	確認模式持久化、驗證防護硬停止、完整工具負載流式傳輸、新的記憶經驗教訓文章	git checkout v1.5.3
v1.5.2	2025-11-29	流式生成器管道、意圖/查詢/搜索升級、日誌驅動的圖表 + 基線標籤	git checkout v1.5.2
v1.5.1	2025-11-23	內聯圖表流式傳輸、分析MCP工具、儀表盤用戶體驗升級	git checkout v1.5.1
v1.5.0	2025-11-20	強化學習閉環、Docker/Compose打包、5標籤Gradio用戶界面	git checkout v1.5.0
v1.0.0	2025-10	階段1 - 3基線（本體 + 工具 + 智能體）	git checkout v1.0.0

📝 更新日誌

2025-12-01

• 確認循環持久化：確認分支現在將每個執行的工具（參數 + 觀察結果）推回 tool_log、記憶和 ConversationState，使後續回合能立即看到已完成的訂單，而無需重新運行結賬流程
• 強制SHACL驗證：ontology_validate_order 加入 CRITICAL_TOOLS 列表，提醒信息會阻止最終回覆，直到驗證完成；訂單確認後，智能體主動詢問是否繼續支付
• 聊天中顯示完整工具輸出：流式事件現在包含完整的JSON觀察結果，Gradio用戶界面不再截斷長負載，使審計和調試變得簡單
• 新的經驗教訓文檔：發佈 docs/articles/12-memory-intent-lessons.md，記錄使用記憶進行意圖檢測和推理的實際注意事項

2025-11-30

• 本體優先推理覆蓋：ecommerce_ontology.py 現在優先加載 ontology_rules.ttl 用於折扣、物流、退貨、取消四大流程，命中規則時返回 rule_applied，無匹配才退回靜態策略；對應 tests/test_commerce_service.py、tests/test_services.py 已通過全量pytest
• 日誌統一與按日輪轉：所有Python模塊寫入 logs/server.log（日切 + server_YYYYMMDD.log 歸檔），start_all.sh 默認設置 DISABLE_SCRIPT_LOG_FILES=1 防止重複日誌，如需舊行為可手動置0；新增 ONTOLOGY_SERVER_LOG_DIR/ONTOLOGY_LOG_BACKUP_COUNT 控制輸出目錄與留存天數
• 本體資產清理：ontology_commerce.ttl 和 ontology_ecommerce.ttl 補齊SWRL前綴、變量、折扣實體與規則，使Owlready2/外部引擎讀取更穩定；README/配置章節同步記錄新的日誌變量與使用方式

2025-11-29

• 真正的流式循環：react_agent.py 現在提供基於生成器的 run_stream 方法，DeepSeek適配器發出令牌增量，Gradio用戶界面逐令牌渲染思考過程和最終答案，實現透明的推理回放
• 意圖 + 檢索棧：可配置的多策略意圖跟蹤器、基於大語言模型的 query_rewriter.py 以及 commerce_service.py/db_service.py 中的FTS5→LIKE→類別回退策略，在保留小眾意圖召回率的同時，大大提高了通用查詢（如 “電子產品”）的準確性
• 可追溯文檔： 使用Mermaid圖和PNG證據記錄五個基於日誌的序列，README文件鏈接到該文檔，標籤 v1.5.2 標誌著版本歷史表中的新基線

詳細的中文更新日誌見 README.zh.md（與英文亮點對應）。

🙏 致謝

• LangChain & FastAPI – ReAct智能體編排 + MCP服務器
• Gradio – 五標籤電商用戶界面框架
• ChromaDB & SQLite – 語義記憶 + 電商數據存儲
• Stable Baselines3 / Gymnasium / TensorBoard – 強化學習訓練與可視化
• DeepSeek – 大語言模型提供商
• RDFLib & PySHACL – 本體推理 + SHACL驗證
• SQLAlchemy – ORM基礎

🧩 案例研究

• 場景：預算20萬元的VIP買家要求智能體 “花光預算” 購買最貴的手機，涵蓋洞察 → 推薦 → 購物車 → 支付 → 售後跟蹤
• 亮點：16步記憶鏈、22個MCP工具（6次本體調用、2次SHACL檢查）、動態圖表、自動VIP折扣、購物車 + 結賬編排
• 完整流程：

📖 引用

@software{ontology_rl_commerce_agent_2025,
  author  = {Shark8848},
  title   = {Ontology RL Commerce Agent},
  year    = {2025},
  url     = {https://github.com/shark8848/ontology-mcp-server-RL-Stable-Baselines3},
  version = {v1.2.3}
}

📄 許可證

本項目採用 MIT許可證 發佈。簡體中文參考翻譯見 LICENSE.zh.md。

📧 聯繫我們

作者：shark8848@gmail.com — 如果本項目對你有幫助，請給倉庫點個星！