LangChain 怎么接入 OpenAI 兼容 API？

更新于 2026-10-26 · gpt.boats

简答：LangChain 通常通过独立的 langchain-openai 包和 ChatOpenAI 接入 OpenAI 兼容 API。先确认服务端的模型名与接口路径，再设置 api_key、base_url 和 model，运行最小 invoke 示例；若失败，优先检查路径是否重复包含 /v1、Key 是否有效、模型名是否被服务端支持。

定义：OpenAI 兼容 API 是使用部分 OpenAI 风格请求与响应格式的接口，LangChain 可通过 ChatOpenAI 的 base_url 连接这类端点，但兼容范围仍由服务端实现决定。

先试这一步：最小可运行的 Python 接入示例

LangChain 当前将 OpenAI 集成拆分为独立的 langchain-openai 包，Python 中可使用 ChatOpenAI 初始化聊天模型。官方参考页列出了 model、api_key、base_url、timeout 和 max_retries 等参数。可先安装依赖：

python -m pip install -U langchain-openai

下面示例使用环境变量，避免把 Key 直接写进源码。把 https://api.example.com/v1 换成服务商实际提供的兼容接口地址，把 your-model-name 换成该服务商返回的模型名：

import os
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
model=os.environ["OPENAI_MODEL"],
api_key=os.environ["OPENAI_API_KEY"],
base_url=os.environ["OPENAI_BASE_URL"],
temperature=0,
timeout=60,
max_retries=0,
use_responses_api=False,
)

response = model.invoke("用一句话解释什么是 API")
print(response.content)

官方 LangChain 文档展示了安装 langchain-openai、设置 OPENAI_API_KEY 并创建模型实例的基本流程；兼容端点则需要额外设置 base_url。LangChain OpenAI 集成文档与ChatOpenAI 参数参考可交叉核对参数名称。

三个配置项怎么填：api_key、base_url、model

ChatOpenAI 的 base_url 用于指定 API 请求基础地址；未显式传入时，文档还说明它会读取 OPENAI_API_BASE，底层 SDK 也会读取 OPENAI_BASE_URL。为了减少环境变量优先级造成的误判，排查时建议先在代码中显式传入 base_url。ChatOpenAI 初始化参数与环境变量说明

是否包含 /v1 不能只凭 LangChain 判断。官方兼容服务示例分别展示了 http://localhost:1234/v1 和 http://localhost:8000/v1，这说明很多服务把版本路径放在基础地址中，但最终仍应以目标服务的路由定义为准。LangChain OpenAI 兼容 API 示例

用环境变量和 .env 管理 Key

开发机上可以先用系统环境变量验证链路：

export OPENAI_API_KEY="你的密钥"
export OPENAI_BASE_URL="https://api.example.com/v1"
export OPENAI_MODEL="服务端模型名"
python app.py

如果使用 PowerShell：

$env:OPENAI_API_KEY = "你的密钥"
$env:OPENAI_BASE_URL = "https://api.example.com/v1"
$env:OPENAI_MODEL = "服务端模型名"
python .\app.py

也可以用 .env 文件保存本地开发配置，再在程序启动时加载：

python -m pip install -U python-dotenv

from dotenv import load_dotenv
load_dotenv()

.env 内容示例：

OPENAI_API_KEY=你的密钥
OPENAI_BASE_URL=https://api.example.com/v1
OPENAI_MODEL=服务端模型名

不要把 .env 提交到 Git 仓库，也不要在日志、异常页面或前端代码中输出完整 Key。生产环境应改用部署平台的密钥管理或环境变量，并给 Key 设置尽可能小的权限范围。

同步、流式和异步调用怎么写

最小同步调用使用 invoke，适合先确认鉴权、路径和模型名都正确。确认普通调用成功后，再测试流式输出：

for chunk in model.stream("分三点说明什么是 OpenAI 兼容 API"):
print(chunk.content, end="", flush=True)

LangChain 参考文档提供了流式调用方式，并说明流式 Token 用量需要服务端和客户端支持相应的 usage 数据；兼容接口未必返回该字段，因此不要把“能流式输出”和“能统计流式 Token”视为同一能力。ChatOpenAI 流式与 usage 参考

异步调用可使用 ainvoke 或 astream：

import asyncio

async def main():
response = await model.ainvoke("异步回答：什么是 API Router？")
print(response.content)

asyncio.run(main())

如果服务端只实现 Chat Completions，而模型名或客户端配置触发了其他接口路径，可能出现 404。对兼容服务排查时可显式设置 use_responses_api=False，先让请求走 Chat Completions 方向；这只是针对该类兼容端点的排查设置，最终以服务端支持的接口为准。ChatOpenAI 接口选择与兼容端点示例

model_kwargs 和 extra_body 不要混用

这是接入兼容 API 时最容易混淆的参数区别：

• model_kwargs：用于标准 OpenAI 请求参数中没有被 ChatOpenAI 显式声明、但仍应放在顶层请求体的参数，例如某些标准参数。
• extra_body：用于服务商自定义字段，例如 vLLM 或 LM Studio 的专用参数，字段会放到额外请求体中。

例如，服务端文档明确要求传入自定义字段时，可以写：

model = ChatOpenAI(
model="custom-model",
base_url="http://localhost:8000/v1",
api_key="EMPTY",
extra_body={"use_beam_search": True}
)

LangChain 参考页明确建议：非标准、供应商专用参数使用 extra_body，不要把这类字段放进 model_kwargs。如果只是传递标准参数，例如 max_completion_tokens 或 stream_options，再根据参数是否已被类显式支持决定直接传入或放进 model_kwargs。extra_body 参数说明

兼容 API 的工具调用、结构化输出与非标准字段

OpenAI 兼容主要表示请求和响应的某些接口形态相近，不代表所有高级能力都一致。工具调用需要服务端实现 OpenAI 风格的 tool calling，并且模型本身也要支持；LangChain 的 bind_tools 参考文档将其前提写为模型兼容 OpenAI 工具调用接口。bind_tools 官方参考

结构化输出可以通过 with_structured_output 配置 function_calling、json_mode 或 json_schema 等方法，但兼容服务是否支持这些模式、是否支持严格 Schema 校验，要以服务端能力为准。不要因为普通文本调用成功，就直接假设工具调用和结构化输出也能用。with_structured_output 官方参考

此外，ChatOpenAI 的官方参考明确说明，它主要面向 OpenAI 标准规格；第三方服务增加的非标准响应字段，例如某些推理内容字段，不一定会被提取或保留。如果业务依赖这些字段，应优先查找对应的 LangChain 专用供应商集成，而不是只修改 base_url。ChatOpenAI API 范围说明

401、404、模型不存在与请求格式错误排查表

建议按“最小请求、固定模型、固定路径、逐项增加参数”的顺序排查。不要一开始同时启用工具调用、结构化输出、流式 usage 和供应商自定义字段，否则很难判断是哪一层不兼容。

Python 与 JavaScript 的包名差异

如果项目使用 LangChain.js，安装包不是 Python 的 langchain-openai，而是：

npm install @langchain/openai @langchain/core

JavaScript 初始化时使用 ChatOpenAI，并通过配置对象传入模型和 Key；官方 JavaScript 参考还展示了通过 configuration.baseURL 设置基础地址的写法。LangChain.js OpenAI 集成参考

因此，Python 和 JavaScript 不要混用安装命令或参数名称：Python 侧重点是 langchain-openai、base_url；JavaScript 侧使用 @langchain/openai，具体基础地址参数按对应版本参考文档核对。

安全提醒与使用边界

本文介绍的是通用 OpenAI 兼容接口接入方法，本站为独立的 AI API 接入指南，不代表任何接口服务商的官方文档。不同服务的模型列表、计费、限速、并发和高级能力可能变化，具体信息应以目标服务商当前文档为准。

如果你已经完成 Key、Base URL 和模型名核对，但仍需要一个可用于开发测试的 AI API 接入入口，可在继续前先确认自己的调用场景、模型需求和安全策略。

常见问题

LangChain 接入 OpenAI 兼容 API 时，base_url 要不要写 /v1？

不能一概而论。许多兼容服务示例把 /v1 写在 base_url 中，但最终要以服务端实际路由为准。重点是避免重复拼接 /v1，并确认客户端最终请求的路径。

为什么 API Key 正确，LangChain 仍然返回 401？

先确认程序实际读取到的环境变量，再检查 Key 是否属于当前 base_url 指向的服务。排查时可显式传入 api_key，并用最小 invoke 请求验证，不要同时加入工具调用或自定义参数。

ChatOpenAI 能不能直接调用所有第三方模型？

不能保证。ChatOpenAI 主要面向 OpenAI 标准规格，第三方非标准响应字段和高级能力可能无法保留或调用。若业务依赖供应商专用字段，应查看对应的 LangChain 专用集成。

LangChain 的 model_kwargs 和 extra_body 有什么区别？

model_kwargs 主要用于标准请求参数的补充，extra_body 用于供应商自定义字段或需要嵌套传递的参数。兼容服务的专用参数优先按官方说明放入 extra_body。

为什么普通对话成功，但工具调用或结构化输出失败？

普通文本调用只说明基础请求链路可用，不代表服务端支持工具调用、JSON Schema、严格结构化输出或流式 Token 用量。需要逐项确认目标模型和服务端是否支持对应能力。

相关阅读

• OpenAI API 401 鉴权错误排查
• 模型不存在与 404 排查
• 上下文长度与 Token 限制
• 另一个客户端的 OpenAI 兼容配置示例

参考资料

1. OpenAI integration - Docs by LangChain（docs.langchain.com）
2. BaseChatOpenAI / ChatOpenAI 官方参考（reference.langchain.com）
3. langchain_openai 官方参考与 OpenAI 兼容 API 示例（reference.langchain.com）
4. extra_body 参数官方参考（reference.langchain.com）
5. bind_tools 官方参考（reference.langchain.com）
6. with_structured_output 官方参考（reference.langchain.com）
7. LangChain.js OpenAI 集成官方参考（reference.langchain.com）
8. reference.langchain.com（reference.langchain.com）