langchain-openai 从第一行 invoke 到 Azure 部署：ChatOpenAI 流式、工具调用、Responses API 完整实战指南

langchain-openai 从第一行 invoke 到 Azure 部署ChatOpenAI 流式、工具调用、Responses API 完整实战指南【免费下载链接】langchainThe agent engineering platform.项目地址: https://gitcode.com/GitHub_Trending/la/langchain如果你要在 Python 里把 GPT 系列模型接进自己的业务langchain-openai是目前最省事的桥梁它把官方openaiSDK 的能力对齐成 LangChain 的标准接口ChatOpenAI负责聊天与流式输出OpenAIEmbeddings负责向量化Azure 三件套负责企业部署。本文按场景 能力两条线拆解这个包先给你一张能力总表定位每个类再按跑通 → 流式统计 → 工具与结构化 → 高级 API → Azure → 排错的实际落地顺序逐节展开每一节都只保留最短可运行片段和必须知道的坑。能力速查先对号入座找类在动手之前先花一分钟确认你要用的到底是哪个入口。下表是 langchain_openai/ 顶层导出的全部成员直接按场景对号入座类 / 符号模块适用场景一句话定位ChatOpenAIchat_models/绝大多数聊天场景继承BaseChatOpenAI同时覆盖 Chat Completions 与 Responses API 两条通道AzureChatOpenAI同上Azure 上部署的 OpenAI 服务增加azure_deployment、api_version等 Azure 专属字段OpenAIllms/非聊天的纯文本补全对应gpt-3.5-turbo-instruct这类 instruct 模型继承BaseLLMAzureOpenAI同上Azure 上的传统补全OpenAI的 Azure 变体OpenAIEmbeddingsembeddings/文本向量化内置超长文本分块 加权平均AzureOpenAIEmbeddings同上Azure 向量化OpenAIEmbeddings的 Azure 变体custom_tooltools/OpenAI 自定义工具装饰器让工具接受自由格式的长字符串输入StreamChunkTimeoutErrorchat_models._client_utils流式排错流式分块等待超时时抛出的异常它本质上是包装层而非替代品网络请求仍然走openaiSDK这个包负责参数对齐、response_metadata/usage_metadata的归一化以及把 OpenAI 的异常翻译成语义更清晰的 LangChain 异常。版本信息上当前发行版为1.6.7要求 Python3.10,4.0核心依赖是langchain-core1.6.6,2.0.0、openai2.45.0,4.0.0、tiktoken0.7.0,1.0.0和certifi具体见 pyproject.toml。从安装到密钥把第一条消息跑起来装包与配置密钥两条命令就能让环境就绪。官方推荐uvpip完全等价uv add langchain-openai # 或者 pip install -U langchain-openai密钥通过环境变量注入不用写进代码export OPENAI_API_KEYyour-api-key从 chat_models/base.py 的客户端参数定义可以确认解析优先级api_key缺省时读OPENAI_API_KEYorganization回退到OPENAI_ORG_IDbase_url则是显式传参 →OPENAI_API_BASE→OPENAI_BASE_URL三级回退最后一级由底层 SDK 接管。在 langchain 仓库内联调时pyproject.toml 的[tool.uv.sources]把langchain-core、langchain、langchain-tests指向../../core、../../langchain_v1、../../standard-tests的可编辑安装改动核心包无需重新打包。第一条消息与返回结构from langchain_openai import ChatOpenAI model ChatOpenAI(modelgpt-4.1-mini, temperature0, max_retries2) ai_msg model.invoke([ (system, You are a helpful translator. Translate to French.), (human, I love programming.), ]) print(ai_msg.content) print(ai_msg.usage_metadata) # input / output / total tokens返回值是标准AIMessage两个字段最常用usage_metadata给出input_tokens/output_tokens/total_tokensresponse_metadata携带model_name、finish_reason、system_fingerprint、token_usage开了logprobs时还有logprobs。生成侧常用参数是model、temperature、max_tokens、logprobs、stream_options客户端侧是timeout、max_retries、api_key、base_url、organization。这里有个很实用的透传机制任何没有被显式声明为类字段的参数都会原样塞进底层chat.completions.create(...)。所以ChatOpenAI(..., frequency_penalty0.2)、初始化后.bind(frequency_penalty0.2)、或者在invoke时临时传frequency_penalty0.2三者在请求层面完全等价——OpenAI SDK 的参数面在这里是完整可达的。流式输出与 token 统计两个最容易踩的坑边生成边打印for chunk in model.stream(messages): print(chunk.text, end)stream吐出的每个chunk都是AIMessageChunk需要聚合完整消息时直接累加full next(stream)然后循环full chunk。异步场景把invoke/stream/batch换成ainvoke/astream/abatch即可用法一一对应。流式里为什么看不到 usage这是生产环境最高频的疑问非流式调用自带usage_metadata流式却拿不到。原因是 OpenAI 默认不在流里推送用量必须显式要求。for chunk in model.stream(messages, stream_usageTrue): if chunk.usage_metadata: print(chunk.usage_metadata)stream_usageTrue等价于在请求里下发stream_options{include_usage: True}初始化时传stream_options也能达到同样效果。忘记开这个开关流式日志里就永远只有内容、没有账本。工具调用与结构化输出让模型按规矩办事bind_tools 绑定 Pydantic 工具ChatOpenAI原生对接 OpenAI 函数调用协议工具定义就是普通的 Pydantic 模型from pydantic import BaseModel, Field class GetWeather(BaseModel): Get the current weather in a given location location: str Field(..., descriptionCity 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)三个控制旋钮值得记住strictTrue强制模型严格遵循参数的 JSON Schemaparallel_tool_calls默认TrueOpenAI SDK1.32起支持想禁用可以在invoke(..., parallel_tool_callsFalse)临时关也可以.bind(parallel_tool_callsFalse)固定还能通过model_kwargs在初始化时写死。结构化输出、JSON 模式与 custom_toolclass Joke(BaseModel): setup: str Field(descriptionThe setup of the joke) punchline: str Field(descriptionThe punchline to the joke) rating: int | None Field(descriptionHow funny, 1 to 10) result model.with_structured_output(Joke).invoke(Tell me a joke about cats)with_structured_output直接返回 Pydantic 实例而纯 JSON 约束走model.bind(response_format{type: json_object})模型返回原始 JSON 字符串需要自己解析。另一条路是 OpenAI 的自定义工具Custom Tools工具输入是一段自由格式的长字符串而不是结构化参数。tools/custom_tool.py 里的装饰器会把函数返回值包装成{type: custom_tool_call_output, output: ...}结构from langchain_openai import custom_tool custom_tool def execute_code(code: str) - str: Execute python code. return 27装饰器还支持format参数为工具输出附加上下文无关文法grammar约束。Responses API推理展示、服务端会话与 flex 计费开启方式与 output_versionChat Completions 之外的新通道/v1/responses两个开关即可启用model ChatOpenAI( model..., use_responses_apiTrue, output_versionresponses/v1, )output_versionresponses/v1的作用是把推理摘要、内置工具调用这类响应条目直接格式化进消息的content字段而不是塞在additional_kwargs里——新应用建议直接采用这种输出版本。推理模型与 reasoning 参数推理模型的思考过程可以要求服务端摘要后回传类比成先给你剧透版剧情再给正文reasoning {effort: medium, summary: auto} # effort: low|medium|high; summary: 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])会话状态续接与 service_tierResponses API 允许服务端替你保管上下文像电话免提一样只要把上一轮的响应 ID 回传历史消息就不用重复发送。first model.invoke(Hi, Im Bob.) second model.invoke( What is my name?, previous_response_idfirst.response_metadata[id], )初始化时设use_previous_response_idTrue可以全自动请求载荷自动丢弃到最近一次响应为止的输入并用最近响应 ID 填充previous_response_id。对接 OpenAI 兼容端点又启用了推理时如果频繁出现请求格式错误优先切换到use_previous_response_idTrue让会话状态交给服务端保管比客户端拼装历史更稳。成本档位方面service_tierflex选择更便宜的 flex 层级代价是响应更慢、资源不保证可用beta 特性仅部分模型支持适合批量评测、数据增强这类离线任务。Azure OpenAI 部署参数、环境变量与令牌认证环境变量与最小配置Azure 的寻址方式与官方 API 完全不同——不是模型名而是部署名 REST API 版本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-name, api_version2024-..., # Azure REST API 版本注意不是模型版本 )字段定义见 chat_models/azure.pyazure_endpoint缺省读AZURE_OPENAI_ENDPOINTopenai_api_type用于兼容旧式配置。Embeddings 与补全模型的 Azure 变体AzureOpenAIEmbeddings、AzureOpenAI分别位于 embeddings/azure.py 和 llms/azure.py字段约定与聊天模型一致。用 Entra ID 令牌替代 API Key企业内网环境常常禁用静态密钥Azure 支持基于 Microsoft Entra ID原 Azure AD的令牌认证model AzureChatOpenAI( azure_deploymentyour-deployment-name, azure_ad_tokentoken, # 或 azure_ad_token_provider 动态提供令牌 )azure_ad_token适合短生命周期的静态令牌azure_ad_token_provider适合需要自动刷新的场景二者选其一即可替代api_key。生产排错异常映射、兼容服务与工程化九类异常一张表OpenAI SDK 的裸异常对业务代码不友好chat_models/base.py 做了完整映射让你用except精准分层处理异常类继承关系触发场景OpenAIContextOverflowErroropenai.BadRequestErrorContextOverflowError上下文超长OpenAIAuthenticationErroropenai.AuthenticationErrorModelAuthenticationError密钥无效 / 认证失败OpenAIPermissionDeniedError权限拒绝类无访问权限OpenAIInvalidRequestErroropenai.BadRequestErrorModelInvalidRequestError请求体非法OpenAIModelNotFoundErroropenai.NotFoundErrorModelNotFoundError模型名不存在OpenAIRateLimitErroropenai.RateLimitErrorModelRateLimitError触发限流OpenAIAPIErroropenai.InternalServerErrorModelAPIError服务端 5xxOpenAIConnectionErroropenai.APIConnectionErrorModelConnectionError连接失败OpenAITimeoutErroropenai.APITimeoutErrorModelTimeoutError请求超时统一捕获策略建议OpenAIRateLimitError走指数退避重试OpenAIContextOverflowError走截断或压缩上下文OpenAIConnectionError/OpenAITimeoutError交给max_retries自动兜底。兼容服务base_url 与 extra_body 的分工LM Studio、vLLM、Ollama 这类 OpenAI 兼容服务只需要换base_url就能接进来但参数放置位置有讲究# LM Studio支持 TTL 自动卸载 model ChatOpenAI( base_urlhttp://localhost:1234/v1, api_keylm-studio, # 任意非空字符串即可 modelmlx-community/QwQ-32B-4bit, extra_body{ttl: 300}, ) # 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}, )参数路由规则源码 docstring 明确约定参数容器落点典型用途model_kwargs合并进请求体顶层标准 OpenAI 参数max_completion_tokens、stream_options、modalities、audioextra_body嵌套在extra_body键下兼容服务商私有参数vLLM 的use_beam_search、LM Studio 的ttl两条硬性提醒私有参数误放进model_kwargs会直接触发 API 报错同时模型名可能触发 Responses API 路由/v1/chat/completions与/v1/responses的选择部分依据模型名推断与base_url无关对接兼容服务请显式设use_responses_apiFalse。另外ChatOpenAI只遵循官方 API 规范第三方响应里的非标准字段如reasoning_content不会被提取保留接 DeepSeek、OpenRouter 建议用各自的专属包。工程化测试、快照与静态检查单测集中在 tests/unit_tests覆盖chat_models、embeddings、llms、token 计数、兼容层与密钥加载集成测试放在 tests/integration_tests用vcrpy录制回放真实 API 交互避免重复计费。pyproject.toml 中的质量门槛pytest 默认带--snapshot-warn-unused --strict-markers --covlangchain_openairuff 开启select [ALL]并采用 Google 风格 docstringmypy 设了disallow_untyped_defs true。跨包一致性则由 libs/standard-tests/ 的标准测试套件统一校验。向量化与遗留补全补齐剩下的两块拼图OpenAIEmbeddings 的分块加权机制默认模型是text-embedding-ada-002text-embedding-3系列可以加dimensions指定输出维度from langchain_openai import OpenAIEmbeddings embeddings OpenAIEmbeddings(modeltext-embedding-3-large, dimensions1024) vec embeddings.embed_query(hello) vecs embeddings.embed_documents([hello, goodbye])关键默认值一览定义见 embeddings/base.py参数默认值说明embedding_ctx_length8191单条文本嵌入前允许的最大 token 数chunk_size1000单批请求的文本条数max_retries2最大重试次数request_timeoutNonefloat /httpx.Timeout/ Nonetiktoken_enabledTrue本地分词计数False时改用 transformers 分词tiktoken_model_nameNone指定计费用 tiktoken 模型Azure / 兼容服务适用show_progress_barFalse批量嵌入时显示进度条skip_emptyFalse是否跳过空字符串它的长文本策略可以类比把长文拆成几段分别打分再按篇幅加权出总分超过embedding_ctx_length的文本会被切块分别嵌入最后按各块 token 数加权平均并归一化逻辑在_process_batched_chunked_embeddings里。对 OpenRouter、Ollama、vLLM 这类兼容服务很多实现不支持本地分词建议check_embedding_ctx_lengthFalse直接发原文必要时再加encoding_formatfloat绕开 base64 编码问题。传统补全OpenAI 类非聊天的 instruct 风格补全模型走 llms/base.py 的OpenAI类继承BaseLLM接口形态与ChatOpenAI类似但输入是纯字符串from langchain_openai import OpenAI llm OpenAI(modelgpt-3.5-turbo-instruct, temperature0, max_retries2) print(llm.invoke(The meaning of life is )) for piece in llm.stream(The meaning of life is ): print(piece, end|)选型落点聊天、工具、结构化输出、Responses API 一律用ChatOpenAI只有维护 instruct 系列老模型时才用OpenAI向量入库用OpenAIEmbeddings企业 Azure 环境把三个类分别换成Azure前缀版本其余代码基本不动。【免费下载链接】langchainThe agent engineering platform.项目地址: https://gitcode.com/GitHub_Trending/la/langchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考