调用大模型 API：参数怎么调、报错怎么处理

一、请求的基本结构

{
  "model": "your-model",
  "messages": [
    {"role": "system", "content": "你是一个严谨的技术编辑。"},
    {"role": "user", "content": "把下面这段改写成 100 字以内的摘要：..."}
  ],
  "temperature": 0.3,
  "max_tokens": 300
}

messages 是对话数组，角色通常有：

• system：设定身份与规则，优先级最高，每次都要带。
• user：用户输入。
• assistant：模型历史回复（多轮对话时回填）。
• tool / function：工具调用结果（视厂商而定）。

二、两个采样参数

temperature（0–2，常见 0–1）：

• 越低越确定，适合抽取、分类、代码生成。
• 越高越发散，适合创意写作、头脑风暴。
• 设 0 也不保证完全确定（底层并行计算、模型版本变化都会带来差异）。

top_p（核采样）：

• 只从累积概率达到 p 的候选词里采样。
• 一般只调其中一个，两个都调会让行为难以预测。

实践建议：

三、max_tokens 与截断

max_tokens 限制输出长度（不是输入）。

• 设太小：回答被截断，JSON 少个右括号，解析直接失败。
• 设太大：不浪费钱（按实际生成计费），但可能生成啰嗦内容，且增加延迟。

被截断的典型信号是 finish_reason: "length"。生产环境要检查这个字段，截断时要么重试（提高上限），要么降级处理。

四、流式输出

stream = client.chat.completions.create(model=..., messages=..., stream=True)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end='', flush=True)

适合聊天界面（首字延迟低、体验好）。注意：

• 流式下无法轻易拿到完整 usage（部分厂商在最后一个 chunk 给）。
• 出错时可能已经输出了一半内容，前端要能处理「中途失败」。
• 结构化输出（JSON）建议非流式，避免边生成边解析。

五、报错与重试

退避重试的写法：

import time, random
for attempt in range(4):
    try:
        return call()
    except RateLimitError:
        if attempt == 3:
            raise
        time.sleep((2 ** attempt) + random.random())

要点：只对可重试的错误重试（429、5xx、超时），400 重试只是浪费额度；加随机抖动避免同时重试造成二次拥塞；设置总时长上限。

六、密钥与成本

• 密钥放服务端环境变量，绝不进前端代码（浏览器里等于公开）。
• 按环境分配不同密钥，便于限额与吊销。
• 记录每次调用的 token 与耗时，按功能维度统计。
• 设置每日预算告警，防止被刷。

七、稳定性设计

• 超时：单次请求设 10–60 秒，别用默认无限等待。
• 降级：模型不可用时返回缓存结果或提示稍后重试，而不是白屏报错。
• 幂等：同一请求重复调用不应产生副作用（如重复下单）。
• 输出校验：要求 JSON 时要解析并校验字段，失败则重试或走兜底逻辑。
• 提示版本化：把提示当代码管理，改动可回溯。

八、调试建议

• 先用最小请求验证连通（一条 hi），再逐步加参数。
• 打印完整请求体与响应（注意脱敏），多数问题一眼可见。
• 返回的 JSON 不合法时，用 JSON 格式化校验 定位是少了逗号还是被截断。
• 输出太长时用 字数统计 核对是否超出预期。

小结

system 定规则、user 给任务；抽取类任务 temperature 调低；max_tokens 管输出，检查 finish_reason；429 与 5xx 用指数退避重试，400 直接修；密钥只在服务端；上线要有超时、降级与输出校验。