> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# ChatOpenRouter 集成

> 使用 LangChain Python 集成 ChatOpenRouter 聊天模型。

本文将帮助您开始使用 OpenRouter [聊天模型](/oss/python/langchain/models)。OpenRouter 是一个统一的 API，通过单一端点提供对多个提供商（OpenAI、Anthropic、Google、Meta 等）模型的访问。

<Tip>
  **API 参考**

  有关所有功能和配置选项的详细文档，请查阅 [`ChatOpenRouter`](https://reference.langchain.com/python/integrations/langchain_openrouter) API 参考。
</Tip>

有关可用模型的完整列表，请访问 [OpenRouter 模型页面](https://openrouter.ai/models)。

## 概述

### 集成详情

| 类                                                                                            | 包                                                                                                  | 可序列化 | JS/TS 支持 |                                                                                                         下载量                                                                                                        |                                                                                                                          最新版本                                                                                                                          |
| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :--: | :------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| [`ChatOpenRouter`](https://reference.langchain.com/python/integrations/langchain_openrouter) | [`langchain-openrouter`](https://reference.langchain.com/python/integrations/langchain_openrouter) | beta |     ❌    | <a href="https://pypi.org/project/langchain-openrouter/" target="_blank"><img src="https://static.pepy.tech/badge/langchain-openrouter/month" alt="Downloads per month" noZoom height="100" class="rounded" /></a> | <a href="https://pypi.org/project/langchain-openrouter/" target="_blank"><img src="https://img.shields.io/pypi/v/langchain-openrouter?style=flat-square&label=%20&color=orange" alt="PyPI - Latest version" noZoom height="100" class="rounded" /></a> |

### 模型特性

| [工具调用](/oss/python/langchain/tools) | [结构化输出](/oss/python/langchain/structured-output) | [图像输入](/oss/python/langchain/messages#multimodal) | 音频输入 | 视频输入 | [令牌级流式传输](/oss/python/langchain/streaming/) | 原生异步 | [令牌使用量](/oss/python/langchain/models#token-usage) | [对数概率](/oss/python/langchain/models#log-probabilities) |
| :---------------------------------: | :----------------------------------------------: | :-----------------------------------------------: | :--: | :--: | :-----------------------------------------: | :--: | :-----------------------------------------------: | :----------------------------------------------------: |
|                  ✅                  |                         ✅                        |                         ✅                         |   ✅  |   ✅  |                      ✅                      |   ✅  |                         ✅                         |                            ✅                           |

## 设置

要通过 OpenRouter 访问模型，您需要创建一个 [OpenRouter 账户](https://openrouter.ai/)，获取 API 密钥，并安装 `langchain-openrouter` 集成包。

### 安装

LangChain OpenRouter 集成位于 `langchain-openrouter` 包中：

<CodeGroup>
  ```bash pip theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  pip install -U langchain-openrouter
  ```

  ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  uv add langchain-openrouter
  ```
</CodeGroup>

### 凭证

前往 [OpenRouter 密钥页面](https://openrouter.ai/settings/keys) 注册并生成 API 密钥。完成后，设置 `OPENROUTER_API_KEY` 环境变量：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import getpass
import os

if not os.getenv("OPENROUTER_API_KEY"):
    os.environ["OPENROUTER_API_KEY"] = getpass.getpass("输入您的 OpenRouter API 密钥：")
```

要启用模型调用的自动追踪，请设置您的 [LangSmith](/langsmith/home) API 密钥：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("输入您的 LangSmith API 密钥：")
os.environ["LANGSMITH_TRACING"] = "true"
```

## 实例化

现在我们可以实例化模型对象并生成聊天补全：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    temperature=0,
    max_tokens=1024,
    max_retries=2,
    # 其他参数...
)
```

***

## 调用

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
messages = [
    (
        "system",
        "你是一个将英语翻译成法语的助手。翻译用户的句子。",
    ),
    ("human", "I love programming."),
]
ai_msg = model.invoke(messages)
ai_msg.content
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
"J'adore la programmation."
```

***

## 流式传输

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
for chunk in model.stream("写一首关于大海的短诗。"):
    print(chunk.text, end="", flush=True)
```

也支持异步流式传输：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
async for chunk in model.astream("写一首关于大海的短诗。"):
    print(chunk.text, end="", flush=True)
```

***

## 工具调用

OpenRouter 使用 OpenAI 兼容的工具调用格式。您可以描述工具及其参数，让模型返回一个包含要调用工具及其输入参数的 JSON 对象。

### 绑定工具

使用 `ChatOpenRouter.bind_tools`，您可以将 Pydantic 类、字典模式、LangChain 工具或函数作为工具传递给模型。在底层，这些会被转换为 OpenAI 工具模式，并在每次模型调用中传递。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from pydantic import BaseModel, Field


class GetWeather(BaseModel):
    """获取指定地点的当前天气"""

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


model_with_tools = model.bind_tools([GetWeather])
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ai_msg = model_with_tools.invoke(
    "旧金山的天气怎么样",
)
ai_msg
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
AIMessage(content='', response_metadata={'finish_reason': 'tool_calls'}, tool_calls=[{'name': 'GetWeather', 'args': {'location': 'San Francisco, CA'}, 'id': 'call_abc123', 'type': 'tool_call'}], usage_metadata={'input_tokens': 68, 'output_tokens': 17, 'total_tokens': 85})
```

### 工具调用

AIMessage 有一个 `tool_calls` 属性。它包含一个与模型提供商无关的标准化格式的工具调用。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ai_msg.tool_calls
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[{'name': 'GetWeather',
  'args': {'location': 'San Francisco, CA'},
  'id': 'call_abc123',
  'type': 'tool_call'}]
```

### 严格模式

传递 `strict=True` 以保证模型输出与工具定义中提供的 JSON Schema 完全匹配：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model_with_tools = model.bind_tools([GetWeather], strict=True)
```

有关绑定工具和工具调用输出的更多信息，请查阅 [工具调用](/oss/python/langchain/tools) 文档。

***

## 结构化输出

`ChatOpenRouter` 通过 [`with_structured_output`](/oss/python/langchain/models#structured-output) 方法支持结构化输出。有两种方法可用：`function_calling`（默认）和 `json_schema`。

<Accordion title="单个模型调用">
  使用 `with_structured_output` 生成结构化的模型响应。指定 `method="json_schema"` 以使用基于 JSON Schema 的结构化输出；否则方法默认为函数调用。

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain_openrouter import ChatOpenRouter
  from pydantic import BaseModel, Field

  model = ChatOpenRouter(model="openai/gpt-4.1")

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

  structured_model = model.with_structured_output(Movie, method="json_schema")  # [!code highlight]
  response = structured_model.invoke("提供电影《盗梦空间》的详细信息")
  response
  ```

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  Movie(title='Inception', year=2010, director='Christopher Nolan', rating=8.8)
  ```
</Accordion>

<Accordion title="智能体响应格式">
  使用 [`ProviderStrategy`](/oss/python/langchain/agents#providerstrategy) 指定 `response_format`，以便在生成智能体最终响应时启用结构化输出。

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.structured_output import ProviderStrategy
  from pydantic import BaseModel

  class Weather(BaseModel):
      temperature: float
      condition: str

  def weather_tool(location: str) -> str:
      """获取某个地点的天气。"""
      return "Sunny and 75 degrees F."

  agent = create_agent(
      model="openrouter:openai/gpt-4.1",
      tools=[weather_tool],
      response_format=ProviderStrategy(Weather),  # [!code highlight]
  )

  result = agent.invoke({
      "messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]
  })

  result["structured_response"]
  ```

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  Weather(temperature=75.0, condition='Sunny')
  ```
</Accordion>

您可以在 `function_calling` 和 `json_schema` 方法中传递 `strict=True` 以强制完全遵循模式。`strict` 参数不支持 `json_mode`。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
structured_model = model.with_structured_output(Movie, method="json_schema", strict=True)
```

***

## 推理输出

对于支持推理的模型（例如 `anthropic/claude-sonnet-4.5`、`deepseek/deepseek-r1`），您可以通过 `reasoning` 参数启用推理令牌。详情请参阅 [OpenRouter 推理文档](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens)：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    max_tokens=16384,
    reasoning={"effort": "high", "summary": "auto"},
)

ai_msg = model.invoke("529 的平方根是多少？")

# 通过 content_blocks 访问推理内容
for block in ai_msg.content_blocks:
    if block["type"] == "reasoning":
        print(block["reasoning"])
```

有关内容块的更多信息，请参阅 [标准内容块](/oss/python/langchain/messages#standard-content-blocks) 指南。

`reasoning` 字典支持两个键：

* `effort`：控制推理令牌预算。值：`"xhigh"`、`"high"`、`"medium"`、`"low"`、`"minimal"`、`"none"`。
* `summary`：控制响应中返回的推理摘要的详细程度。值：`"auto"`、`"concise"`、`"detailed"`。

推理令牌使用量包含在 `usage_metadata` 中：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
print(ai_msg.usage_metadata)
# {'input_tokens': ..., 'output_tokens': ..., 'total_tokens': ...,
#  'output_token_details': {'reasoning': ...}}
```

<Note>
  努力程度到预算的映射取决于模型。例如，Google Gemini 模型将努力程度映射到内部的 `thinkingLevel` 而不是精确的令牌预算。详情请参阅 [OpenRouter 推理文档](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens)。
</Note>

***

## 多模态输入

OpenRouter 支持接受多模态输入的模型的 [多模态输入](/oss/python/langchain/messages#multimodal)。可用的模态取决于您选择的模型——请查看 [OpenRouter 模型页面](https://openrouter.ai/models) 了解详情。

### 支持的输入方法

| 方法             |  图像 |  音频 |  视频 | PDF |
| -------------- | :-: | :-: | :-: | :-: |
| HTTP/HTTPS URL |  ✅  |  ❌  |  ✅  |  ✅  |
| Base64 内联数据    |  ✅  |  ✅  |  ✅  |  ✅  |

<Note>
  并非所有模型都支持所有模态。请查看 [OpenRouter 模型页面](https://openrouter.ai/models) 了解特定模型的支持情况。
</Note>

### 图像输入

使用带有列表内容格式的 [`HumanMessage`](https://reference.langchain.com/python/langchain-core/messages/human/HumanMessage) 提供图像输入以及文本。

<CodeGroup>
  ```python URL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain_openrouter import ChatOpenRouter
  from langchain.messages import HumanMessage

  model = ChatOpenRouter(model="openai/gpt-4o")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "描述这张图片。"},
          {
              "type": "image",
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Base64 编码 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import base64
  import httpx
  from langchain_openrouter import ChatOpenRouter
  from langchain.messages import HumanMessage

  model = ChatOpenRouter(model="openai/gpt-4o")

  image_url = "https://picsum.photos/id/237/200/300"
  image_data = base64.b64encode(httpx.get(image_url, follow_redirects=True).content).decode("utf-8")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "描述这张图片。"},
          { # [!code highlight]
              "type": "image", # [!code highlight]
              "base64": image_data, # [!code highlight]
              "mime_type": "image/jpeg", # [!code highlight]
          }, # [!code highlight]
      ]
  )
  response = model.invoke([message])
  ```
</CodeGroup>

### 音频输入

提供音频输入以及文本。音频以 base64 内联数据形式传递。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import base64
from pathlib import Path
from langchain_openrouter import ChatOpenRouter
from langchain.messages import HumanMessage

model = ChatOpenRouter(model="google/gemini-2.5-flash")

audio_data = base64.b64encode(Path("/path/to/audio.wav").read_bytes()).decode("utf-8")

message = HumanMessage(
    content=[
        {"type": "text", "text": "转录这段音频。"},
        { # [!code highlight]
            "type": "audio", # [!code highlight]
            "base64": audio_data, # [!code highlight]
            "mime_type": "audio/wav", # [!code highlight]
        }, # [!code highlight]
    ]
)
response = model.invoke([message])
```

### 视频输入

视频输入会自动转换为 OpenRouter 的 `video_url` 格式。

<CodeGroup>
  ```python URL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain_openrouter import ChatOpenRouter
  from langchain.messages import HumanMessage

  model = ChatOpenRouter(model="google/gemini-2.5-pro-preview")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "描述这个视频。"},
          {
              "type": "video",
              "url": "https://example.com/video.mp4",
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Base64 编码 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import base64
  from pathlib import Path
  from langchain_openrouter import ChatOpenRouter
  from langchain.messages import HumanMessage

  model = ChatOpenRouter(model="google/gemini-2.5-pro-preview")

  video_data = base64.b64encode(Path("/path/to/video.mp4").read_bytes()).decode("utf-8")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "描述这个视频。"},
          { # [!code highlight]
              "type": "video", # [!code highlight]
              "base64": video_data, # [!code highlight]
              "mime_type": "video/mp4", # [!code highlight]
          }, # [!code highlight]
      ]
  )
  response = model.invoke([message])
  ```
</CodeGroup>

### PDF 输入

提供 PDF 文件输入以及文本。

<CodeGroup>
  ```python URL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain_openrouter import ChatOpenRouter
  from langchain.messages import HumanMessage

  model = ChatOpenRouter(model="google/gemini-2.5-pro-preview")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "总结这个文档。"},
          {
              "type": "file",
              "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
              "mime_type": "application/pdf",
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Base64 编码 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import base64
  from pathlib import Path
  from langchain_openrouter import ChatOpenRouter
  from langchain.messages import HumanMessage

  model = ChatOpenRouter(model="google/gemini-2.5-pro-preview")

  pdf_data = base64.b64encode(Path("/path/to/document.pdf").read_bytes()).decode("utf-8")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "总结这个文档。"},
          { # [!code highlight]
              "type": "file", # [!code highlight]
              "base64": pdf_data, # [!code highlight]
              "mime_type": "application/pdf", # [!code highlight]
          }, # [!code highlight]
      ]
  )
  response = model.invoke([message])
  ```
</CodeGroup>

***

## 令牌使用量元数据

调用后，令牌使用量信息可在响应的 `usage_metadata` 属性中找到：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ai_msg = model.invoke("讲个笑话。")
ai_msg.usage_metadata
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'input_tokens': 12,
 'output_tokens': 25,
 'total_tokens': 37}
```

当底层提供商在其响应中包含详细的令牌细分时，它们会自动显示。当提供商未报告这些字段或其值为零时，这些字段会被省略。

### 推理令牌

`output_token_details.reasoning` 报告模型用于内部思维链推理的令牌数量。这在使用推理模型（例如 `deepseek/deepseek-r1`、`openai/o3`）或显式启用推理时出现：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    reasoning={"effort": "high"},
)

ai_msg = model.invoke("529 的平方根是多少？")
ai_msg.usage_metadata
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'input_tokens': 39,
 'output_tokens': 98,
 'total_tokens': 137,
 'output_token_details': {'reasoning': 62}}
```

### 缓存的输入令牌

`input_token_details.cache_read` 报告从提供商的提示缓存中提供的输入令牌数量，`input_token_details.cache_creation` 报告首次调用时写入缓存的令牌数量。

提示缓存需要在消息内容块中显式的 `cache_control` 断点。在要缓存的内容块上传递 `{"cache_control": {"type": "ephemeral"}}`：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter(model="anthropic/claude-sonnet-4.5")

long_system = "你是一个乐于助人的助手。 " * 200
messages = [
    ("system", [{"type": "text", "text": long_system, "cache_control": {"type": "ephemeral"}}]),
    ("human", "打个招呼。"),
]

# 第一次调用写入缓存
ai_msg = model.invoke(messages)
ai_msg.usage_metadata
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'input_tokens': 1210,
 'output_tokens': 12,
 'total_tokens': 1222,
 'input_token_details': {'cache_creation': 1201}}
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 第二次调用从缓存读取
ai_msg = model.invoke(messages)
ai_msg.usage_metadata
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'input_tokens': 1210,
 'output_tokens': 12,
 'total_tokens': 1222,
 'input_token_details': {'cache_read': 1201}}
```

<Note>
  如果消息内容块上没有 `cache_control`，提供商将不会缓存提示，这些字段也不会出现。
</Note>

流式传输时，从最终块聚合令牌使用量：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
stream = model.stream("讲个笑话。")
full = next(stream)
for chunk in stream:
    full += chunk
full.usage_metadata
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'input_tokens': 12,
 'output_tokens': 25,
 'total_tokens': 37}
```

***

## 响应元数据

调用后，提供商和模型元数据可在 `response_metadata` 属性中找到：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ai_msg = model.invoke("讲个笑话。")
ai_msg.response_metadata
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'model_name': 'anthropic/claude-sonnet-4.5',
 'id': 'gen-1771043112-yLUz3txgvHSjkyCQK8KQ',
 'created': 1771043112,
 'object': 'chat.completion',
 'finish_reason': 'stop',
 'logprobs': None,
 'model_provider': 'openrouter'}
```

如果存在，`native_finish_reason` 字段包含底层提供商的原始完成原因，可能与标准化的 `finish_reason` 不同。

***

## 提供商路由

OpenRouter 上的许多模型由多个提供商提供服务。`openrouter_provider` 参数让您可以控制哪些提供商处理您的请求以及如何选择它们。

### 排序和过滤提供商

使用 `order` 设置首选提供商序列。OpenRouter 按顺序尝试每个提供商，如果某个提供商不可用，则回退到下一个：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    openrouter_provider={
        "order": ["Anthropic", "Google"],
        "allow_fallbacks": True,  # 默认值；如果需要，可以回退到顺序列表之外
    },
)
```

要仅将请求限制在特定提供商，请使用 `only`。要排除某些提供商，请使用 `ignore`：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 仅使用这些提供商（不回退到其他提供商）
model = ChatOpenRouter(
    model="openai/gpt-4o",
    openrouter_provider={"only": ["OpenAI", "Azure"]},
)

# 使用除 DeepInfra 之外的任何提供商
model = ChatOpenRouter(
    model="meta-llama/llama-4-maverick",
    openrouter_provider={"ignore": ["DeepInfra"]},
)
```

### 按成本、速度或延迟排序

默认情况下，OpenRouter 在提供商之间进行负载均衡，优先考虑较低成本。使用 `sort` 更改优先级：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 优先选择最快的提供商（最高的令牌/秒）
model = ChatOpenRouter(
    model="openai/gpt-4o",
    openrouter_provider={"sort": "throughput"},
)

# 优先选择延迟最低的提供商
model = ChatOpenRouter(
    model="openai/gpt-4o",
    openrouter_provider={"sort": "latency"},
)
```

### 数据收集策略

如果您的用例要求提供商不存储或训练您的数据，请将 `data_collection` 设置为 `"deny"`：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    openrouter_provider={"data_collection": "deny"},
)
```

### 按量化过滤

对于开放权重模型，您可以限制路由到特定的精度级别：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model = ChatOpenRouter(
    model="meta-llama/llama-4-maverick",
    openrouter_provider={"quantizations": ["fp16", "bf16"]},
)
```

### 路由参数

`route` 参数控制高级路由行为：

* `"fallback"`：启用跨提供商的自动故障转移（默认行为）。
* `"sort"`：基于 `openrouter_provider` 中配置的排序策略进行路由。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    route="fallback",
)
```

### 组合选项

提供商选项可以组合使用：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model = ChatOpenRouter(
    model="openai/gpt-4o",
    openrouter_provider={
        "order": ["OpenAI", "Azure"],
        "allow_fallbacks": False,       # 严格——仅使用顺序中的提供商
        "require_parameters": True,     # 跳过不支持所有参数的提供商
        "data_collection": "deny",
    },
)
```

有关完整选项列表，请参阅 [OpenRouter 提供商路由文档](https://openrouter.ai/docs/guides/routing/provider-selection)。

***

## 应用归属

OpenRouter 通过 HTTP 标头支持应用归属。您可以通过初始化参数或环境变量设置这些：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    app_url="https://myapp.com",   # 或 OPENROUTER_APP_URL 环境变量
    app_title="My App",            # 或 OPENROUTER_APP_TITLE 环境变量
)
```

***

## API 参考

有关 `ChatOpenRouter` 所有功能和配置的详细文档，请查阅 [`ChatOpenRouter`](https://reference.langchain.com/python/integrations/langchain_openrouter) API 参考。

有关 OpenRouter 平台、模型和功能的更多信息，请参阅 [OpenRouter 文档](https://openrouter.ai/docs)。

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\oss\python\integrations\chat\openrouter.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>