大模型应用开发 / 系统课时

封装模型客户端

封装模型客户端

直接在业务代码里散落请求参数、超时、重试和供应商字段映射,会很快失去可维护性。本节用一个统一客户端加适配器的实现,把稳定的业务接口与变化频繁的模型服务协议隔离开。

学习目标

  • 设计稳定的统一请求与响应结构,把供应商差异限制在适配器内部。
  • 在客户端层集中处理超时、有限重试和错误转换。
  • 明确哪些错误可以重试,哪些业务语义不应由通用客户端猜测。

先确定封装边界

统一客户端应该负责横切能力:公共参数、超时、重试、鉴权注入、错误分类和调用观测。供应商适配器只负责协议差异,例如请求字段名、响应字段位置、模型标识和特定错误码映射。

业务层最好只依赖稳定结构,例如 { model, messages, temperature } 与 { text }。当某个服务把输入叫 input、另一个叫 messages 时,这种差异不应泄漏到业务代码。

统一模型客户端与多供应商适配器架构

用统一客户端隔离协议差异

下面的 Node.js 20+ 示例同时启动两个本地模拟服务。Provider A 使用 messages/temperature,Provider B 使用 input/randomness;统一客户端通过适配器屏蔽差异,并让 Provider B 第一次返回 503,以验证重试与错误转换。

js
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();

预期输出

text
A: 模拟-A: 你好
retry 1: HTTP 503
B: 模拟-B: 你好

示例使用系统随机分配的本地端口,实际端口值不会影响上述输出。

超时与重试要有明确上限

超时应覆盖单次网络尝试,而不是让一次请求无限等待。重试只适合瞬时故障,例如连接失败、429 或部分 5xx;参数错误、鉴权失败和明确的 4xx 通常应立即返回。退避策略可以在真实项目中加入指数退避和抖动,但最大尝试次数必须有限。

对于会触发外部副作用的模型调用,例如“生成后自动下单”或“调用工具修改数据”,通用客户端不能仅凭 HTTP 状态判断是否安全重试。此时应由更上层的编排逻辑提供幂等键、调用记录或明确的重放策略。

错误转换只统一形状,不掩盖原因

客户端层可以把供应商错误归一为 status、retryable、code、requestId 等稳定字段,但不要把所有异常都转换成同一个“模型调用失败”。日志和监控仍应保留原始状态码、供应商请求 ID 与根因链,方便定位限流、超时、鉴权或协议变化。

当接入新的模型服务时,优先新增适配器并补充契约测试,而不是在统一客户端里堆 if provider === ...。只要业务请求模型保持稳定,供应商切换、字段变化和错误码差异就可以被限制在很小的代码范围内。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

封装模型客户端

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通