SuperAPI AI 工具集

openrouter-sdk-patterns

编程与开发

查看项目

更新于 10-16 07:07

技能介绍

用途

本技能用于构建生产级的 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 默认请求头发送,用于仪表盘归属统计。

主要能力

  1. 类型化返回:每次调用返回 CompletionResult(dataclass/interface),包含 content、实际服务的模型、prompt_tokens/completion_tokens、generation_id 与 latency_ms。
  2. 重试策略:OpenAI SDK 内置指数退避重试,覆盖 429(遵循 Retry-After 头)、5xx 与连接错误;可通过构造函数配置 max_retries 与 timeout。需要超出 SDK 能力的重试时,可叠加 tenacity 装饰器。
  3. 中间件模式:通过 with_cost_tracking 在每次请求后查询 GET /api/v1/generation?id= 并累计会话成本。
  4. 额度与限流查询:check_credits() 调用 GET /api/v1/auth/key,返回剩余额度与速率限制数据。
  5. 错误处理映射:将 SDK 异常对应到 HTTP 状态与修复方式(401 密钥错误、429 限流、超时、400 参数错误)。
  6. 企业级实践:集中单一封装、依赖注入便于测试、按 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 查询,会带来额外请求开销。
  • 具体价格、收费与平台支持范围资料中暂未提供。