最佳實踐

生產環境最佳化

從您的 TokSpan 整合中獲得最低延遲、最高吞吐量及最小成本。這些是我們在自身生產環境中運行的最佳實踐模式。

降低延遲

使用連線池

重複使用 HTTP 連線可省去每次請求的 TLS 交握開銷（每次呼叫約節省 50–100ms）。OpenAI SDK 會自動使用連線池，但在生產環境中，請調整池大小：

python
import httpx
from openai import OpenAI

# Production-grade client with connection pooling
client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokspan.com/v1",
    http_client=httpx.Client(
        limits=httpx.Limits(
            max_keepalive_connections=20,
            max_connections=50,
        ),
        timeout=60.0,  # total timeout
    ),
)

互動式體驗請一律使用串流

在每個面向使用者的請求中設定 stream: true。串流可在約 100ms 內傳回第一個 Token，無需等待 5–30 秒的完整回應。實作方式請參閱聊天補全 — 串流。

邊緣路由

對 api.tokspan.com 的請求會透過 TokSpan 的邊緣網路提供服務，將流量路由至託管您模型的後端區域。您無需任何設定。

善用 Prompt 快取

Prompt 快取可將重複 Prompt 的首 Token 時間縮短最多 80%。請將靜態內容（系統指令、上下文）放置在 messages 陣列的開頭。詳細說明請參閱Prompt 快取指南。

延遲檢查清單

最佳化方式延遲影響實施難度
連線池每次請求減少 50–100ms低
啟用串流感知延遲：減少 5–30 秒低
Prompt 快取快取命中時減少 80%中

降低成本

智慧模型選擇

並非每個任務都需要 GPT 或 Claude Opus。將簡單任務路由至更便宜的模型：

任務類型推薦模型相較 GPT 的成本
分類、擷取、標記GPT mini, Claude Haiku, Gemini Flash便宜 10–50 倍
草稿撰寫、摘要、翻譯DeepSeek, Llama, Mistral便宜 3–10 倍
複雜推理、程式碼生成GPT, Claude Opus基準
批次／背景處理DeepSeek 或其他低成本模型便宜 5–15 倍

設定消費上限

在儀表板中為每個金鑰設定消費上限。金鑰用盡額度時會自動停用——不會有意外帳單。為開發金鑰設定較低的上限，為分享給客戶的金鑰設定更嚴格的限制。請參閱金鑰範圍設定。

成本檢查清單

最佳化方式成本影響實施難度
將簡單任務路由至小型模型該類任務減少 70–95%中
啟用 Prompt 快取快取命中時減少 50–90%低
為每個金鑰設定消費上限嚴格限制最高消費低
每週檢視使用量儀表板及早發現異常低

最大化吞吐量

非同步 + 批次處理

對於大量處理，請使用非同步客戶端和並行請求。TokSpan 的基礎架構可水平擴展——您的吞吐量上限通常是速率限制，而非伺服器：

python
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")

async def process_batch(prompts: list):
    tasks = [
        client.chat.completions.create(
            model="MODEL_NAME",
            messages=[{"role": "user", "content": p}],
        )
        for p in prompts
    ]
    return await asyncio.gather(*tasks)

並行處理指南

作為起始參考：

  • 按使用量付費：先從適度的並行數開始（5–10 個並行請求），再依觀察到的延遲與回應逐步調高
  • 企業方案：自訂並行數——請聯絡我們了解您的上限

若開始收到 429 回應，請降低並行數，並在重試前退避（含抖動的指數退避）。速率限制因方案與模型而異——詳見速率限制。

生產環境可靠性

使用指數退避重試

網路瞬斷和暫時的供應商問題時有發生。請一律將 API 呼叫包裝在重試邏輯中：

python
import time
import random
from openai import OpenAI, RateLimitError, APIError

def chat_with_retry(client, model, messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except RateLimitError:
            if attempt == max_retries - 1: raise
            # Exponential backoff with jitter
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
        except APIError as e:
            if e.status_code < 500 or attempt == max_retries - 1: raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)

自動同模型容錯移轉

若服務您所用模型的供應商發生停機，TokSpan 會自動將請求重新路由至提供同一模型的另一家供應商——零請求遺失、無需人工介入。容錯移轉保持在相同模型內，因此輸出行為保持一致。請參閱自動容錯移轉。

API 金鑰策略

  • 開發金鑰：低預算（例如 $10），限制使用便宜模型，無 IP 限制
  • Staging 金鑰：中等預算（例如 $50），可使用生產模型集，設有 IP 限制
  • 生產金鑰：較高預算，可使用所有模型，限制僅限生產伺服器 IP

每 90 天輪換金鑰。若您管理多個專案，請為每個專案使用獨立的金鑰。

快速參考：生產環境檢查清單

上線前請逐項確認此檢查清單：

  • <strong>使用生產等級的用戶端</strong>——連線池與明確的逾時設定（見上文）
  • <strong>為每個面向使用者的請求啟用串流</strong>，以獲得即時回應的使用者體驗
  • <strong>對 <code>429</code> 與 <code>5xx</code> 錯誤實作含抖動的指數退避重試</strong>
  • <strong>為每個金鑰設定預算與 IP 白名單</strong>，避免洩漏導致巨額帳單
  • <strong>將靜態 Prompt 內容置於開頭</strong>，以最大化快取命中率並降低成本