企业官网建设流程全解析

MTGA 是一款基于本地代理的方案，用于绕过 IDE 的固定模型服务商限制。它的「模型路由」页面用targets（上游目标）、published_models（发布模型）、failover_pools（故障转移池）三个核心概念，统一管理多个上游 API，并实现 429 限流时的自动故障转移。本文带你一步步完成 MTGA 模型路由的完整配置。

模型路由三大核心概念一览表

配置前先看懂每部分负责什么，它们对应「模型路由」页签左侧的三个分区：

请求流转过程：IDE 以"发布模型名"发请求 → MTGA 查targets并把模型名替换成真实上游模型 → 命中触发状态码时自动切到failover_pools的下一个成员。

💡 打开 MTGA 后默认停留在的第一个页签就是「模型路由」，界面组件见 ModelRoutingPanel.vue。

第一步：创建上游目标（targets 配置步骤）

1. 在「上游目标」分区点击新增，依次填写：
   • Target ID：唯一标识，如target-1（必填）
   • 显示名称：便于自己识别，如 "Claude 主线路"
   • Provider：选择上游类型，支持OpenAI Chat Completion、OpenAI Response、Anthropic、Gemini
   • API Base：只填域名，例如https://api.openai.com
   • 上游模型：真实的模型 ID，如gpt-5
   • API Key：该上游对应的密钥
   • Middle Route：中间路由前缀，不懂可保持默认
2. 点击保存，一条上游目标即创建完成。

各 Provider 的差异与推荐写法见 docs/provider-support.md；目标字段的解析与校验逻辑位于 model_routing.py。

第二步：发布模型（published_models 配置步骤）

IDE"看到"的并不是上游真实模型名，而是你发布的发布模型名——这正是 MTGA 模型路由配置的关键所在：

1. 在「发布模型」分区新增一条：
   • 发布模型名称：IDE 侧将使用这个名字，例如想叫gpt-5就填gpt-5
   • 主目标：选择第一步创建的某个 target
   • 故障转移池：可不选（默认"不启用故障转移"）
   • 启用（暴露给下游）：勾选后才会对 IDE 暴露该名称
2. 保存后，IDE 请求中携带的模型名会被 MTGA 自动改写为主目标的真实上游模型再转发。

对应的映射结构PublishedModel定义在 model_routing.py；名称不存在或未启用时，代理会返回404 model_not_found。

第三步：配置故障转移池（429 自动切换与冷却机制）

故障转移池解决"上游被限流，请求直接失败"的问题：

1. 在「故障转移池」分区新增一个池：
   • Pool ID：如failover-pool-1
   • 触发状态码：上游返回哪些状态码时触发切换，默认429
   • 冷却秒数：命中触发后该目标暂停多久，默认10秒
   • 成员：勾选候选的"目标 + 模型"组合，将按顺序依次尝试
2. 回到发布模型，在「故障转移池」字段选中该池，完成绑定。

⚡ 运行机制：主目标返回 429 时，MTGA 会把它标记为冷却，当前请求立即转发到池内下一个成员；冷却结束后主目标自动回到候选。连接超时、连接失败等网络层错误同样会触发转移。默认值见 model_routing.py，冷却标记与切换的执行逻辑见 proxy_app.py。

完整配置示例：双上游自动故障转移

假设你有同一个模型的两条上游线路，按最小配置即可获得高可用：

1. 创建两个目标：primary与backup
2. 创建故障池pool-a（触发 429、冷却 10 秒、成员为backup）
3. 创建发布模型public-gpt：主目标primary，绑定pool-a

最终等效的配置结构如下（仅供参考，实际在 GUI 中完成）：

{ "targets": [ { "id": "primary", "api_base": "https://primary.example.com", "upstream_model": "gpt-primary", "api_key": "sk-..." }, { "id": "backup", "api_base": "https://backup.example.com", "upstream_model": "gpt-backup", "api_key": "sk-..." } ], "failover_pools": [ { "id": "pool-a", "trigger_statuses": [429], "cooldown_seconds": 10, "members": [{ "target_id": "backup" }] } ], "published_models": [ { "name": "public-gpt", "enabled": true, "primary_target_id": "primary", "failover_pool_id": "pool-a" } ] }

配置完成后，primary一旦返回 429，请求会透明切换到backup，IDE 端通常毫无感知。这套组合的测试用例可参考 test_proxy_app.py。

MTGA 模型路由常见问题排查

Q：IDE 报 "Model not found" 怎么办？请求携带的名称与published_models中的条目不匹配，或该模型未启用。请确认 IDE 里填写的名称与「发布模型名称」完全一致。

Q：为什么删除不了某个目标？被发布模型引用为目标时无法删除，需先把发布模型的「主目标」改成别的；仅被故障池引用的目标删除后会自动从池中移除。

Q："MTGA Auth Key" 是什么？它是 MTGA 本地代理的入站鉴权 Key，留空则入站请求不做鉴权；上游 API Key 在「上游目标」中单独维护，两者互不影响。

Q：主目标和备用的都在冷却中会怎样？此时没有可用目标，代理返回503 route_unavailable，等待冷却结束或为池增加更多成员即可。

参考文件与模块路径

🎯 掌握targets、published_models与failover_pools这三类资源，就掌握了 MTGA 模型路由的全部：一个页签配置完成，即可实现多上游模型透明转发与自动故障转移。