ChatOpenRouter 完整配置详解

OpenRouter 是一个兼容 OpenAI 接口的模型路由服务，单一端点背后聚合了 400 余个模型与 70 余家提供商。此前，许多教程教导开发者通过将 ChatOpenAI 的 base_url 指向 OpenRouter 来实现集成，但这种方式缺乏类型支持且依赖非官方约定。现在，官方专用包 langchain-openrouter 已发布至 PyPI，@langchain/openrouter 也已上线 npm，提供了更规范的集成路径。ChatOpenRouter 可以像任何 LangChain 聊天模型一样插入链或 Agent，唯一的 OpenRouter 特有参数只有模型字符串本身。

快速上手只需三步：安装包、配置密钥、发起调用。通过 pip install -U langchain-openrouter 安装后，将 API 密钥写入环境变量 OPENROUTER_API_KEY，ChatOpenRouter 会自动读取。实例化时传入 provider/model 格式的模型字符串，例如 anthropic/claude-sonnet-4.5，同时可设置 temperature、max_tokens、max_retries 等标准 LangChain 参数。TypeScript 用户使用 @langchain/openrouter 包，写法结构完全一致。切换模型只需修改一个字符串，链的其余部分——提示词、工具定义、输出解析——均无需改动。

流式响应通过 stream_events 方法实现，异步场景使用 astream_events，两者的每 token 费率与非流式调用完全相同，流式传输仅用于改善用户体验而非降低成本。调用时需传入 version='v3' 以获取当前事件模式，token 用量统计可从最终聚合消息的 usage_metadata 字段直接读取，无需额外发起查询请求。对于 LangChain Agent，还支持 openrouter:provider/model 前缀的简写形式，在 create_agent 层面直接指定模型，跳过构造函数。

工具调用与结构化输出是生产场景的核心需求。bind_tools 方法接受 Pydantic 模型列表，配合 strict=True 可强制模型严格遵循工具 schema 而非自由发挥参数。with_structured_output 则将 schema 绑定到整个响应，支持 function_calling 和 json_schema 两种方法，后者在模型原生支持时提供更严格的 JSON schema 校验。需要注意的是，strict 参数仅适用于 function_calling 和 json_schema 方法，不适用于 json_mode，且并非所有模型都支持所有方法，具体能力需查阅模型目录。

路由层是 OpenRouter 区别于简单代理的核心价值所在。当某个提供商出现故障或过载时，路由层会自动将请求切换至其他可用提供商，整个过程对链代码完全透明。开发者可通过 openrouter_provider 和 route 参数显式控制路由行为，例如设置 require_parameters: true 以确保请求只发往支持所传参数的提供商，从而避免因参数不兼容导致的静默降级。未完成的请求不计费这一机制，使得在路由切换过程中不会产生额外的经济损失，降低了在生产环境中启用多提供商故障转移的门槛。

要点

• 官方专用包 langchain-openrouter（PyPI）和 @langchain/openrouter（npm）已发布，旧版 ChatOpenAI base_url 覆盖方案应升级至新路径
• 模型切换只需修改 provider/model 格式的字符串，链的提示词、工具定义和输出解析均无需改动
• 路由层自动处理负载均衡与跨提供商故障转移，未完成请求不计费，生产环境启用多提供商容灾成本极低
• 工具调用与结构化输出支持 strict=True 强制 schema 校验，但需确认目标模型是否支持对应方法
• 该包处于 Beta 阶段，建议始终使用 pip install -U 安装最新版本以获取最新功能和修复