大模型应用开发 / 系统课时
封装模型客户端
封装模型客户端
直接在业务代码里散落请求参数、超时、重试和供应商字段映射,会很快失去可维护性。本节用一个统一客户端加适配器的实现,把稳定的业务接口与变化频繁的模型服务协议隔离开。
学习目标
- 设计稳定的统一请求与响应结构,把供应商差异限制在适配器内部。
- 在客户端层集中处理超时、有限重试和错误转换。
- 明确哪些错误可以重试,哪些业务语义不应由通用客户端猜测。
先确定封装边界
统一客户端应该负责横切能力:公共参数、超时、重试、鉴权注入、错误分类和调用观测。供应商适配器只负责协议差异,例如请求字段名、响应字段位置、模型标识和特定错误码映射。
业务层最好只依赖稳定结构,例如 { model, messages, temperature } 与 { text }。当某个服务把输入叫 input、另一个叫 messages 时,这种差异不应泄漏到业务代码。

用统一客户端隔离协议差异
下面的 Node.js 20+ 示例同时启动两个本地模拟服务。Provider A 使用 messages/temperature,Provider B 使用 input/randomness;统一客户端通过适配器屏蔽差异,并让 Provider B 第一次返回 503,以验证重试与错误转换。
import http from "node:http";
let providerBCalls = 0;
const server = http.createServer(async (req, res) => {
let body = "";
for await (const chunk of req) body += chunk;
const data = JSON.parse(body || "{}");
res.setHeader("content-type", "application/json");
if (req.url === "/provider-a") {
res.end(JSON.stringify({
output_text: `模拟-A: ${data.messages?.[0]?.content ?? ""}`
}));
return;
}
if (req.url === "/provider-b") {
providerBCalls += 1;
if (providerBCalls === 1) {
res.statusCode = 503;
res.end(JSON.stringify({ error: "temporarily unavailable" }));
return;
}
res.end(JSON.stringify({
answer: `模拟-B: ${data.input ?? ""}`
}));
return;
}
res.statusCode = 404;
res.end(JSON.stringify({ error: "not found" }));
});
await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
const { port } = server.address();
const baseUrl = `http://127.0.0.1:${port}`;
class ModelClientError extends Error {
constructor(message, { status = 0, retryable = false } = {}) {
super(message);
this.name = "ModelClientError";
this.status = status;
this.retryable = retryable;
}
}
class ProviderAAdapter {
async send(request, { signal }) {
const response = await fetch(`${baseUrl}/provider-a`, {
method: "POST",
headers: { "content-type": "application/json" },
signal,
body: JSON.stringify({
model: request.model,
messages: request.messages,
temperature: request.temperature
})
});
return parseResponse(response, data => ({ text: data.output_text }));
}
}
class ProviderBAdapter {
async send(request, { signal }) {
const response = await fetch(`${baseUrl}/provider-b`, {
method: "POST",
headers: { "content-type": "application/json" },
signal,
body: JSON.stringify({
model: request.model,
input: request.messages.map(item => item.content).join("\n"),
randomness: request.temperature
})
});
return parseResponse(response, data => ({ text: data.answer }));
}
}
async function parseResponse(response, mapSuccess) {
const data = await response.json();
if (!response.ok) {
throw new ModelClientError(`HTTP ${response.status}`, {
status: response.status,
retryable: response.status === 429 || response.status >= 500
});
}
return mapSuccess(data);
}
class UnifiedModelClient {
constructor(adapter, { timeoutMs = 3000, maxRetries = 1 } = {}) {
this.adapter = adapter;
this.timeoutMs = timeoutMs;
this.maxRetries = maxRetries;
}
async generate(request) {
for (let attempt = 0; ; attempt += 1) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), this.timeoutMs);
try {
return await this.adapter.send(request, { signal: controller.signal });
} catch (error) {
const normalized = this.normalizeError(error);
if (!normalized.retryable || attempt >= this.maxRetries) throw normalized;
console.log(`retry ${attempt + 1}: ${normalized.message}`);
} finally {
clearTimeout(timer);
}
}
}
normalizeError(error) {
if (error instanceof ModelClientError) return error;
if (error?.name === "AbortError") {
return new ModelClientError("request timeout", { retryable: true });
}
return new ModelClientError(error?.message ?? "unknown error");
}
}
const request = {
model: "demo-model",
messages: [{ role: "user", content: "你好" }],
temperature: 0.2
};
const clientA = new UnifiedModelClient(new ProviderAAdapter());
const clientB = new UnifiedModelClient(new ProviderBAdapter(), { maxRetries: 1 });
console.log("A:", (await clientA.generate(request)).text);
console.log("B:", (await clientB.generate(request)).text);
server.close();预期输出
A: 模拟-A: 你好
retry 1: HTTP 503
B: 模拟-B: 你好示例使用系统随机分配的本地端口,实际端口值不会影响上述输出。
超时与重试要有明确上限
超时应覆盖单次网络尝试,而不是让一次请求无限等待。重试只适合瞬时故障,例如连接失败、429 或部分 5xx;参数错误、鉴权失败和明确的 4xx 通常应立即返回。退避策略可以在真实项目中加入指数退避和抖动,但最大尝试次数必须有限。
对于会触发外部副作用的模型调用,例如“生成后自动下单”或“调用工具修改数据”,通用客户端不能仅凭 HTTP 状态判断是否安全重试。此时应由更上层的编排逻辑提供幂等键、调用记录或明确的重放策略。
错误转换只统一形状,不掩盖原因
客户端层可以把供应商错误归一为 status、retryable、code、requestId 等稳定字段,但不要把所有异常都转换成同一个“模型调用失败”。日志和监控仍应保留原始状态码、供应商请求 ID 与根因链,方便定位限流、超时、鉴权或协议变化。
当接入新的模型服务时,优先新增适配器并补充契约测试,而不是在统一客户端里堆 if provider === ...。只要业务请求模型保持稳定,供应商切换、字段变化和错误码差异就可以被限制在很小的代码范围内。