本地 LLM OpenAI API：本地運行，切換至託管

術語含義

人們使用「本地 LLM OpenAI API」一詞指代兩種相關事物。第一種是你自己在筆記型電腦或家庭伺服器上運行的語言模型，它在本地埠上監聽並使用 OpenAI 聊天格式。第二種是將應用程式針對該格式編寫的習慣，以便後端的模型可以進行替換。

格式是一個簡單的合約。你的應用程式傳送包含 model 名稱與 messages 列表的 JSON 主體，每個項目都帶有 system、user 或 assistant 角色。伺服器回覆包含生成訊息的 JSON 物件，或者如果你要求串流輸出，則回覆一小塊一小塊的串流。Python 和 JavaScript 的官方 SDK 封裝了這個功能，它們允許你覆蓋 Base URL，這就是整個關鍵所在。

許多本地工具公開此合約。Ollama、LM Studio、llama.cpp 伺服器與 vLLM 均提供 OpenAI 風格的路由。託管服務也是如此，這就是為什麼相同的二十行客戶端程式碼可以與兩者通訊。本站的端點屬於託管類型。它接受 POST /v1/chat/completions 與 GET /v1/models，並可透過 https://api.onekeyllmapi.com/v1 訪問。

本地與託管一覽

兩者無絕對優劣。它們在控制權與工作量之間取捨。該表格僅列出類別層面的差異，而非特定產品的差異。

如果你的資料必須永遠不離開你控制的機器，本地部署勝出，託管服務不是合適的工具。如果你的硬體容納不下更大的模型，或你需要一個能從多個位置存取的 bot，託管服務勝出。常見的設定是兩者都保留，並依任務選擇。

將客戶端從本地切換至託管

如果你的程式碼已經能與本地執行器通訊，只需修改三個值。其餘一切不變，包括建構提示詞的方式以及讀取串流區塊的邏輯。

1. Base URL。請使用 https://api.onekeyllmapi.com/v1 而非你的本機地址。
2. API 金鑰。 本地伺服器通常忽略金鑰。託管伺服器需要它作為 Authorization: Bearer <key>，SDK 會為你發送它。
3. 模型 ID。 本地名稱取決於你下載的內容。此處的 ID 為 uncensored。

保持靈活性的一種整潔方法是從環境變數讀取所有三個值，這樣一個檔案即可在兩處運行。

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.onekeyllmapi.com/v1"),
    api_key=os.environ.get("LLM_API_KEY", "YOUR_KEY"),
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

models = client.models.list()
print([m.id for m in models.data])

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Answer in two sentences."},
        {"role": "user", "content": "Why do OpenAI-style endpoints make switching models easy?"},
    ],
    temperature=0.5,
)
print(resp.choices[0].message.content)

來自命令列的相同呼叫，適合快速冒煙測試：

Copycurl https://api.onekeyllmapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "uncensored", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 20}'

使用 Node 時，模式相同：

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.LLM_BASE_URL ?? "https://api.onekeyllmapi.com/v1",
  apiKey: process.env.LLM_API_KEY,
});

const res = await client.chat.completions.create({
  model: process.env.LLM_MODEL ?? "uncensored",
  messages: [{ role: "user", content: "Name three uses for JSON mode." }],
});
console.log(res.choices[0].message.content);

OpenAI 相容性的涵蓋範圍

相容意味著線路格式匹配。它不保證原始服務提供的每個功能都存在。在遷移真實應用程式之前，請針對目標檢查以下每項內容。

此 API 支援的功能

• POST /v1/chat/completions 的聊天完成與 GET /v1/models 的模型列表。
• 透過 stream: true 的伺服器發送事件進行串流輸出，並在串流結束時報告用量。
• 透過 tools 與 tool_choice 進行函式呼叫，串流輸出 tool_calls，並將結果作為 role: "tool" 訊息發送回傳。
• 透過 response_format: {"type": "json_object"} 的 JSON 模式。
• 採樣控制：temperature、top_p、stop、seed 與懲罰參數均會傳遞。

它不做什麼

• 無影像、音訊或影片生成。僅支援文字。
• 無嵌入端點與微調。如果你的應用程式構建向量索引，你需要獨立的嵌入來源。
• 僅單一模型。該模型是由獨立供應商運行的開放權重模型。它不是任何大型供應商的官方 API，也不是跨供應商的路由器，因此你無法透過更改 ID 在模型系列之間進行選擇。

本地執行器有時會以相反方式不同：本地伺服器可能提供嵌入路由或允許加載多個模型，上下文大小取決於你的配置。閱讀目標的文件，並保留一份應用程式真正使用的功能簡短清單。快速入門文件 完整展示了請求欄位。

上下文、限制與成本差異

離開本地伺服器時有三個數字會改變。第一個是上下文視窗。本地執行器的上下文長度是與記憶體相關的設定。此處固定為 100,000 token，由提示詞與完成內容共享，且 max_tokens 是可選的。第二個是並行處理。你自己的機器可以排隊任意深度，但此處的完整金鑰允許 8 個並行請求與每分鐘 300 個請求，試用金鑰則為 2 個與 60 個。第三個是帳單。

託管使用的成本為每 100 萬輸入 token $0.15，每 100 萬輸出 token $0.50，從預付額度按量付費。以每日作業為例：摘要器每天處理 400 份文件，每份輸入 3,000 token，輸出 300 token。輸入為 400 x 3,000 = 1,200,000 token，成本為 1.2 x $0.15 = $0.18。輸出為 400 x 300 = 120,000 token，成本為 0.12 x $0.50 = $0.06。當日總計 $0.24，30 天月份為 $7.20。在決定之前，請與保持 GPU 運行及硬體本身的成本進行比較。

當超出限制時，API 會回應 HTTP 429，代碼為 rate_limited 或 concurrency。對於短暫過載，它會添加 Retry-After: 5。保留等待並重試的邏輯。失敗或被拒絕的請求不會收費。額度永不過期，因此空閒月份不產生費用。

串流請求會保留其並行請求槽位，直到串流結束，因此請關閉你停止讀取的串流。儲值始於 $20；等級與獎金位於 定價頁面。

切換異常時的除錯

大多數遷移失敗都歸因於少數幾個原因。請按此順序逐一排查。

• 404 或連線錯誤。 Base URL 可能缺少 /v1 後綴，或是多了路徑。請完全照 https://api.onekeyllmapi.com/v1 使用。
• 驗證錯誤。 金鑰遺漏或放在錯誤的標頭中。格式為 Authorization: Bearer <key>。SDK 使用者應確認環境變數確實已載入。
• 找不到模型。 你的設定中仍保留舊的本地模型名稱。請呼叫 GET /v1/models 並使用它列出的 ID，即 uncensored。
• 負載下的 429。 你已超過完整金鑰的 8 個並行請求或每分鐘 300 次請求的限制。請加入佇列或信號量。
• 某個參數似乎被忽略。 檢查它是否為上述列出的傳遞欄位之一，並與固定的 seed 和低溫度設定進行行為比較。

每個回應都包含 X-Request-Id 標頭。請將其記錄在你的請求 ID 旁邊，以便後續追蹤不良回應。如果你運行生產流量並希望隨時間衡量品質，網站文章 LLM Observability: Myths vs Facts 是很好的下一步閱讀。回應標頭 X-Balance-USD、X-RateLimit-Limit-Requests 和 X-RateLimit-Limit-Concurrency 也值得擷取。

無承諾試用

測試程式碼能否順利移植最便宜的方法是實際執行一次。使用 Google 或電子郵件與密碼建立帳戶，然後在金鑰頁面領取 $0.50 的試用額度。只需點擊一次，不需要信用卡，每人限領一次，有效期為 7 天。前往 API 金鑰頁面 取得金鑰，設定上述三個環境變數，然後執行你現有的測試套件。

如果測試通過且用量符合你的預算，請從 $20 開始儲值，可使用信用卡（Visa、Mastercard、Apple Pay、Google Pay）或加密貨幣（TRC20 上的 USDT、Base 上的 USDC）。提示詞不會用於訓練。該模型針對合法成人用途調整為不會拒絕回答，唯一的固定規則是不允許出現涉及未成年人的性內容。

更多指南

• LLM 可觀察性：神話與事實