| # Pydantic AI 整合說明文件 | |
| ## 📋 概述 | |
| 本次更新整合了 Pydantic AI 框架到 LineBot 專案中，主要解決商品查詢準確性問題，特別是像 "是否有推薦貓砂?" 這類自然語言查詢。 | |
| ## 🎯 解決的問題 | |
| ### 原有問題 | |
| - 用戶詢問 "是否有推薦貓砂?" 時，系統常常回答沒有相關資訊 | |
| - 商品查詢意圖識別不準確 | |
| - 缺乏智能推薦功能 | |
| ### 解決方案 | |
| - 整合 Pydantic AI 框架，提供更精確的意圖識別 | |
| - 移植 inventory 專案的查詢功能，增強商品搜尋能力 | |
| - 新增智能商品推薦系統 | |
| ## 🔧 技術架構變更 | |
| ### 新增組件 | |
| 1. **Pydantic AI 服務** (`backend/services/pydantic_ai_service.py`) | |
| - 商品查詢意圖分析 | |
| - 智能推薦系統 | |
| - 結構化輸出驗證 | |
| 2. **增強商品服務** (`backend/services/enhanced_product_service.py`) | |
| - 進階商品搜尋 | |
| - 商品推薦功能 | |
| - 庫存狀態分析 | |
| 3. **新增依賴** | |
| - `pydantic-ai[groq]`: Pydantic AI 框架 | |
| ### 修改組件 | |
| 1. **訊息路由器** (`backend/services/message_router.py`) | |
| - 新增商品查詢路由邏輯 | |
| - 整合 Pydantic AI 意圖分析 | |
| - 保留原有 `/chat` 和 `/search` 功能 | |
| 2. **主應用** (`backend/main.py`) | |
| - 新增 `/product-query` API 端點 | |
| ## 🚀 功能特性 | |
| ### 1. 智能意圖識別 | |
| ```python | |
| # 自動識別商品查詢意圖 | |
| "是否有推薦貓砂?" → 商品推薦查詢 (信心度: 0.8) | |
| "有什麼狗糧推薦?" → 商品推薦查詢 (信心度: 0.9) | |
| "查詢iPhone庫存" → 庫存查詢 (信心度: 0.7) | |
| ``` | |
| ### 2. 智能商品推薦 | |
| - 基於關鍵字的商品匹配 | |
| - 優先顯示有庫存的商品 | |
| - 提供推薦原因說明 | |
| ### 3. 增強的庫存資訊 | |
| - 實時庫存狀態顯示 | |
| - 庫存警告提醒 | |
| - 緊急程度分級 | |
| ## 📱 使用指南 | |
| ### LINE Bot 使用方式 | |
| #### 1. 指令模式（原有功能保留） | |
| ``` | |
| /chat 今天天氣如何？ # 聊天模式 | |
| /search iPhone 15 Pro # 商品查詢模式 | |
| /help # 顯示幫助 | |
| ``` | |
| #### 2. 智能模式（新增功能） | |
| 直接輸入訊息，系統自動判斷意圖： | |
| ``` | |
| 是否有推薦貓砂？ # → 智能商品推薦 | |
| 有什麼狗糧推薦？ # → 智能商品推薦 | |
| 查詢寵物用品庫存 # → 庫存查詢 | |
| iPhone 還有庫存嗎？ # → 庫存查詢 | |
| 你好！ # → 聊天模式 | |
| ``` | |
| ### API 端點 | |
| #### 1. 原有端點（保留） | |
| - `POST /chat`: 直接聊天 | |
| - `POST /search`: 直接搜尋 | |
| - `POST /route`: 智能路由 | |
| #### 2. 新增端點 | |
| - `POST /product-query`: 專門的商品查詢 | |
| ### API 使用範例 | |
| ```bash | |
| # 商品查詢 API | |
| curl -X POST "http://localhost:7860/product-query" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "message": "是否有推薦貓砂？", | |
| "user_id": "test_user" | |
| }' | |
| # 智能路由 API | |
| curl -X POST "http://localhost:7860/route" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "message": "有什麼狗糧推薦？", | |
| "user_id": "test_user" | |
| }' | |
| ``` | |
| ## ⚙️ 配置要求 | |
| ### 環境變數 | |
| ```env | |
| # 必需 | |
| GROQ_API_KEY=your_groq_api_key_here | |
| DB_HOST=your_database_host | |
| DB_NAME=your_database_name | |
| DB_USER=your_database_user | |
| DB_PASSWORD=your_database_password | |
| # LINE Bot (如果使用) | |
| LINE_CHANNEL_ACCESS_TOKEN=your_line_token | |
| LINE_CHANNEL_SECRET=your_line_secret | |
| ``` | |
| ### 依賴安裝 | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| ## 🧪 測試 | |
| ### 運行測試腳本 | |
| ```bash | |
| python test_pydantic_ai_integration.py | |
| ``` | |
| ### 測試案例 | |
| 1. 商品推薦查詢 | |
| 2. 庫存查詢 | |
| 3. 意圖分析準確性 | |
| 4. 路由統計 | |
| ## 📊 路由統計 | |
| 系統會追蹤各種路由模式的使用情況： | |
| - 💬 聊天模式 | |
| - 🔍 搜尋模式 | |
| - 🛍️ 商品查詢（新增） | |
| - 🧠 智能路由 | |
| - ❓ 幫助模式 | |
| - ❌ 錯誤次數 | |
| 查看統計：輸入 `統計` 或 `stats` | |
| ## 🔄 路由邏輯 | |
| ``` | |
| 用戶訊息 | |
| ↓ | |
| 是否有前綴？ | |
| ├─ /chat → 聊天模式 | |
| ├─ /search → 搜尋模式 | |
| ├─ /help → 幫助模式 | |
| └─ 無前綴 → 智能路由 | |
| ↓ | |
| Pydantic AI 意圖分析 | |
| ↓ | |
| 商品查詢？(信心度>0.6) | |
| ├─ 是 → 商品查詢模式 | |
| └─ 否 → 關鍵字分析 | |
| ↓ | |
| 搜尋關鍵字？ | |
| ├─ 是 → 搜尋模式 | |
| └─ 否 → 聊天模式 | |
| ``` | |
| ## 🚨 注意事項 | |
| ### LINE 群組使用 | |
| - **保留前綴設計**：在群組中使用 `/chat` 和 `/search` 前綴，避免所有訊息都觸發 AI | |
| - **智能路由**：只在私聊或明確需要時使用無前綴訊息 | |
| ### 效能考量 | |
| - Pydantic AI 查詢會消耗 Groq API token | |
| - 建議在生產環境中監控 API 使用量 | |
| - 可以調整意圖識別的信心度閾值 | |
| ### 錯誤處理 | |
| - 當 Pydantic AI 不可用時，會自動降級到原有的搜尋功能 | |
| - 完整的錯誤日誌記錄 | |
| ## 📈 預期效果 | |
| ### 查詢準確性提升 | |
| - **之前**：「是否有推薦貓砂？」→ 沒有相關資訊 | |
| - **現在**：「是否有推薦貓砂？」→ 顯示貓砂商品列表，包含庫存狀態 | |
| ### 用戶體驗改善 | |
| - 更自然的對話方式 | |
| - 智能推薦功能 | |
| - 詳細的庫存資訊 | |
| ### 系統可維護性 | |
| - 模組化設計 | |
| - 完整的測試覆蓋 | |
| - 清晰的錯誤處理 | |
| ## 🔮 未來擴展 | |
| 1. **多語言支援**：擴展到英文查詢 | |
| 2. **個人化推薦**：基於用戶歷史的推薦 | |
| 3. **語音查詢**：整合語音識別 | |
| 4. **圖片查詢**：支援商品圖片搜尋 | |
| --- | |
| **版本**：v1.0 | |
| **更新日期**：2025-01-12 | |
| **作者**：Augment Agent | |