模型接入与系统提示词:多 provider 抽象与 fallback、覆盖默认人设(dg P03/P04/M04)
学会把多个模型 provider 统一抽象成一层,支持失败自动切换,并理解为什么必须覆盖框架默认的系统提示词。
今日目标
- 能实现一个至少支持 3 个 provider、可按配置切换的模型调用层
- 能给 Agent 写一段自定义 system prompt,覆盖框架默认人设
- 能说出模型调用失败时 fallback 策略要考虑哪些因素(延迟、成本、可用性)
前三天你的代码里始终只有一家 provider:地址写死在 fetch 里,模型名最好也不过来自一个 MODEL 环境变量(D1 实验第 4 步就是这么干的)——换模型 id 可以,换厂商就得动代码。今天把这层彻底拆开。读完回来把上面三条勾掉。
小白版讲解
只接一家模型,等于把命交给别人的运维
想象你开了一家只有一个供货商的餐厅。菜品、价格、出餐速度全靠他,平时相安无事,直到某天早上他的货车抛锚——你不是"生意差一点",你是今天开不了门。
接模型也是同一件事。代码里写死 openai/gpt-4o-mini,等于把服务的可用性完全绑定在某一家厂商的运维水平上。而大模型 API 的可用性比你想象的低:区域性故障、账号触发限流(rate limit)、模型被下线或改名、某次调用莫名卡住 60 秒不返回——这些不是"小概率意外",是每月都会遇上几次的日常。
算笔账你就明白为什么不能赌。假设某家厂商的月可用性是 99.5%,听着很高,但那意味着一个月里有约 3.6 小时你的 Agent 是废的,用户看到的全是转圈和报错。而如果接了三家、且它们的故障互不相关,三家同时挂掉的概率是 0.5% 的三次方,即千万分之一点二五——不可用时间从 3.6 小时(12960 秒)掉到 0.33 秒,一秒都不到。同样的代码量级,可用性差了四个多数量级,约四万倍。
但这个数字有个必须说清的前提:故障互不相关。 本章的示例和今天的实验为了让你一把 key 就跑通,三个 provider 全走 OpenRouter 这一个聚合网关——那是三个模型 id,不是三条独立的路:网关一挂、key 一被封,三家一起完蛋,聚合网关自己成了新的单点。真正的冗余要接不同厂商的直连端点,凭证、机房、计费各自独立,那个四万倍才算数。面试官爱从这里切进来,所以要主动说:数量级是拿独立当前提算的,共用网关不满足这个前提。
问题是,前三天的代码离"接三家"有多远?看一眼你现在写的:
// 前三天的写法:地址写死在调用处,模型名最好的情况来自一个环境变量
const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: process.env.MODEL ?? 'openai/gpt-4o-mini',
messages,
}),
})
const json = await res.json()
// 这一家挂了怎么办?没有别的路可走——整个服务跟着它一起挂。# 前三天的写法:地址写死在调用处,模型名最好的情况来自一个环境变量
res = httpx.post(
"https://openrouter.ai/api/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
json={
"model": os.environ.get("MODEL", "openai/gpt-4o-mini"),
"messages": messages,
},
)
body = res.json()
# 这一家挂了怎么办?没有别的路可走——整个服务跟着它一起挂。// 前三天的写法:地址写死在调用处,模型名最好的情况来自一个环境变量
var mapper = new ObjectMapper();
var payload = mapper.createObjectNode();
payload.put("model", System.getenv().getOrDefault("MODEL", "openai/gpt-4o-mini"));
payload.set("messages", messages);
var request = HttpRequest.newBuilder(URI.create("https://openrouter.ai/api/v1/chat/completions"))
.header("Authorization", "Bearer " + System.getenv("OPENROUTER_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
.build();
var res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
// 这一家挂了怎么办?没有别的路可走——整个服务跟着它一起挂。// 前三天的写法:地址写死在调用处,模型名最好的情况来自一个环境变量
let env = ProcessInfo.processInfo.environment
let model = env["MODEL"] ?? "openai/gpt-4o-mini"
var request = URLRequest(url: URL(string: "https://openrouter.ai/api/v1/chat/completions")!)
request.httpMethod = "POST"
request.setValue("Bearer \(env["OPENROUTER_API_KEY"] ?? "")", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(ChatRequest(model: model, messages: messages))
let (data, _) = try await URLSession.shared.data(for: request)
// 这一家挂了怎么办?没有别的路可走——整个服务跟着它一起挂。这段代码没有一行是"错"的,问题在于它只有一条路。MODEL 变量看着像留了灵活性,可它换得了模型 id、换不了厂商:地址、鉴权头、响应字段的形状全焊死在这次调用里。真出事时你只能改变量重启,再祈祷另一家的响应格式恰好一样。
还有一个更现实的理由:价格和能力每个月都在变。今天最划算的模型,两个月后可能被另一家的新版本超越,价格还便宜一半。如果换模型意味着重写调用代码、重测所有 prompt,你就会因为"太麻烦"而一直用着贵的慢的那个。接入成本高,本质上是在剥夺你未来做选择的自由。
所以生产级 Agent 的第一条规矩是:模型是可替换的零件,不是写死的地基。
那问题来了——三家的请求格式、响应结构、报错方式各不相同,接三家岂不是要把调用代码写三遍?答案当然是"加一层抽象",但难的不是那一层,是它背后的三件事:哪几类错误重试就是白烧钱(404 被绝大多数人归错了桶)、fallback 怎么在你毫无察觉时把账单翻三倍、以及一个一年省六万多的分层路由算法。 下面挨个讲清楚。
面试题库
为什么生产级 Agent 通常要接入多个模型 provider?Why do production agents usually integrate more than one model provider?
国内高频海外高频基础#model-routing#reliability🔒 解锁本章后查看答题要点。
设计模型 fallback 策略时要权衡哪些因素?What trade-offs shape a model fallback strategy?
国内高频海外高频进阶#model-routing#reliability#cost🔒 解锁本章后查看答题要点。
系统提示词(system prompt)在 Agent 里起什么作用?为什么不能用框架默认的?What does the system prompt do in an agent, and why not rely on the framework default?
国内高频海外高频进阶#prompt-engineering#system-prompt🔒 解锁本章后查看答题要点。
如何在成本和延迟之间给不同任务选择合适的模型?How do you pick the right model per task, balancing cost against latency?
国内高频海外高频进阶#model-routing#cost#latency🔒 解锁本章后查看答题要点。
