OpenRouter统一LLM API平台：构建高可用AI应用的路由与故障转移实践

在实际 AI 应用开发中，直接调用单一大型语言模型（LLM）的 API 往往面临诸多挑战：不同模型提供商（如 OpenAI、Anthropic、Google、DeepSeek 等）的 API 接口各异，计费方式复杂，模型能力与成本差异巨大。当某个模型服务出现故障、响应超时或达到调用限额时，应用会直接中断，缺乏容错能力。此外，开发者还需要手动管理 API 密钥、处理不同模型的上下文长度限制和输出格式差异，这些琐碎但关键的工作极大地分散了开发精力，降低了开发效率。

OpenRouter 正是为了解决这些问题而生的一个统一 LLM API 平台。它不是一个新模型，而是一个智能的“路由层”或“代理层”。其核心价值在于，开发者只需使用一套统一的 API 接口和密钥，即可访问其集成的数十个主流 LLM（如 GPT-4、Claude 3、Gemini、DeepSeek 等）。OpenRouter 会自动处理与各个上游供应商的通信、计费转换和错误处理。更重要的是，它提供了强大的路由（Routing）和故障转移（Fallbacks）机制。你可以定义一套规则，例如“优先使用性价比最高的模型，如果失败或超时，则自动切换到备用模型”，从而构建出高可用、高性价比的 AI 应用后端。

本文面向正在构建或计划构建生产级 AI 应用的开发者、架构师以及技术决策者。我们将从零开始，带你理解 OpenRouter 的核心概念，完成账户配置与充值，并通过一个完整的 Python 示例项目，演示如何利用其路由和故障转移功能，构建一个健壮的聊天应用后端。你将学会如何配置模型优先级、设置预算、处理各类 API 错误，并最终掌握一套可复用于实际项目的工程实践。

1. 理解 OpenRouter 的核心机制：路由、回退与统一接口

在深入代码之前，必须清晰理解 OpenRouter 解决的几个核心工程问题及其背后的工作机制。这能帮助你在设计应用架构时做出正确决策。

1.1 统一 API 接口：告别供应商锁定

传统的 LLM 集成方式要求开发者针对每个供应商编写特定的 SDK 调用代码，管理不同的 API 密钥和端点（Endpoint）。OpenRouter 通过提供一个标准化的 RESTful API 接口（模仿 OpenAI API 格式），彻底抽象了底层供应商的差异。

这意味着，如果你已经熟悉 OpenAI 的 ChatCompletion API，那么迁移到 OpenRouter 几乎无需修改业务逻辑代码。你只需要将请求发送到https://openrouter.ai/api/v1/chat/completions，并在请求头中指定你想要调用的模型（如openai/gpt-4-turbo或anthropic/claude-3-opus），OpenRouter 便会充当中间人，完成请求的转发和响应的回传。这种设计极大地降低了集成和维护成本。

1.2 智能路由：成本、性能与质量的平衡

路由是 OpenRouter 最核心的功能之一。它允许你为一个请求指定多个候选模型，并定义选择策略。常见的路由策略包括：

1. 优先级路由：按顺序尝试模型列表，使用第一个可用的模型。这常用于设置主备模型。
2. 成本优化路由：在满足性能要求的前提下，自动选择单位成本最低的模型。
3. 延迟优化路由：自动选择响应最快的模型。

在实际配置中，你可以通过请求参数或预设的“路由配置”来指定这些策略。例如，你可以创建一个路由规则：“对于一般问答，优先使用deepseek/deepseek-chat（低成本）；如果问题涉及复杂推理，则路由到openai/gpt-4o（高能力）”。OpenRouter 会根据你设定的条件（如输入 token 长度、关键词匹配等）自动执行路由决策。

1.3 故障转移：构建高可用应用的关键

故障转移（Fallback）是路由策略的一个特例，主要目标是保障服务的可用性。当主模型因网络问题、服务宕机、速率限制（Rate Limit）或余额不足而请求失败时，系统不会直接向用户返回错误，而是自动、无缝地切换到预先配置的备用模型上继续处理请求。

这个过程对应用层是透明的。例如，你的应用配置了[“openai/gpt-4”, “anthropic/claude-3-sonnet”, “google/gemini-pro”]作为模型链。当请求gpt-4失败（返回非 2xx 状态码或超时），OpenRouter 会自动重试claude-3-sonnet，以此类推，直到有一个模型成功响应或所有模型都失败。这显著提升了终端用户体验和系统的整体 SLA（服务等级协议）。

1.4 统一计费与预算控制

OpenRouter 提供了统一的计费面板，将不同供应商以 Token 为单位的计费方式，统一转换为以美元计费。你可以在平台上为每个 API 密钥设置预算（Budget）和速率限制，防止因意外流量或循环调用导致巨额账单。这种集中式的财务管理和监控，对于团队协作和成本控制至关重要。

2. 环境准备与 OpenRouter 账户配置

在开始编码前，你需要完成 OpenRouter 账户的注册、API 密钥的创建以及充值。这是后续所有操作的基础。

2.1 注册账户与获取 API 密钥

1. 访问官网：打开 OpenRouter 官方网站。
2. 注册登录：使用邮箱或第三方账号（如 GitHub）完成注册并登录。
3. 创建 API 密钥：
   • 进入控制台（Dashboard）页面。
   • 找到 “API Keys” 部分。
   • 点击 “Create Key” 按钮。
   • 为密钥命名（例如my-production-key），并设置权限（通常保持默认即可）。
   • 创建成功后，系统会生成一个以sk-or-开头的密钥字符串。请立即复制并妥善保存，因为它只显示一次。

2.2 账户充值

OpenRouter 采用预付费（Pre-paid）模式。你需要先为账户充值，才能调用需要付费的模型（部分模型有免费额度）。

1. 在控制台找到 “Billing” 或 “Add Funds” 选项。
2. 选择充值金额（例如 10 美元）。平台支持常见的支付方式。
3. 完成支付流程。充值成功后，余额会显示在控制台显眼位置。

2.3 本地开发环境准备

我们将使用 Python 进行演示。请确保你的开发环境满足以下要求：

• Python 版本：>= 3.8
• 包管理工具：pip
• 网络：能够正常访问 OpenRouter API 端点。

首先，创建一个新的项目目录并初始化虚拟环境，这是管理项目依赖的最佳实践。

# 创建项目目录 mkdir openrouter-demo && cd openrouter-demo # 创建虚拟环境（以 venv 为例） python -m venv venv # 激活虚拟环境 # 在 Windows 上： venv\Scripts\activate # 在 macOS/Linux 上： source venv/bin/activate

激活虚拟环境后，命令行提示符前通常会显示(venv)标识。接下来，安装必要的 Python 库。我们将使用requests库进行 HTTP 调用，并使用python-dotenv管理环境变量。

pip install requests python-dotenv

2.4 管理敏感信息：使用环境变量

永远不要将 API 密钥等敏感信息硬编码在代码中。我们将使用.env文件来存储它们。

在项目根目录下创建名为.env的文件，并填入你的 OpenRouter API 密钥：

# .env 文件内容 OPENROUTER_API_KEY=sk-or-你的实际密钥 OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

同时，创建一个.gitignore文件，确保.env不会被提交到版本控制系统。

# .gitignore 文件内容 venv/ __pycache__/ *.pyc .env

3. 构建基础请求：从单一模型调用开始

在实现复杂的路由和故障转移之前，我们先实现一个最基础的、调用单一模型的聊天完成（Chat Completion）功能。这能帮助我们熟悉 OpenRouter 的 API 格式，并验证环境配置是否正确。

3.1 项目结构与基础工具函数

在项目根目录下创建以下文件结构：

openrouter-demo/ ├── .env ├── .gitignore ├── config.py ├── openrouter_client.py └── main.py

config.py文件负责加载环境变量，并提供配置信息。

# config.py import os from dotenv import load_dotenv # 加载 .env 文件中的环境变量 load_dotenv() class Config: # 从环境变量读取 API 密钥和基础 URL API_KEY = os.getenv("OPENROUTER_API_KEY") BASE_URL = os.getenv("OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1") # 基础请求头 @staticmethod def get_headers(): return { "Authorization": f"Bearer {Config.API_KEY}", "Content-Type": "application/json", # OpenRouter 允许你指定调用来源，方便在仪表盘区分流量 "HTTP-Referer": "https://my-awesome-app.com", # 替换为你的网站或项目 URL "X-Title": "OpenRouter Demo App", # 替换为你的应用名称 } @staticmethod def check_config(): """检查关键配置是否已设置""" if not Config.API_KEY: raise ValueError("OPENROUTER_API_KEY 未在 .env 文件中设置。") print("配置检查通过。")

openrouter_client.py文件将封装与 OpenRouter API 交互的核心逻辑。

# openrouter_client.py import requests import json from config import Config class OpenRouterClient: def __init__(self): self.base_url = Config.BASE_URL self.headers = Config.get_headers() Config.check_config() def _make_request(self, endpoint, payload): """内部方法：发起 POST 请求""" url = f"{self.base_url}/{endpoint}" try: response = requests.post(url, headers=self.headers, json=payload, timeout=30) response.raise_for_status() # 如果状态码不是 2xx，抛出 HTTPError return response.json() except requests.exceptions.Timeout: raise Exception(f"请求超时: {url}") except requests.exceptions.HTTPError as e: # 尝试解析错误信息 error_detail = "未知错误" try: error_detail = response.json().get('error', {}).get('message', str(e)) except: error_detail = str(e) raise Exception(f"API 请求失败 ({response.status_code}): {error_detail}") except requests.exceptions.RequestException as e: raise Exception(f"网络请求异常: {e}") def chat_completion(self, model, messages, **kwargs): """ 调用聊天补全接口 Args: model (str): OpenRouter 模型标识符，如 'openai/gpt-3.5-turbo' messages (list): 对话消息列表，格式同 OpenAI API **kwargs: 其他可选参数，如 temperature, max_tokens 等 Returns: dict: API 响应数据 """ endpoint = "chat/completions" payload = { "model": model, "messages": messages, **kwargs # 将其他参数合并到 payload 中 } return self._make_request(endpoint, payload) def get_choice_text(self, response): """从标准响应中提取第一个候选文本""" return response['choices'][0]['message']['content']

3.2 实现并验证基础调用

现在，我们在main.py中编写代码，使用上面创建的客户端调用一个具体模型。

# main.py from openrouter_client import OpenRouterClient def basic_chat(): client = OpenRouterClient() # 定义对话消息。格式与 OpenAI API 完全一致。 messages = [ {"role": "system", "content": "你是一个乐于助人的助手。"}, {"role": "user", "content": "请用中文简单介绍一下你自己。"} ] # 指定一个模型。这里使用 Anthropic 的 Claude 3 Haiku，它性价比较高。 model = "anthropic/claude-3-haiku" # 可选参数 params = { "temperature": 0.7, "max_tokens": 500, } print(f"正在调用模型: {model}") print(f"用户消息: {messages[1]['content']}") print("-" * 40) try: response = client.chat_completion(model, messages, **params) answer = client.get_choice_text(response) print(f"助手回复:\n{answer}") print("-" * 40) # 打印一些元数据，如使用的 token 数量 usage = response.get('usage', {}) print(f"消耗情况: 输入 {usage.get('prompt_tokens', 'N/A')} tokens, " f"输出 {usage.get('completion_tokens', 'N/A')} tokens.") except Exception as e: print(f"调用失败: {e}") if __name__ == "__main__": basic_chat()

运行这个脚本，验证你的配置是否正确：

python main.py

如果一切正常，你将看到类似以下的输出：

配置检查通过。 正在调用模型: anthropic/claude-3-haiku 用户消息: 请用中文简单介绍一下你自己。 ---------------------------------------- 助手回复: 你好！我是由 Anthropic 创造的 AI 助手 Claude。我基于 Claude 3 Haiku 模型运行，通过 OpenRouter 平台为您提供服务。我乐于助人，可以协助您解答问题、进行对话、处理文本任务等。有什么我可以帮您的吗？ ---------------------------------------- 消耗情况: 输入 45 tokens, 输出 78 tokens.

这个基础调用成功，意味着你的 API 密钥、网络环境和基础代码都是正确的。接下来，我们将在此基础上增加路由和故障转移能力。

4. 实现路由与故障转移策略

OpenRouter 的路由和故障转移功能可以通过两种主要方式实现：

1. 客户端逻辑：在你的应用代码中，顺序调用多个模型，自己处理错误和切换。这种方式灵活，但代码复杂度高。
2. 服务端路由（推荐）：利用 OpenRouter API 的原生支持，在单个请求中指定多个模型或路由规则。这种方式更简洁，可靠性更高，因为切换逻辑由 OpenRouter 服务端处理。

我们将重点介绍第二种，即 OpenRouter 原生支持的方式。

4.1 使用模型列表实现简单故障转移

OpenRouter 的/chat/completions接口的model参数，除了接受单个模型标识符，还可以接受一个模型数组。当提供数组时，OpenRouter 会按数组顺序尝试这些模型，直到有一个成功返回响应。

修改openrouter_client.py中的chat_completion方法，使其支持模型列表：

# 在 openrouter_client.py 的 OpenRouterClient 类中更新 chat_completion 方法 def chat_completion(self, model, messages, **kwargs): """ 调用聊天补全接口 Args: model (str or list): 单个模型标识符，或模型标识符的列表（用于故障转移） messages (list): 对话消息列表 **kwargs: 其他可选参数 Returns: dict: API 响应数据，包含一个额外的 `_model_used` 字段指示最终使用的模型 """ endpoint = "chat/completions" payload = { "model": model, # 这里可以是字符串或列表 "messages": messages, **kwargs } response_data = self._make_request(endpoint, payload) # 从响应头中获取实际使用的模型（OpenRouter 可能会返回这个信息） # 注意：实际实现中需要根据 OpenRouter 的响应格式调整。 # 一种更可靠的方式是在请求中添加一个特殊参数或查看响应体。 # 目前，我们假设如果请求成功，则使用了列表中的第一个成功模型。 # 我们可以在返回的数据中添加一个自定义字段。 # 由于 OpenRouter 响应格式与 OpenAI 兼容，它可能不直接包含最终模型名。 # 我们可以通过检查请求的模型参数是列表还是字符串来推断。 # 更优解：使用下面 4.2 节介绍的 `route` 参数。 return response_data

然后，创建一个新的演示文件demo_fallback.py来展示故障转移：

# demo_fallback.py from openrouter_client import OpenRouterClient import time def fallback_demo(): client = OpenRouterClient() messages = [ {"role": "user", "content": "什么是机器学习？用一句话解释。"} ] # 定义一个模型优先级列表。 # 顺序很重要：会先尝试第一个，如果失败（如超时、无权限、余额不足），则尝试第二个，以此类推。 # 这里故意放入一个不存在的模型 `fake/model` 来模拟失败场景。 model_list = [ "fake/model", # 这个模型不存在，会触发失败 "openai/gpt-3.5-turbo", # 第一个备用模型 "google/gemini-pro", # 第二个备用模型 ] print("开始故障转移演示...") print(f"模型列表: {model_list}") print("-" * 40) start_time = time.time() try: response = client.chat_completion(model_list, messages, max_tokens=100) answer = client.get_choice_text(response) elapsed = time.time() - start_time print(f"请求成功，耗时 {elapsed:.2f} 秒。") print(f"回答: {answer}") # 注意：标准响应可能不包含最终使用的模型名。 # 在实际生产代码中，你可能需要记录请求参数和响应，或使用下文介绍的 `route` 参数。 print("提示：由于第一个模型不存在，OpenRouter 应自动使用了列表中的下一个可用模型。") except Exception as e: elapsed = time.time() - start_time print(f"所有模型尝试均失败，总耗时 {elapsed:.2f} 秒。") print(f"最终错误: {e}") if __name__ == "__main__": fallback_demo()

运行此脚本，你会观察到即使第一个模型失败，请求依然成功，因为 OpenRouter 自动尝试了列表中的后续模型。

4.2 使用route参数实现声明式路由（推荐）

OpenRouter 提供了一个更强大的route参数，允许你在请求体中定义更复杂的路由逻辑，而不是简单的顺序列表。route参数的值是一个字符串，目前支持fallback模式。

修改openrouter_client.py，增加一个支持route参数的方法：

# 在 openrouter_client.py 的 OpenRouterClient 类中添加新方法 def chat_completion_with_route(self, route_type, models, messages, **kwargs): """ 使用声明式路由调用聊天补全接口 Args: route_type (str): 路由类型，如 'fallback' models (list): 模型标识符列表 messages (list): 对话消息列表 **kwargs: 其他可选参数 Returns: dict: API 响应数据 """ endpoint = "chat/completions" payload = { "route": route_type, # 例如 “fallback” "models": models, # 模型列表 "messages": messages, **kwargs } return self._make_request(endpoint, payload)

创建一个新的演示文件demo_route_fallback.py：

# demo_route_fallback.py from openrouter_client import OpenRouterClient def route_fallback_demo(): client = OpenRouterClient() messages = [ {"role": "user", "content": "编写一个 Python 函数计算斐波那契数列的第 n 项。"} ] # 使用 route 参数明确指定故障转移行为 models_for_fallback = [ "anthropic/claude-3-opus", # 主模型（能力强，可能贵或慢） "openai/gpt-4o", # 第一备用 "anthropic/claude-3-sonnet", # 第二备用 "deepseek/deepseek-chat", # 第三备用（经济型） ] print("使用声明式路由 (route=fallback) 进行调用...") print(f"备用链: {models_for_fallback}") print("-" * 40) try: response = client.chat_completion_with_route( route_type="fallback", models=models_for_fallback, messages=messages, temperature=0.3, max_tokens=300 ) answer = client.get_choice_text(response) print(f"回答:\n{answer}") print("-" * 40) # 查看响应中是否包含路由信息（取决于 OpenRouter API 实现） # print(f"完整响应: {json.dumps(response, indent=2, ensure_ascii=False)}") except Exception as e: print(f"调用失败: {e}") if __name__ == "__main__": route_fallback_demo()

使用route参数是更清晰、更面向未来的方式，它明确表达了开发者的意图，并且可能支持未来更复杂的路由策略。

4.3 构建一个健壮的聊天应用后端

现在，我们将上述知识整合，构建一个简单的、具备故障转移能力的聊天后端类。这个类会封装模型选择策略、错误处理和基础会话管理。

创建chat_backend.py：

# chat_backend.py import json import time from openrouter_client import OpenRouterClient class RobustChatBackend: def __init__(self, primary_models, fallback_models, system_prompt=None): """ 初始化聊天后端 Args: primary_models (list): 主用模型列表（按优先级排序） fallback_models (list): 故障转移模型列表（按优先级排序） system_prompt (str, optional): 系统提示词 """ self.client = OpenRouterClient() self.primary_models = primary_models self.fallback_models = fallback_models self.system_prompt = system_prompt self.conversation_history = [] if system_prompt: self.conversation_history.append({"role": "system", "content": system_prompt}) def add_user_message(self, content): """添加用户消息到历史记录""" self.conversation_history.append({"role": "user", "content": content}) def add_assistant_message(self, content): """添加助手消息到历史记录""" self.conversation_history.append({"role": "assistant", "content": content}) def get_reply(self, user_input, max_retries=2): """ 获取助手回复，具备重试和故障转移能力 Args: user_input (str): 用户输入 max_retries (int): 对同一模型策略的最大重试次数 Returns: tuple: (success(bool), reply_text(str), model_used(str), error_msg(str)) """ self.add_user_message(user_input) # 构建本次请求的模型链：主用模型 + 备用模型 model_chain = self.primary_models + self.fallback_models last_error = None for attempt in range(max_retries): for i, model in enumerate(model_chain): print(f"[尝试] 第 {attempt + 1} 轮，使用模型: {model}") try: # 使用支持列表的 chat_completion 方法 response = self.client.chat_completion( model=model, # 这里传入单个模型，由外层循环控制故障转移 messages=self.conversation_history, temperature=0.7, max_tokens=800 ) reply_text = self.client.get_choice_text(response) self.add_assistant_message(reply_text) # 在实际项目中，可以从响应中解析更精确的模型信息 return True, reply_text, model, None except Exception as e: last_error = f"模型 {model} 失败: {e}" print(f" -> 失败: {e}") # 如果这个模型失败，继续尝试链中的下一个模型 continue # 如果一整轮所有模型都失败了，等待片刻后重试（指数退避） if attempt < max_retries - 1: wait_time = 2 ** attempt # 指数退避：1, 2, 4秒... print(f"一轮尝试全部失败，等待 {wait_time} 秒后重试...") time.sleep(wait_time) # 所有重试都失败 # 从历史记录中移除最后一条用户消息，因为对话未成功 if self.conversation_history and self.conversation_history[-1]["role"] == "user": self.conversation_history.pop() return False, None, None, f"所有模型尝试均失败。最后错误: {last_error}" def clear_history(self): """清空对话历史，保留系统提示""" self.conversation_history = [] if self.system_prompt: self.conversation_history.append({"role": "system", "content": self.system_prompt})

创建一个主程序main_robust_chat.py来使用这个后端：

# main_robust_chat.py from chat_backend import RobustChatBackend def main(): # 定义模型策略：优先使用较新或性价比较高的模型，备用一些稳定但可能稍贵的模型 primary = ["openai/gpt-4o", "anthropic/claude-3-haiku"] fallback = ["google/gemini-pro", "meta-llama/llama-3-70b-instruct"] system_prompt = "你是一个专业的软件工程师助手，回答要简洁、准确。" chat_backend = RobustChatBackend(primary, fallback, system_prompt) print("健壮聊天后端已启动。输入 ‘quit’ 退出，输入 ‘clear’ 清空历史。") print(f"主用模型: {primary}") print(f"备用模型: {fallback}") print("-" * 50) while True: try: user_input = input("\nYou: ").strip() if not user_input: continue if user_input.lower() == 'quit': print("再见！") break if user_input.lower() == 'clear': chat_backend.clear_history() print("对话历史已清空。") continue print("思考中...") success, reply, model_used, error = chat_backend.get_reply(user_input) if success: print(f"\nAssistant (via {model_used}):") print(reply) else: print(f"\n抱歉，请求失败: {error}") except KeyboardInterrupt: print("\n程序被中断。") break except Exception as e: print(f"\n发生未预期错误: {e}") if __name__ == "__main__": main()

运行这个程序，你将得到一个具有自动故障转移能力的命令行聊天工具。你可以通过临时断开网络或模拟错误来测试其容错性。

5. 关键配置、错误处理与生产环境建议

将 OpenRouter 用于生产环境，除了基础调用和故障转移，还需要关注配置细节、错误处理和运维实践。

5.1 关键请求参数与配置

下表列出了调用 OpenRouter API 时最常用和最关键的一些参数：

5.2 常见 API 错误与排查路径

即使有故障转移，理解并妥善处理错误对于调试和运维至关重要。以下是调用 OpenRouter API 时可能遇到的常见错误及其处理方式。

5.3 生产环境最佳实践

1. 密钥与配置管理：

   • 使用环境变量或专业的密钥管理服务（如 AWS Secrets Manager, HashiCorp Vault）存储 API 密钥。
   • 为不同环境（开发、测试、生产）使用不同的 API 密钥，并在 OpenRouter 控制台设置相应的预算和限制。

2. 预算与成本控制：

   • 在 OpenRouter 控制台为每个密钥设置月度预算和每分钟/每日请求限制，防止意外消费。
   • 在代码中集成使用量监控，定期检查response[‘usage’]中的 token 消耗，并记录到你的监控系统。
   • 对于非关键任务，优先考虑性价比高的模型（如 DeepSeek, Claude Haiku）。

3. 日志与监控：

   • 记录所有请求的元数据：请求模型、实际使用模型（如果可知）、消耗 token、耗时、是否触发故障转移。
   • 设置告警，当故障转移频率异常升高或特定模型错误率飙升时通知团队。

4. 性能与可靠性：

   • 设置合理的客户端超时（如 30-60 秒），避免线程阻塞。
   • 使用连接池（如requests.Session）来复用 HTTP 连接，提升性能。
   • 考虑在应用层增加一个本地缓存，对于完全相同的提示词和参数，可以返回缓存结果，减少 API 调用和成本。

5. 模型选型策略：

   • 定期评估 OpenRouter 上模型的价格和性能变化。
   • 建立自己的模型性能基准测试，根据实际任务（代码生成、文案创作、逻辑推理）的表现来选择主用和备用模型。
   • 可以利用 OpenRouter 的“按需路由”功能，根据输入内容（如长度、语言、主题）动态选择最合适的模型。

6. 扩展方向与进阶使用

掌握了基础集成和故障转移后，你可以探索 OpenRouter 的更多高级功能来优化你的应用。

6.1 利用模型特定参数

某些上游模型支持独有的参数。OpenRouter 允许你通过provider字段传递这些参数。例如，调用 Anthropic 模型时可能需要max_tokens_to_sample参数。

# 示例：调用 Claude 模型时使用特定参数 payload = { "model": "anthropic/claude-3-opus", "messages": [...], "max_tokens": 1000, "provider": { "anthropic": { "max_tokens_to_sample": 1000 } } }

你需要查阅 OpenRouter 和对应模型供应商的文档来了解可用的特定参数。

6.2 流式响应处理

对于需要实时显示生成内容的场景（如聊天界面），可以使用流式响应。OpenRouter 支持 Server-Sent Events (SSE) 格式的流。

# 流式响应示例（概念代码） import requests def stream_chat_completion(): url = f"{Config.BASE_URL}/chat/completions" headers = Config.get_headers() payload = { "model": "openai/gpt-4o", "messages": [{"role": "user", "content": "讲一个故事"}], "stream": True, "max_tokens": 500 } response = requests.post(url, headers=headers, json=payload, stream=True) for line in response.iter_lines(): if line: decoded_line = line.decode('utf-8') if decoded_line.startswith('data: '): data = decoded_line[6:] # 去掉 ‘data: ‘ 前缀 if data == '[DONE]': break try: chunk = json.loads(data) delta = chunk['choices'][0]['delta'] if 'content' in delta: print(delta['content'], end='', flush=True) except json.JSONDecodeError: pass

6.3 构建更复杂的路由逻辑

虽然 OpenRouter 服务端目前主要提供fallback路由，但你可以在客户端实现更复杂的路由逻辑。例如：

• 基于输入长度的路由：对于短问题，使用快速廉价模型；对于长文档分析，使用上下文窗口大的模型。
• 基于内容类型的路由：代码相关的问题路由给 Code Llama 或 GPT-4，创意写作路由给 Claude。
• 基于成本预算的路由：在月度预算范围内，优先使用高质量模型；预算紧张时，自动切换到经济模型。

这需要你在客户端维护一个路由决策器，根据输入和上下文动态构造发送给 OpenRouter 的model或models列表。

通过本文的步骤，你不仅学会了如何调用 OpenRouter API，更重要的是掌握了如何利用其路由和故障转移机制，构建一个具备生产级可用性和成本效益的 AI 应用后端。从配置账户、编写基础客户端，到实现健壮的故障转移策略，再到处理各类错误和规划生产部署，这套流程可以直接应用于你的实际项目。接下来，你可以尝试将此外部服务集成到你的 Web 框架（如 FastAPI、Flask）或移动应用后端中，并开始设计更符合你业务需求的智能模型调度策略。