第 3 章 · Model Routing 模型路由
本章目标：理解 Mastra 统一模型接口的设计思想，学会配置多个提供商并在项目间自由切换模型。
3.1 为什么需要模型路由
不同 LLM 提供商的 SDK 接口各不相同：OpenAI 用 chat.completions.create，Anthropic 用 messages.create，参数名、错误结构、流式格式都有差异。如果直接依赖某家 SDK，后续换模型就要重写调用层。
Mastra 的 Model Routing 提供统一抽象：
- 一个字符串格式
"provider/model"表达"用哪家的哪个模型"； - 40+ 提供商共用同一套调用/流式/工具调用协议；
- 切换模型 = 改一个字符串，业务代码零改动。
常用模型 ID 一览（完整列表见 mastra.ai/models）：
text
openai/gpt-5.6-sol anthropic/claude-opus-4-7
openai/gpt-5-mini anthropic/claude-sonnet-4-6
google/gemini-2.5-flash anthropic/claude-haiku-4-53.2 配置提供商密钥
每个提供商只需要对应的环境变量，无需安装额外 SDK：
bash
# .env —— 按需配置，可同时存在多家
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...typescript
// Agent 直接使用字符串即可，Mastra 自动解析 provider 前缀
import { Agent } from '@mastra/core/agent';
export const writerAgent = new Agent({
id: 'writer',
name: 'Writer',
instructions: 'You are a concise technical writer.',
model: 'anthropic/claude-sonnet-4-6', // 自动读取 ANTHROPIC_API_KEY
});3.3 运行时切换模型
同一个 Agent 可以在创建后动态替换模型，适合 A/B 测试或降级场景：
typescript
import { mastra } from './mastra';
const agent = mastra.getAgent('writer');
// 场景一：日常使用主力模型
let res = await agent.generate('写一句产品口号');
console.log(res.text);
// 场景二：高峰期切换到更快更便宜的模型
agent.__updateModel?.('anthropic/claude-haiku-4-5');
res = await agent.generate('写一句产品口号');更常见的做法是在注册时就按用途拆成多个 Agent：
typescript
// src/mastra/index.ts —— 不同任务绑定不同档位的模型
export const mastra = new Mastra({
agents: {
// 重推理任务用旗舰模型
analyst: analystAgent, // model: 'openai/gpt-5.6-sol'
// 高频轻量任务用 mini 档
summarizer: summaryAgent, // model: 'openai/gpt-5-mini'
// 长上下文归档用便宜大窗口模型
archiver: archiveAgent,
},
});3.4 选择模型的决策框架
| 维度 | 考量 | 示例 |
|---|---|---|
| 任务复杂度 | 复杂推理/代码生成 → 旗舰；分类/摘要 → mini | 客服分流用 mini |
| 成本 | 旗舰与 mini 价差可达 10–30 倍 | 批处理任务选低价模型 |
| 延迟 | 面向用户的实时对话优先低延迟 | haiku / gpt-5-mini |
| 上下文长度 | 长文档分析需要大窗口模型 | gemini-2.5-flash |
typescript
// 按运行环境动态选择模型：开发用便宜档，生产用旗舰档
const model =
process.env.NODE_ENV === 'production'
? 'openai/gpt-5.6-sol'
: 'openai/gpt-5-mini';
export const adaptiveAgent = new Agent({
id: 'adaptive',
name: 'Adaptive Agent',
instructions: 'You are a helpful assistant.',
model,
});组合策略
生产系统的常见模式是"模型梯队"：入口用一个便宜模型做意图分类，简单请求直接回答，复杂请求升级到旗舰模型——成本能降一个数量级。
本章小结
- Model Routing 用
"provider/model"字符串统一 40+ 提供商，切换模型零代码改动； - 密钥通过标准环境变量注入（OPENAI_API_KEY 等），可同时配置多家；
- 按任务复杂度/成本/延迟/上下文四个维度为不同 Agent 分配不同档位模型；
- 生产环境推荐"模型梯队"模式控制整体成本。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. Mastra 模型路由中，model 字段 "google/gemini-2.5-flash" 的两部分分别代表？
2. 想把某个 Agent 从 GPT 切换到 Claude，最小改动是什么？
3. 下列哪种做法最符合 Mastra 官方推荐的多模型管理方式？
4. 面向终端用户的实时聊天场景，选择模型时最应优先考虑？
🛠️ 动手实践
- 在项目中同时配置 OpenAI 与 Anthropic 的 Key，让两个 Agent 分别用两家的模型回答同一问题并对比风格。
- 把你的 Agent 模型从旗舰档切到 mini 档，在 Studio 中对比两次回复质量与响应速度。
- 访问 mastra.ai/models，找出支持 100 万 token 上下文的模型 ID 并记录其提供商前缀。