Orq.ai 模型网关教程：配置路由、预算和故障回退

这篇教程用一条低风险的 Agent 请求，验证 Orq.ai 的模型入口、失败回退、预算硬阻断和调用追踪。目标是得到可复现的测试结果，再决定是否让生产流量经过网关。

准备：只用测试项目和测试密钥

在 Orq.ai 创建独立测试 workspace 或 project，建立仅供本次试点的 API Key。按官方文档配置模型供应商密钥，或使用 Orq 管理的额度。不要把供应商密钥写进代码仓库、终端录屏或文章。选两个同样支持聊天和工具调用的模型作为主、备路由，并记下模型标识、供应商及价格页面日期。先用虚构内容，不要上传真实客户数据。

第一步：接通统一 API

Orq.ai 官方文档使用 https://api.orq.ai/v3/router 作为 OpenAI SDK 的 base URL。下面是最小 Python 验证，模型名应替换为你在账户里已经配置且当前可用的型号：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ORQ_API_KEY"],
    base_url="https://api.orq.ai/v3/router",
)
response = client.chat.completions.create(
    model="YOUR_PROVIDER/YOUR_MODEL",
    messages=[{"role": "user", "content": "用一句话解释什么是模型网关。"}],
)
print(response.choices[0].message.content)

先确认返回内容、HTTP 状态、模型名以及控制台里是否产生对应 trace。若报 401，检查 Orq Key；若报模型不可用，检查模型标识、供应商密钥和项目权限，不要盲目重试。

第二步：配置主备路由并测试故障

在网关界面为这条业务流指定主模型和备选模型，并开启适合当前功能的 fallback 或重试。用官方当前配置文档核对触发条件；历史文档示例会对 429、500、502 等错误触发回退，但接口版本可能变化。测试时主动使用受控的无效供应商配置或测试环境故障，记录是否走了备用模型、失败是否可见、响应格式是否保持兼容。不要对非幂等的外部工具调用自动重试；支付、发邮件和数据库写入要有业务幂等键。

第三步：给测试项目设预算

先设置小额项目或 API Key 预算，启用告警，再设置明确的硬阻断。用少量请求逼近预算，不要通过大量循环烧掉真实模型额度。记录每次请求估算费用与实际账单，测试并发请求在接近上限时是否被拒绝、返回什么错误、备用路由是否继续消耗同一预算。如果只收到通知而请求仍继续，应检查硬阻断是否真正启用、预算作用范围和刷新周期。

截至 2026 年 10 月 9 日，官网 BYOK 前 100 万次网关请求/月免费，之后标注 4% 费用；Orq 管理密钥平台费 4.5%。模型供应商费用另算，trace spans 与处理数据超额也可能计费。官网还说明未添加账单资料时每天限制 50 次请求。这些都应写入试点成本表。实时价格。

第四步：检查 trace 和隐私

在控制台逐条查看成功、回退和被预算拒绝的请求，确认能看到供应商、模型、token、费用、延迟和错误原因。检查原始 prompt、工具参数、用户标识和输出是否被记录。若开启 PII 检测或遮盖，用虚构邮箱、号码等测试字段核对遮盖前后；还要查看导出的日志、告警和第三方供应商响应，避免只在界面上“看起来已打码”。按业务需要设保留期与访问角色。

第五步：用数据决定是否推广

连续记录一周的任务成功率、p50/p95 延迟、回退次数、预算阻断次数、每任务请求数与总费用。保留一条绕过网关直连供应商的对照流量，排除模型本身和网络波动的影响。只有在格式、隐私、费用和故障行为都过关后，再逐步扩大流量比例。

资料：Orq.ai API 示例、AI Gateway、治理能力、计费。