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 以内,以保持在并发限制之下;不提供嵌入功能。

简短回答:使用不同基础 URL 的 ChatOpenAI
LangChain 通过 langchain-openai 包与 OpenAI 风格服务器通信。其 ChatOpenAI 类允许你覆盖请求去向,这正是自定义接口所需。安装该包,然后传入三个值:基础 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 的好处:针对标准聊天界面编写的提示词、记忆类、检索器和代理保持有效。你应该检查的是提示词本身。经过调整以无内容拒绝进行响应的模型会按字面意思遵循指令,因此模糊的系统提示词会产生模糊的行为。明确说明角色、格式和长度。
在设计检索管道之前,有一个限制值得了解。此服务仅支持文本。没有嵌入功能,因此指向此基础 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 输出
通过 response_format: {"type": "json_object"} 支持 JSON 模式。在 LangChain 中,最简单的方法是使用 JSON 模式方法的 with_structured_output,它还会根据模式验证结果。
# 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 密钥和模型的 ChatOpenAI 即可。仅当 API 使用不同格式时才需要继承。
我可以在此接口上使用 OpenAIEmbeddings 吗?
不可以。该服务仅支持文本,没有嵌入功能。请使用本地嵌入模型或其他提供商获取向量,并在此接口上进行生成。
我应该传入哪个模型名称?
传入 uncensored 作为模型。GET /v1/models 返回相同的 ID。
为什么在批处理作业中收到 429 错误?
你超过了每分钟请求数或并发请求限制。将完整密钥的 max_concurrency 降至 8 以下,或将试用密钥降至 2,并保留重试功能。
LangChain 的流式输出在此处可用吗?
可用。调用 stream 或 astream 使用服务器发送事件,使用情况将在流结束时发送。
只差一张表单,即可获得密钥
创建账户,复制密钥,更改基础 URL。这就是全部设置。