從 OpenAI 遷移到 RouteAPI

本指南幫助您將現有的 OpenAI 應用程式遷移到 RouteAPI。大多數場景下，您只需要修改 Base URL 和 API Key，其他程式碼保持不變。

為什麼遷移到 RouteAPI

RouteAPI 在保持 OpenAI 相容性的基礎上提供更多能力：

統一多供應商存取 - 除了 OpenAI，還可以使用 Claude、Gemini、Azure、AWS Bedrock 等模型，無需改動程式碼
成本管理與預算控制 - 集中管理多個模型的用量和額度，避免超支
可觀測性增強 - 統一的請求日誌、用量統計和效能監控
高可用與負載平衡 - 自動故障轉移和多渠道負載分配
靈活的權限與配額 - 為不同團隊、專案或環境建立獨立的 Token 和限額

遷移難度評估

場景	改動範圍	預計耗時
使用 OpenAI SDK（Python/Node.js）	僅修改初始化配置（2 行程式碼）	< 5 分鐘
使用 LangChain/LiteLLM 等框架	修改配置參數	< 10 分鐘
使用 Cursor/Claude Code 等客戶端	修改設定面板的 Base URL 和 Key	< 5 分鐘
直接使用 HTTP 請求	修改請求 URL 和認證標頭	< 10 分鐘

基礎配置修改

遷移的核心步驟是修改兩個配置項：

1. 修改 Base URL

將 OpenAI 的 Base URL 替換為 RouteAPI：

# OpenAI 原始位址
https://api.openai.com/v1

# RouteAPI 位址
https://api.routeapi.ai/v1

2. 替換 API Key

使用 RouteAPI Token 替換 OpenAI API Key：

登入 RouteAPI 控制台
在 API Keys 頁面建立新令牌
複製並儲存令牌（格式類似 sk-...）

3. 環境變數管理

建議使用環境變數管理金鑰：

# .env 檔案
ROUTEAPI_KEY=sk-your-routeapi-token

安全提示：不要把 Token 提交到版本庫，使用 .gitignore 排除 .env 檔案。

Python SDK 遷移

OpenAI SDK

只需修改 base_url 和 api_key 參數：

# 遷移前 - OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-proj-...",  # OpenAI Key
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
)

# 遷移後 - RouteAPI
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],  # 使用 RouteAPI Token
    base_url="https://api.routeapi.ai/v1",  # 指向 RouteAPI
)

response = client.chat.completions.create(
    model="gpt-4",  # 或使用其他模型如 claude-3-5-sonnet-20241022
    messages=[{"role": "user", "content": "Hello"}],
)

變化點：

新增 base_url 參數
替換 api_key，建議從環境變數讀取
可選：更換 model 為 RouteAPI 支援的其他模型

LangChain 配置

# 遷移前
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key="sk-proj-...",
)

# 遷移後
from langchain_openai import ChatOpenAI
import os

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

LiteLLM 配置

# 遷移前
import litellm

response = litellm.completion(
    model="gpt-4",
    api_key="sk-proj-...",
    messages=[{"role": "user", "content": "Hello"}],
)

# 遷移後
import litellm
import os

response = litellm.completion(
    model="gpt-4",
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
    messages=[{"role": "user", "content": "Hello"}],
)

Node.js SDK 遷移

OpenAI SDK

只需修改初始化配置：

// 遷移前 - OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-proj-...',  // OpenAI Key
});

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
});

// 遷移後 - RouteAPI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,  // 使用 RouteAPI Token
  baseURL: 'https://api.routeapi.ai/v1',  // 指向 RouteAPI
});

const response = await client.chat.completions.create({
  model: 'gpt-4',  // 或使用其他模型如 claude-3-5-sonnet-20241022
  messages: [{ role: 'user', content: 'Hello' }],
});

變化點：

新增 baseURL 參數
替換 apiKey，建議從環境變數讀取
可選：更換 model 為 RouteAPI 支援的其他模型

客戶端工具遷移

如果您使用 IDE 客戶端或編碼代理，只需在設定面板修改配置：

客戶端	配置文件
Cursor	Cursor 接入配置
Claude Code	Claude Code 接入配置
OpenCode	OpenCode 接入配置
Codex (oh-my-codex)	Codex 接入配置

通常只需修改兩項：

Base URL / API Endpoint → https://api.routeapi.ai/v1
API Key → 您的 RouteAPI Token

參數相容性檢查

保持不變的參數

以下參數在 RouteAPI 中與 OpenAI 行為一致：

model - 模型 ID
messages - 對話訊息陣列
temperature - 隨機性控制（0-2）
max_tokens - 最大生成 Token 數
top_p - 核採樣參數
frequency_penalty - 頻率懲罰
presence_penalty - 存在懲罰
stop - 停止序列
stream - 是否啟用串流回應
user - 終端使用者識別碼
n - 返回結果數量

需要注意的參數

某些參數的支援取決於所選模型的能力：

參數	說明	依賴
`tools` / `tool_choice`	工具呼叫（Function Calling）	需要模型支援工具呼叫
`response_format`	結構化輸出（JSON mode）	需要模型支援 JSON 輸出
`seed`	確定性採樣種子	部分模型支援
`logprobs` / `top_logprobs`	返回 token 機率	部分模型支援

建議：對進階參數，先在測試環境驗證目標模型是否支援。

顯式零值處理

RouteAPI 遵循 Rule 5 約定：

如果客戶端顯式傳入 temperature=0、top_p=0 或 max_tokens=0，這些值會被原樣轉發到上游模型
不會被當作「未設定」而忽略

這意味著您可以放心使用 temperature=0 來獲得確定性輸出。

模型名稱

查詢可用模型

遷移後，您可以存取 OpenAI 之外的更多模型。使用 /v1/models 介面查詢：

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

回應範例：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1677610602,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.0-flash-exp",
      "object": "model",
      "created": 1677610602,
      "owned_by": "google"
    }
    // ...更多模型
  ]
}

使用模型 ID

重要：請求時使用模型的 id 欄位（如 claude-3-5-sonnet-20241022），而不是顯示名稱（如 “Claude 3.5 Sonnet”）。

# ✅ 正確 - 使用模型 ID
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
)

# ❌ 錯誤 - 使用顯示名稱
response = client.chat.completions.create(
    model="Claude 3.5 Sonnet",  # 會報錯
    messages=[...],
)

跨供應商模型替換

遷移到 RouteAPI 後，您可以輕鬆嘗試不同供應商的模型：

# OpenAI 模型
model="gpt-4"
model="gpt-4o"

# Anthropic Claude 模型
model="claude-3-5-sonnet-20241022"
model="claude-3-5-haiku-20241022"

# Google Gemini 模型
model="gemini-2.0-flash-exp"
model="gemini-1.5-pro-002"

# AWS Bedrock 模型（透過 RouteAPI）
model="anthropic.claude-3-5-sonnet-20241022-v2:0"

只需修改 model 參數，其他程式碼無需改動。

測試和驗證

測試清單

遷移完成後，建議按以下清單驗證：

認證測試 - 確認 Token 有效，能成功呼叫 /v1/models
基礎呼叫 - 測試 chat.completions.create 是否正常返回
串流回應 - 如果使用 stream=True，驗證串流輸出是否正常
工具呼叫 - 如果使用 Function Calling，驗證工具呼叫流程
錯誤處理 - 測試餘額不足、限流、無效參數等錯誤場景
用量統計 - 在 RouteAPI 控制台查看用量日誌是否正確記錄

常見問題排查

錯誤碼	常見原因	解決方法
401 Unauthorized	Token 無效或缺失	檢查 `Authorization` 標頭格式：`Bearer sk-...`
402 Payment Required	餘額不足或額度耗盡	登入控制台充值或提高 Token 額度
404 Not Found	Base URL 錯誤或路徑拼寫錯誤	確認 Base URL 為 `https://api.routeapi.ai/v1`
429 Too Many Requests	觸發限流	降低請求頻率，或聯絡管理員提高限額
500 Internal Server Error	上游模型服務異常	重試請求，或切換到備用模型

除錯技巧：

使用 cURL 直接測試介面，排除 SDK 配置問題
檢查 RouteAPI 控制台的用量日誌，查看具體錯誤資訊
對比原 OpenAI 請求和 RouteAPI 請求的參數差異

範例：使用 cURL 測試

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

如果 cURL 請求成功，說明 Token 和 Base URL 配置正確，問題可能出在 SDK 層。

分步遷移建議

對於生產環境，建議採用漸進式遷移策略：

1. 先在測試環境驗證

在開發或測試環境完整測試遷移後的程式碼
驗證核心功能、邊界情況和錯誤處理
對比 OpenAI 和 RouteAPI 的回應內容和效能

2. 灰度發布

使用功能開關（Feature Flag）控制 Base URL 切換
先對小部分流量啟用 RouteAPI
觀察錯誤率、延遲和使用者回饋

範例：使用環境變數控制

import os

# 透過環境變數控制是否使用 RouteAPI
USE_ROUTEAPI = os.getenv("USE_ROUTEAPI", "false").lower() == "true"

if USE_ROUTEAPI:
    base_url = "https://api.routeapi.ai/v1"
    api_key = os.environ["ROUTEAPI_KEY"]
else:
    base_url = "https://api.openai.com/v1"
    api_key = os.environ["OPENAI_API_KEY"]

client = OpenAI(api_key=api_key, base_url=base_url)

3. 監控用量日誌和錯誤率

遷移後密切關注：

請求成功率 - 是否有異常的 4xx/5xx 錯誤
回應延遲 - P50、P95、P99 延遲分布
Token 用量 - 計費是否符合預期
模型可用性 - 不同模型的成功率和延遲

在 RouteAPI 控制台的「用量日誌」頁面可以查看詳細記錄。

4. 回滾方案

準備快速回滾到 OpenAI 的方案：

保留原 OpenAI API Key，不要立即刪除
使用配置中心或環境變數管理 Base URL，便於快速切換
在監控中設定告警閾值，自動觸發回滾

# 回滾範例：修改環境變數即可切換
# USE_ROUTEAPI=false -> 使用 OpenAI
# USE_ROUTEAPI=true -> 使用 RouteAPI

遷移後的最佳化建議

1. 利用多模型能力

RouteAPI 支援多個供應商的模型。根據場景選擇最合適的模型：

延遲敏感場景 - 使用 gemini-2.0-flash-exp 或 gpt-4o-mini
複雜推理任務 - 使用 claude-3-5-sonnet-20241022 或 gpt-4
成本最佳化 - 對比不同模型的性價比，選擇最優方案

2. 設定獨立 Token

為不同專案、環境或團隊建立獨立的 Token：

開發環境 - 低額度 Token，避免測試時產生大量費用
生產環境 - 高額度 Token，並設定告警
不同團隊 - 獨立 Token 便於成本歸屬和稽核

3. 啟用請求日誌

在 RouteAPI 控制台查看詳細的請求日誌：

每次請求的模型、Token 用量、延遲
錯誤請求的原因和堆疊
用量趨勢和成本分析

這些日誌有助於最佳化成本和排查問題。

取得協助

如果遷移過程中遇到問題：

查看 API 參考文件
造訪 RouteAPI 控制台查看用量日誌
聯絡技術支援取得協助

相關文件：