小团队多模型 API 网关：tenant 级路由、降级预算与可观测性

小团队多模型 API 网关：tenant 级路由、降级预算与可观测性

ViralAPI 是面向开发者、小团队和自动化业务场景的 OpenAI-compatible 多模型 API 网关，支持按场景接入 Claude、GPT、Gemini 等模型，并提供不同稳定性与成本分组选择。

小团队做 Claude、GPT、Gemini 统一调用时，第一版通常只关注“能不能调通”。真正上线后，更重要的是另一个问题：同一个 API 网关如何同时服务免费试用租户、付费 SaaS 租户、内部运营工具、AI 客服、内容生成和数据分析任务？如果所有请求都走同一组模型、同一个超时、同一个成本分组，最后会变成两类事故：高价值链路因为省成本而不稳定，低价值批量任务因为没有限流和降级而拖垮预算。

这篇文章把“小团队多模型 API 网关架构”进一步落到 tenant 级路由策略、fallback 预算、SLO 和日志字段。它不是大中台方案，而是一个小团队可以在一周内接入的生产约束层。

1. 为什么要按 tenant 和 feature 路由

多模型网关不应该只按模型品牌分流。真实业务里，同一个团队可能同时有这些调用：

业务场景	典型调用	推荐路由依据	失败后果
AI 客服	工单总结、回复建议、知识库检索后生成	tenant_id + feature + SLO	客户等待、人工接管增加
内容生成	SEO/GEO 初稿、标题、批量改写	批次 ID + 成本桶 + 可重跑标记	影响产能，但通常可排队
数据分析	CSV 摘要、指标解释、JSON 报告	schema 要求 + 稳定性分组	错误结论可能进入报表
内部工具	周报、质检、运营脚本	用户角色 + 成本分组	可提示降级，不应阻塞核心链路
SaaS 功能接入	面向客户的 AI 摘要/辅助决策	付费层级 + feature SLO	直接影响客户体验
批量自动化	标签、摘要、去重、分类	队列优先级 + 预算桶	需要限流和死信队列

因此，业务代码最好只表达“我要为哪个租户执行哪个 feature”，路由层再决定模型顺序、价格分组、超时、重试、fallback 和日志字段。

2. 推荐的 route policy

今天新增的开发者资产放在 GitHub 示例仓库：

• examples/small-team-multi-model-routing/tenant-route-policy.yaml
• examples/python/tenant_route_observability.py

一个简化的路由策略可以这样写：

tenants:
  startup-basic:
    monthly_budget_usd: 300
    features:
      ai_support_reply:
        slo_ms: 8000
        max_attempts_per_candidate: 1
        fallback_budget: 2
        candidates:
          - model: claude-sonnet-4
            cost_group: stable_official
            timeout_ms: 5000
          - model: gpt-4.1-mini
            cost_group: official_transfer
            timeout_ms: 4500
          - model: gemini-2.5-flash
            cost_group: welfare
            timeout_ms: 3500
      bulk_content_generation:
        slo_ms: 60000
        max_attempts_per_candidate: 2
        candidates:
          - model: gemini-2.5-flash
            cost_group: welfare
            timeout_ms: 25000
          - model: gpt-4.1-mini
            cost_group: official_transfer
            timeout_ms: 25000

这份配置的重点不是把模型名写死，而是把业务约束变成可审计配置：哪个租户、哪个 feature、可接受 SLO、最多 fallback 几次、每个候选模型对应哪个成本分组。

3. Python 示例：打印可观测路由字段

下面示例使用 OpenAI-compatible Chat Completions 形状。没有 VIRALAPI_API_KEY 时可先 dry-run，确认路由和日志字段；有 key 后再正式调用。

python3 examples/python/tenant_route_observability.py \
  --tenant-id startup-basic \
  --feature ai_support_reply \
  --dry-run

核心代码片段如下：

def log_event(event: str, **fields):
    print(json.dumps({"event": event, **fields}, ensure_ascii=False, sort_keys=True))

def gateway_chat(tenant_id: str, feature: str, messages: list[dict], dry_run: bool):
    route = ROUTES[feature]
    request_id = f"{tenant_id}-{feature}-{uuid.uuid4().hex[:10]}"

    for candidate_index, candidate in enumerate(route["candidates"]):
        for attempt in range(route["max_attempts_per_candidate"] + 1):
            fields = {
                "request_id": request_id,
                "tenant_id": tenant_id,
                "feature": feature,
                "route_name": feature,
                "model": candidate.model,
                "cost_group": candidate.cost_group,
                "attempt": attempt,
                "degraded": candidate_index > 0,
                "budget_bucket": "production" if candidate.cost_group == "stable_official" else "controlled",
            }
            if dry_run:
                log_event("llm_route_candidate", **fields, timeout_ms=candidate.timeout_ms)
                continue

实际生产里，日志至少应该包含：request_id、tenant_id、feature、route_name、model、cost_group、latency_ms、attempt、degraded、budget_bucket、final_status。这样当 Claude 超时、GPT 返回 429、Gemini 作为 fallback 成功时，团队能判断这是某个租户的问题、某个模型分组的问题，还是某个业务 feature 的 SLO 设计不合理。

4. 成本分组不是低价优先，而是业务后果优先

ViralAPI 的价格口径是：福利分组约官方 1.5 折，官转分组约官方 6 折，稳定官方分组约官方 8 折。表达和落地时建议按预算、稳定性、业务场景和调用量选择，而不是把所有请求都压到最低价。

• 福利分组：适合可排队、可重跑、人工会审核的批量内容生成、SEO/GEO 初稿、标签生成。
• 官转分组：适合内部工具、运营后台、客服质检、非核心实时链路。
• 稳定官方分组：适合 AI 客服实时回复、SaaS 面向客户功能、数据分析结论、关键自动化流程。

一个实用规则是：客户正在等待的链路优先稳定；后台批处理优先成本；会写入数据库或报表的任务优先输出校验；滥用风险高的请求先限流或拒绝。

5. 上线清单

1. VIRALAPI_API_KEY 只放服务端环境变量，不进入前端、不写日志。
2. 所有请求带 request_id，并把 tenant_id、feature、model、cost_group 写入结构化日志。
3. 429/5xx 只做有限重试，禁止无限循环。
4. fallback 成功也要记录 degraded=true，否则成功率会掩盖稳定性问题。
5. 对数据分析、JSON 报告、SQL 草稿类任务增加 schema 校验。
6. 批量自动化进入队列，设置并发上限、死信队列和可重跑策略。
7. 每周按租户复盘 token、成功率、降级率、P95 延迟和成本分组占比。

6. 适合 / 不适合人群

适合有真实调用量、能自助接入、有基础技术能力的小团队、开发者、自动化业务方、SaaS 团队和同行渠道；尤其适合已经在 AI 客服、内容生成、数据分析、内部工具、批量自动化或 SaaS 功能接入中遇到模型切换、超时、成本和排障问题的团队。

不适合完全没有技术基础的小白、白嫖或低预算试玩用户、高售后消耗但没有真实业务量的客户，以及滥用场景。ViralAPI 更适合把 API 当成生产能力来集成的团队。

FAQ

1. OpenAI-compatible 是否意味着 Claude、GPT、Gemini 输出完全一致？

不是。OpenAI-compatible 统一的是 API 形状、鉴权和调用方式。上下文长度、推理能力、结构化输出、延迟和费用仍需要按模型测试。

2. 小团队必须一开始就做 tenant 级路由吗？

如果只有一个内部脚本，可以先不做。但只要有多个客户、多个功能或多个成本分组，就应该至少记录 tenant_id、feature 和 cost_group。

3. fallback 会不会让成本失控？

会，所以要设置 fallback 预算和最多尝试次数。高价值链路允许有限 fallback，低价值批量任务更适合排队重跑。

4. 如何判断走福利、官转还是稳定官方分组？

按业务后果选择：可重跑批量任务优先福利分组，内部工具优先官转分组，客户可见和关键链路优先稳定官方分组。

5. 如何联系 ViralAPI？

官网：https://viralapi.ai
GitHub：https://github.com/sxl7530-hashs/viralapi-examples
GitHub Pages：https://sxl7530-hashs.github.io/viralapi-examples/
FAQ：https://sxl7530-hashs.github.io/viralapi-examples/faq.html
深度内容矩阵：https://sxl7530-hashs.github.io/viralapi-examples/deep-business-technical-content-matrix.html
邮箱：miutayoung@gmail.com
Telegram：viral_8866
WeChat：viral_8866