1. 托管部署的公开边界

同一家厂商可能同时提供 API、开权重、云 marketplace 和企业私有化方案，它们公开的信息并不相同。下表只写官方文档中终端用户能验证的契约；开权重 runtime 另见自部署页。

提供方公开控制面客户端工程动作
OpenAIResponses/Chat、Batch、prompt cache、gpt-oss 自部署文档。将请求级缓存、异步批处理和模型 lifecycle 纳入客户端。
GoogleGemini Batch / Context Cache、Vertex quota / Provisioned Throughput、Gemma self-host。按 project-region-model-version 管理容量承诺。
xAIprompt cache、x-grok-conv-id / prompt_cache_key、rate limits、Agent Tools。用会话身份与稳定前缀提高 cache 机会，处理 429。
DeepSeekOpenAI/Anthropic compatible endpoint、模型切换、rate limit、user_id 逻辑隔离。测试工具、1M/API context、缓存与调度的接口语义。
Kimikimi-k3、1M context、max reasoning、cache hit/miss 计价与模型/effort 切换后的 re-prefill。把 model、effort、模板和工具 schema 纳入 cache identity；为 miss 保留完整 prefill 基线。
Z.ai / MiniMax / Hunyuan各家 API、工具、模型 ID、streaming / 兼容层和公开配额。建立 provider adapter、模型版本 pin 和重试策略。

2. 把托管模型看成状态机，而不是 1 个无状态 HTTP 函数

client request → model/version selection → quota / queue admission → prefix/cache identity → generation / tool-call rounds → stream / completion / usage record → retry, fallback, audit 可观察的是契约和结果；内部 worker、KV page、NIC 与机架通常不可观察。

这些公开状态已经足够约束客户端：固定版本，保持缓存前缀稳定，为流式中断准备幂等恢复，给工具 schema 做版本管理，对限流和 transient failure 退避，并在模型退役前跑回归。API benchmark 测到的是整项服务，不能当成某厂 GPU 吞吐的直接证据。

3. Batch、prompt cache 和 prefix routing：分别核算

OpenAI 和 Gemini 提供异步 Batch 与 cache，xAI、DeepSeek、Kimi、MiniMax 也各有缓存或上下文管理接口。这些能力要分别处理：

  • Batch：把非交互任务移出低延迟通道，通常使用单独限额和完成窗口。
  • Prompt/prefix cache：稳定前缀可能复用计算状态。命中取决于模型、region、TTL、请求形状、模板和平台策略。
  • Kimi K3：API 价格为 cache-hit input $0.30/MTok、cache-miss input $3.00/MTok、output $15.00/MTok。切换 model 或 reasoning effort 会让现有 cache 失效并重新 prefill；当前默认 max reasoning。
  • sticky routing:prompt_cache_key 或会话 ID 可以提高相邻请求落到可复用状态的机会。
  • 上下文压缩：评测时同时检查任务语义、费用与延迟。

容量计划要保留 cache-miss 基线。缓存驱逐、切换 K3 effort 或请求发生微小变化时，p99 会回到这条基线。

4. 多供应商客户端应统一什么，不应伪统一什么

内部可以统一一层 provider adapter。输入侧规范 messages、media、tool schema、effort 和 stream policy；输出侧规范 finish reason、usage、tool call、request id、retryability 与 cache diagnostics。适配器只统一业务需要的字段，不能假定各平台的 reasoning、cache、batch 或多模态语义相同。

统一字段为什么不能强行统一的字段
model revision / date防止供应商切换模型后静默回归模型内部 context/attention 实现
idempotency / request trace支持流式断开和 retry 审计供应商 worker identity
tool schema + validation避免 parser 差异进入业务层隐藏 CoT / reasoning token 政策
token and cost accounting比较实际请求，而非宣传价硬件运行成本或电耗
rate-limit telemetry做 backoff / circuit breaker队列内部优先级算法

5. 区域、数据驻留与预留容量：逐产品执行

OpenAI 的数据控制文档明确区分 regional storage 与 regional processing。Google Vertex Provisioned Throughput 以 project-region-model-version 为控制面作用域；xAI 的区域可用性按具体产品和公告日期记录。

容量设计分 3 层：交互请求使用 SLO 与 fallback；可延迟请求使用 Batch；关键业务使用明确的预留、配额或企业 SLA，并配置跨 provider 降级。

6. 托管 API 的部署验收清单

  1. 为每个模型保存产品名称、version/date、API endpoint、区域、最大 context、费用和变更公告。
  2. 测试 cache hit 和 miss 2 类请求，分别记录 TTFT、TPOT、cost、使用量和 p95/p99。
  3. 针对 429、5xx、stream drop、tool parse error、content filter 和 model migration 写可重放测试。
  4. Batch 验证完成窗口、幂等性、partial failure 与大批量回填。
  5. 多供应商 fallback 要测 prompt/template 差异、tool schema 差异和安全规则差异，不能只改 model id。
  6. 合规与区域要求逐项引用适用产品文档和日期。

7. 缓存友好的路由与多供应商 fallback

稳定前缀、会话 key、model pin 与 region 选择共同影响 cache 机会；在有公开 sticky-routing hint 时可使用它，但应用仍要接受 cache miss。fallback 不应在 1 个 stream 已生成半截时盲切模型：应以请求类型、工具副作用、结构化输出和可接受语义差异为条件，必要时返回可重试状态而非悄悄合并两家结果。

8. 工具、数据和审计：API adapter 的最小安全边界

每次调用应记录 provider request id、model/version、权限、token/cost、tool schema version 和必要的输入输出摘要。工具执行要在模型生成之后单独授权、校验和隔离；模型返回的 JSON 只是候选参数，不是可信指令。对数据驻留、日志和 cache 的承诺要链接到具体产品文档及日期，而不是使用 1 个模糊的“全球 API”标签。

9. 一手来源

一手来源使用范围
OpenAI Batch / Prompt caching异步容量与 cache/routing 公开语义。
Gemini Batch / Gemini caching / Vertex PTGoogle API、cache、容量控制面。
xAI cache / rate limitsxAI 会话 cache 与限流。
DeepSeek rate limits / updatesDeepSeek API 模型/隔离与版本迁移。
Kimi K3 发布 / Kimi Code 模型文档K3 API 上线、价格、1M、reasoning effort 和 cache invalidation。
Z.ai API、MiniMax API、Hunyuan API中国模型厂的公开接口层。