Hugging Face's logo

Spaces:
mickeywu520
/
linebot_pydantic_fastapi
Sleeping

App Files Community
linebot_pydantic_fastapi / PYDANTIC_AI_INTEGRATION.md
mickeywu520's picture
mickeywu520
整合 Pydantic AI 框架並優化專案結構
7e828dc
preview code
|
raw
history blame contribute delete
5.67 kB

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. 智能意圖識別 

# 自動識別商品查詢意圖
"是否有推薦貓砂?" → 商品推薦查詢 (信心度: 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 使用範例 

# 商品查詢 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"
  }'

⚙️ 配置要求

環境變數 

# 必需
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

依賴安裝 

pip install -r requirements.txt

🧪 測試

運行測試腳本 

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