Hugging Face's logo

Spaces:
mickeywu520
/
linebot_pydantic_fastapi
Sleeping

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

LineBot 操作指南

🤖 系統概述

本 LineBot 系統整合了 Pydantic AI 框架，提供智能商品查詢、聊天和業務查詢功能。系統設計考慮了 LINE 群組使用場景，避免不必要的 AI token 消耗。

📱 用戶操作指南

基本指令

1. 聊天模式 

/chat 你好！今天天氣如何？
/chat 推薦一些好用的功能
  • 用途：一般對話、問候、非業務相關問題
  • 適用場景：群組聊天、客戶服務
  • AI 服務：使用 Groq 進行自然對話

2. 商品查詢模式 

/search iPhone 15 Pro
/search 價格 1000-5000
/search 庫存不足的商品
  • 用途：傳統的商品搜尋和業務查詢
  • 適用場景：明確的商品查詢需求
  • 查詢範圍：商品、訂單、庫存、客戶資料

3. 幫助指令 

/help
幫助
說明
  • 用途：顯示系統使用說明
  • 回應：完整的功能介紹和使用範例

智能模式（無前綴）

商品推薦查詢 

是否有推薦貓砂？
有什麼狗糧推薦？
推薦一些寵物用品
  • 特點：自動識別推薦意圖
  • 回應：智能推薦相關商品，包含庫存資訊
  • 優勢：更自然的對話方式

庫存查詢 

查詢iPhone庫存
寵物用品還有多少？
低庫存商品有哪些？
  • 特點：自動識別庫存查詢意圖
  • 回應：詳細的庫存狀態和警告提醒

一般對話 

你好！
今天天氣如何？
謝謝你的幫助
  • 特點：自動識別為聊天意圖
  • 回應：友善的對話回應

🏢 管理員操作指南

系統監控

1. 健康檢查 

curl http://localhost:7860/health

回應內容：

  • 系統狀態
  • 資料庫連線狀態
  • 資料庫連線資訊

2. 路由統計

在 LINE 中輸入：統計 或 stats

統計內容：

  • 各模式使用次數和百分比
  • Groq 服務狀態
  • Pydantic AI 服務狀態

API 端點管理

1. 直接聊天 API 

curl -X POST "http://localhost:7860/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "今天天氣如何？",
    "user_id": "admin_user"
  }'

2. 直接搜尋 API 

curl -X POST "http://localhost:7860/search" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "iPhone 15",
    "user_id": "admin_user"
  }'

3. 商品查詢 API 

curl -X POST "http://localhost:7860/product-query" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "是否有推薦貓砂？",
    "user_id": "admin_user"
  }'

4. 智能路由 API 

curl -X POST "http://localhost:7860/route" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "有什麼狗糧推薦？",
    "user_id": "admin_user"
  }'

系統配置

環境變數檢查 

# 檢查必要的環境變數
echo $GROQ_API_KEY
echo $DB_HOST
echo $LINE_CHANNEL_ACCESS_TOKEN

服務狀態檢查 

# 在 Python 中檢查服務狀態
from backend.services.pydantic_ai_service import ProductQueryService
from backend.services.groq_service import GroqService

product_service = ProductQueryService()
groq_service = GroqService()

print(f"Pydantic AI 可用: {product_service.is_available()}")
print(f"Groq 服務可用: {groq_service.is_available()}")

🔧 故障排除

常見問題

1. 商品查詢沒有結果

可能原因：

  • 資料庫中沒有相關商品
  • 關鍵字匹配不準確
  • 商品被標記為已刪除

解決方案：

  • 檢查資料庫商品資料
  • 嘗試使用不同的關鍵字
  • 使用 /search 進行傳統查詢

2. Pydantic AI 服務不可用

錯誤訊息：「商品查詢服務暫時無法使用」

解決方案：

  • 檢查 GROQ_API_KEY 環境變數
  • 確認 Groq API 配額
  • 系統會自動降級到傳統搜尋

3. 資料庫連線失敗

錯誤訊息：「資料庫連線測試失敗」

解決方案：

  • 檢查資料庫連線參數
  • 確認資料庫服務運行狀態
  • 檢查網路連線

日誌查看

應用程式日誌 

# 查看即時日誌
tail -f app.log

# 搜尋特定錯誤
grep "ERROR" app.log
grep "商品查詢錯誤" app.log

特定功能日誌 

# Pydantic AI 相關
grep "Pydantic AI" app.log

# 路由統計
grep "智能路由" app.log

# 資料庫查詢
grep "資料庫" app.log

📊 效能監控

API 回應時間

  • 聊天模式：通常 1-3 秒
  • 商品查詢：通常 2-5 秒
  • 智能路由：通常 1-4 秒

資源使用

  • 記憶體：約 200-500MB
  • CPU：低負載時 < 10%
  • 網路：主要是 API 調用

Token 使用監控

  • 監控 Groq API 使用量
  • 設定使用量警告
  • 考慮實施使用限制

🚀 部署指南

開發環境 

# 1. 安裝依賴
pip install -r requirements.txt

# 2. 設定環境變數
cp .env.example .env
# 編輯 .env 文件

# 3. 運行測試
python test_pydantic_ai_integration.py

# 4. 啟動服務
uvicorn backend.main:app --host 0.0.0.0 --port 7860

生產環境 

# 使用 Docker
docker build -t linebot-pydantic .
docker run -p 7860:7860 --env-file .env linebot-pydantic

# 或使用 Docker Compose
docker-compose up -d

LINE Webhook 設定

  1. 在 LINE Developers Console 設定 Webhook URL
  2. URL 格式：https://your-domain.com/webhook
  3. 確認 SSL 憑證有效

📋 維護檢查清單

每日檢查

  • 系統健康狀態
  • API 回應時間
  • 錯誤日誌
  • Groq API 使用量

每週檢查

  • 路由統計分析
  • 資料庫效能
  • 商品資料更新
  • 用戶回饋收集

每月檢查

  • 系統效能評估
  • 功能使用分析
  • 安全性檢查
  • 備份驗證

📞 支援聯絡

技術問題

  • 檢查日誌文件
  • 參考故障排除指南
  • 聯絡系統管理員

功能建議

  • 記錄用戶需求
  • 評估實施可行性
  • 規劃功能更新

版本：v1.0
更新日期：2025-01-12
維護團隊：開發團隊