用途
本技能用于构建生产级的 OpenRouter 客户端封装。OpenAI 的 Python/TypeScript SDK 通过把 base_url 改为 https://openrouter.ai/api/v1 即可原生对接 OpenRouter。技能围绕类型化封装、重试策略、中间件与可复用模式展开,适合在创建 SDK 或客户端库时使用。
前置条件
- 一个 OpenRouter API 密钥(sk-or-v1-...),以 OPENROUTER_API_KEY 环境变量导出;设置方式参见 openrouter-install-auth 技能。
- Python 3.8+ 并安装 OpenAI SDK 与 requests(用于 /auth/key 额度检查与 /generation 成本查询),或 Node.js 18+ 并安装 OpenAI SDK。
- 可选:若需要 SDK 内置退避之外的自定义重试装饰器,可安装 tenacity。
- 一个应用名称与 URL,作为 HTTP-Referer / X-Title 默认请求头发送,用于仪表盘归属统计。
主要能力
- 类型化返回:每次调用返回 CompletionResult(dataclass/interface),包含 content、实际服务的模型、prompt_tokens/completion_tokens、generation_id 与 latency_ms。
- 重试策略:OpenAI SDK 内置指数退避重试,覆盖 429(遵循 Retry-After 头)、5xx 与连接错误;可通过构造函数配置 max_retries 与 timeout。需要超出 SDK 能力的重试时,可叠加 tenacity 装饰器。
- 中间件模式:通过 with_cost_tracking 在每次请求后查询 GET /api/v1/generation?id= 并累计会话成本。
- 额度与限流查询:check_credits() 调用 GET /api/v1/auth/key,返回剩余额度与速率限制数据。
- 错误处理映射:将 SDK 异常对应到 HTTP 状态与修复方式(401 密钥错误、429 限流、超时、400 参数错误)。
- 企业级实践:集中单一封装、依赖注入便于测试、按 SLA 设置 max_retries(交互式 2、批处理 5)、中间件用 try/catch 包裹避免影响主流程。
使用方式
以 Python 为例:在构造函数中把 OpenAI 客户端指向 base_url="https://openrouter.ai/api/v1",从环境变量读取 OPENROUTER_API_KEY,并设置 HTTP-Referer / X-Title 默认请求头。complete() 方法组装 system 与 user 消息,调用 chat.completions.create,记录延迟并返回类型化结果。可选缓存仅在 temperature 为 0 时启用,以请求内容的 SHA-256 作为键。TypeScript 版本结构相同,使用 baseURL、maxRetries、timeout 与 defaultHeaders。
重试配置示例:
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key="sk-or-v1-...",
max_retries=5, # Default is 2
timeout=120.0, # Per-request timeout in seconds
)
自定义重试示例:
import tenacity
@tenacity.retry(
retry=tenacity.retry_if_exception_type((RateLimitError, APITimeoutError)),
wait=tenacity.wait_exponential(min=1, max=60),
stop=tenacity.stop_after_attempt(5),
before_sleep=lambda state: log.warning(f"Retry {state.attempt_number}: {state.outcome.exception()}"),
)
def robust_complete(client, **kwargs):
return client.chat.completions.create(**kwargs)
成本追踪中间件示例:
from functools import wraps
from typing import Callable
def with_cost_tracking(fn: Callable) -> Callable:
"""Middleware that logs cost per request."""
total_cost = {"value": 0.0}
@wraps(fn)
def wrapper(*args, **kwargs):
result = fn(*args, **kwargs)
# Query generation cost asynchronously
import requests
gen = requests.get(
f"https://openrouter.ai/api/v1/generation?id={result.id}",
headers={"Authorization": f"Bearer {args[0].api_key}"},
).json()
cost = float(gen.get("data", {}).get("total_cost", 0))
total_cost["value"] += cost
log.info(f"Request cost: ${cost:.6f} | Session total: ${total_cost['value']:.4f}")
return result
wrapper.total_cost = total_cost
return wrapper
输出
- 每次调用返回类型化 CompletionResult:content、实际服务模型、prompt_tokens/completion_tokens、gen-... generation_id 与 latency_ms。
- 每次请求输出结构化日志,例如 [openai/gpt-4o-mini] 12+87 tokens, 843.2ms。
- 成本追踪中间件输出单次请求成本与会话累计,例如 Request cost: $0.000123 | Session total: $0.0045。
- check_credits() 返回来自 /api/v1/auth/key 的用量与限额字典。
适用场景
- 需要统一日志、重试与成本统计的生产应用。
- 构建内部 SDK 或客户端库,供多个服务复用。
- 需要在测试中通过依赖注入在 OpenRouter 与直连供应商客户端之间切换。
限制
- 需要有效的 OpenRouter API 密钥,否则返回 401。
- 缓存仅在 temperature 为 0 的确定性请求下启用。
- 成本追踪依赖额外的 /generation 查询,会带来额外请求开销。
- 具体价格、收费与平台支持范围资料中暂未提供。