docs/model-remapping-logic.md

模型重映射逻辑（当前实现）

最后更新：2026-03-02

本文描述当前代理中的模型重映射链路（含 Gemini 3/3.1 Pro 调整后的行为）。

1）整体流程

无论是 OpenAI 协议还是 Gemini 原生协议，请求模型都会经过两段处理：

1. 静态路由解析（全局规则）：
   • 在选账号前执行一次。
   • 代码：src-tauri/src/proxy/common/model_mapping.rs 的 resolve_model_route。
2. 动态账号感知改写（条件回退）：
   • 在选中账号后执行。
   • 代码：src-tauri/src/proxy/token_manager.rs 的 resolve_dynamic_model_for_account。

使用该流程的入口：

• src-tauri/src/proxy/handlers/openai.rs
• src-tauri/src/proxy/handlers/gemini.rs

2）静态路由优先级

resolve_model_route(original_model, custom_mapping) 的优先级从高到低为：

1. 官方动态淘汰转发规则：
   • DYNAMIC_MODEL_FORWARDING_RULES
2. 用户自定义精确映射：
   • custom_mapping[original_model]
3. 用户自定义通配符映射：
   • 按“非 * 字符数”比较，越具体优先级越高
4. 系统内置默认映射：
   • map_claude_model_to_gemini

都不命中时，模型名原样透传。

3）当前 Gemini Pro 内置映射策略

当前策略是：具体模型 ID 直接透传；只有泛别名会归一化。

具体 ID（不做跨版本强制改写）：

• gemini-3-pro-high -> gemini-3-pro-high
• gemini-3-pro-low -> gemini-3-pro-low
• gemini-3-pro-preview -> gemini-3-pro-preview
• gemini-3.1-pro-high -> gemini-3.1-pro-high
• gemini-3.1-pro-low -> gemini-3.1-pro-low
• gemini-3.1-pro-preview -> gemini-3.1-pro-preview

泛别名（仍映射到 preview 入口）：

• gemini-3-pro -> gemini-3-pro-preview
• gemini-3.1-pro -> gemini-3.1-pro-preview

代码位置：

• src-tauri/src/proxy/common/model_mapping.rs

4）动态账号感知改写（仅在需要时触发）

选中账号后，系统会读取该账号本地 quota 里的可用模型，判断当前模型是否可用。

行为如下：

1. 读取账号 JSON：quota.models[*].name。
2. 仅针对 Gemini 3/3.1 Pro 家族构造候选回退列表。
3. 候选顺序：
   • 先尝试当前模型
   • 再按预设顺序尝试同家族其他兼容模型
4. 选中第一个在账号可用集合里存在的模型。
5. 若都不命中，则保持当前模型不变。

关键点：

• 如果请求模型本身可用，不会发生重映射。
• 只有请求模型不可用且存在兼容候选时，才会重映射。

代码位置：

• src-tauri/src/proxy/token_manager.rs
  • get_available_models_from_json
  • build_dynamic_model_candidates
  • resolve_dynamic_model_for_account

5）日志观测点

可通过日志判断每一步是否触发：

• 静态映射日志：
  • [Router] 系统默认映射: <original> -> <mapped>
• 动态改写日志：
  • [Dynamic-Model-Rewrite] account=<id> <from> -> <to>

如果某次请求没有出现 Dynamic-Model-Rewrite，说明该账号直接使用了当前模型。

6）示例

示例 A（不改写）：

• 请求：gemini-3-pro-high
• 账号可用模型包含：gemini-3-pro-high
• 最终上游模型：gemini-3-pro-high

示例 B（发生回退改写）：

• 请求：gemini-3-pro-high
• 账号不可用：gemini-3-pro-high
• 账号可用：gemini-3.1-pro-high
• 最终上游模型：gemini-3.1-pro-high

示例 C（泛别名）：

• 请求：gemini-3-pro
• 静态阶段先映射为：gemini-3-pro-preview
• 动态阶段再根据账号可用模型决定是否继续回退。

7）设计目标

该设计同时满足三点：

• 具体模型优先保持用户原始意图。
• 泛别名保留历史兼容能力。
• 多账号能力不一致时，通过动态回退提升可用性。