Gemini API接入时如何设计错误处理和降级策略

这篇偏实操，围绕 Gemini API 接入、错误处理、RAG、多模型配置和压测指标，把容易漏掉的工程问题摊开讲。

Gemini API 进入项目后，错误处理和降级策略决定了用户体验下限。

CSDN 上聊 Gemini API，最好不要只停留在“怎么请求”。请求代码很快就能写出来，更影响项目质量的是工程细节：配置、日志、重试、降级、成本统计和可观测性。

先看一个常见场景

一个线上 AI 摘要接口如果偶发超时，用户看到的别是一串报错，而应该是可理解的提示、可恢复的任务状态，或者自动切换到备用模型。

demo 阶段很容易忽略这个问题，因为大家只看一次调用有没有成功。但线上系统会遇到更多情况：请求过长、接口超时、模型返回格式异常、用户连续提交、预算被快速消耗。只要这些分支没有处理，用户体验就不稳定。

接入时我会先这样做

业务代码不要直接依赖具体模型名
每次调用记录 model、latency、status、token usage 和 task_id
区分可重试错误和不可重试错误
为关键任务配置 fallback model
对长输入、并发和异常输入分别做测试

这些设计并不复杂，但越早做越省事。等调用量上来以后再补日志和降级，往往要改很多已经散落的业务代码。

示例

import time
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://147ai.com/v1")

def call_model(messages, model="gemini-2.0-flash", retries=2):
    last_error = None
    for attempt in range(retries + 1):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                timeout=20,
            )
        except Exception as exc:
            last_error = exc
            time.sleep(0.5 * (attempt + 1))
    raise RuntimeError(f"model call failed: {last_error}")

这段只说明结构，不是完整生产代码。正式项目里还需要把密钥放到环境变量或密钥管理系统里，并把调用结果写入日志或监控平台。

先把需求翻译成工程指标

不要只写“接入 Gemini”。最好写清楚接口超时时间、重试次数、fallback 模型、日志字段和压测指标。需求越具体，后面越少扯皮。

这里最值得多想的一点

很多团队会把“调用失败”理解成网络错误，其实线上更麻烦的是半失败：接口返回了，但内容不完整；模型没有报错，但 JSON 格式坏了；摘要看起来顺，但把关键数字漏掉了。

所以错误处理不能只写 try/except。最好把失败分成几类：连接失败、超时、配额不足、内容安全拦截、格式不符合预期、业务校验失败。前几类可以重试，后几类要么降级，要么交给人工处理。这个分类一旦写清楚，客服和运营遇到问题时也知道该怎么解释。

一个反面例子

有些 AI 功能上线初期看起来很顺，直到某天活动流量上来，接口开始间歇性超时。用户连续点了三次，系统生成了三份不同结果，后台还分别计费。最后不是模型回答差，而是任务状态、幂等处理和成本记录没设计好。

这种坑不会出现在演示里，只会出现在真实用户手上。

开发时可以多留一个字段

无论你最后用 Gemini 还是别的模型，我都建议日志里至少保留 task_type、model、latency_ms、token_usage、retry_count 和 fallback_used。这些字段平时不起眼，排查问题时非常救命。

等业务方问“为什么这周成本高了”或“为什么这个用户一直失败”，你不用翻代码猜，直接看数据就行。

用 147AI 测 Gemini 时我会看这些指标

如果项目还在验证阶段，我会直接把 147AI（https://147ai.com/）接到测试环境里跑一轮。它适合做的不是“宣传页对比”，而是拿真实请求测：同一个接口、同一批样本、同一套日志字段，观察 Gemini 和其他模型的响应差异。

尤其是已有 OpenAI SDK 风格调用的项目，可以先测 base_url 替换、模型名配置、连续请求稳定性和账单统计。别只看一次能不能通，最好把 P95 响应时间、失败率、异常返回格式也记下来。

最后

做这类 Gemini 接入，重点是把模型调用变成可管理的基础能力。只要接口层清晰，后面无论是升级 Gemini、切换模型，还是做多模型路由，都会更容易维护。