从安装到上线langchain-openai 实战指南一篇打通 OpenAI 接入 LangChain 的全部场景【免费下载链接】langchainThe agent engineering platform.项目地址: https://gitcode.com/GitHub_Trending/la/langchainlangchain-openai是 LangChain 官方维护的 OpenAI 集成包它基于openaiPython SDK把 GPT 系列聊天模型、传统补全模型和 Embedding 模型包装成 LangChain 标准接口BaseChatModel、BaseLLM、Embeddings让你可以直接在Runnable链、Agent 和工作流里调用 OpenAI。本文按想做什么来组织内容从三步拿到第一个回答到流式、工具调用、结构化输出再到 Responses API、向量化和 Azure/兼容服务落地最后汇总常见坑。三步拿到第一个回答uv 安装、配 Key、首次调用整个准备过程只需要三步。第一步安装。推荐用uv一条命令装好uv add langchain-openai不用uv的话pip install -U langchain-openai同样可以。当前版本为1.6.7见 pyproject.toml要求 Python3.10,4.0核心依赖是langchain-core1.6.6,2.0.0、openai2.45.0,4.0.0外加tiktoken本地 token 计数和certifiCA 证书。第二步配 Key。设置环境变量即可代码里不用再显式传api_keyexport OPENAI_API_KEYyour-api-key几个容易忽略的回退规则源码里写得很明确base_url未显式传入时依次回退到环境变量OPENAI_API_BASE、OPENAI_BASE_URLorganization回退到OPENAI_ORG_ID。第三步发第一个请求。from langchain_openai import ChatOpenAI model ChatOpenAI(modelgpt-4.1-mini, temperature0) messages [ (system, You are a helpful translator. Translate the user sentence to French.), (human, I love programming.), ] ai_msg model.invoke(messages) print(ai_msg.content) # 回答正文 print(ai_msg.usage_metadata) # {input_tokens: ..., output_tokens: ..., total_tokens: ...} print(ai_msg.response_metadata[finish_reason])invoke返回的是标准的AIMessage正文在contentresponse_metadata里有token_usage、model_name、system_fingerprint、finish_reason等信息usage_metadata是结构化的 token 统计。还有一个很实用的机制未被显式声明为类参数的参数会直接透传给底层openaiSDK 的create(...)。也就是说ChatOpenAI(..., frequency_penalty0.2)与每次调用时传invoke(..., frequency_penalty0.2)等价——OpenAI SDK 的完整参数面你都能用不必等 LangChain 逐个封装。场景一基础问答怎么发消息格式怎么写上一节的例子其实已经是一个完整的问答了这里把消息格式讲透。输入既可以是(role, content)元组也可以是消息对象SystemMessage、HumanMessage等来自langchain_core.messagesfrom langchain_core.messages import SystemMessage, HumanMessage messages [ SystemMessage(Answer in one sentence.), HumanMessage(What is LangChain?), ] ai_msg model.invoke(messages)多轮对话就是维护一个消息列表把上一轮的AIMessage和工具消息继续追加进去。 顺带一提如果你用的是非聊天式的纯补全模型如gpt-3.5-turbo-instruct走的是langchain_openai.llms里的OpenAI类用法一致model.invoke(The meaning of life is )直接返回字符串model.stream(...)逐段输出。日常开发 95% 的场景用ChatOpenAI就够了。场景二流式输出与异步调用怎么写同步流式stream返回的每个chunk是携带增量内容的AIMessageChunk直接打印.textfor chunk in model.stream(messages): print(chunk.text, end)需要拿完整消息就累加AIMessageChunk支持stream model.stream(messages) full next(stream) for chunk in stream: full chunk异步是另一组方法一一对应await model.ainvoke(messages) # 异步单次 async for chunk in model.astream(messages): ... await model.abatch([messages, other_messages]) # 异步批量注意两个实战细节流式时想要 token 统计必须显式开启stream_usageTrue它等价于在请求里下发stream_options{include_usage: True}然后从累加后的完整消息上读usage_metadatastream model.stream(messages, stream_usageTrue) full next(stream) for chunk in stream: full chunk print(full.usage_metadata)流式中断会抛出StreamChunkTimeoutError包顶层已导出需要区分网络断了和模型还在生成时可以针对它单独做重试逻辑。场景三工具调用怎么绑定custom_tool 是什么用 bind_tools 绑定 Pydantic 工具OpenAI 的函数调用协议在 LangChain 里对应的就是bind_tools工具用 Pydantic 模型定义from pydantic import BaseModel, Field class GetWeather(BaseModel): Get the current weather in a given location location: str Field(..., descriptionThe city and state, e.g. San Francisco, CA) model_with_tools model.bind_tools([GetWeather]) ai_msg model_with_tools.invoke(Which city is hotter today: LA or NY?) print(ai_msg.tool_calls) # [{name: GetWeather, args: {location: ...}, id: call_...}, ...]拿到tool_calls后你执行工具、把结果包成ToolMessage回传模型继续生成——这就是 Agent 循环的骨架。两个可调参数strictTrue可要求模型严格遵循工具参数的 JSON Schema并行工具调用默认开启parallel_tool_callsTrue。想关掉可以在调用时传invoke(..., parallel_tool_callsFalse)也可以model.bind(parallel_tool_callsFalse)或在初始化时通过model_kwargs固定。custom_tool自由格式输入的自定义工具OpenAI 的 Custom Tools 允许工具参数是自由格式的长字符串典型场景把整段代码丢给模型执行。仓库提供了custom_tool装饰器tools/custom_tool.py它会把你的函数返回值包装成{type: custom_tool_call_output, output: ...}from langchain_openai import ChatOpenAI, custom_tool custom_tool def execute_code(code: str) - str: Execute python code. return 27 model ChatOpenAI(modelgpt-5, output_versionresponses/v1) # 配合 LangGraph 的 create_react_agent(model, [execute_code]) 使用装饰器还支持format参数用上下文无关文法grammar约束工具输出格式。场景四结构化输出与 JSON 模式怎么选with_structured_output直接拿 Pydantic 对象让模型按你定义的 schema 输出返回的就是对象而不是字符串解析和校验一步到位from pydantic import BaseModel, Field class Joke(BaseModel): Joke to tell user. setup: str Field(descriptionThe setup of the joke) punchline: str Field(descriptionThe punchline to the joke) rating: int | None Field(descriptionHow funny the joke is, from 1 to 10) structured_model model.with_structured_output(Joke) joke structured_model.invoke(Tell me a joke about cats) # Joke(setupWhy was the cat sitting on the computer?, # punchlineTo keep an eye on the mouse!, ratingNone)JSON 模式只要合法 JSON不想上 schemabind(response_format{type: json_object})只保证输出是合法 JSON字段结构由你在 prompt 里约定json_model model.bind(response_format{type: json_object}) ai_msg json_model.invoke( Return a JSON object with key random_ints and a value of 10 random ints in [0-99] ) # ai_msg.content 是 JSON 字符串自行 json.loads经验法则字段需要类型/取值约束就上with_structured_output只是输出别带废话才用 JSON 模式。进阶模型调用Responses API、推理与 Flex 档位ChatOpenAI对 OpenAI 的 Responses API 支持已经比较完整三个开关model ChatOpenAI( model..., use_responses_apiTrue, # 请求改走 /v1/responses 通道 output_versionresponses/v1, # 新版消息格式 )注意output_versionresponses/v1会把推理摘要、内置工具调用等内容格式化进消息的content字段而不是塞在additional_kwargs里新应用建议统一用这个格式。推理模型reasoning通过reasoning参数控制思考力度与摘要reasoning { effort: medium, # low | medium | high summary: auto, # detailed | auto | None } model ChatOpenAI(model..., reasoningreasoning, output_versionresponses/v1) response model.invoke(What is 3^3?) for block in response.content: if block[type] reasoning: for summary in block[summary]: print(summary[text])会话状态续接Responses API 支持服务端保存会话。把上一次响应的 ID 作为previous_response_id传入即可延续对话不必每次重发全部历史response model.invoke(Hi, Im Bob.) second model.invoke( What is my name?, previous_response_idresponse.response_metadata[id], )也可以初始化时设use_previous_response_idTrue请求会自动丢弃到最近一次响应为止的输入消息并用最近响应 ID 填充previous_response_id。 源码提示对接 OpenAI 兼容端点且启用推理时如果遇到请求格式错误优先改用这个参数让服务端自己持有会话状态。服务端内置工具配合 Responses API 可以直接绑定 OpenAI 的服务端工具如网页搜索model ChatOpenAI(model..., output_versionresponses/v1) model_with_tools model.bind_tools([{type: web_search}])省钱档位service_tierflex走 flex 层级价格更低但响应可能更慢适合模型评测、数据增强等非实时任务beta 特性仅部分模型支持。向量化OpenAIEmbeddings 使用与长文本分块机制Embedding 部分实现langchain_core.embeddings.Embeddings接口embeddings/base.pyfrom langchain_openai import OpenAIEmbeddings embeddings OpenAIEmbeddings( modeltext-embedding-3-large, # dimensions1024 # text-embedding-3 及以后系列可指定输出维度 ) vector embeddings.embed_query(hello) # 单条 vectors embeddings.embed_documents([hello, goodbye]) # 批量 await embeddings.aembed_query(hello) # 异步几个关键默认值源码里可直接查到model默认text-embedding-ada-002embedding_ctx_length8191单次嵌入的最大 token 数chunk_size1000每个批次的文本条数max_retries2tiktoken_enabledTrue用 tiktoken 本地分词做长度校验。长文本怎么处理当文本超过embedding_ctx_length时它会被切块分别嵌入最终结果按各块的 token 数加权平均再归一化逻辑见_process_batched_chunked_embeddings。所以超长文档不会报错只是向量是多块的合成。⚠️ 接 OpenRouter、Ollama、vLLM 等兼容服务时的标准姿势embeddings OpenAIEmbeddings( model..., base_url..., check_embedding_ctx_lengthFalse, # 很多兼容服务不支持 token 化直接发原文 # encoding_formatfloat, # 避免 base64 编码问题 )生产落地Azure 部署、兼容服务与异常处理Azure OpenAI企业环境走 Azure 时换一套类名和环境变量export AZURE_OPENAI_API_KEYyour-api-key export AZURE_OPENAI_ENDPOINThttps://your-endpoint.openai.azure.com/from langchain_openai import AzureChatOpenAI model AzureChatOpenAI( azure_deploymentyour-deployment, # Azure 部署名 api_version2024-05-01-preview, # REST API 版本注意这不是模型版本 )两个容易混淆的点api_version是 Azure REST API 的版本号和模型版本无关model参数在 Azure 里只用于 tracing 和 token 计数不影响实际调用真正决定调用的是azure_deployment。还支持azure_ad_token/azure_ad_token_provider用 Microsoft Entra ID 令牌替代 API Key。Embeddings 与补全模型的 Azure 版本分别是AzureOpenAIEmbeddings和AzureOpenAI。OpenAI 兼容服务base_url 与 extra_body接 LM Studio、vLLM、Ollama 等本地或第三方服务时base_url指定地址、api_key填任意占位值即可# LM Studio支持 TTL 自动卸载 model ChatOpenAI( base_urlhttp://localhost:1234/v1, api_keylm-studio, modelmlx-community/QwQ-32B-4bit, extra_body{ttl: 300}, # 5 分钟无活动自动卸载模型 ) # vLLM model ChatOpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, modelmeta-llama/Llama-2-7b-chat-hf, extra_body{use_beam_search: True, best_of: 4}, )model_kwargs和extra_body的分工是踩坑重灾区记住一句话标准 OpenAI 参数走model_kwargs合并进请求体顶层如max_completion_tokens、modalities兼容服务商的自定义参数必须走extra_body嵌套在extra_body键下。自定义参数误塞进model_kwargs会直接报 API 错误。另外两点注意请求走/v1/chat/completions还是/v1/responses会部分依据模型名推断对接兼容服务时建议显式设use_responses_apiFalse消除歧义ChatOpenAI只解析官方 OpenAI 规范的响应字段第三方供应商加的非标准字段如reasoning_content、reasoning_details不会被提取保留。接 OpenRouter、DeepSeek 这类服务商优先用对应的专属包ChatOpenRouter、ChatDeepSeek。异常处理包把 OpenAI SDK 的异常统一翻译成了 LangChain 标准异常定义在 chat_models/base.py你可以按语义精确捕获限流抛OpenAIRateLimitError、上下文超长抛OpenAIContextOverflowError同时继承openai.BadRequestError和 LangChain 的ContextOverflowError、超时抛OpenAITimeoutError、连接问题抛OpenAIConnectionError认证/模型不存在/权限拒绝也各有对应类。统一兜底可以捕获基类ModelAPIError这一族。常见坑 FAQQ1自定义参数到底放model_kwargs还是extra_body标准 OpenAI 参数max_completion_tokens、stream_options、audio等放model_kwargs会拍平到请求体顶层vLLM 的use_beam_search、LM Studio 的ttl这类非标准参数放extra_body。放错位置会直接 API 报错。Q2流式调用后拿不到usage_metadata流式请求默认不带用量传stream_usageTrue再累加 chunk最后一个统计信息会合进full.usage_metadata。Q3长文本 embedding 报 token 超限默认embedding_ctx_length8191会自动分块后加权平均正常不会报错如果接的是兼容服务改用check_embedding_ctx_lengthFalse跳过本地分词校验直接发原文。Q4接了第三方服务响应里的reasoning_content之类的字段拿不到ChatOpenAI只认官方 OpenAI 规范字段供应商私货不会被保留。这种情况换供应商专属包。Q5限流、超时怎么兜底初始化时设max_retriesEmbeddings 默认 2 次处理可重试错误不可重试的按上面提到的异常类精确捕获后做降级或告警。Q6工具调用后 Agent 循环在非 OpenAI 端点上挂了试试ChatOpenAI(..., use_responses_apiTrue, use_previous_response_idTrue)让服务端保持会话状态绕开推理历史转发问题。一页速查包langchain-openai当前版本1.6.7Python3.10底层依赖openaiSDK安装uv add langchain-openai密钥export OPENAI_API_KEYyour-api-key端点回退链base_url→OPENAI_API_BASE→OPENAI_BASE_URL聊天ChatOpenAI(modelgpt-4.1-mini).invoke(messages)→ 返回AIMessage纯补全OpenAI(modelgpt-3.5-turbo-instruct).invoke(...)流式model.stream(msgs)要统计加stream_usageTrue流中断抛StreamChunkTimeoutError异步ainvoke/astream/abatch工具model.bind_tools([PydanticModel])读ai_msg.tool_calls自由字符串工具用custom_tool结构化输出model.with_structured_output(MyModel)轻量 JSONmodel.bind(response_format{type: json_object})向量化OpenAIEmbeddings(modeltext-embedding-3-large)长文本自动分块 token 加权平均Responses APIuse_responses_apiTrue, output_versionresponses/v1会话续接传previous_response_idservice_tierflex省钱AzureAzureChatOpenAI(azure_deployment..., api_version...)配AZURE_OPENAI_API_KEYAZURE_OPENAI_ENDPOINT兼容服务base_url指向服务地址自定义参数走extra_body必要时显式use_responses_apiFalse【免费下载链接】langchainThe agent engineering platform.项目地址: https://gitcode.com/GitHub_Trending/la/langchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考