openrouter

OpenRouter 技能

全面支持 OpenRouter API 开发，通过单一端点统一访问数百种 AI 模型，并提供智能路由、自动回退和标准化接口。

何时使用此技能

出现以下情况时，应触发此技能：

• 通过统一接口调用多个 AI 模型提供商的 API
• 实施模型回退策略或自动路由
• 使用 OpenAI 兼容的 SDK，但目标是多个提供商
• 配置高级采样参数（temperature、top_p、penalties）
• 设置流式响应或结构化 JSON 输出
• 比较不同 AI 模型的成本
• 构建需要自动切换提供商的应用
• 在不同模型间实现函数／工具调用
• 询问 OpenRouter 特有功能（路由、回退、零完成保险）

快速参考

基本聊天补全（Python）

from openai import OpenAI

client = OpenAI(
  base_url="https://openrouter.ai/api/v1",
  api_key="<OPENROUTER_API_KEY>",
)

completion = client.chat.completions.create(
  model="openai/gpt-4o",
  messages=[{"role": "user", "content": "What is the meaning of life?"}]
)
print(completion.choices[0].message.content)

基本聊天补全（JavaScript/TypeScript）

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{"role": 'user', "content": 'What is the meaning of life?'}],
});
console.log(completion.choices[0].message);

cURL 请求

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "What is the meaning of life?"}]
  }'

模型回退配置（Python）

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    extra_body={
        "models": ["anthropic/claude-3.5-sonnet", "gryphe/mythomax-l2-13b"],
    },
    messages=[{"role": "user", "content": "Your prompt here"}]
)

模型回退配置（TypeScript）

const completion = await client.chat.completions.create({
    model: 'openai/gpt-4o',
    models: ['anthropic/claude-3.5-sonnet', 'gryphe/mythomax-l2-13b'],
    messages: [{ role: 'user', content: 'Your prompt here' }],
});

自动路由器（动态模型选择）

completion = client.chat.completions.create(
    model="openrouter/auto",  # Automatically selects best model for the prompt
    messages=[{"role": "user", "content": "Your prompt here"}]
)

高级参数示例

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Write a creative story"}],
    temperature=0.8,           # Higher for creativity (0.0-2.0)
    max_tokens=500,            # Limit response length
    top_p=0.9,                 # Nucleus sampling (0.0-1.0)
    frequency_penalty=0.5,     # Reduce repetition (-2.0-2.0)
    presence_penalty=0.3       # Encourage topic diversity (-2.0-2.0)
)

流式响应

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end='')

JSON 模式（结构化输出）

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{
        "role": "user",
        "content": "Extract person's name, age, and city from: John is 30 and lives in NYC"
    }],
    response_format={"type": "json_object"}
)

使用 Seed 实现确定性输出

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Generate a random number"}],
    seed=42,            # Same seed = same output (when supported)
    temperature=0.0     # Deterministic sampling
)

核心概念

模型路由

OpenRouter 提供智能路由能力：

• 自动路由器（openrouter/auto）：使用 NotDiamond 根据提示词自动选择最佳模型
• 回退模型：指定多个模型；主模型失败时会自动重试
• 提供商路由：自动在不同提供商间路由，以提升可靠性

身份验证

• 使用 API 密钥进行 Bearer 令牌身份验证
• 可通过编程方式管理 API 密钥
• 兼容 OpenAI SDK 的身份验证模式

模型命名约定

模型采用 provider/model-name 格式：

• openai/gpt-4o - OpenAI 的 GPT-4 Optimized
• anthropic/claude-3.5-sonnet - Anthropic 的 Claude 3.5 Sonnet
• google/gemini-2.0-flash-exp:free - Google 的免费 Gemini 模型
• openrouter/auto - 自动路由系统

采样参数

Temperature（0.0-2.0，默认值：1.0）

• 值越低，响应越可预测、越聚焦
• 值越高，响应越有创意、越多样
• 事实性任务使用较低值（0.0-0.3），创意任务使用较高值（0.8-1.5）

Top P（0.0-1.0，默认值：1.0）

• 将选项限制在可能出现的令牌范围内
• 动态过滤不太可能出现的选项
• 在一致性和多样性之间取得平衡

频率／存在惩罚（-2.0-2.0，默认值：0.0）

• 频率惩罚：按令牌使用次数的比例抑制重复
• 存在惩罚：更简单的惩罚，不按出现次数缩放
• 正值减少重复，负值鼓励重复使用

最大令牌数（整数）

• 设置响应的最大长度
• 不得超过上下文长度减去提示词长度
• 可用于控制成本并确保回复简洁

响应格式

• 标准 JSON：默认聊天补全格式
• 流式传输：使用 stream: true 的服务器发送事件（SSE）
• JSON 模式：使用 response_format: {"type": "json_object"} 保证输出有效 JSON
• 结构化输出：经过架构验证的 JSON 响应

高级功能

• 工具／函数调用：将模型连接到外部 API
• 多模态输入：支持图像、PDF、音频
• 提示词缓存：降低重复提示词的成本
• 网页搜索集成：利用网络数据增强响应
• 零完成保险：防止响应失败
• Logprobs：获取令牌概率，用于置信度分析

参考文件

此技能在 references/ 中包含全面的文档：

• llms-full.md - 可用模型完整列表及其元数据
• llms-small.md - 精选的热门模型子集
• llms.md - 标准模型列表

需要详细了解模型信息时，使用 view 阅读特定参考文件。

使用此技能

初学者

1. 从基本的聊天补全示例开始（上文的 Python/JavaScript/cURL）
2. 使用标准 OpenAI SDK，轻松完成集成
3. 尝试 openai/gpt-4o 或 anthropic/claude-3.5-sonnet 等简单模型名称
4. 初期尽量使用简单参数（仅设置模型和消息）

中级用户

1. 实现模型回退数组，提高可靠性
2. 尝试采样参数（temperature、top_p）
3. 在对话应用中使用流式传输，提升用户体验
4. 尝试使用 openrouter/auto 自动选择模型
5. 实现 JSON 模式，以提取结构化数据

高级用户

1. 同时微调多个采样参数
2. 使用回退链实现自定义路由逻辑
3. 使用 logprobs 进行置信度评分
4. 利用工具/函数调用功能
5. 根据任务选择合适的模型，以优化成本
6. 实现提示词缓存策略
7. 使用 seed 参数进行可复现测试

常见模式

使用回退机制处理错误

try:
    completion = client.chat.completions.create(
        model="openai/gpt-4o",
        extra_body={
            "models": [
                "anthropic/claude-3.5-sonnet",
                "google/gemini-2.0-flash-exp:free"
            ]
        },
        messages=[{"role": "user", "content": "Your prompt"}]
    )
except Exception as e:
    print(f"All models failed: {e}")

成本优化路由

# Use cheaper models for simple tasks
simple_completion = client.chat.completions.create(
    model="google/gemini-2.0-flash-exp:free",
    messages=[{"role": "user", "content": "Simple question"}]
)

# Use premium models for complex tasks
complex_completion = client.chat.completions.create(
    model="openai/o1",
    messages=[{"role": "user", "content": "Complex reasoning task"}]
)

上下文感知温度

# Low temperature for factual responses
factual = client.chat.completions.create(
    model="openai/gpt-4o",
    temperature=0.2,
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)

# High temperature for creative content
creative = client.chat.completions.create(
    model="openai/gpt-4o",
    temperature=1.2,
    messages=[{"role": "user", "content": "Write a unique story opening"}]
)

资源

官方文档

• API 参考：https://openrouter.ai/docs/api-reference/overview
• 快速入门指南：https://openrouter.ai/docs/quickstart
• 模型列表：https://openrouter.ai/docs/models
• 参数指南：https://openrouter.ai/docs/api-reference/parameters

主要端点

• 聊天补全：POST https://openrouter.ai/api/v1/chat/completions
• 列出模型：GET https://openrouter.ai/api/v1/models
• 生成信息：GET https://openrouter.ai/api/v1/generation

注意事项

• OpenRouter 会对所有提供商的 API 架构进行规范化
• 使用兼容 OpenAI 的 API 格式，便于迁移
• 如果模型达到速率限制或不可用，会自动回退到其他提供商
• 价格基于实际使用的模型（使用回退机制时尤为重要）
• 响应包含处理请求的模型的元数据
• 所有模型均支持通过 Server-Sent Events 进行流式传输
• 兼容常见框架（LangChain、Vercel AI SDK 等）

最佳实践

1. 始终为生产应用实现回退机制
2. 根据任务类型设置合适的温度（事实类任务设低，创意类任务设高）
3. 设置 max_tokens，以控制成本和响应长度
4. 启用流式传输，提升聊天应用的用户体验
5. 需要保证结构化输出时使用 JSON 模式
6. 开发期间使用 seed 参数进行测试，确保结果可复现
7. 根据任务选择合适的模型，以监控成本
8. 不确定哪个模型表现最佳时使用自动路由
9. 妥善处理速率限制和故障
10. 缓存重复请求的提示词，以降低成本