LangChain models：模型使用完全指南

LangChain中的LLM/聊天模型是其核心组件，作为AI智能体的推理引擎，支持文本生成、工具调用、多模态处理等能力，且通过标准化接口实现了不同模型提供商的无缝切换。

一、模型核心概述 🧠

LLM（大语言模型）是能像人类一样解读和生成文本的强大AI工具，无需为每个任务做专门训练，即可完成内容创作、翻译、摘要、问答等工作。 除基础文本生成外，主流模型还支持以下核心能力：

• ⚙️ 工具调用：调用外部工具（如数据库查询|API调用）并将结果融入回复

• 📋 结构化输出：让模型回复严格遵循自定义的格式规范

• 🖼️ 多模态：处理/返回文本外的其他数据（图片|音频|视频）

• 🧐 推理：通过多步推理得出问题结论

核心定位

模型是LangChain智能体（Agent）的推理引擎，决定智能体的决策流程：调用哪些工具→如何解析工具结果→何时返回最终答案。 模型的质量直接决定智能体的可靠性和性能，不同模型有不同的擅长场景：

• 部分擅长执行复杂指令 | 部分擅长结构化推理 | 部分支持超大上下文窗口（处理海量信息）

接口优势

LangChain的标准化模型接口适配了几乎所有主流模型提供商，可轻松实验、切换不同模型，找到适配业务场景的最优解。

二、模型的基础使用方式 📌

LangChain中的模型有两种核心使用形式，且两种形式共用一套模型接口，可从简单的独立使用平滑升级为复杂的智能体工作流：

1. 与智能体结合：创建智能体时动态指定模型，由模型驱动智能体完成复杂任务

2. 独立使用：在智能体循环外直接调用模型，完成文本生成、分类、信息提取等简单任务

三、模型初始化 🔧

LangChain中初始化独立模型最简便的方式是使用**init_chat_model函数，可适配所有主流模型提供商，只需指定模型名称+配置密钥即可。 以下是六大主流提供商的初始化代码示例，包含依赖安装+代码逐行解析**，所有示例均为LangChain官方推荐写法。

通用说明

• 环境变量：各提供商需配置专属API密钥/端点，通常通过os.environ设置，也可在初始化时直接传入

• init_chat_model：统一初始化入口，自动适配不同提供商的模型类，替代了传统的逐个导入ChatOpenAI/ChatAnthropic等类的方式

• 模型标识：可通过provider:model格式指定（如google_genai:gemini-2.5-flash-lite），明确提供商和模型

3.1 OpenAI 初始化

# 安装OpenAI集成依赖
pip install -U "langchain[openai]"

import os
from langchain.chat_models import init_chat_model

# 设置OpenAI API密钥（从OpenAI官网申请，格式为sk-xxx）
os.environ["OPENAI_API_KEY"] = "sk-..."
# 初始化gpt-4.1模型
model = init_chat_model("gpt-4.1")

代码解析：

• 导入init_chat_model：LangChain统一的聊天模型初始化函数

• os.environ["OPENAI_API_KEY"]：设置OpenAI的身份验证密钥，不配置则无法调用API

• init_chat_model("gpt-4.1")：自动识别为OpenAI模型，返回可直接调用的模型对象

3.2 Anthropic 初始化

pip install -U "langchain[anthropic]"

import os
from langchain.chat_models import init_chat_model

os.environ["ANTHROPIC_API_KEY"] = "sk-..."
# 初始化Claude最新版模型
model = init_chat_model("claude-sonnet-4-5-20250929")

3.3 Azure OpenAI 初始化

pip install -U "langchain[openai]"

import os
from langchain.chat_models import init_chat_model

# 配置Azure OpenAI专属环境变量
os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..." # Azure的模型访问端点（如https://xxx.openai.azure.com/）
os.environ["OPENAI_API_VERSION"] = "2025-03-01-preview" # API版本

# 初始化Azure OpenAI的gpt-4.1模型
model = init_chat_model(
    "azure_openai:gpt-4.1",
    azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"], # Azure的模型部署名
)

关键说明：Azure OpenAI需额外配置部署名和端点，与原生OpenAI区分开。

3.4 Google Gemini 初始化

pip install -U "langchain[google-genai]"

import os
from langchain.chat_models import init_chat_model

os.environ["GOOGLE_API_KEY"] = "..." # Google AI Studio申请的密钥
model = init_chat_model("google_genai:gemini-2.5-flash-lite")

3.5 AWS Bedrock 初始化

pip install -U "langchain[aws]"

from langchain.chat_models import init_chat_model

# 无需手动设置环境变量，需提前通过AWS CLI配置凭证（参考官方链接）
model = init_chat_model(
    "anthropic.claude-3-5-sonnet-20240620-v1:0",
    model_provider="bedrock_converse", # 指定为Bedrock提供商
)

关键说明：Bedrock的凭证需通过AWS CLI/控制台配置，而非直接设置环境变量。

3.6 HuggingFace 初始化

pip install -U "langchain[huggingface]"

import os
from langchain.chat_models import init_chat_model

os.environ["HUGGINGFACEHUB_API_TOKEN"] = "hf_..." # HuggingFace官网申请的令牌
model = init_chat_model(
    "microsoft/Phi-3-mini-4k-instruct", # HuggingFace上的模型仓库名
    model_provider="huggingface", # 指定为HuggingFace提供商
    temperature=0.7, # 自定义模型参数
    max_tokens=1024, # 自定义模型参数
)

关键说明：可直接调用HuggingFace Hub上的开源模型，支持传入自定义模型参数。

初始化后快速调用

无论哪种提供商，初始化完成后均可通过**invoke**快速调用模型：

# 向模型提问并获取回复
response = model.invoke("为什么鹦鹉会学人说话？")
print(response)

四、模型核心方法 📡

LangChain为模型对象提供了三大核心调用方法，适配不同的业务场景，所有提供商的模型均支持这一套方法，实现接口统一。

4.1 Invoke：同步单次调用

作用：向模型传入输入（单条消息/对话历史），等待模型生成完整回复后一次性返回，是最基础、最常用的方法。 适用场景：简单问答、短文本生成、信息提取等无需实时展示的场景。 核心特点：同步阻塞 | 返回完整的AIMessage对象（包含文本、元数据等）。

4.2 Stream：流式实时调用

作用：向模型传入输入，模型生成内容时实时返回消息块（Chunk），无需等待完整回复，可实现“打字机效果”。 适用场景：聊天机器人、长文本生成等需要提升用户体验的场景。 核心特点：异步非阻塞 | 返回AIMessageChunk迭代器 | 消息块可聚合为完整AIMessage。

4.3 Batch：批量并行调用

作用：向模型一次性传入多个独立的输入请求，模型并行处理所有请求并返回结果列表，相比循环调用invoke，性能更高、成本更低。 适用场景：批量文本生成、批量问答、批量分类等需要处理大量独立请求的场景。 核心特点：并行处理 | 批量返回 | 支持控制最大并发数。

除上述三大核心方法外，LangChain还支持嵌入模型、向量库等周边技术的集成，可参考官方集成页面。

五、模型配置参数 ⚙️

初始化模型时，可通过关键字参数（kwargs）传入配置参数，控制模型的行为。参数分为标准通用参数（所有提供商均支持）和提供商专属参数（仅特定提供商支持）。

5.1 标准通用参数（必看）

所有模型均支持以下核心参数，是调优模型的关键：

参数名	类型	必选	核心作用 & 示例说明
model	字符串	是	模型名称/标识，可通过provider:model格式指定（如openai:o1）
api_key	字符串	否	模型提供商的身份验证密钥，通常通过环境变量设置，无需手动传入
temperature	数字	否	控制模型输出的随机性，0→1，值越高越有创意，值越低越确定 🔹 示例：temperature=0（适合问答）
max_tokens	数字	否	限制模型输出的Token总数，控制回复长度 🔹 示例：max_tokens=512（限制回复最多512个Token）
timeout	数字	否	模型请求的超时时间（秒），超时则取消请求 🔹 示例：timeout=30（30秒超时）
max_retries	数字	否	请求失败时的最大重试次数（网络超时/速率限制时触发） 🔹 示例：max_retries=3（最多重试3次）

5.2 传入参数的代码示例

# 初始化模型时传入自定义参数
model = init_chat_model(
    "claude-sonnet-4-5-20250929", # 模型标识
    temperature=0.7, # 中等随机性
    timeout=30, # 30秒超时
    max_tokens=1000, # 输出最多1000个Token
)

5.3 提供商专属参数

不同提供商的模型有专属参数，例如OpenAI的ChatOpenAI支持use_responses_api（指定使用Responses/Completions API）。 查询方式：可前往LangChain官方的聊天模型集成页面，查看对应提供商的所有支持参数。

六、模型的具体调用方式 📞

模型的三大核心方法对应不同的调用写法，以下对Invoke/Stream/Batch分别做代码示例+详细解析，并补充高级用法。

6.1 Invoke：同步单次调用

支持单条消息和对话历史两种输入形式，对话历史可实现多轮聊天。

6.1.1 单条消息调用

# 传入单条文本消息
response = model.invoke("为什么鹦鹉的羽毛五颜六色？")
print(response) # 输出完整的AIMessage对象

6.1.2 对话历史调用

对话历史需指定消息角色（system/user/assistant），模型会根据历史上下文生成回复，支持字典格式和Message对象格式（推荐）。

方式1：字典格式（简单易用）

# 定义对话历史，包含系统提示、用户问题、助手回复、新的用户问题
conversation = [
    {"role": "system", "content": "你是一个将英语翻译成法语的助手。"},
    {"role": "user", "content": "翻译：I love programming."},
    {"role": "assistant", "content": "J'adore la programmation."},
    {"role": "user", "content": "翻译：I love building applications."}
]
# 传入对话历史
response = model.invoke(conversation)
print(response) # AIMessage("J'adore créer des applications.")

方式2：Message对象格式（功能更全，推荐）

# 导入LangChain的消息对象
from langchain.messages import HumanMessage, AIMessage, SystemMessage

# 用消息对象定义对话历史
conversation = [
    SystemMessage("你是一个将英语翻译成法语的助手。"), # 系统提示：定义模型的角色
    HumanMessage("翻译：I love programming."), # 人类消息：用户的问题
    AIMessage("J'adore la programmation."), # 助手消息：模型的历史回复
    HumanMessage("翻译：I love building applications.") # 新的人类消息
]
# 调用模型
response = model.invoke(conversation)
print(response) # AIMessage("J'adore créer des applications.")

关键说明

• 消息角色：system（系统提示，定义模型行为）| user（用户输入）| assistant（模型历史回复）

• 返回类型：LangChain聊天模型返回AIMessage对象，而传统的文本补全LLM直接返回字符串；聊天模型均以Chat为前缀（如ChatOpenAI）。

6.2 Stream：流式实时调用

返回消息块迭代器，可通过循环实时获取内容，还支持消息块聚合、事件流式输出等高级用法。

6.2.1 基础流式调用（打字机效果）

# 流式调用模型，循环获取消息块
for chunk in model.stream("为什么鹦鹉的羽毛五颜六色？"):
    print(chunk.text, end="|", flush=True) # 实时打印，| 分隔消息块

输出效果：为|什|么|鹦|鹉|的|羽|毛|五|颜|六|色|？|鹦|鹉|的|羽|毛|五|颜|六|色|主|要|是|为|了|...

6.2.2 消息块聚合（还原完整回复）

流式返回的AIMessageChunk可通过**+**聚合为完整的AIMessage，与invoke的返回结果一致：

full = None # 初始化完整消息对象
for chunk in model.stream("天空是什么颜色的？"):
    # 聚合消息块
    full = chunk if full is None else full + chunk
    print(full.text) # 实时打印聚合后的内容

# 聚合完成后，可像使用invoke结果一样使用full
print(full.content_blocks) # 输出完整的内容块

输出效果：

天
天空
天空是
天空是蓝色的
天空是蓝色的，因为...

6.2.3 高级：事件流式输出（astream_events）

通过astream_events可流式获取模型调用的全生命周期事件（开始/流式/结束），方便过滤和监控，支持异步调用：

import asyncio # 导入异步库

# 定义异步调用函数
async def stream_events_demo():
    async for event in model.astream_events("你好"):
        if event["event"] == "on_chat_model_start":
            print(f"请求输入：{event['data']['input']}")
        elif event["event"] == "on_chat_model_stream":
            print(f"实时Token：{event['data']['chunk'].text}")
        elif event["event"] == "on_chat_model_end":
            print(f"完整回复：{event['data']['output'].text}")

# 执行异步函数
asyncio.run(stream_events_demo())

输出效果：

请求输入：你好
实时Token：你
实时Token：好
实时Token：！
实时Token：我
实时Token：是
完整回复：你好！我是LangChain调用的AI助手，请问有什么可以帮你的？

6.2.4 自动流式（Auto-streaming）

LangChain支持自动流式，即使调用invoke方法，若检测到应用处于流式模式（如LangGraph智能体），会自动切换为流式输出，并触发on_llm_new_token回调事件，无需手动调用stream。

6.3 Batch：批量并行调用

支持批量输入、按完成顺序返回、控制最大并发数三种用法，适合处理大量独立请求。

6.3.1 基础批量调用

# 定义批量输入列表（多个独立问题）
batch_inputs = [
    "为什么鹦鹉的羽毛五颜六色？",
    "飞机是怎么飞起来的？",
    "什么是量子计算？"
]
# 批量调用模型
responses = model.batch(batch_inputs)
# 遍历输出结果
for response in responses:
    print(response.text)

关键说明：batch是客户端侧的并行调用，与OpenAI/Anthropic的服务端批量API不同，需注意区分。

6.3.2 按完成顺序返回（batch_as_completed）

batch会等待所有请求处理完成后统一返回，batch_as_completed会每完成一个请求就立即返回，结果可能乱序，包含输入索引方便还原：

# 按完成顺序返回结果
for response in model.batch_as_completed(batch_inputs):
    print(response.text) # 先完成的请求先输出

6.3.3 控制最大并发数

处理大量输入时，可通过RunnableConfig的max_concurrency限制并行调用数，避免触发提供商的速率限制：

# 批量调用并设置最大并发数为5
responses = model.batch(
    batch_inputs,
    config={
        'max_concurrency': 5, # 最多同时处理5个请求
    }
)

七、工具调用（Tool Calling） ⚙️

工具调用是LangChain模型的核心能力，模型可根据用户请求自动选择并调用外部工具，将工具结果融入最终回复，是实现智能体的基础。 别名：工具调用也常被称为函数调用（Function Calling），二者含义完全一致。

7.1 工具调用的核心概念

1. 工具的组成：每个工具包含Schema（模式，定义工具名称/描述/参数） + 执行函数（实现工具的实际功能）

2. 调用流程：用户提问→模型分析请求并决定调用的工具→执行工具获取结果→模型处理结果并生成最终回复

3. 核心方法：通过bind_tools将工具绑定到模型，模型即可在调用时选择使用工具

7.2 基础：绑定自定义工具

通过@tool装饰器可快速定义自定义工具，再通过bind_tools绑定到模型，代码示例+解析如下：

# 导入tool装饰器
from langchain.tools import tool

# 定义自定义工具：获取天气
# @tool装饰器会自动生成工具的Schema（名称/描述/参数）
@tool
def get_weather(location: str) -> str:
    """获取指定地点的天气情况（工具描述，模型会根据此描述判断是否调用）"""
    return f"{location}今天是晴天，气温25℃。"

# 将工具绑定到模型，生成带工具的模型对象
model_with_tools = model.bind_tools([get_weather])  

# 向模型提问，触发工具调用
response = model_with_tools.invoke("波士顿的天气怎么样？")
# 解析模型的工具调用请求
for tool_call in response.tool_calls:
    print(f"调用工具：{tool_call['name']}")
    print(f"工具参数：{tool_call['args']}")

输出效果：

调用工具：get_weather
工具参数：{'location': 'Boston'}

关键说明：

• @tool装饰器：自动将普通函数转为LangChain的Tool对象，函数的文档字符串会作为工具描述，模型会根据描述判断是否调用

• bind_tools：绑定工具后，模型的返回结果会包含tool_calls字段，存储工具调用的名称和参数

• 独立使用模型时：需手动执行工具并将结果返回给模型；与智能体结合时，智能体循环会自动处理工具执行和结果返回

7.3 工具执行循环（手动实现）

模型返回工具调用请求后，需手动执行工具并将工具结果作为消息传入模型，模型会根据工具结果生成最终回复，形成完整的调用循环：

# 1. 绑定工具到模型
model_with_tools = model.bind_tools([get_weather])

# 2. 定义对话历史，传入用户问题
messages = [{"role": "user", "content": "波士顿的天气怎么样？"}]
# 3. 模型生成工具调用请求，添加到对话历史
ai_msg = model_with_tools.invoke(messages)
messages.append(ai_msg)

# 4. 执行工具并收集结果，将结果添加到对话历史
for tool_call in ai_msg.tool_calls:
    tool_result = get_weather.invoke(tool_call) # 执行工具
    messages.append(tool_result) # 添加工具结果（ToolMessage）

# 5. 将工具结果传入模型，生成最终回复
final_response = model_with_tools.invoke(messages)
print(final_response.text) # 输出：波士顿今天是晴天，气温25℃。

关键说明：工具执行后返回的ToolMessage包含tool_call_id，可与模型的工具调用请求一一对应，模型会根据该ID关联结果。

7.4 强制工具调用

默认情况下，模型可自主决定是否调用工具，若需强制模型调用工具（指定某一个/任意一个），可在bind_tools中设置tool_choice：

# 强制调用任意一个绑定的工具
model_with_tools = model.bind_tools([tool_1, tool_2], tool_choice="any")

# 强制调用指定的工具（tool_1）
model_with_tools = model.bind_tools([tool_1, tool_2], tool_choice="tool_1")

7.5 并行工具调用

多数模型支持并行调用多个工具（如同时查询波士顿和东京的天气），模型会根据请求的独立性自动判断是否并行，无需额外配置：

# 绑定天气工具
model_with_tools = model.bind_tools([get_weather])

# 提问触发并行工具调用
response = model_with_tools.invoke("波士顿和东京的天气怎么样？")

# 模型会生成多个工具调用请求
print(response.tool_calls)

输出效果：

[
  {'name': 'get_weather', 'args': {'location': 'Boston'}, 'id': 'call_1'},
  {'name': 'get_weather', 'args': {'location': 'Tokyo'}, 'id': 'call_2'},
]

关闭并行工具调用

若需禁用并行，可在bind_tools中设置parallel_tool_calls=False（OpenAI/Anthropic均支持）：

model_with_tools = model.bind_tools([get_weather], parallel_tool_calls=False)

7.6 流式工具调用

流式调用模型时，工具调用请求会以**ToolCallChunk**的形式实时返回，可实时解析工具调用的名称和参数：

# 流式调用带工具的模型
for chunk in model_with_tools.stream("波士顿和东京的天气怎么样？"):
    # 遍历流式工具调用块
    for tool_chunk in chunk.tool_call_chunks:
        if name := tool_chunk.get("name"):
            print(f"正在调用工具：{name}")
        if args := tool_chunk.get("args"):
            print(f"工具参数实时更新：{args}")

输出效果：

正在调用工具：get_weather
工具参数实时更新：{"lo"
工具参数实时更新："location": "B"
工具参数实时更新："location": "Boston"}
正在调用工具：get_weather
工具参数实时更新：{"location": "T"
工具参数实时更新："location": "Tokyo"}

也可通过**+**聚合工具调用块，还原完整的工具调用请求：

gathered = None
for chunk in model_with_tools.stream("波士顿的天气怎么样？"):
    gathered = chunk if gathered is None else gathered + chunk
    print(gathered.tool_calls) # 实时输出聚合后的工具调用请求

八、结构化输出 📋

让模型的回复严格遵循自定义的格式规范（如JSON/对象），避免解析繁琐的自然语言，方便后续代码处理，是工业级应用的必备能力。 LangChain支持三种结构化输出的Schema定义方式，优先级：Pydantic > TypedDict > JSON Schema，且支持嵌套结构。

8.1 方式1：Pydantic BaseModel（推荐，功能最全）

Pydantic是Python的数据验证库，可定义字段类型/描述/验证规则/嵌套结构，模型会严格按照Pydantic模型生成输出，自动完成数据验证。

代码示例：定义电影信息的结构化输出

# 导入Pydantic的基础模型和字段
from pydantic import BaseModel, Field

# 定义Pydantic模型，描述电影信息的结构
class Movie(BaseModel):
    """电影信息的结构化模型（模型描述，会传给大模型）"""
    title: str = Field(..., description="电影的标题")
    year: int = Field(..., description="电影的上映年份")
    director: str = Field(..., description="电影的导演")
    rating: float = Field(..., description="电影的评分，满分10分")

# 将模型绑定到LangChain模型，开启结构化输出
model_with_structure = model.with_structured_output(Movie)
# 调用模型，获取结构化输出
response = model_with_structure.invoke("提供《盗梦空间》的详细信息")
print(response) # 输出：Movie(title='盗梦空间', year=2010, director='克里斯托弗·诺兰', rating=8.8)
print(type(response)) # 输出：<class '__main__.Movie'>（Pydantic对象，可直接调用属性）
print(response.title) # 输出：盗梦空间

核心优势：自动数据验证（如year必须是整数，否则报错）| 支持嵌套结构 | 可直接调用属性，无需解析。

8.2 方式2：TypedDict（轻量，无运行时验证）

TypedDict是Python内置的类型注解工具，比Pydantic更轻量，无运行时数据验证，适合简单的结构化场景。

# 导入TypedDict和Annotated（用于添加描述）
from typing_extensions import TypedDict, Annotated

# 定义TypedDict，描述电影信息
class MovieDict(TypedDict):
    """电影信息的结构化字典（模型描述）"""
    title: Annotated[str, ..., "电影的标题"]
    year: Annotated[int, ..., "电影的上映年份"]
    director: Annotated[str, ..., "电影的导演"]
    rating: Annotated[float, ..., "电影的评分，满分10分"]

# 开启结构化输出
model_with_structure = model.with_structured_output(MovieDict)
# 调用模型
response = model_with_structure.invoke("提供《盗梦空间》的详细信息")
print(response) # 输出：{'title': '盗梦空间', 'year': 2010, 'director': '克里斯托弗·诺兰', 'rating': 8.8}
print(type(response)) # 输出：<class 'dict'>（普通字典）

8.3 方式3：JSON Schema（通用，跨语言）

JSON Schema是通用的结构化描述规范，支持跨语言使用，适合需要与其他系统对接的场景，需手动传入JSON格式的Schema。

import json

# 定义JSON Schema，描述电影信息
json_schema = {
    "title": "Movie",
    "description": "电影信息的结构化模型",
    "type": "object",
    "properties": {
        "title": {"type": "string", "description": "电影的标题"},
        "year": {"type": "integer", "description": "电影的上映年份"},
        "director": {"type": "string", "description": "电影的导演"},
        "rating": {"type": "number", "description": "电影的评分，满分10分"}
    },
    "required": ["title", "year", "director", "rating"] # 必选字段
}

# 开启结构化输出，指定方法为json_schema
model_with_structure = model.with_structured_output(
    json_schema,
    method="json_schema",
)
# 调用模型
response = model_with_structure.invoke("提供《盗梦空间》的详细信息")
print(response) # 输出：{'title': '盗梦空间', 'year': 2010, ...}

8.4 结构化输出的关键配置

8.4.1 method参数：指定结构化输出的实现方式

不同提供商支持不同的实现方式，需通过method指定，核心值：

• json_schema：使用提供商的原生结构化输出能力（推荐，精度最高）

• function_calling：通过工具调用实现结构化输出，强制模型调用符合Schema的“虚拟工具”

• json_mode：早期的JSON生成方式，需在提示词中描述Schema，模型生成合法JSON即可

8.4.2 include_raw：返回原始消息对象

设置include_raw=True，可同时获取解析后的结构化结果和原始的AIMessage对象，方便查看Token用量、元数据等信息：

# 开启include_raw
model_with_structure = model.with_structured_output(Movie, include_raw=True)  
response = model_with_structure.invoke("提供《盗梦空间》的详细信息")
print(response)

输出效果：

{
    "raw": AIMessage(content='{"title":"盗梦空间","year":2010,...}', ...), # 原始消息
    "parsed": Movie(title='盗梦空间', year=2010, ...), # 解析后的Pydantic对象
    "parsing_error": None, # 解析错误（无则为None）
}

8.4.3 嵌套结构化结构

支持定义嵌套的Schema（如电影包含演员列表），Pydantic和TypedDict均支持，以下为Pydantic示例：

from pydantic import BaseModel, Field

# 子模型：演员信息
class Actor(BaseModel):
    name: str = Field(..., description="演员的名字")
    role: str = Field(..., description="演员饰演的角色")

# 父模型：电影详细信息（包含演员列表）
class MovieDetails(BaseModel):
    title: str = Field(..., description="电影标题")
    year: int = Field(..., description="上映年份")
    cast: list[Actor] = Field(..., description="演员列表，包含名字和角色")
    genres: list[str] = Field(..., description="电影类型")
    budget: float | None = Field(None, description="电影预算，单位：百万美元，可选")

# 开启结构化输出
model_with_structure = model.with_structured_output(MovieDetails)
# 调用模型
response = model_with_structure.invoke("提供《盗梦空间》的演员和类型信息")
print(response.cast) # 输出演员列表的Pydantic对象

九、支持的模型提供商 📦

LangChain支持所有主流的模型提供商，包括但不限于： OpenAI | Anthropic | Google Gemini | Azure OpenAI | AWS Bedrock | HuggingFace | Ollama | Together AI | vLLM
每个提供商均提供多种不同能力的模型，完整的支持列表可前往LangChain官方的集成页面查看。

十、高级主题 🚀

以下为LangChain模型的高级功能，适合工业级应用和复杂场景的开发，包含核心用法和代码示例。

10.1 模型配置文件（Model Profile）💾

Beta功能，需langchain>=1.1，模型对象可通过.profile属性暴露自身的能力字典（如最大输入Token、是否支持多模态、是否支持工具调用），方便动态适配模型能力。

10.1.1 查看模型Profile

# 查看模型的能力配置
print(model.profile)

典型输出：

{
  "max_input_tokens": 400000, # 最大输入Token数
  "image_inputs": True, # 是否支持图片输入（多模态）
  "reasoning_output": True, # 是否支持推理输出
  "tool_calling": True, # 是否支持工具调用
  "structured_output": True # 是否支持结构化输出
}

数据来源：主要由开源项目models.dev提供，LangChain会在此基础上补充专属字段。

10.1.2 自定义/更新Profile

若Profile数据缺失/过期，可手动自定义或更新：

方式1：初始化时传入自定义Profile

# 定义自定义Profile
custom_profile = {
    "max_input_tokens": 100000,
    "tool_calling": True,
    "structured_output": True,
}
# 初始化模型时传入
model = init_chat_model("gpt-4.1", profile=custom_profile)

方式2：原地更新Profile（避免修改共享对象，推荐用model_copy）

# 复制模型并更新Profile
new_profile = model.profile | {"structured_output": False} # 新增/修改字段
new_model = model.model_copy(update={"profile": new_profile})

10.1.3 上游数据更新

若需修复models.dev的原始数据，可通过PR提交到其GitHub仓库，再通过LangChain的CLI工具刷新Profile数据。

10.2 多模态（Multimodal）🖼️

支持处理/返回非文本数据（图片|音频|视频）的模型为多模态模型，需通过内容块（content blocks）向模型传入非文本数据，LangChain支持跨提供商标准格式和提供商原生格式。

10.2.1 多模态输出示例

模型可返回包含图片的内容块（base64编码）：

# 让多模态模型生成一张猫的图片
response = model.invoke("画一张猫的图片")
# 查看输出的内容块
print(response.content_blocks)

典型输出：

[
    {"type": "text", "text": "这是为你生成的猫的图片："},
    {"type": "image", "base64": "xxx...", "mime_type": "image/jpeg"}, # 图片的base64编码
]

10.3 推理能力（Reasoning）🧐

多数模型支持多步推理，可将推理过程流式输出，方便查看模型的思考逻辑，部分模型还支持指定推理等级（如low/high）。

流式输出推理步骤

# 流式调用模型，提取推理步骤
for chunk in model.stream("为什么鹦鹉会学人说话？"):
    # 过滤出推理类型的内容块
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    # 输出推理步骤，无则输出文本
    print(reasoning_steps if reasoning_steps else chunk.text)

10.4 本地模型（Local Models）🖥️

LangChain支持在本地硬件上运行模型，适合数据隐私要求高、自定义模型、避免云服务成本的场景，Ollama是最简单的本地模型运行工具，其他本地集成可参考官方集成页面。

10.5 提示词缓存（Prompt Caching）⚡

主流提供商均支持提示词缓存，对重复的Token序列进行缓存，减少重复计算，降低延迟和成本，分为两种类型：

• 隐式缓存：提供商自动缓存，命中后自动减费（如OpenAI | Gemini）

• 显式缓存：需手动指定缓存点，精准控制（如ChatOpenAI的prompt_cache_key | Anthropic的缓存中间件）

缓存生效条件：通常需要输入Token数超过最小阈值，具体可参考提供商文档；缓存使用情况会体现在模型回复的Token用量元数据中。

10.6 服务端工具使用（Server-side Tool Use）🌐

部分提供商支持服务端工具调用，模型可在单个对话轮次中直接调用服务商提供的工具（如网页搜索|代码解释器），无需客户端手动执行，结果会直接融入回复。

代码示例：调用服务端网页搜索工具

from langchain.chat_models import init_chat_model

# 初始化模型
model = init_chat_model("gpt-4.1-mini")
# 绑定服务端工具（web_search）
tool = {"type": "web_search"}
model_with_tools = model.bind_tools([tool])
# 调用模型，触发服务端工具调用
response = model_with_tools.invoke("今天的正面新闻有哪些？")
# 查看包含工具调用和结果的内容块
print(response.content_blocks)

关键说明：服务端工具调用无需手动添加ToolMessage，所有操作在服务商侧完成，属于单轮对话。

10.7 速率限制（Rate Limiting）🚦

模型提供商通常会限制单位时间内的调用次数，超出则触发速率限制错误，LangChain支持通过rate_limiter参数配置客户端速率限制，避免触发服务商限制。

代码示例：使用内置的InMemoryRateLimiter

# 导入内置的内存速率限制器
from langchain_core.rate_limiters import InMemoryRateLimiter

# 定义速率限制器：10秒1次请求，每100ms检查一次，最大突发数10
rate_limiter = InMemoryRateLimiter(
    requests_per_second=0.1,
    check_every_n_seconds=0.1,
    max_bucket_size=10,
)

# 初始化模型时传入速率限制器
model = init_chat_model(
    model="gpt-4.1",
    model_provider="openai",
    rate_limiter=rate_limiter  
)

关键说明：客户端速率限制器仅限制调用次数，不限制请求的Token大小。

10.8 基础URL/代理（Base URL / Proxy）🔗

10.8.1 自定义Base URL

可通过base_url参数指定自定义的API端点，适配支持OpenAI兼容API的提供商（如Together AI | vLLM）：

model = init_chat_model(
    model="MODEL_NAME", # 兼容平台的模型名
    model_provider="openai", # 指定为openai兼容
    base_url="https://api.together.ai/v1", # 自定义Base URL
    api_key="YOUR_API_KEY", # 兼容平台的API密钥
)

10.8.2 代理配置

部分模型集成支持HTTP代理，适合内网部署场景，以OpenAI为例：

from langchain_openai import ChatOpenAI

# 配置代理
model = ChatOpenAI(
    model="gpt-4o",
    openai_proxy="http://proxy.example.com:8080" # 代理地址
)

关键说明：代理支持因提供商而异，需参考对应集成的文档。

10.9 日志概率（Log Probabilities）📊

部分模型支持返回Token级别的日志概率，表示模型生成该Token的可能性，需通过bind(logprobs=True)开启：

# 开启日志概率
model = init_chat_model("gpt-4o", model_provider="openai").bind(logprobs=True)
# 调用模型
response = model.invoke("为什么鹦鹉会学人说话？")
# 查看日志概率
print(response.response_metadata["logprobs"])

10.10 Token用量统计（Token Usage）📈

主流提供商都会返回Token用量信息，包含输入/输出Token数，该信息会嵌入在模型返回的AIMessage对象中；流式场景下，部分提供商（如OpenAI）需手动开启用量统计。 LangChain支持通过回调处理器和上下文管理器****聚合统计多个模型的Token用量，适合多模型流水线场景。

方式1：回调处理器（UsageMetadataCallbackHandler）

from langchain.chat_models import init_chat_model
from langchain_core.callbacks import UsageMetadataCallbackHandler

# 初始化两个不同的模型
model_1 = init_chat_model("gpt-4o-mini")
model_2 = init_chat_model("claude-haiku-4-5-20251001")

# 初始化Token用量回调处理器
callback = UsageMetadataCallbackHandler()
# 调用模型并传入回调
result_1 = model_1.invoke("你好", config={"callbacks": [callback]})
result_2 = model_2.invoke("你好", config={"callbacks": [callback]})
# 查看聚合的Token用量
print(callback.usage_metadata)

方式2：上下文管理器（推荐，自动管理）

from langchain.chat_models import init_chat_model
from langchain_core.callbacks import get_usage_metadata_callback

# 初始化两个模型
model_1 = init_chat_model("gpt-4o-mini")
model_2 = init_chat_model("claude-haiku-4-5-20251001")

# 使用上下文管理器统计用量
with get_usage_metadata_callback() as cb:
    model_1.invoke("你好")
    model_2.invoke("你好")
    print(cb.usage_metadata) # 输出聚合的用量信息

典型输出：包含每个模型的输入/输出Token数、总Token数、Token类型详情。

10.11 调用配置（Invocation Config）⚙️

调用模型时，可通过config参数传入**RunnableConfig字典，实现运行时的行为控制**（如自定义名称、标签、元数据、回调），适合调试和生产环境的监控。

代码示例：传入调用配置

response = model.invoke(
    "讲一个笑话",
    config={
        "run_name": "joke_generation",      # 本次调用的自定义名称（方便LangSmith调试）
        "tags": ["humor", "demo"],          # 标签（用于分类和过滤）
        "metadata": {"user_id": "123"},     # 自定义元数据（如用户ID）
        "callbacks": [my_callback_handler], # 自定义回调处理器
    }
)

核心配置项

配置项	作用
run_name	本次调用的名称，不继承给子调用
tags	标签列表，继承给所有子调用，用于LangSmith过滤
metadata	自定义键值对，继承给所有子调用，用于跟踪上下文
max_concurrency	批量调用时的最大并发数
callbacks	回调处理器列表，监控模型调用生命周期
recursion_limit	链式调用的最大递归深度，防止无限循环

10.12 可配置模型（Configurable Models）🔄

可创建运行时动态切换的模型，无需重新初始化，支持动态切换模型提供商/模型名/参数，适合A/B测试、多模型切换的场景。

10.12.1 基础动态切换模型

from langchain.chat_models import init_chat_model

# 初始化可配置模型，不指定具体模型
configurable_model = init_chat_model(temperature=0)

# 运行时切换为gpt-5-nano
configurable_model.invoke(
    "你叫什么名字？",
    config={"configurable": {"model": "gpt-5-nano"}},
)

# 运行时切换为Claude
configurable_model.invoke(
    "你叫什么名字？",
    config={"configurable": {"model": "claude-sonnet-4-5-20250929"}},
)

关键说明：若初始化时不指定模型，model和model_provider会默认成为可配置字段。

10.12.2 自定义可配置字段+前缀

可指定需要动态配置的字段，并添加前缀（适合多模型链式调用，避免字段冲突）：

# 初始化可配置模型，指定可配置字段和前缀
first_model = init_chat_model(
        model="gpt-4.1-mini", # 默认模型
        temperature=0, # 默认参数
        configurable_fields=("model", "model_provider", "temperature", "max_tokens"), # 可配置字段
        config_prefix="first", # 配置前缀
)

# 运行时动态修改参数
first_model.invoke(
    "你叫什么名字？",
    config={
        "configurable": {
            "first_model": "claude-sonnet-4-5-20250929", # 带前缀的模型名
            "first_temperature": 0.5, # 带前缀的温度
            "first_max_tokens": 100, # 带前缀的最大Token
        }
    },
)

10.12.3 可配置模型结合工具/结构化输出

可配置模型支持绑定工具、结构化输出等操作，且绑定后的配置会适配所有动态切换的模型：

from pydantic import BaseModel, Field

# 定义工具的Pydantic模型
class GetPopulation(BaseModel):
    """获取指定地点的人口数"""
    location: str = Field(..., description="城市和州，如San Francisco, CA")

# 初始化可配置模型，绑定工具
model = init_chat_model(temperature=0)
model_with_tools = model.bind_tools([GetPopulation])

# 切换为gpt-4.1-mini，调用工具
model_with_tools.invoke(
    "2024年洛杉矶和纽约哪个城市人口多？",
    config={"configurable": {"model": "gpt-4.1-mini"}}
).tool_calls

# 切换为Claude，调用工具（无需重新绑定）
model_with_tools.invoke(
    "2024年洛杉矶和纽约哪个城市人口多？",
    config={"configurable": {"model": "claude-sonnet-4-5-20250929"}}
).tool_calls

关键说明：不同模型的工具调用格式会由LangChain自动适配，无需手动修改。

---

以上为LangChain模型模块的完整使用指南，涵盖基础用法、核心配置、高级功能，所有代码示例均为官方推荐写法，可直接复制实操。若需更细节的提供商专属用法，可参考LangChain官方的聊天模型集成页面和API参考文档。