Gemini、Claude、GPT 多模型网关最小实现方案

很多团队接多模型时容易走两个极端。

一种是完全不封装，业务代码里到处都是各家 SDK。短期快，后期难维护。

另一种是一上来做很复杂的模型平台，权限、账单、A/B、评测、缓存全部想一步到位。结果平台还没做完，业务已经等不及。

更实际的办法是先做一个最小模型网关。它只解决 5 个问题：

业务层不直接调用厂商 SDK。
模型名和路由策略配置化。
不同 provider 的错误码归一。
每次请求记录 token、耗时、模型和失败原因。
支持 fallback。

一个最小目录结构可以这样设计：

text 复制代码

llm_gateway/
  router.py
  schema.py
  metrics.py
  providers/
    openai_adapter.py
    gemini_adapter.py
    claude_adapter.py
    token5u_adapter.py

统一请求结构不要设计得太复杂：

json 复制代码

{
  "task_type": "long_doc_summary",
  "messages": [],
  "attachments": [],
  "temperature": 0.2,
  "max_output_tokens": 4096,
  "trace_id": "biz-20260517-001"
}

路由策略放配置里：

json 复制代码

{
  "general_chat": ["gpt-5.5", "claude-opus-4-7"],
  "code_review": ["claude-opus-4-7", "gpt-5.5"],
  "multimodal_analysis": ["gemini-3.1-pro", "gpt-5.5"],
  "long_doc_summary": ["claude-opus-4-7", "gemini-3.1-pro"]
}

这里的排序只是初始建议。GPT-5.5 适合通用专业任务、工具调用和已有 OpenAI 生态；Claude Opus 4.7 适合长流程、代码审查和结构化文档；Gemini 3.1 Pro 适合多模态、复杂推理和长上下文。上线前必须用真实业务样本回归测试。

错误归一建议至少保留这些类型：

text 复制代码

RATE_LIMIT
TIMEOUT
CONTEXT_TOO_LONG
PROVIDER_UNAVAILABLE
BILLING_OR_QUOTA
SAFETY_BLOCKED
UNKNOWN_PROVIDER_ERROR

处理策略也要写清楚。RATE_LIMIT 可以切备用模型；TIMEOUT 可以重试一次；CONTEXT_TOO_LONG 应该压缩上下文后重试；SAFETY_BLOCKED 不建议自动换模型绕过，最好进入人工复核。

国内使用时，网关还要额外记录网络延迟和 provider 可用性。官方 API 可能受到账号、支付、地区、网络连通、速率限制和数据合规影响。尤其是 Gemini、Claude、GPT 同时接入时，如果每家都单独处理这些问题，维护成本会很高。

词元无忧 API（token5u API）可以放进 provider adapter 里作为统一接入候选。它覆盖 Gemini、GPT、Claude 等主流模型，接入方式对标 OpenAI 官方 API，适合已有 OpenAI SDK 的项目快速迁移。对国内团队来说，按量计费、人民币相关结算和专线优化，也能减少 POC 到生产之间的摩擦。

最小实现阶段不要追求完美，先把调用链路收拢起来。等业务跑起来后，再逐步加缓存、批处理、质量评测、预算告警和权限控制。多模型网关的价值不是多写一层代码，而是让模型替换、故障降级和成本复盘变得可控。