RouterBase 模型路由

概述

使用 routerbase 来为单一 API 密钥和统一的 OpenAI 兼容接口，选择并记录背后所使用的模型。该能力帮助智能体将工作负载需求转化为切实可行的模型候选清单、回退方案以及验证检查表。

当需要精确的目录 API 调用方式、模型示例或选型启发式规则时，请查阅 references/routerbase-models.md。

路由工作流

1. 对任务模态进行分类：聊天（chat）、图像（image）、视频（video）、音频（audio）、嵌入（embeddings）或混合模态（mixed）。
2. 识别硬性约束条件：质量目标、延迟预算、价格上限、上下文长度、工具调用（tool calling）、视觉能力（vision）、JSON 模式、地域/合规性要求，以及回退容忍度。
3. 尽可能查询实时的 RouterBase 目录：

curl "https://routerbase.com/api/v1/models?task=chat" 
  -H "Authorization: Bearer $ROUTERBASE_API_KEY"

4. 筛选出一个主用模型及一至两个备用模型。优先选择与主用模型模态相同、能力特征相近的备用模型。
5. 在最终推荐前，核查当前定价信息：

curl "https://routerbase.com/api/v1/pricing" 
  -H "Authorization: Bearer $ROUTERBASE_API_KEY"

6. 以表格形式记录决策依据：使用场景、主用模型、备用模型、选择理由、验证测试项及已知注意事项。

选型启发式规则

• 对于通用聊天任务，优先选用性能均衡且响应快速的模型；仅在推理质量或上下文长度确有更高要求时，再升级至更高级别模型。
• 对于高风险推理任务，应选用旗舰级模型，并强制要求人工审核输出结果。
• 对于延迟敏感型用户体验（UX），优先选用小尺寸模型或 flash-tier 模型，并保持提示词（prompt）简洁紧凑。
• 对于依赖大量工具调用的智能体，应选择明确声明支持 tool calling 的聊天模型，并针对实际使用的工具 schema 进行端到端测试。
• 对于需返回 JSON 格式输出的场景，在所选模型支持 JSON 模式时使用 response_format 参数，并在应用层代码中加入 schema 校验逻辑。
• 为获得提示缓存（prompt caching）优势，应将稳定的系统提示词、策略定义及工具描述置于可变用户内容之前。
• 对于多模态媒体工作流，应按模态独立设计路由逻辑；图像、视频和音频端点具有不同的同步/异步行为。

回退机制设计

除非用户已在自身账户或上游配置中启用 RouterBase 的智能路由功能，否则请在应用层实现显式的回退逻辑。

const modelPlan = [
  "anthropic/claude-sonnet-4-6",
  "google/gemini-2.5-flash",
];

for (const model of modelPlan) {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    if (!isRetryableRouterBaseError(error)) throw error;
  }
}

对可重试错误应采取保守分类策略：瞬时网络故障、超时、429 和 5xx 错误属于合理重试范围；而鉴权失败（auth errors）、无效模型 ID、校验错误（validation errors）及策略错误（policy errors）不应盲目重试。

推荐格式规范

在提出路由方案建议时，应包含以下内容：

• 主用模型及其适配原因；
• 备用模型及其所作权衡；
• 当前目录与定价信息的核查状态；
• 所有需验证的功能假设，例如工具调用、视觉能力、JSON 模式、上下文长度、提示缓存或流式响应等；
• 一份最小化评估提示（eval prompt）或请求样例（request fixture），供用户在生产部署前自行运行验证。

切勿假定价格或支持的模型 ID 是永久不变的。RouterBase 官方文档明确指出：其模型目录与定价信息会随上游提供商的变更而动态更新。