PYDANTIC_AI_INTEGRATION.md

# 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