简介:本文面向开发者、运维和架构师,讲解大模型API接入的完整流程。内容包括上线前的配额估算与密钥配置,首次调用验证,超时与重试策略,灰度发布,监控告警阈值,成本预算以及回滚步骤。读者可以直接套用其中的检查清单、排错表和代码示例,减少上线风险,缩短故障定位时间。
本文适用于通过 HTTP API 调用厂商托管大模型的场景。模型推理由厂商完成,接入方负责客户端、密钥、网络出口、Agent 编排、日志与监控。若要自行部署开源权重,需要另行规划 GPU 资源,不在本文范围内。
接入前,请以厂商官方文档为准确认以下信息:接口地址、模型名称与版本、单次请求的上下文上限、计费单价、速率限制与错误码定义。本文示例中的地址、模型名和价格均为占位符。
按以下公式估算配额:
示例:日请求 20,000 次,平均输入 3,000 Token,平均输出 800 Token,则日 Token 需求为 20,000 × 3,800 = 76,000,000。余量取 30% 时,月配额为 76,000,000 × 30 × 1.3 = 2,964,000,000。若峰值并发为 40,平均响应 8 秒,则峰值 QPS 约为 5。
首次调用只验证三件事:网络连通、凭证有效、配额可用。请求体保持最小化。
export API_BASE_URL="https://<模型API端点>"export API_KEY="<从密钥管理服务读取,不要写入代码>"curl -sS -X POST "${API_BASE_URL}/chat/completions" \-H "Authorization: Bearer ${API_KEY}" \-H "Content-Type: application/json" \--max-time 60 \-d '{"model": "<MODEL_VERSION>","messages": [{"role": "user", "content": "请用一句话介绍你自己。"}],"max_tokens": 128}'
返回后检查以下内容:choices[0].message.content 是否为非空文本;usage 中的 prompt_tokens、completion_tokens、total_tokens 是否存在;HTTP 状态码是否为 200。若接口字段与此不同,以厂商文档为准。
常见错误码的处理方式如下:
| 状态码 | 含义 | 处理方式 |
|---|---|---|
| 400 | 请求参数错误 | 不重试。检查模型名与请求体格式 |
| 401 | 鉴权失败 | 不重试。检查密钥是否过期、是否注入正确环境 |
| 403 | 权限不足 | 不重试。确认模型已开通,账号权限正确 |
| 429 | 限流或配额超限 | 优先按 Retry-After 响应头等待后重试,同时降低并发 |
| 500/502/503/504 | 服务端或网关异常 | 退避重试。持续失败时切换备用模型或降级 |
超时与重试必须一起配置。超时过短会把正常的长请求判为失败,重试过多则会放大流量并触发限流。
推荐初始值如下:
import osimport randomimport timeimport requestsBASE = os.environ["API_BASE_URL"]KEY = os.environ["API_KEY"]TIMEOUT = float(os.getenv("TIMEOUT_SECONDS", "60"))MAX_RETRY = int(os.getenv("MAX_RETRY", "3"))RETRYABLE = {429, 500, 502, 503, 504}def call_model(payload: dict) -> dict:last_status = Nonefor attempt in range(MAX_RETRY + 1):try:resp = requests.post(f"{BASE}/chat/completions",headers={"Authorization": f"Bearer {KEY}"},json=payload,timeout=(5, TIMEOUT),)except requests.Timeout:last_status = "timeout"else:if resp.status_code == 200:return resp.json()if resp.status_code not in RETRYABLE:resp.raise_for_status()last_status = resp.status_codeif attempt == MAX_RETRY:breaktime.sleep(min(2 ** attempt, 30) + random.uniform(0, 1))raise RuntimeError(f"调用失败,已重试 {MAX_RETRY} 次,最后状态:{last_status}")
收到 429 且响应头包含 Retry-After 时,应优先使用该值作为等待时间,而不是使用上面的默认退避。
长上下文处理的要点如下:
上线验证分三层:
若刚经历模型版本升级,先用同一测试集对比新旧版本的输出质量,再决定是否切换。质量评估可采用人工打分或自动评分,并记录每个版本的平均分与不合格样本。
灰度节奏建议为 5%、20%、50%、100%。每个阶段至少观察 30 分钟,指标全部达标后再进入下一阶段。
| 指标 | 统计口径 | 示例告警阈值 |
|---|---|---|
| 成功率 | 2xx 请求数 ÷ 总请求数,5 分钟窗口 | 低于 99% 告警,低于 95% 紧急告警 |
| P95 延迟 | 端到端耗时,5 分钟窗口 | 超过基线 1.5 倍并持续 10 分钟 |
| 超时率 | 超时请求数 ÷ 总请求数 | 超过 1% 并持续 5 分钟 |
| 429 占比 | 429 请求数 ÷ 总请求数 | 超过 2% 并持续 5 分钟 |
| 401 数量 | 鉴权失败次数 | 出现即告警,通知密钥负责人 |
| 日 Token 消耗 | 当日 total_tokens 累计 | 达到日预算的 80% 时告警 |
日志字段建议包含:request_id、business_line、model_version、status_code、error_code、latency_ms、retry_count、prompt_tokens、completion_tokens。日志中不记录完整的用户输入和输出,只记录长度、哈希值或脱敏后的片段。
日成本 = 输入 Token ÷ 1000 × 输入单价 + 输出 Token ÷ 1000 × 输出单价。单价以厂商价格表为准。
预算告警分为三级:
成本突增时,按 business_line 汇总 total_tokens 逐项排查:上下文是否未截断,重试是否形成循环,是否存在异常高频的调用。
回滚依赖配置中心,不依赖重新发版。步骤如下:
发布窗口期需要安排人员值守。回滚步骤应提前演练一次,确保配置中心的权限和切换流程都可用。
| 现象 | 日志检索条件 | 判断标准 | 处置 |
|---|---|---|---|
| 鉴权失败 | status_code=401 | 连续出现即为异常 | 检查密钥有效期、是否被轮换、环境变量是否注入 |
| 配额超限 | status_code=429 | 占比超过 2% | 按 Retry-After 退避,降低并发,申请扩容 |
| 请求超时 | error_code=timeout | P99 接近超时阈值 | 将超时调大到 P99 的 1.5 倍,长任务改为异步 |
| 服务端错误 | status_code=5xx | 占比超过 1% 并持续 5 分钟 | 重试,仍失败则切换备用模型或降级 |
| 输出质量下降 | 固定测试集得分 | 较基线下降超过 5 个百分点 | 回滚到旧版本,保存失败样本 |
| 成本突增 | total_tokens 按业务线汇总 | 日增幅超过 50% | 检查上下文截断、重试循环和调用频次 |