LangChain 自訂 LLM API:指向任何 Base URL
使用 langchain 自訂 LLM API 不需要撰寫自訂類別:與 OpenAI 相容的聊天包裝函式接受 Base URL、金鑰與模型名稱。以下是精確設定,以及串流、工具、JSON 輸出與限制處理。
重點摘要
- ChatOpenAI 接受 base_url、api_key 與 model,因此不需要繼承。
- 使用模型 uncensored 與 Base URL https://api.llmapistatus.com/v1.
- 工具呼叫、串流輸出與 JSON 模式皆通過端點運作。
- 將並行鏈結限制在 8 以保持在並行限制內;不提供嵌入功能。

簡短答案:使用不同 Base URL 的 ChatOpenAI
LangChain 透過 langchain-openai套件與 OpenAI 相容伺服器通訊。其 ChatOpenAI 類別可讓你覆寫請求的目的地,這正是自訂端點所需。安裝套件後,傳入三個值:Base URL https://api.llmapistatus.com/v1、你的金鑰和模型 ID uncensored。
使用 pip install -U langchain-openai langchain-core 安裝。
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmapistatus.com/v1",
api_key=os.environ["LLM_API_KEY"],
temperature=0.7,
)
print(llm.invoke("Reply with the single word: ready").content)
如果印出回覆,則連線正確。你可從 API 金鑰頁面 取得金鑰;快速入門 為純 SDK 使用者顯示相同的切換方式。端點提供 POST /v1/chat/completions 與 GET /v1/models,這兩個方法正是 OpenAI 包裝函式進行聊天所需。
關於「自訂 LLM」一詞的說明。LangChain 也記錄了透過繼承基底類別來撰寫自訂聊天模型的方法,這對於不使用 OpenAI 格式的 API 很有意義。此端點支援該格式,因此繼承只會增加維護程式碼。僅在包裝函式無法表達所需行為時才使用。
使用提示詞與輸出解析建立鏈結
有了模型物件,LangChain 中的其他功能運作方式與任何聊天模型相同。以下是以表達式語言風格撰寫的小型鏈結:提示詞範本、模型與字串解析器。
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You are a blunt technical editor. Answer in at most {limit} words."),
("human", "Rewrite this for clarity:\n\n{text}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({
"limit": 60,
"text": "The thing that we did was basically to make the cache be invalidated on write.",
}))
此鏈結中的任何部分都不需要知道或在意模型位於不同網域。這就是相容 API 的好處:針對標準聊天介面撰寫的提示詞、記憶類別、檢索器與代理程式都能繼續運作。你應該檢查的是提示詞本身。經過調整以無審查回答的模型會嚴格遵循指示,因此模糊的系統提示詞會產生模糊的行為。請明確說明角色、格式與長度。
在設計檢索管線之前,有一個限制值得了解。此服務僅支援文字。沒有嵌入功能,因此指向此 Base URL 的 OpenAIEmbeddings 會失敗。請使用本地嵌入模型或其他供應商處理向量資料庫,並僅使用此端點進行生成。
串流接收到達的 token
當你傳送 stream: true 時,端點支援伺服器發送事件,LangChain 會將其轉換為迭代器。你不需要自行設定旗標;呼叫 .stream() 即可。
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
for chunk in llm.stream("Write a four-line poem about a failing cron job."):
print(chunk.content, end="", flush=True)
print()
對於非同步伺服器,請使用 astream。JavaScript 函式庫中也存在相同的呼叫:
import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({
model: "uncensored",
apiKey: process.env.LLM_API_KEY,
configuration: { baseURL: "https://api.llmapistatus.com/v1" },
});
const stream = await llm.stream("Write a four-line poem about a failing cron job.");
for await (const chunk of stream) {
process.stdout.write(chunk.content);
}
請記住,串流請求會保留其並行槽位,直到最後一個事件到達。如果使用者關閉瀏覽器分頁而你的伺服器繼續讀取串流,該槽位仍會被佔用。當用戶端斷開連線時,請取消上游請求。用量數字會在串流結束時到達,你可以在那裡讀取用於帳單記錄的最終 token 計數。
函式呼叫與代理程式
支援工具呼叫:端點接受 tools 與 tool_choice,串流回傳 tool_calls,並接受帶有 role: "tool" 的訊息作為你的結果。在 LangChain 中,你使用 bind_tools 附加工具,讓框架建立訊息。
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from langchain_core.tools import tool
@tool
def get_order_status(order_id: str) -> str:
'Look up the status of an order by its id.'
return f"Order {order_id} shipped yesterday."
llm_tools = llm.bind_tools([get_order_status])
ai = llm_tools.invoke("Where is order A-1042?")
print(ai.tool_calls)
執行呼叫並回傳結果是迴圈的第二部分:
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
# llm_tools comes from the previous snippet
from langchain_core.messages import HumanMessage, ToolMessage
messages = [HumanMessage("Where is order A-1042?")]
ai = llm_tools.invoke(messages)
messages.append(ai)
for call in ai.tool_calls:
result = get_order_status.invoke(call["args"])
messages.append(ToolMessage(content=result, tool_call_id=call["id"]))
print(llm_tools.invoke(messages).content)
開放權重模型在選擇工具與填充參數方面的表現各異。保持工具描述簡短具體,每次呼叫使用較少的工具,並在函式中驗證參數而非完全信任它們。如果代理程式陷入迴圈,請降低 temperature 並在代理程式執行器中設定最大步驟數。
結構化與 JSON 輸出
JSON 模式透過 response_format: {"type": "json_object"} 支援。在 LangChain 中,最簡單的路徑是使用 JSON 模式方法的 with_structured_output,這也會根據 schema 驗證結果。
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from pydantic import BaseModel
class Ticket(BaseModel):
title: str
priority: str
tags: list[str]
structured = llm.with_structured_output(Ticket, method="json_mode")
result = structured.invoke(
"Return JSON with keys title, priority and tags for this report: "
"login page times out on mobile, affects many users."
)
print(result)
JSON 模式保證輸出為 JSON 物件,但不保證包含你所需的欄位。兩個習慣有幫助。首先,在提示詞中命名鍵,如上所述;產生 JSON 的指示應明確。其次,將呼叫包裝在重試中,若失敗則重新解析。pydantic 檢查會捕捉遺失的欄位與錯誤的類型,附加錯誤訊息的重試通常能解決問題。
你也可以在建立模型時直接設定 response_format,使用 model_kwargs={"response_format": {"type": "json_object"}},這對於以 JSON 解析器結束的純鏈結很方便。
速率限制、重試與並行鏈結
批次作業與代理程式會同時發出許多呼叫,這也是自訂端點與本地模型的差異之處。完整金鑰允許 8 個並行請求與每分鐘 300 個請求。試用金鑰允許 2 個並行與每分鐘 60 個。超過限制時,API 會回傳 HTTP 429 與錯誤程式碼 rate_limited 或 concurrency;在暫時過載時,會回傳 429 與 Retry-After: 5。
兩個 LangChain 設定可處理大部分情況。模型接受 max_retries,以指數退避重試暫時性失敗,runnables 在其配置中接受 max_concurrency 值用於批次工作:
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmapistatus.com/v1",
api_key=os.environ["LLM_API_KEY"],
max_retries=4,
timeout=120,
)
questions = [f"Summarise item {i} in one sentence." for i in range(40)]
answers = llm.batch(questions, config={"max_concurrency": 6})
在完整金鑰上將上限設為 6 可為其他請求(例如來自同一應用程式的使用者呼叫)保留空間。在試用金鑰上請使用 1 或 2。不要僅依賴重試來解決並行問題:如果上限高於限制,重試只會重現相同的衝突。從回應標頭讀取 X-RateLimit-Limit-Requests 與 X-RateLimit-Limit-Concurrency 可告訴你金鑰允許的限制。
長輸入在 100,000-token 視窗內沒問題,提示詞與完成內容共用此視窗,且請求主體限制為 8 MB。LangChain 文字分割器設定為每個區塊數千個 token,可讓你遠離這兩個限制。
疑難排解自訂端點
自訂 Base URL 的大多數問題可歸類為短清單,且每個問題都有快速測試方法。
- 驗證錯誤。LangChain 也會讀取
OPENAI_API_KEY環境變數。如果你明確傳遞api_key,該值會優先,但過期的變數仍可能讓你忘記設定的第二個模型物件產生混淆。每次都要傳遞金鑰,並將環境變數命名為其他名稱,例如LLM_API_KEY。 - 找不到錯誤。 Base URL 必須以
/v1結尾。LangChain 會自行附加/chat/completions,因此在 Base URL 中加入它會產生重複路徑。 - 未知模型。 使用相同金鑰查詢
GET /v1/models並複製它印出的 ID。它應該是uncensored。 - 長鏈結中的靜默卡住。 在模型上設定
timeout並記錄X-Request-Id回應標頭。如果你聯繫支援團隊,該 ID 可讓他們找到確切的請求。 - 令人驚訝的輸出。 在發送前印出最終提示詞。LangChain 中的大多數奇怪答案來自填入了意外變數的範本,而非模型本身。
如有疑問,請使用純 curl 對相同 URL 重現失敗的呼叫。如果 curl 運作正常但 LangChain 不行,則錯誤在於你的鏈結;如果兩者都失敗,請檢查金鑰與餘額。
在開發時檢查成本
鏈結會隱藏 token 計數,因此請及早測量。每個回應都包含用量,回應標頭包含 X-Balance-USD。價格為每 1M 輸入 token $0.15,每 1M 輸出 token $0.50,從預付額度計費。
一個具體範例:一個檢索鏈將 6,000 個 token 的上下文與問題發送出去,並取得 400 個 token 的回傳,其輸入成本為 6,000 x $0.15 / 1M = $0.0009,輸出成本為 400 x $0.50 / 1M = $0.0002,因此每次呼叫成本為 $0.0011。在測試中執行 5,000 次此類呼叫的成本為 $5.50。在讓 代理程式迴圈在夜間運行之前,了解這一點很有用。
失敗或遭拒的請求不會計費。定價頁面列出儲值金額從 $20 到 $500 不等並附贈獎金,新帳戶可以一鍵領取 $0.50 的免費試用額度,足以在設定服務時進行數百次小型測試呼叫。
更多指南
問答
我必須繼承 LangChain 的聊天模型基底類別嗎?
不需要。此端點與 OpenAI 相容,因此使用自訂 base_url、api_key 和模型的 ChatOpenAI 即可運作。僅當 API 使用不同格式時才需要繼承。
我可以在此端點使用 OpenAIEmbeddings 嗎?
不行。該服務僅支援文字,沒有嵌入功能。請使用本地嵌入模型或其他供應商來處理向量,並使用此端點進行生成。
我應該傳遞哪個模型名稱?
傳遞 uncensored 作為模型。GET /v1/models 會回傳相同的 ID。
為什麼在批次作業中會收到 429 錯誤?
你已超過每分鐘請求數或並行請求數限制。請將完整金鑰的 max_concurrency 設為低於 8,或將試用金鑰設為低於 2,並保持重試功能開啟。
LangChain 的串流輸出在此處運作嗎?
可以。呼叫 stream 或 astream 會使用伺服器發送事件(SSE),並在串流結束時發送用量資訊。
只差一張表單,即可取得金鑰
建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。