需求起源：为什么需要兼容层？

某金融 SaaS 客户原有业务基于 OpenAI API 实现智能工单分类，因合规要求需切换至国产模型。技术团队提出两个核心诉求： 1. 业务代码零修改：保持 /v1/chat/completions 等端点不变 2. 故障隔离：当 DeepSeek 实例异常时自动降级到备用厂商

第一阶段：天真的字段对齐

初期采用简单字段映射方案：

# 错误示例：粗暴转换
if deepseek_error == "rate_limit":
    return {"code": 429, "message": "Rate limit reached"}  # 直接拷贝OpenAI文案

三天后暴露问题： - DeepSeek 的 context_length_exceeded 被映射为通用 400 Bad Request，前端无法针对性提示用户缩短文本 - 运维无法通过日志区分是网关限流（NGINX 层面）还是 DeepSeek 服务限流 - 客户端重试逻辑缺乏标准化，导致部分异常请求被无限重试

第二阶段：建立错误分类矩阵

制定三层错误编码体系（文档中需明确标注「扩展字段」）：

层级	示例错误码	来源	处理建议
网关原生	GW_429	网关自身限流	检查客户端请求频率
厂商标准	DEEPSEEK_400_CONTEXT_LEN	DeepSeek 原始错误	缩短输入文本或分批次处理
业务自定义	CUSTOM_503_FALLBACK	降级到备用厂商	等待自动恢复或人工介入

关键改进： 1. 在响应头增加 X-Error-Source: upstream|gateway 2. 错误消息模板包含可操作建议（如「当前上下文 12k tokens，请缩短至 8k 以内」） 3. 为每个错误类型设计专用的重试策略模板

生产环境真实故障复盘

事故现象： - 监控显示 DeepSeek 实例 CPU 持续 100%，但网关日志未见异常请求量 - 客户端出现大面积超时，但错误率统计却显示正常

根因分析： 1. 客户端重试逻辑未遵循 Retry-After 头，采用固定 1 秒间隔重试 2. DeepSeek 的 503 状态码被网关统一转换为 429，丢失了服务不可用语义 3. 网关的熔断阈值设置过高（1000 QPS），未能及时保护下游

解决方案： 1. 在网关层实现阶梯式退避：

# 在流量超过阈值时，按客户端IP哈希熔断
limit_req_zone $binary_remote_addr zone=deepseek:10m rate=30r/s;
limit_req_status 529;  # 使用非标准状态码避免客户端误解

2. 错误响应中保留原始厂商的 retry_after_seconds 字段 3. 增加基于响应时间的动态熔断（平均延迟 >500ms 时触发）

观测体系建设

通过 Prometheus 暴露三类指标： 1. 请求来源分布： - gateway_requests_total{client="web",vendor="deepseek"} - gateway_fallback_requests_total{reason="timeout"} 2. 错误类型直方图： - 按三层分类打标（gateway/vendor/custom） - 记录原始错误码与转换后错误码的映射关系 3. 时延监控： - 区分网关处理耗时和 DeepSeek 推理耗时 - 统计 P95/P99 分位数

深度优化：会话一致性保障

当启用故障转移时，发现以下问题： - 不同厂商的 tokenizer 差异导致 max_tokens 计算不准 - 会话历史在不同模型间切换时出现语义断层

应对措施： 1. 在网关层统一计算 token 数量：

# 使用DeepSeek官方tokenizer进行计算
from deepseek_tokenizer import tokenize
input_tokens = len(tokenize(prompt))

2. 为每个会话绑定固定厂商，仅在完全不可用时才切换 3. 在响应头中添加 X-Token-Count 用于调试

经验总结与检查清单

必须实现的网关功能

• [ ] 错误码转换矩阵文档（含示例响应）
• [ ] 请求头透传 X-Request-Id 用于全链路追踪
• [ ] 基于令牌桶的客户端级限流
• [ ] 熔断器状态指标暴露（开/半开/闭）

常见陷阱

1. 不要完全隐藏厂商差异：保留 X-Model-Vendor 等调试头
2. 熔断策略需双向配置：既要防止客户端压垮网关，也要避免网关无节制调用下游
3. 文档必须标注边界：例如 DeepSeek 的 max_tokens 计算方式与 OpenAI 存在 5% 偏差
4. 测试要覆盖故障场景：包括：
5. 故意返回 5xx 错误测试客户端重试逻辑
6. 模拟高延迟测试熔断器灵敏度
7. 突然切断节点连接测试故障转移

延伸思考

当需要同时接入多个国产模型时，建议： 1. 为每个厂商维护独立的连接池 2. 实现基于性能指标的动态路由 3. 建立统一的模型能力注册表（输出格式、最大上下文等）

最终通过这套方案，客户在零业务代码改动的情况下，实现了 99.95% 的月度可用率，异常请求的排查时间从平均 2 小时缩短至 15 分钟。