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", # 根据提示自动选择最佳模型
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, # 值越高越有创造性 (0.0-2.0)
max_tokens=500, # 限制响应长度
top_p=0.9, # 核采样 (0.0-1.0)
frequency_penalty=0.5, # 减少重复 (-2.0-2.0)
presence_penalty=0.3 # 鼓励主题多样性 (-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, # 相同的 seed = 相同的输出(当支持时)
temperature=0.0 # 确定性采样
)
关键概念
模型路由
OpenRouter 提供智能路由能力:
- 自动路由器 (
openrouter/auto):使用 NotDiamond 根据您的提示自动选择最佳模型 - 回退模型:指定多个模型,如果主模型失败则自动重试
- 提供商路由:自动跨提供商路由以确保可靠性
身份验证
- 使用带有 API 密钥的 Bearer token 认证
- 可以以编程方式管理 API 密钥
- 兼容 OpenAI SDK 认证模式
模型命名约定
模型使用 provider/model-name 格式:
openai/gpt-4o- OpenAI 的 GPT-4 Optimizedanthropic/claude-3.5-sonnet- Anthropic 的 Claude 3.5 Sonnetgoogle/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)
- 将选择范围限制在可能 token 的百分比内
- 动态过滤不太可能出现的选项
- 在一致性和多样性之间取得平衡
频率/存在惩罚 (-2.0-2.0, 默认: 0.0)
- Frequency: 根据使用比例劝阻重复 tokens
- Presence: 简单的惩罚,不按计数缩放
- 正值减少重复,负值鼓励重复
Max Tokens (整数)
- 设置最大响应长度
- 不能超过上下文长度减去提示长度
- 用于控制成本和强制简洁回复
响应格式
- 标准 JSON:默认的聊天补全格式
- 流式响应:使用
stream: true的服务端推送事件 (SSE) - JSON 模式:使用
response_format: {"type": "json_object"}保证有效的 JSON - 结构化输出:经过模式验证的 JSON 响应
高级功能
- 工具/函数调用:将模型连接到外部 API
- 多模态输入:支持图像、PDF、音频
- 提示缓存:降低重复提示的成本
- 网络搜索集成:使用网络数据增强响应
- 零补全保险:防止响应失败
- Logprobs:访问 token 概率以进行置信度分析
参考文件
此技能在 references/ 中包含全面的文档:
- llms-full.md - 包含元数据的完整可用模型列表
- llms-small.md - 精选的流行模型子集
- llms.md - 标准模型列表
当需要详细的模型信息时,请使用 view 读取特定的参考文件。
使用此技能
对于初学者
- 从基础的聊天补全示例开始(上面的 Python/JavaScript/cURL)
- 使用标准的 OpenAI SDK 实现轻松集成
- 尝试简单的模型名称,如
openai/gpt-4o或anthropic/claude-3.5-sonnet - 初始时保持参数简单(仅模型和消息)
对于中级用户
- 为实现可靠性实施模型回退数组
- 尝试采样参数(temperature、top_p)
- 在会话应用中使用流式响应以获得更好的用户体验
- 尝试使用
openrouter/auto进行自动模型选择 - 使用 JSON 模式进行结构化数据提取
对于高级用户
- 同时微调多个采样参数
- 使用回退链实现自定义路由逻辑
- 使用 logprobs 进行置信度评分
- 利用工具/函数调用能力
- 通过为每个任务选择合适的模型来优化成本
- 实施提示缓存策略
- 使用 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}")
成本优化路由
# 对简单任务使用更便宜的模型
simple_completion = client.chat.completions.create(
model="google/gemini-2.0-flash-exp:free",
messages=[{"role": "user", "content": "Simple question"}]
)
# 对复杂任务使用高级模型
complex_completion = client.chat.completions.create(
model="openai/o1",
messages=[{"role": "user", "content": "Complex reasoning task"}]
)
上下文感知的温度
# 低温度用于事实性响应
factual = client.chat.completions.create(
model="openai/gpt-4o",
temperature=0.2,
messages=[{"role": "user", "content": "What is the capital of France?"}]
)
# 高温度用于创造性内容
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 格式,方便迁移
- 如果模型受到速率限制或宕机,自动进行提供商回退
- 定价基于实际使用的模型(对回退很重要)
- 响应中包含有关哪个模型处理了请求的元数据
- 所有模型都支持通过服务端推送事件进行流式传输
- 与流行的框架兼容(LangChain、Vercel AI SDK 等)
最佳实践
- 始终为生产应用程序实施回退
- 根据任务类型使用适当的温度(事实性任务低,创造性任务高)
- 设置 max_tokens 以控制成本和响应长度
- 启用流式传输以获得更好的聊天应用用户体验
- 在需要保证结构化输出时使用 JSON 模式
- 在开发期间使用 seed 参数测试以获得可重现的结果
- 通过为每个任务选择合适的模型来监控成本
- 在不确定哪个模型性能最佳时使用自动路由
- 针对速率限制和失败实施适当的错误处理
- 为重复请求缓存提示以降低成本