Models（模型）

    这简化了基于事件类型和其他元数据的过滤，并将在后台聚合完整消息。请参阅下面的示例。

    ```python
    async for event in model.astream_events("Hello"):

        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}")

        else:
            pass
    ```
    ```txt
    输入：Hello
    Token: Hi
    Token:  there
    Token: !
    Token:  How
    Token:  can
    Token:  I
    ...
    完整消息：Hi there! How can I help today?
    ```

    <Tip>
        请参阅 @[`astream_events()`][BaseChatModel.astream_events] 参考了解事件类型和其他详情。
    </Tip>
    :::

    :::js
    LangChain Chat Model 还可以使用
    [`streamEvents()`][BaseChatModel.streamEvents] 流式传输语义事件。

    这简化了基于事件类型和其他元数据的过滤，并将在后台聚合完整消息。请参阅下面的示例。

    ```typescript
    const stream = await model.streamEvents("Hello");
    for await (const event of stream) {
        if (event.event === "on_chat_model_start") {
            console.log(`输入：${event.data.input}`);
        }
        if (event.event === "on_chat_model_stream") {
            console.log(`Token: ${event.data.chunk.text}`);
        }
        if (event.event === "on_chat_model_end") {
            console.log(`完整消息：${event.data.output.text}`);
        }
    }
    ```
    ```txt
    输入：Hello
    Token: Hi
    Token:  there
    Token: !
    Token:  How
    Token:  can
    Token:  I
    ...
    完整消息：Hi there! How can I help today?
    ```

    请参阅 @[`streamEvents()`][BaseChatModel.streamEvents] 参考了解事件类型和其他详情。
    :::
</Accordion>
<Accordion title='"自动流式" Chat Model'>
    LangChain 通过在某些情况下自动启用流式模式简化了 Chat Model 的流式传输，即使你没有显式调用流式方法。当你使用非流式调用方法但仍希望流式传输整个应用程序（包括 Chat Model 的中间结果）时，这特别有用。

    例如，在 [LangGraph Agent](/oss/langchain/agents) 中，你可以在节点中调用 `model.invoke()`，但如果在流式模式下运行，LangChain 会自动委托给流式传输。

    #### 工作原理

    当你 `invoke()` 一个 Chat Model 时，如果 LangChain 检测到你要流式传输整个应用程序，它会自动切换到内部流式模式。就使用 invoke 的代码而言，调用的结果是一样的；然而，当 Chat Model 被流式传输时，LangChain 会负责在 LangChain 的回调系统中调用 @[`on_llm_new_token`] 事件。

    :::python
    回调事件允许 LangGraph `stream()` 和 `astream_events()` 实时显示 Chat Model 的输出。
    :::
    :::js
    回调事件允许 LangGraph `stream()` 和 `streamEvents()` 实时显示 Chat Model 的输出。
    :::
</Accordion>

Batch（批量）

将独立请求集合批量处理到模型可以显著提高性能并降低成本，因为处理可以并行完成：

:::python

responses = model.batch([
    "为什么鹦鹉有彩色的羽毛？",
    "飞机是如何飞行的？",
    "什么是量子计算？"
])
for response in responses:
    print(response)

它**不同于**推理提供商支持的批量 API，如 [OpenAI](https://platform.openai.com/docs/guides/batch) 或 [Anthropic](https://platform.claude.com/docs/en/build-with-claude/batch-processing#message-batches-api)。

默认情况下，@[batch()][BaseChatModel.batch] 只返回整个批次的最终输出。如果你想在每个输入完成生成时接收其输出，可以使用 @[batch_as_completed()][BaseChatModel.batch_as_completed] 流式传输结果：

for response in model.batch_as_completed([
    "为什么鹦鹉有彩色的羽毛？",
    "飞机是如何飞行的？",
    "什么是量子计算？"
]):
    print(response)

```python 带最大并发数的批量
model.batch(
    list_of_inputs,
    config={
        'max_concurrency': 5,  # 限制为 5 个并行调用
    }
)
```

请参阅 @[`RunnableConfig`] 参考了解支持的属性完整列表。

有关批处理的更多详情，请参阅 @[参考][BaseChatModel.batch]。 :::

:::js

const responses = await model.batch([
  "为什么鹦鹉有彩色的羽毛？",
  "飞机是如何飞行的？",
  "什么是量子计算？",
]);
for (const response of responses) {
  console.log(response);
}

```typescript 带最大并发数的批量
model.batch(
  listOfInputs,
  {
    maxConcurrency: 5,  # 限制为 5 个并行调用
  }
)
```

请参阅 @[`RunnableConfig`] 参考了解支持的属性完整列表。

有关批处理的更多详情，请参阅 @[参考][BaseChatModel.batch]。 :::

工具调用（Tool Calling）

模型可以请求调用执行任务的工具，例如从数据库获取数据、搜索网络或运行代码。工具是以下内容的配对：

1. 一个模式（Schema），包括工具的名称、描述和/或参数定义（通常是 JSON Schema）
2. 要执行的函数或 协程。

以下是用户和模型之间的基本工具调用流程：

:::python

sequenceDiagram
    participant U as User
    participant M as Model
    participant T as Tools

    U->>M: "旧金山和纽约的天气怎么样？"
    M->>M: 分析请求并决定需要的工具

    par 并行工具调用
        M->>T: get_weather("San Francisco")
        M->>T: get_weather("New York")
    end

    par 工具执行
        T-->>M: 旧金山天气数据
        T-->>M: 纽约天气数据
    end

    M->>M: 处理结果并生成响应
    M->>U: "旧金山：72°F 晴朗，纽约：68°F 多云"

:::

:::js

sequenceDiagram
    participant U as User
    participant M as Model
    participant T as Tools

    U->>M: "旧金山和纽约的天气怎么样？"
    M->>M: 分析请求并决定需要的工具

    par 并行工具调用
        M->>T: getWeather("San Francisco")
        M->>T: getWeather("New York")
    end

    par 工具执行
        T-->>M: 旧金山天气数据
        T-->>M: 纽约天气数据
    end

    M->>M: 处理结果并生成响应
    M->>U: "旧金山：72°F 晴朗，纽约：68°F 多云"

:::

:::python 要使你定义的工具可供模型使用，你必须使用 @[bind_tools][BaseChatModel.bind_tools] 绑定它们。在后续调用中，模型可以根据需要选择调用任何绑定的工具。 :::

:::js 要使你定义的工具可供模型使用，你必须使用 @[bindTools][BaseChatModel.bindTools] 绑定它们。在后续调用中，模型可以根据需要选择调用任何绑定的工具。 :::

一些模型提供商提供 内置工具，可以通过模型或调用参数启用（例如 ChatOpenAI、ChatAnthropic）。有关详情，请查看相应的 提供商参考。

:::python

from langchain.tools import tool

@tool
def get_weather(location: str) -> str:
    """获取某地的天气。"""
    return f"今天是 {location} 的晴天。"


model_with_tools = model.bind_tools([get_weather])  # [!code highlight]

response = model_with_tools.invoke("波士顿的天气怎么样？")
for tool_call in response.tool_calls:
    # 查看模型进行的工具调用
    print(f"工具：{tool_call['name']}")
    print(f"参数：{tool_call['args']}")

:::

:::js

import { tool } from "langchain";
import * as z from "zod";
import { ChatOpenAI } from "@langchain/openai";

const getWeather = tool(
  (input) => `今天是 ${input.location} 的晴天。`,
  {
    name: "get_weather",
    description: "获取某地的天气。",
    schema: z.object({
      location: z.string().describe("要获取天气的位置"),
    }),
  },
);

const model = new ChatOpenAI({ model: "gpt-4.1" });
const modelWithTools = model.bindTools([getWeather]);  # [!code highlight]

const response = await modelWithTools.invoke("波士顿的天气怎么样？");
const toolCalls = response.tool_calls || [];
for (const tool_call of toolCalls) {
  // 查看模型进行的工具调用
  console.log(`工具：${tool_call.name}`);
  console.log(`参数：${tool_call.args}`);
}

:::

当绑定用户定义的工具时，模型的响应包括执行工具的请求。当将模型与 Agent 分开使用时，由你执行请求的工具并将结果返回给模型用于后续推理。当使用 Agent 时，Agent 循环将为你处理工具执行循环。

下面，我们展示了一些使用工具调用的常见方法。

    这是一个简单的示例：

    :::python

    ```python 工具执行循环
    # 将（可能多个）工具绑定到模型
    model_with_tools = model.bind_tools([get_weather])

    # 步骤 1：模型生成工具调用
    messages = [{"role": "user", "content": "波士顿的天气怎么样？"}]
    ai_msg = model_with_tools.invoke(messages)
    messages.append(ai_msg)

    # 步骤 2：执行工具并收集结果
    for tool_call in ai_msg.tool_calls:
        # 使用生成的参数执行工具
        tool_result = get_weather.invoke(tool_call)
        messages.append(tool_result)

    # 步骤 3：将结果传递回模型以获取最终响应
    final_response = model_with_tools.invoke(messages)
    print(final_response.text)
    # "波士顿当前的天气是 72°F，晴朗。"
    ```

    :::
    :::js

    ```typescript 工具执行循环
    // 将（可能多个）工具绑定到模型
    const modelWithTools = model.bindTools([get_weather])

    // 步骤 1：模型生成工具调用
    const messages = [{"role": "user", "content": "波士顿的天气怎么样？"}]
    const ai_msg = await modelWithTools.invoke(messages)
    messages.push(ai_msg)

    // 步骤 2：执行工具并收集结果
    for (const tool_call of ai_msg.tool_calls) {
        // 使用生成的参数执行工具
        const tool_result = await get_weather.invoke(tool_call)
        messages.push(tool_result)
    }

    // 步骤 3：将结果传递回模型以获取最终响应
    const final_response = await modelWithTools.invoke(messages)
    console.log(final_response.text)
    # "波士顿当前的天气是 72°F，晴朗。"
    ```

    :::

    每个 @[`ToolMessage`] 返回的工具都包含一个 `tool_call_id`，与原始工具调用匹配，帮助模型将结果与请求关联起来。
</Accordion>
<Accordion title="强制工具调用" icon="asterisk">
    默认情况下，模型可以根据用户的输入自由选择使用哪个绑定的工具。但是，你可能想要强制选择工具，确保模型使用给定列表中的特定工具或**任何**工具：

    :::python

    <CodeGroup>
        ```python 强制使用任何工具
        model_with_tools = model.bind_tools([tool_1], tool_choice="any")
        ```
        ```python 强制使用特定工具
        model_with_tools = model.bind_tools([tool_1], tool_choice="tool_1")
        ```
    </CodeGroup>

    :::
    :::js

    <CodeGroup>
        ```typescript 强制使用任何工具
        const modelWithTools = model.bindTools([tool_1], { toolChoice: "any" })
        ```
        ```typescript 强制使用特定工具
        const modelWithTools = model.bindTools([tool_1], { toolChoice: "tool_1" })
        ```
    </CodeGroup>
    :::
</Accordion>
<Accordion title="并行工具调用" icon="stack-2">
    许多模型支持在适当时并行调用多个工具。这允许模型同时从不同来源收集信息。

    :::python

    ```python 并行工具调用
    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'},
    # ]


    # 执行所有工具（可以使用异步并行完成）
    results = []
    for tool_call in response.tool_calls:
        if tool_call['name'] == 'get_weather':
            result = get_weather.invoke(tool_call)
        ...
        results.append(result)
    ```

    :::
    :::js

    ```typescript 并行工具调用
    const modelWithTools = model.bindTools([get_weather])

    const response = await modelWithTools.invoke(
        "波士顿和东京的天气怎么样？"
    )


    // 模型可能生成多个工具调用
    console.log(response.tool_calls)
    # [
    #   { name: 'get_weather', args: { location: 'Boston' }, id: 'call_1' },
    #   { name: 'get_time', args: { location: 'Tokyo' }, id: 'call_2' }
    # ]


    // 执行所有工具（可以使用异步并行完成）
    const results = []
    for (const tool_call of response.tool_calls || []) {
        if (tool_call.name === 'get_weather') {
            const result = await get_weather.invoke(tool_call)
            results.push(result)
        }
    }
    ```

    :::

    模型根据请求操作的独立性智能地确定何时适合并行执行。

    <Tip>
    大多数支持工具调用的模型默认启用并行工具调用。一些（包括 [OpenAI](/oss/integrations/chat/openai) 和 [Anthropic](/oss/integrations/chat/anthropic)）允许你禁用此功能。要禁用，设置 `parallel_tool_calls=False`：
    ```python
    model.bind_tools([get_weather], parallel_tool_calls=False)
    ```
    </Tip>
</Accordion>
<Accordion title="流式工具调用" icon="rss">
    流式传输响应时，工具调用通过 @[`ToolCallChunk`] 渐进式构建。这让你可以在工具调用生成时看到它们，而不是等待完整响应。

    :::python

    ```python 流式工具调用
    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 id_ := tool_chunk.get("id"):
                print(f"ID: {id_}")
            if args := tool_chunk.get("args"):
                print(f"参数：{args}")

    # 输出：
    # 工具：get_weather
    # ID: call_SvMlU1TVIZugrFLckFE2ceRE
    # 参数：{"lo
    # 参数：catio
    # 参数：n": "B
    # 参数：osto
    # 参数：n"}
    # 工具：get_weather
    # ID: call_QMZdy6qInx13oWKE7KhuhOLR
    # 参数：{"lo
    # 参数：catio
    # 参数：n": "T
    # 参数：okyo
    # 参数："}
    ```

    你可以累积块来构建完整的工具调用：

    ```python 累积工具调用
    gathered = None
    for chunk in model_with_tools.stream("波士顿的天气怎么样？"):
        gathered = chunk if gathered is None else gathered + chunk
        print(gathered.tool_calls)
    ```

    :::
    :::js

    ```typescript 流式工具调用
    const stream = await modelWithTools.stream(
        "波士顿和东京的天气怎么样？"
    )
    for await (const chunk of stream) {
        # 工具调用块渐进式到达
        if (chunk.tool_call_chunks) {
            for (const tool_chunk of chunk.tool_call_chunks) {
            console.log(`工具：${tool_chunk.get('name', '')}`)
            console.log(`参数：${tool_chunk.get('args', '')}`)
            }
        }
    }

    # 输出：
    # 工具：get_weather
    # 参数：
    # 工具：
    # 参数：{"loc
    # 工具：
    # 参数：ation": "BOS"}
    # 工具：get_time
    # 参数：
    # 工具：
    # 参数：{"timezone": "Tokyo"}
    ```

    你可以累积块来构建完整的工具调用：

    ```typescript 累积工具调用
    let full: AIMessageChunk | null = null
    const stream = await modelWithTools.stream("波士顿的天气怎么样？")
    for await (const chunk of stream) {
        full = full ? full.concat(chunk) : chunk
        console.log(full.contentBlocks)
    }
    ```

    :::
</Accordion>

结构化输出（Structured Output）

可以请求模型提供与给定模式匹配的响应格式。这对于确保输出可以轻松解析并用于后续处理非常有用。LangChain 支持多种模式类型和强制执行结构化输出的方法。

:::python Pydantic 模型 提供最丰富的功能集，包括字段验证、描述和嵌套结构。

    ```python
    from pydantic import BaseModel, Field

    class Movie(BaseModel):
        """一部有详细信息的电影。"""
        title: str = Field(..., description="电影的标题")
        year: int = Field(..., description="电影发行的年份")
        director: str = Field(..., description="电影的导演")
        rating: float = Field(..., description="电影的评分（满分 10 分）")

    model_with_structure = model.with_structured_output(Movie)
    response = model_with_structure.invoke("提供电影《盗梦空间》的详细信息")
    print(response)  # Movie(title="盗梦空间", year=2010, director="Christopher Nolan", rating=8.8)
    ```
</Tab>
<Tab title="TypedDict">
    Python 的 `TypedDict` 提供了比 Pydantic 模型更简单的替代方案，当你不需要运行时验证时很理想。

    ```python
    from typing_extensions import TypedDict, Annotated

    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': 'Christopher Nolan', 'rating': 8.8}
    ```
</Tab>
<Tab title="JSON Schema">
    提供 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 以获得最大控制和互操作性。

    ```python
    import json

    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"]
    }

    model_with_structure = model.with_structured_output(
        json_schema,
        method="json_schema",
    )
    response = model_with_structure.invoke("提供电影《盗梦空间》的详细信息")
    print(response)  # {'title': '盗梦空间', 'year': 2010, ...}
    ```
</Tab>

:::js Zod Schema 是定义输出模式的首选方法。请注意，当提供 Zod Schema 时，模型输出还将使用 Zod 的 parse 方法针对模式进行验证。

    ```typescript
    import * as z from "zod";

    const Movie = z.object({
      title: z.string().describe("电影的标题"),
      year: z.number().describe("电影发行的年份"),
      director: z.string().describe("电影的导演"),
      rating: z.number().describe("电影的评分（满分 10 分）"),
    });

    const modelWithStructure = model.withStructuredOutput(Movie);

    const response = await modelWithStructure.invoke("提供电影《盗梦空间》的详细信息");
    console.log(response);
    // {
    //   title: "盗梦空间",
    //   year: 2010,
    //   director: "Christopher Nolan",
    //   rating: 8.8,
    // }
    ```
</Tab>
<Tab title="JSON Schema">
    为了获得最大控制或互操作性，你可以提供原始 JSON Schema。

    ```typescript
    const jsonSchema = {
      "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"],
    }

    const modelWithStructure = model.withStructuredOutput(
      jsonSchema,
      { method: "jsonSchema" },
    )

    const response = await modelWithStructure.invoke("提供电影《盗梦空间》的详细信息")
    console.log(response)  # {'title': '盗梦空间', 'year': 2010, ...}
    ```
</Tab>
<Tab title="Standard Schema">
    也支持任何实现 [Standard Schema](https://standardschema.dev/) 规范的库的模式。Standard Schema 对象在运行时通过模式的 `~standard.validate()` 方法进行验证。

    ```typescript
    import * as v from "valibot";
    import { toStandardJsonSchema } from "@valibot/to-json-schema";

    const Movie = toStandardJsonSchema(
      v.object({
        title: v.pipe(v.string(), v.description("电影的标题")),
        year: v.pipe(v.number(), v.description("电影发行的年份")),
        director: v.pipe(v.string(), v.description("电影的导演")),
        rating: v.pipe(v.number(), v.description("电影的评分（满分 10 分）")),
      })
    );

    const modelWithStructure = model.withStructuredOutput(Movie);

    const response = await modelWithStructure.invoke("提供电影《盗梦空间》的详细信息");
    console.log(response);
    // {
    //   title: "盗梦空间",
    //   year: 2010,
    //   director: "Christopher Nolan",
    //   rating: 8.8,
    // }
    ```
</Tab>

:::python 结构化输出的关键注意事项

- **方法参数**：一些提供商支持不同的结构化输出方法：
    - `'json_schema'`：使用提供商提供的专用结构化输出功能。
    - `'function_calling'`：通过强制遵循给定模式的 [工具调用](#tool-calling) 派生结构化输出。
    - `'json_mode'`：一些提供商提供的 `'json_schema'` 的前身。生成有效的 JSON，但必须在提示中描述模式。
- **包含原始数据**：设置 `include_raw=True` 以同时获取解析的输出和原始 AI 消息。
- **验证**：Pydantic 模型提供自动验证。`TypedDict` 和 JSON Schema 需要手动验证。

请参阅你的 [提供商集成页面](/oss/integrations/providers/overview) 了解支持的方法和配置选项。

:::js 结构化输出的关键注意事项：

- **方法参数**：一些提供商支持不同的方法（`'jsonSchema'`、`'functionCalling'`、`'jsonMode'`）
- **包含原始数据**：使用 @[`includeRaw: true`][BaseChatModel.with_structured_output(include_raw)] 同时获取解析的输出和原始 @[`AIMessage`]
- **验证**：Zod 和 Standard Schema 对象提供自动验证，而 JSON Schema 需要手动验证
- **Standard Schema**：支持任何实现 [Standard Schema](https://standardschema.dev/) 规范的模式库，并在运行时验证

请参阅你的 [提供商集成页面](/oss/integrations/providers/overview) 了解支持的方法和配置选项。

:::python
```python
from pydantic import BaseModel, Field

class Movie(BaseModel):
    """一部有详细信息的电影。"""
    title: str = Field(..., description="电影的标题")
    year: int = Field(..., description="电影发行的年份")
    director: str = Field(..., description="电影的导演")
    rating: float = Field(..., description="电影的评分（满分 10 分）")

model_with_structure = model.with_structured_output(Movie, include_raw=True)  # [!code highlight]
response = model_with_structure.invoke("提供电影《盗梦空间》的详细信息")
response
# {
#     "raw": AIMessage(...),
#     "parsed": Movie(title=..., year=..., ...),
#     "parsing_error": None,
# }
```
:::

:::js
```typescript
import * as z from "zod";

const Movie = z.object({
  title: z.string().describe("电影的标题"),
  year: z.number().describe("电影发行的年份"),
  director: z.string().describe("电影的导演"),
  rating: z.number().describe("电影的评分（满分 10 分）"),
});

const modelWithStructure = model.withStructuredOutput(Movie, { includeRaw: true });

const response = await modelWithStructure.invoke("提供电影《盗梦空间》的详细信息");
console.log(response);
// {
#   raw: AIMessage { ... },
#   parsed: { title: "盗梦空间", ... }
# }
```
:::

    class Actor(BaseModel):
        name: str
        role: str

    class MovieDetails(BaseModel):
        title: str
        year: int
        cast: list[Actor]
        genres: list[str]
        budget: float | None = Field(None, description="预算（百万美元）")

    model_with_structure = model.with_structured_output(MovieDetails)
    ```

    ```python TypedDict
    from typing_extensions import Annotated, TypedDict

    class Actor(TypedDict):
        name: str
        role: str

    class MovieDetails(TypedDict):
        title: str
        year: int
        cast: list[Actor]
        genres: list[str]
        budget: Annotated[float | None, ..., "预算（百万美元）"]

    model_with_structure = model.with_structured_output(MovieDetails)
    ```
</CodeGroup>
:::

:::js
```typescript
import * as z from "zod";

const Actor = z.object({
  name: z.string(),
  role: z.string(),
});

const MovieDetails = z.object({
  title: z.string(),
  year: z.number(),
  cast: z.array(Actor),
  genres: z.array(z.string()),
  budget: z.number().nullable().describe("预算（百万美元）"),
});

const modelWithStructure = model.withStructuredOutput(MovieDetails);
```
:::

高级主题

模型配置文件（Model Profiles）

:::python LangChain Chat Model 可以通过 .profile 属性公开支持的功能和能力的字典：

model.profile
# {
#   "max_input_tokens": 400000,
#   "image_inputs": True,
#   "reasoning_output": True,
#   "tool_calling": True,
#   ...
# }

请参阅 API 参考 中的完整字段集。

大部分模型配置文件数据由 models.dev 项目提供支持，这是一个提供模型能力数据的开源项目。这些数据增加了额外的字段以用于 LangChain。这些增强与上游项目保持一致。

模型配置文件数据允许应用程序动态处理模型功能。例如：

1. 摘要中间件 可以根据模型的上下文窗口大小触发摘要。
2. create_agent 中的 结构化输出 策略可以自动推断（例如，通过检查对原生结构化输出功能的支持）。
3. 可以根据支持的 模态 和最大输入 token 来限制模型输入。

**选项 1（快速修复）**

你可以使用任何有效的配置文件实例化 Chat Model：

```python
custom_profile = {
    "max_input_tokens": 100_000,
    "tool_calling": True,
    "structured_output": True,
    # ...
}
model = init_chat_model("...", profile=custom_profile)
```

`profile` 也是一个普通的 `dict`，可以就地更新。如果模型实例是共享的，考虑使用 `model_copy` 以避免突变共享状态。

```python
new_profile = model.profile | {"key": "value"}
model.model_copy(update={"profile": new_profile})
```

**选项 2（在上游修复数据）**

数据的主要来源是 [models.dev](https://models.dev/) 项目。这些数据与 LangChain [集成包](/oss/integrations/providers/overview) 中的额外字段和覆盖合并，并与这些包一起发布。

可以通过以下过程更新模型配置文件数据：

1. （如果需要）通过向其 [GitHub 仓库](https://github.com/sst/models.dev) 提交 pull request 更新 [models.dev](https://models.dev/) 的源数据。
2. （如果需要）通过向 LangChain [集成包](/oss/integrations/providers/overview) 提交 pull request 更新 `langchain_<package>/data/profile_augmentations.toml` 中的额外字段和覆盖。
3. 使用 [`langchain-model-profiles`](https://pypi.org/project/langchain-model-profiles/) CLI 工具从 [models.dev](https://models.dev/) 获取最新数据，合并增强并更新配置文件数据：

```bash
pip install langchain-model-profiles
```

```bash
langchain-profiles refresh --provider <provider> --data-dir <data_dir>
```

此命令：
- 从 models.dev 下载 `<provider>` 的最新数据
- 合并 `<data_dir>` 中 `profile_augmentations.toml` 的增强
- 将合并的配置文件写入 `<data_dir>` 中的 `profiles.py`

例如：来自 LangChain [monorepo](https://github.com/langchain-ai/langchain) 中的 [`libs/partners/anthropic`](https://github.com/langchain-ai/langchain/tree/master/libs/partners/anthropic)：

```bash
uv run --with langchain-model-profiles --provider anthropic --data-dir langchain_anthropic/data
```

:::js LangChain Chat Model 可以通过 .profile 属性公开支持的功能和能力的字典：

model.profile;
// {
//   maxInputTokens: 400000,
//   imageInputs: true,
//   reasoningOutput: true,
//   toolCalling: true,
//   ...
// }

请参阅 API 参考 中的完整字段集。

大部分模型配置文件数据由 models.dev 项目提供支持，这是一个提供模型能力数据的开源项目。这些数据增加了额外的字段以用于 LangChain。这些增强与上游项目保持一致。

模型配置文件数据允许应用程序动态处理模型功能。例如：

1. 摘要中间件 可以根据模型的上下文窗口大小触发摘要。
2. createAgent 中的 结构化输出 策略可以自动推断（例如，通过检查对原生结构化输出功能的支持）。
3. 可以根据支持的 模态 和最大输入 token 来限制模型输入。

**选项 1（快速修复）**

你可以使用任何有效的配置文件实例化 Chat Model：

```typescript
const customProfile = {
maxInputTokens: 100_000,
toolCalling: true,
structuredOutput: true,
// ...
};
const model = initChatModel("...", { profile: customProfile });
```

**选项 2（在上游修复数据）**

数据的主要来源是 [models.dev](https://models.dev/) 项目。这些数据与 LangChain [集成包](/oss/integrations/providers/overview) 中的额外字段和覆盖合并，并与这些包一起发布。

可以通过以下过程更新模型配置文件数据：

1. （如果需要）通过向其 [GitHub 仓库](https://github.com/sst/models.dev) 提交 pull request 更新 [models.dev](https://models.dev/) 的源数据。
2. （如果需要）通过向 LangChain [集成包](/oss/integrations/providers/overview) 提交 pull request 更新 `langchain-<package>/profiles.toml` 中的额外字段和覆盖。

多模态（Multimodal）

某些模型可以处理和返回非文本数据，如图像、音频和视频。你可以通过提供 内容块 将非文本数据传递给模型。

1. 跨提供商标准格式的数据（请参阅 [我们的 Messages 指南](/oss/langchain/messages)）
2. OpenAI [Chat Completions](https://platform.openai.com/docs/api-reference/chat) 格式
3. 特定提供商原生的任何格式（例如，Anthropic 模型接受 Anthropic 原生格式）

有关详情，请参阅 Messages 指南的 多模态部分。

某些模型 可以在其响应中返回多模态数据。如果被调用这样做，生成的 @[AIMessage] 将具有多模态类型的内容块。

:::python

response = model.invoke("创建一张猫的图片")
print(response.content_blocks)
# [
#     {"type": "text", "text": "这是一张猫的图片"},
#     {"type": "image", "base64": "...", "mime_type": "image/jpeg"},
# ]

:::

:::js

const response = await model.invoke("创建一张猫的图片");
console.log(response.contentBlocks);
// [
#   { type: "text", text: "这是一张猫的图片" },
#   { type: "image", data: "...", mimeType: "image/jpeg" },
# ]

:::

有关特定提供商的详情，请参阅 集成页面。

推理（Reasoning）

许多模型能够执行多步推理以得出结论。这涉及将复杂问题分解为更小、更易于管理的步骤。

如果底层模型支持， 你可以展示这个推理过程以更好地了解模型如何得出最终答案。

:::python python 流式推理输出 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)

```python 完整推理输出
response = model.invoke("为什么鹦鹉有彩色的羽毛？")
reasoning_steps = [b for b in response.content_blocks if b["type"] == "reasoning"]
print(" ".join(step["reasoning"] for step in reasoning_steps))
```

:::js typescript 流式推理输出 const stream = model.stream("为什么鹦鹉有彩色的羽毛？"); for await (const chunk of stream) { const reasoningSteps = chunk.contentBlocks.filter(b => b.type === "reasoning"); console.log(reasoningSteps.length > 0 ? reasoningSteps : chunk.text); }

```typescript 完整推理输出
const response = await model.invoke("为什么鹦鹉有彩色的羽毛？");
const reasoningSteps = response.contentBlocks.filter(b => b.type === "reasoning");
console.log(reasoningSteps.map(step => step.reasoning).join(" "));
```

根据模型，你有时可以指定它应该在推理上投入的努力程度。同样，你可以请求模型完全关闭推理。这可以采取推理的分类”层级”形式（例如 'low' 或 'high'）或整数 token 预算。

有关详情，请参阅 集成页面 或各自 Chat Model 的 参考。

本地模型

LangChain 支持在你自己的硬件上本地运行模型。这对于数据隐私至关重要、你想要调用自定义模型或想要避免使用基于云的模型所产生的成本的场景很有用。

Ollama 是在本地运行 Chat 和嵌入模型的最简单方法之一。

{/* TODO: 当我们有更好的集成目录时，使用本地查询过滤器交叉引用该页面 */}

提示缓存（Prompt Caching）

许多提供商提供提示缓存功能，以减少重复处理相同 token 的延迟和成本。这些功能可以是隐式或显式的：

• 隐式提示缓存：如果请求命中缓存，提供商将自动传递成本节省。示例：OpenAI 和 Gemini。
• 显式缓存：提供商允许你手动指示缓存点以获得更大的控制权或保证成本节省。示例：
  • @[ChatOpenAI]（通过 prompt_cache_key）
  • Anthropic 的 AnthropicPromptCachingMiddleware
  • Gemini。
  • AWS Bedrock

缓存使用将反映在模型响应的 使用元数据 中。

服务器端工具使用

一些提供商支持服务器端 工具调用 循环：模型可以与网络搜索、代码解释器和其他工具交互，并在单个对话轮次中分析结果。

如果模型在服务器端调用工具，响应消息的内容将包括表示工具调用和结果的内容。访问响应消息的 内容块 将以提供商无关的格式返回服务器端工具调用和结果：

:::python

from langchain.chat_models import init_chat_model

model = init_chat_model("gpt-4.1-mini")

tool = {"type": "web_search"}
model_with_tools = model.bind_tools([tool])

response = model_with_tools.invoke("今天有什么正面新闻？")
print(response.content_blocks)

[
    {
        "type": "server_tool_call",
        "name": "web_search",
        "args": {
            "query": "今天的正面新闻",
            "type": "search"
        },
        "id": "ws_abc123"
    },
    {
        "type": "server_tool_result",
        "tool_call_id": "ws_abc123",
        "status": "success"
    },
    {
        "type": "text",
        "text": "以下是今天的一些正面新闻...",
        "annotations": [
            {
                "end_index": 410,
                "start_index": 337,
                "title": "文章标题",
                "type": "citation",
                "url": "..."
            }
        ]
    }
]

:::

:::js

import { initChatModel } from "langchain";

const model = await initChatModel("gpt-4.1-mini");
const modelWithTools = model.bindTools([{ type: "web_search" }])

const message = await modelWithTools.invoke("今天有什么正面新闻？");
console.log(message.contentBlocks);

:::

这表示单个对话轮次；没有关联的 ToolMessage 对象需要像在客户端 工具调用 中那样传递。

有关可用工具和使用详情，请参阅给定提供商的 集成页面。

:::python

速率限制（Rate Limiting）

许多 Chat Model 提供商对给定时间内可以进行的调用次数施加限制。如果你达到速率限制，你通常会收到提供商的速率限制错误响应，并且需要等待才能发出更多请求。

为了帮助管理速率限制，Chat Model 集成接受一个 rate_limiter 参数，可以在初始化时提供以控制发出请求的速率。

```python 定义速率限制器
from langchain_core.rate_limiters import InMemoryRateLimiter

rate_limiter = InMemoryRateLimiter(
    requests_per_second=0.1,  # 每 10 秒 1 个请求
    check_every_n_seconds=0.1,  # 每 100 毫秒检查是否允许发出请求
    max_bucket_size=10,  # 控制最大突发大小。
)

model = init_chat_model(
    model="gpt-5",
    model_provider="openai",
    rate_limiter=rate_limiter  # [!code highlight]
)
```

<Warning>
    提供的速率限制器只能限制单位时间内的请求数。如果你还需要根据请求大小进行限制，它将无能为力。
</Warning>

基础 URL 和代理设置

你可以为实施 OpenAI Chat Completions API 的提供商配置自定义基础 URL。

对于 OpenRouter 和 LiteLLM，首选专用集成：
- [通过 `ChatOpenRouter` 的 OpenRouter](/oss/integrations/chat/openrouter)（`langchain-openrouter`）
- [通过 `ChatLiteLLM` / `ChatLiteLLMRouter` 的 LiteLLM](/oss/integrations/chat)（`langchain-litellm`）

```python
model = init_chat_model(
    model="MODEL_NAME",
    model_provider="openai",
    base_url="BASE_URL",
    api_key="YOUR_API_KEY",
)
```
:::

:::js
许多模型提供商提供 OpenAI 兼容的 API（例如 [Together AI](https://www.together.ai/)、[vLLM](https://github.com/vllm-project/vllm)）。你可以通过指定适当的 `base_url` 参数与这些提供商一起使用 `initChatModel`：

```python
model = initChatModel(
    "MODEL_NAME",
    {
        modelProvider: "openai",
        baseUrl: "BASE_URL",
        apiKey: "YOUR_API_KEY",
    }
)
```
:::

<Note>
    使用直接 Chat Model 类实例化时，参数名称可能因提供商而异。有关详情，请查看相应的 [参考](/oss/integrations/providers/overview)。
</Note>

:::python 对于需要 HTTP 代理的部署，一些模型集成支持代理配置：

```python
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="gpt-4.1",
    openai_proxy="http://proxy.example.com:8080"
)
```

```python
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("你叫什么名字")
```

```python
first_model.invoke(
    "你叫什么名字",
    config={
        "configurable": {
            "first_model": "claude-sonnet-4-6",
            "first_temperature": 0.5,
            "first_max_tokens": 100,
        }
    },
)
```

有关 `configurable_fields` 和 `config_prefix` 的更多详情，请参阅 @[`init_chat_model`] 参考。

```python
from pydantic import BaseModel, Field


class GetWeather(BaseModel):
    """获取给定位置的当前天气"""

        location: str = Field(..., description="城市和州，例如 San Francisco, CA")


class GetPopulation(BaseModel):
    """获取给定位置的当前人口"""

        location: str = Field(..., description="城市和州，例如 San Francisco, CA")


model = init_chat_model(temperature=0)
model_with_tools = model.bind_tools([GetWeather, GetPopulation])

model_with_tools.invoke(
    "2024 年 LA 和 NYC 哪个更大", config={"configurable": {"model": "gpt-4.1-mini"}}
).tool_calls
```
```
[
    {
        'name': 'GetPopulation',
        'args': {'location': 'Los Angeles, CA'},
        'id': 'call_Ga9m8FAArIyEjItHmztPYA22',
        'type': 'tool_call'
    },
    {
        'name': 'GetPopulation',
        'args': {'location': 'New York, NY'},
        'id': 'call_jh2dEvBaAHRaw5JUDthOs7rt',
        'type': 'tool_call'
    }
]
```
```python
model_with_tools.invoke(
    "2024 年 LA 和 NYC 哪个更大",
    config={"configurable": {"model": "claude-sonnet-4-6"}},
).tool_calls
```
```
[
    {
        'name': 'GetPopulation',
        'args': {'location': 'Los Angeles, CA'},
        'id': 'toolu_01JMufPf4F4t2zLj7miFeqXp',
        'type': 'tool_call'
    },
    {
        'name': 'GetPopulation',
        'args': {'location': 'New York City, NY'},
        'id': 'toolu_01RQBHcE8kEEbYTuuS8WqY1u',
        'type': 'tool_call'
    }
]
```