遷移 API：常見 LLM 整合錯誤疑難排解

誤配基礎 URL

第一個失敗點幾乎總是基礎 URL。當您切換供應商時，必須更新您的 SDK 所連線的端點。錯誤的 URL 會在您的有效載荷離開機器之前就導致 404 或 403 錯誤。

確保您的客戶端指向正確的網域。對於我們的服務，基礎 URL 為 https://api.apimigration.com/v1. 此 URL 透過簡單更改 base_url 參數。

• 驗證協議（HTTPS 與 HTTP）。
• 檢查客戶端配置中的尾隨斜線。
• 確認版本路徑（/v1) 符合您的 API 規範。

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

忽略上下文視窗限制

您的模型對於提示與補全的總和有 100,000 個 token 的硬性限制。若超過此限制，API 將拒絕請求或根據實作方式靜默截斷您的歷史記錄。請務必追蹤您的 token 使用量，以避免觸及此上限。

此外，每次請求的最大輸出為 16,000 個權重。如果您沒有設置 max_tokens, 預設值為 2,048 個 token。對於長篇生成任務，此差異顯著的。

• 監控每個請求的總 Token 數量。
• 設定 max_tokens 明確指定以用於長輸出。
• 針對非常長的對話實施滑動視窗邏輯。

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

不正確的流式傳輸實現

串流回應需要特定處理伺服器發送事件（SSE）。如果您將串流視為單一 JSON 物件，您的程式碼將掛起或崩潰。每個區塊包含部分資料，而最後一個區塊包含權杖使用統計數據。

依序讀取串流。隨著每個事件到達進行處理。這可降低最終使用者的感知延遲。不要等待整個回應完成後再進行處理。

• 開啟連線並逐行讀取。
• 解析 data: 行作為 JSON。
• 處理 [DONE] 正確地發出訊號。

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

忽略速率限制

我們的 API 每金鑰每分鐘允許 300 次請求。如果您的應用程式出現尖峰流量，您將收到 429 Too Many Requests 錯誤。您必須實施指數退避機制以優雅地處理這些錯誤。

每個金鑰的並行請求也限制為同時 8 個。超過此限制可能會導致連線池耗盡。請密切監控您的並行連線。

• 為 429 錯誤實作指數退避。
• 將並發連接限制為 8。
• 在高負載情況下使用電路斷路器模式。

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

假設標準 JSON 格式

雖然我們遵循 OpenAI 相容格式，但某些假設可能會導致整合失敗。確保您請求 json_object in response_format 如果您需要嚴格的 JSON。否則，模型可能會返回 Markdown 或純文字。

仔細解析回應。在使用之前驗證 JSON 結構。這可防止下游服務發生執行階段錯誤。

• 設定 response_format 以 {"type": "json_object"}.
• 解析前驗證 JSON。
• 優雅地處理格式錯誤的回應。

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

忽略錯誤處理

API 會失敗。網路超時、伺服器錯誤和無效的載體都會發生。您的程式碼必須在不崩潰的情況下處理這些錯誤。記錄錯誤詳細資訊以進行除錯。

檢查錯誤碼和訊息。對暫時性錯誤進行重試。對永久性錯誤快速失敗。這種區別可以節省時間和資源。

• 記錄錯誤代碼和訊息。
• 在 5xx 錯誤時重試並退避。
• 4xx 錯誤時快速失敗。

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

付款與金鑰輪換問題

我們的 API 透過加密貨幣提供預付費信用額度。信用額度不會過期。如果您信用額度用盡，請求將失敗。請監控您的餘額，並在歸零前充值。

每個帳戶擁有一個有效金鑰。生成新金鑰將立即使舊金鑰失效。請確保您的部署以原子方式更新金鑰，以避免服務中斷。

• 定期監控信用餘額。
• 原子旋轉密鑰。
• 同時更新所有實例。

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

最佳實踐摘要

遷移成功取決於對細節的關注。請驗證您的基礎 URL。遵守上下文限制。正確處理串流。管理速率限制。驗證 JSON。處理錯誤。管理付款和金鑰。遵循這些步驟可確保順利過渡。

上線前請徹底測試您的整合。使用試用額度驗證您的設定。這可防止生產環境中昂貴的停機時間。

• 驗證基礎 URL。
• 遵守上下文限制。
• 正確處理串流。
• 管理速率限制。
• 驗證 JSON。
• 處理錯誤。
• 管理付款和金鑰。

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'