企业官网建设流程全解析

langchain-openai ChatOpenAI 实战：从安装到流式、工具、向量化一次跑通

【免费下载链接】langchainThe agent engineering platform.项目地址: https://gitcode.com/GitHub_Trending/la/langchain

langchain-openai 是 LangChain 官方维护的 OpenAI 集成包，它基于openaiSDK 把 GPT 系列聊天模型、补全模型与 Embedding 模型包装成 LangChain 标准接口，让模型对象可以直接参与链、Agent 与检索工作流。这篇 ChatOpenAI 实战指南面向需要把 GPT 接入 LangChain 的开发者，10 分钟跑通安装与首次调用，再覆盖流式输出、工具调用、结构化输出、向量化与多环境部署。

十分钟跑通：安装 langchain-openai 并发起第一次 ChatOpenAI 调用

✅ 三步完成：装包、配密钥、写最小调用。

uv add langchain-openai # 或 pip install -U langchain-openai export OPENAI_API_KEY="your-api-key"

from langchain_openai import ChatOpenAI model = ChatOpenAI(model="gpt-4.1-mini", temperature=0) ai_msg = model.invoke("把 'I love programming' 翻译成法语") print(ai_msg.content) print(ai_msg.usage_metadata) # {"input_tokens": ..., "output_tokens": ..., "total_tokens": ...}

返回的是标准AIMessage，response_metadata里带有token_usage、model_name、finish_reason等字段。注意api_key未显式传入时会自动读取OPENAI_API_KEY环境变量，organization回退到OPENAI_ORG_ID，一般无需手写。

💡 任何未被显式声明的参数都会原样透传给底层chat.completions.create，例如ChatOpenAI(..., frequency_penalty=0.2)与每次调用时传入frequency_penalty=0.2等价，OpenAI SDK 的完整参数面都可用。

功能实战：ChatOpenAI 的五个高频任务

逐字输出响应：流式调用与用量统计

对话类应用最关心"先出字"。stream返回一系列AIMessageChunk，直接相加即可聚合出完整消息：

stream = model.stream(messages) full = next(stream) for chunk in stream: full += chunk print(full.content) # 需要用量统计时：model.stream(messages, stream_usage=True)

流式场景下默认不返回 token 用量，传入stream_usage=True（等价于下发stream_options={"include_usage": True}）后，聚合消息的usage_metadata才有值。异步侧对应ainvoke/astream/abatch，接口与同步版一一对应。

绑定工具，让模型替你调用

需要查天气、查数据库时，用 Pydantic 模型描述工具参数即可，无需手写 JSON Schema：

from pydantic import BaseModel, Field class GetWeather(BaseModel): """Get the current weather in a given location""" location: str = Field(..., description="The city, e.g. San Francisco, CA") tool_model = model.bind_tools([GetWeather]) ai_msg = tool_model.invoke("Which city is hotter today: LA or NY?") print(ai_msg.tool_calls)

bind_tools支持strict=True强制模型严格遵循参数 Schema；parallel_tool_calls默认开启，可在invoke时传False关闭，也可用model.bind(parallel_tool_calls=False)固化。

直接拿到结构化结果

想让返回值直接变成对象，with_structured_output是最短路径：

from pydantic import BaseModel, Field class Joke(BaseModel): setup: str = Field(description="The setup of the joke") punchline: str = Field(description="The punchline") structured = model.with_structured_output(Joke) print(structured.invoke("Tell me a joke about cats")) # Joke(setup=..., punchline=...)

如果只是要一段合法 JSON 字符串，用model.bind(response_format={"type": "json_object"})开启 JSON 模式即可。

把文本变成向量：Embeddings 与超长文本

向量化是检索类应用的入口，OpenAIEmbeddings实现 LangChain 的Embeddings接口，同步异步都有：

from langchain_openai import OpenAIEmbeddings embeddings = OpenAIEmbeddings(model="text-embedding-3-large", dimensions=1024) print(embeddings.embed_query("hello")) print(len(embeddings.embed_documents(["hello", "goodbye"])))

文本太长怎么办？超过embedding_ctx_length（默认 8191 token）的文本会被自动切块分别嵌入，再按各块 token 数加权平均并归一化，实现见 embeddings/base.py 的_process_batched_chunked_embeddings。对 OpenRouter、Ollama、vLLM 等兼容服务，建议设置check_embedding_ctx_length=False跳过本地 token 化，避免分词器不认识模型名。

延续多轮会话：Responses API 与服务端状态

ChatOpenAI支持走 Responses API 通道，服务端可帮你保留会话状态，不必每轮都重发全部历史：

model = ChatOpenAI(model="gpt-5", use_responses_api=True, output_version="responses/v1") resp = model.invoke("Hi, I'm Bob.") resp2 = model.invoke("What is my name?", previous_response_id=resp.response_metadata["id"])

output_version="responses/v1"会把推理摘要、内置工具调用等条目放进消息的content字段而非additional_kwargs，新应用推荐开启。初始化时也可以直接use_previous_response_id=True，请求会自动丢弃到最近一次响应为止的历史消息。此时还能绑定 OpenAI 服务端内置工具，如model.bind_tools([{"type": "web_search"}])获得网页搜索；自由长文本输入的自定义工具则用包内导出的custom_tool装饰器定义。

ChatOpenAI 关键参数速查表

多环境接入：Azure、兼容端点与传统补全模型

Azure 企业部署。把环境变量换成 Azure 一套，改用AzureChatOpenAI：

export AZURE_OPENAI_API_KEY="your-api-key" export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"

from langchain_openai import AzureChatOpenAI model = AzureChatOpenAI( azure_deployment="your-deployment-name", api_version="2024-05-01-preview", # Azure REST API 版本，不是模型版本 )

api_version是 Azure REST 接口版本，与底层模型版本无关，别混用。也支持azure_ad_token做 Azure AD 令牌认证；向量与补全模型对应AzureOpenAIEmbeddings、AzureOpenAI。

OpenAI 兼容端点。base_url指到 vLLM、Ollama、LM Studio 即可复用同一套代码：

model = ChatOpenAI( base_url="http://localhost:8000/v1", api_key="EMPTY", model="meta-llama/Llama-2-7b-chat-hf", use_responses_api=False, # 避免模型名触发 Responses API 路由 extra_body={"use_beam_search": True, "best_of": 4}, # vLLM 专属参数 )

⚠️ 标准 OpenAI 参数走model_kwargs（合并进请求体顶层，如max_completion_tokens、audio）；服务商自定义参数必须走extra_body（嵌套在该键下）。自定义参数误用model_kwargs会直接触发 API 报错。另外，ChatOpenAI只对齐官方 OpenAI 响应规范，第三方私有的reasoning_content等字段不会被提取，对接 OpenRouter、DeepSeek 等建议优先用对应的供应商专属包。

传统补全模型。如果用的是非聊天式模型（如gpt-3.5-turbo-instruct），入口是OpenAI类：OpenAI(model="gpt-3.5-turbo-instruct").invoke("The meaning of life is ")，同样支持stream与异步调用。

排错与常见坑

包内把 OpenAI SDK 的异常统一映射为 LangChain 标准异常（定义在 chat_models/base.py），便于except分类捕获。高频问题对照：

按场景选入口

langchain-openai 的本质是给 OpenAI SDK 加了一层 LangChain 标准化的"外壳"：invoke/stream/bind_tools这些接口让你在换模型时几乎不用改业务代码。建议从ChatOpenAI的基本调用起步，遇到多轮状态再开 Responses API，接入私有服务时把extra_body与use_responses_api=False记在手上，绝大多数落地问题都有现成答案。

【免费下载链接】langchainThe agent engineering platform.项目地址: https://gitcode.com/GitHub_Trending/la/langchain