把线上服务从旧模型切到 Gemini 4 Argon，这件事的本质是一次配置变更，不是一次代码重构。改名本身只是字符串替换，真正容易出问题的是三处：项目权限对不上导致新模型名不可用、新旧模型返回结构有差异导致下游解析失败、以及切过去之后没有一条干净的退路。建议按核对权限、集中模型名、灰度切流、保留回退开关的顺序推进，并把回退当成必须提前准备好的功能，而不是出问题后再补。

处理方向：先把模型名从模板字符串、业务常量和部署环境变量里抽成一处配置，让切换与回退都只改一个地方；迁移前用同一份请求体分别调用旧模型和 Gemini 4 Argon，逐项比对返回键名、状态字段和错误结构；先用内部账号或小比例流量验证，预设触发回退的条件，并保证旧模型的鉴权、超时、配额配置在迁移期间原样不动。边界：具体权限项、模型可用区域和错误码含义需要结合自己的项目环境确认，绕过权限的做法不应作为迁移手段。

把模型名从代码各处抽成配置变量

先找出模型名散落的位置，通常有四类：调用处写死的字符串、业务常量或枚举、部署环境变量、以及缓存 key、日志标签、限流规则里顺手带上模型名的位置。只改前两类而漏掉后两类，回退时会出现配置说切回去了、日志和缓存还在按新模型分流的情况。

# 改造前：模型名散落在多个文件
# service/chat.py
resp = client.generate(model='gemini-3-pro', prompt=prompt)

# service/summary.py
MODEL = 'gemini-3-pro'

# deploy/prod.env
CHAT_MODEL=gemini-3-pro

# 改造后：config/models.yaml
chat:
  primary: 'gemini-3-pro'          # 旧模型，回退目标
  candidate: 'gemini-4-argon'      # 新模型，灰度目标
  gray_percent: 0
  force_fallback: false
  internal_allowlist:
    - 'svc-test-01'

def resolve_model(cfg, user_id):
    # 单一出口：所有调用都从这里取模型名
    chat = cfg['chat']
    if chat['force_fallback']:
        return chat['primary']
    if user_id in chat['internal_allowlist']:
        return chat['candidate']
    return chat['primary']

替换项和验证方式：常量路径换成自己项目的路径；读取优先级建议配置中心或配置文件高于环境变量，环境变量高于代码默认值，并在启动日志里打印一次最终生效的模型名。配置是否支持热加载取决于部署方式，如果不支持热加载，回退就意味着一次重启，这一点要在设计回退开关之前先确认清楚。

用同一份请求体分别打旧模型和 Gemini 4 Argon，比对返回结构

选一份最简单的请求体，只保留模型名、输入和少量生成参数，然后只替换 model 字段跑两次，把两次原始响应保存下来做比对。请求体越简单，越容易看出结构性差异，而不是被提示词本身的内容差异干扰。

payload = {
    'messages': [{'role': 'user', 'content': 'ping'}],
    'max_output_tokens': 32,
}
# 第一次：payload['model'] = 'gemini-3-pro'
# 第二次：payload['model'] = 'gemini-4-argon'

对照表按下面的字段设计记录，空格处填实际观察到的键名和取值，不要凭印象填。

状态字段和错误结构建议分开记：状态字段影响业务判断，错误结构影响重试和告警策略。下游解析做防御性读取更稳妥，字段缺失时走默认值而不是直接抛异常，否则一个小的结构变化就会在线上放大成错误页。

先给内部账号或小比例流量走新模型

分流的依据优先用稳定的账号标识，不要用请求 ID 或时间戳，否则同一个用户会在新旧模型之间来回跳，提示词模板和缓存都对不上。常见做法是内部账号白名单先全量走新模型，外部用户按稳定哈希取模进入小比例。

import hashlib

def bucket(user_id, total=100):
    h = hashlib.sha256(user_id.encode()).hexdigest()
    return int(h[:8], 16) % total

def pick_model(cfg, user_id, forced=None):
    chat = cfg['chat']
    if chat['force_fallback']:
        return chat['primary']
    if user_id in chat['internal_allowlist']:
        return chat['candidate']
    if forced == 'candidate':
        return chat['candidate']
    if bucket(user_id) < chat['gray_percent']:
        return chat['candidate']
    return chat['primary']

标记灰度请求的做法：在日志字段里固定加 route（primary 或 candidate）和 model_name，必要时在响应头里回传 route，方便按用户复现问题。分流依据、白名单和比例都放在同一份配置里，验证方式是筛选 route=candidate 的请求，确认它们确实带着新模型名发出，并且这批请求的返回被正常解析。

设置回退触发条件与开关，出问题一条配置退回

回退要能在不改代码的前提下完成，所以触发条件最好由程序判定、由配置决定是否生效，而不是靠人盯监控手动改。可用的判定字段通常包括连续鉴权失败次数、单位时间内的超时比例、上游 5xx 比例、响应解析失败次数。下面的数字只是占位，具体阈值需要结合自己的流量和业务容忍度设定。

# config/models.yaml 追加
chat:
  guard:
    auth_error_streak: 3
    parse_error_streak: 3
    timeout_ratio: 0.2
    window_seconds: 60

def should_fallback(cfg, m):
    g = cfg['chat']['guard']
    return (m['auth_error_streak'] >= g['auth_error_streak']
            or m['parse_error_streak'] >= g['parse_error_streak']
            or m['timeout_ratio'] >= g['timeout_ratio'])

开关的读取方式建议和主配置同源，并且走可热更新的通道；如果配置中心支持热加载，回退就是一条配置生效，不需要重启服务。回退动作可以是把 gray_percent 置 0，也可以把 force_fallback 置 true，两者都只改配置值。回退后要保证旧模型的这几点原样不动：模型名、端点与区域、鉴权方式和凭据、超时与重试参数、配额与限流设置、提示词模板。验证方式是观察日志里 route 是否全部回到 primary，同时确认旧模型的报错没有因为回切而出现新的变化。

切换后盯住日志里的错误码与超时字段

切换后需要重点看的字段建议固定下来：timestamp、request_id、model_route、model_name、http_status、error_code、error_type、latency_ms、是否命中超时、retry_count、上游区域标识。这些字段的作用是把权限类问题和性能类问题分开，避免一看到报错就把灰度整体关掉。

• 401、403 或 permission denied：优先核对项目权限、服务账号角色和该模型的可用范围。这类报错不是性能问题，加超时和重试没有意义。
• 404 或 model not found：先核对模型名拼写、调用区域和端点，再确认这个模型名在当前项目下是否已经可用。
• 429 或配额相关错误：偏限流和容量问题，看配额、并发和上游返回的提示，通常与模型名本身无关。
• 400 或 invalid argument：多半是请求体字段与新模型不兼容，回到上一节的对照表逐项核对。
• 5xx：偏上游或网关问题，结合 retry_count 判断是瞬时抖动还是持续异常，持续异常才考虑触发回退。
• 超时字段：单独统计，区分网络层超时、上游排队和本地超时设置过小，避免把本地配置问题误判成模型不可用。

判断口径可以简单一些：权限类报错先停下来核对权限，不要靠重试掩盖；结构类报错先修解析再继续放量；只有持续性的服务异常才走回退开关。回退之后把命中的日志片段保留下来，再决定是继续迁移还是先留在旧模型上观察。