🚀 OpenRouter 整合文件

📋 概述

本專案已整合 OpenRouter API 來提供進階的自然語言處理功能，包括：

更精確的意圖識別
智能實體提取
自然的回應生成

🔧 設定方式

1. 取得 OpenRouter API Key

前往 OpenRouter 官網
註冊帳號並登入
前往 API Keys 頁面
建立新的 API Key
複製 API Key 備用

2. 環境變數設定

在 Hugging Face Spaces 的 Settings 中新增以下環境變數：

# 必要設定
OPENROUTER_API_KEY=your_openrouter_api_key_here

# 可選設定 (預設值已設定)
OPENROUTER_MODEL=anthropic/claude-3-haiku

3. 支援的模型

OpenRouter 支援多種 AI 模型，您可以根據需求選擇：

高性能模型

anthropic/claude-3-sonnet - 更好的理解能力
openai/gpt-4 - 最佳性能
anthropic/claude-3-opus - 最高品質

設定範例

# 使用 GPT-3.5 Turbo
OPENROUTER_MODEL=openai/gpt-3.5-turbo

# 使用 Claude 3 Sonnet
OPENROUTER_MODEL=anthropic/claude-3-sonnet

🎯 功能特色

1. 進階意圖識別

OpenRouter 整合後，系統能更準確地識別用戶意圖：

# 範例輸入
"幫我找一下價格在一千到五千之間的手機"

# 基礎 NLP (規則引擎)
{
    "intent": "search_product",
    "confidence": 0.6,
    "entities": {"min_price": 1000, "max_price": 5000}
}

# 進階 NLP (OpenRouter)
{
    "intent": "search_product",
    "confidence": 0.9,
    "entities": {
        "min_price": 1000,
        "max_price": 5000,
        "category": "手機",
        "product_type": "電子產品"
    }
}

2. 智能回應生成

系統會根據查詢結果生成更自然的回應：

# 基礎回應
"找到 3 筆商品資料。"

# 進階回應 (OpenRouter)
"我為您找到了 3 款符合條件的手機：
1. iPhone 15 Pro - NT$ 35,900
2. Samsung Galaxy S24 - NT$ 28,900  
3. Google Pixel 8 - NT$ 24,900

這些都在您的預算範圍內，您想了解哪一款的詳細資訊呢？"

🔄 降級機制

系統具有完整的降級機制：

優先使用 OpenRouter: 如果 API Key 可用且正常運作
自動降級: 如果 OpenRouter 失敗，自動使用基礎規則引擎
錯誤處理: 完整的錯誤日誌和異常處理

# 在程式碼中的實作
def analyze_message(self, message: str, use_advanced: bool = True):
    if use_advanced and self.openrouter_service.api_key:
        try:
            # 嘗試使用 OpenRouter
            return advanced_analysis
        except Exception as e:
            logger.warning(f"進階 NLP 分析失敗，使用基礎分析: {str(e)}")
    
    # 降級到基礎規則引擎
    return basic_analysis

💰 成本考量

模型成本比較 (每 1M tokens)

模型	輸入成本	輸出成本	適用場景
claude-3-haiku	$0.25	$1.25	日常查詢
gpt-3.5-turbo	$0.50	$1.50	平衡使用
claude-3-sonnet	$3.00	$15.00	複雜查詢
gpt-4	$10.00	$30.00	高精度需求

成本優化建議

使用 claude-3-haiku 作為預設模型 (成本最低)
設定合理的 token 限制 (max_tokens: 300-500)
監控使用量 透過 OpenRouter Dashboard
考慮快取機制 對常見查詢進行快取

🛠️ 開發與測試

本地測試

# 設定環境變數
export OPENROUTER_API_KEY="your_key_here"
export OPENROUTER_MODEL="anthropic/claude-3-haiku"

# 執行測試
python test_api.py

API 測試範例

# 測試進階 NLP
from backend.services.openrouter_service import OpenRouterService

service = OpenRouterService()
result = await service.analyze_intent_advanced("查詢用戶張三的訂單")
print(result)

🔍 監控與除錯

日誌監控

系統會記錄以下資訊：

# 成功使用 OpenRouter
logger.info("使用 OpenRouter 進行進階分析")

# 降級到基礎引擎
logger.warning("進階 NLP 分析失敗，使用基礎分析")

# API 錯誤
logger.error("OpenRouter API 錯誤: 401 Unauthorized")

常見問題

API Key 無效
- 檢查 API Key 是否正確
- 確認 OpenRouter 帳戶餘額
模型不存在
- 檢查模型名稱是否正確
- 參考 OpenRouter 模型列表
請求超時
- 檢查網路連線
- 考慮增加 timeout 設定

📈 效能優化

1. 異步處理

# 使用 asyncio 避免阻塞
async def analyze_intent_advanced(self, message: str):
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.post(...)

2. 錯誤重試

# 實作重試機制
for attempt in range(3):
    try:
        result = await openrouter_request()
        break
    except Exception as e:
        if attempt == 2:
            raise e
        await asyncio.sleep(1)

3. 快取策略

# 快取常見查詢結果
@lru_cache(maxsize=100)
def cached_analysis(message_hash: str):
    return analysis_result

🚀 進階功能

1. 自訂提示詞

您可以修改 openrouter_service.py 中的提示詞來優化特定領域的表現：

def _build_analysis_prompt(self, message: str):
    # 自訂您的提示詞
    prompt = f"""
    您是一個專業的電商客服助手...
    """

2. 多語言支援

# 支援多語言分析
def analyze_message_multilingual(self, message: str, language: str = "zh"):
    prompt = self._build_multilingual_prompt(message, language)

3. 上下文記憶

# 維護對話上下文
def analyze_with_context(self, message: str, conversation_history: List[str]):
    context = {"history": conversation_history}
    return await self.analyze_intent_advanced(message, context)

📞 技術支援

如果您在整合 OpenRouter 時遇到問題：

檢查 OpenRouter 文件
查看系統日誌檔案
參考本專案的 test_api.py 進行測試
確認環境變數設定正確

注意: OpenRouter 是付費服務，請根據您的使用量選擇適合的模型和方案。

Spaces:

mickeywu520
/

linebot_pydantic_fastapi

Sleeping