| # 🚀 OpenRouter 整合文件 | |
| ## 📋 概述 | |
| 本專案已整合 OpenRouter API 來提供進階的自然語言處理功能，包括： | |
| - 更精確的意圖識別 | |
| - 智能實體提取 | |
| - 自然的回應生成 | |
| ## 🔧 設定方式 | |
| ### 1. 取得 OpenRouter API Key | |
| 1. 前往 [OpenRouter 官網](https://openrouter.ai/) | |
| 2. 註冊帳號並登入 | |
| 3. 前往 [API Keys 頁面](https://openrouter.ai/keys) | |
| 4. 建立新的 API Key | |
| 5. 複製 API Key 備用 | |
| ### 2. 環境變數設定 | |
| 在 Hugging Face Spaces 的 Settings 中新增以下環境變數： | |
| ```bash | |
| # 必要設定 | |
| OPENROUTER_API_KEY=your_openrouter_api_key_here | |
| # 可選設定 (預設值已設定) | |
| OPENROUTER_MODEL=anthropic/claude-3-haiku | |
| ``` | |
| ### 3. 支援的模型 | |
| OpenRouter 支援多種 AI 模型，您可以根據需求選擇： | |
| #### 推薦模型 (成本效益佳) | |
| - `anthropic/claude-3-haiku` (預設) - 快速、便宜 | |
| - `openai/gpt-3.5-turbo` - 平衡性能與成本 | |
| - `meta-llama/llama-2-70b-chat` - 開源選項 | |
| #### 高性能模型 | |
| - `anthropic/claude-3-sonnet` - 更好的理解能力 | |
| - `openai/gpt-4` - 最佳性能 | |
| - `anthropic/claude-3-opus` - 最高品質 | |
| #### 設定範例 | |
| ```bash | |
| # 使用 GPT-3.5 Turbo | |
| OPENROUTER_MODEL=openai/gpt-3.5-turbo | |
| # 使用 Claude 3 Sonnet | |
| OPENROUTER_MODEL=anthropic/claude-3-sonnet | |
| ``` | |
| ## 🎯 功能特色 | |
| ### 1. 進階意圖識別 | |
| OpenRouter 整合後，系統能更準確地識別用戶意圖： | |
| ```python | |
| # 範例輸入 | |
| "幫我找一下價格在一千到五千之間的手機" | |
| # 基礎 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. 智能回應生成 | |
| 系統會根據查詢結果生成更自然的回應： | |
| ```python | |
| # 基礎回應 | |
| "找到 3 筆商品資料。" | |
| # 進階回應 (OpenRouter) | |
| "我為您找到了 3 款符合條件的手機： | |
| 1. iPhone 15 Pro - NT$ 35,900 | |
| 2. Samsung Galaxy S24 - NT$ 28,900 | |
| 3. Google Pixel 8 - NT$ 24,900 | |
| 這些都在您的預算範圍內，您想了解哪一款的詳細資訊呢？" | |
| ``` | |
| ## 🔄 降級機制 | |
| 系統具有完整的降級機制： | |
| 1. **優先使用 OpenRouter**: 如果 API Key 可用且正常運作 | |
| 2. **自動降級**: 如果 OpenRouter 失敗，自動使用基礎規則引擎 | |
| 3. **錯誤處理**: 完整的錯誤日誌和異常處理 | |
| ```python | |
| # 在程式碼中的實作 | |
| 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 | 高精度需求 | | |
| ### 成本優化建議 | |
| 1. **使用 claude-3-haiku** 作為預設模型 (成本最低) | |
| 2. **設定合理的 token 限制** (max_tokens: 300-500) | |
| 3. **監控使用量** 透過 OpenRouter Dashboard | |
| 4. **考慮快取機制** 對常見查詢進行快取 | |
| ## 🛠️ 開發與測試 | |
| ### 本地測試 | |
| ```bash | |
| # 設定環境變數 | |
| export OPENROUTER_API_KEY="your_key_here" | |
| export OPENROUTER_MODEL="anthropic/claude-3-haiku" | |
| # 執行測試 | |
| python test_api.py | |
| ``` | |
| ### API 測試範例 | |
| ```python | |
| # 測試進階 NLP | |
| from backend.services.openrouter_service import OpenRouterService | |
| service = OpenRouterService() | |
| result = await service.analyze_intent_advanced("查詢用戶張三的訂單") | |
| print(result) | |
| ``` | |
| ## 🔍 監控與除錯 | |
| ### 日誌監控 | |
| 系統會記錄以下資訊： | |
| ```python | |
| # 成功使用 OpenRouter | |
| logger.info("使用 OpenRouter 進行進階分析") | |
| # 降級到基礎引擎 | |
| logger.warning("進階 NLP 分析失敗，使用基礎分析") | |
| # API 錯誤 | |
| logger.error("OpenRouter API 錯誤: 401 Unauthorized") | |
| ``` | |
| ### 常見問題 | |
| 1. **API Key 無效** | |
| - 檢查 API Key 是否正確 | |
| - 確認 OpenRouter 帳戶餘額 | |
| 2. **模型不存在** | |
| - 檢查模型名稱是否正確 | |
| - 參考 OpenRouter 模型列表 | |
| 3. **請求超時** | |
| - 檢查網路連線 | |
| - 考慮增加 timeout 設定 | |
| ## 📈 效能優化 | |
| ### 1. 異步處理 | |
| ```python | |
| # 使用 asyncio 避免阻塞 | |
| async def analyze_intent_advanced(self, message: str): | |
| async with httpx.AsyncClient(timeout=30.0) as client: | |
| response = await client.post(...) | |
| ``` | |
| ### 2. 錯誤重試 | |
| ```python | |
| # 實作重試機制 | |
| 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. 快取策略 | |
| ```python | |
| # 快取常見查詢結果 | |
| @lru_cache(maxsize=100) | |
| def cached_analysis(message_hash: str): | |
| return analysis_result | |
| ``` | |
| ## 🚀 進階功能 | |
| ### 1. 自訂提示詞 | |
| 您可以修改 `openrouter_service.py` 中的提示詞來優化特定領域的表現： | |
| ```python | |
| def _build_analysis_prompt(self, message: str): | |
| # 自訂您的提示詞 | |
| prompt = f""" | |
| 您是一個專業的電商客服助手... | |
| """ | |
| ``` | |
| ### 2. 多語言支援 | |
| ```python | |
| # 支援多語言分析 | |
| def analyze_message_multilingual(self, message: str, language: str = "zh"): | |
| prompt = self._build_multilingual_prompt(message, language) | |
| ``` | |
| ### 3. 上下文記憶 | |
| ```python | |
| # 維護對話上下文 | |
| def analyze_with_context(self, message: str, conversation_history: List[str]): | |
| context = {"history": conversation_history} | |
| return await self.analyze_intent_advanced(message, context) | |
| ``` | |
| ## 📞 技術支援 | |
| 如果您在整合 OpenRouter 時遇到問題： | |
| 1. 檢查 [OpenRouter 文件](https://openrouter.ai/docs) | |
| 2. 查看系統日誌檔案 | |
| 3. 參考本專案的 `test_api.py` 進行測試 | |
| 4. 確認環境變數設定正確 | |
| --- | |
| **注意**: OpenRouter 是付費服務，請根據您的使用量選擇適合的模型和方案。 |