多模型统一接入层实战：国产大模型API协议归一与流式网关

在实际项目里接入国产大模型，最先遇到的问题往往不是“模型答得好不好”，而是“四家 API 怎么统一管”。DeepSeek、智谱 GLM、豆包、通义千问都能通过 HTTP 调用，但它们的 base_url、模型标识、流式返回格式、错误码和用量字段各有差异。如果每接一家就复制一套 SDK 调用代码，项目很快会出现四份超时配置、四份重试逻辑、四份日志格式，排查一次线上问题要翻四个文件。多模型统一接入层要解决的就是这件事：把协议差异收在适配层，把业务代码统一到一套请求和响应结构上，让切换模型变成改配置而不是改代码。下面从协议差异讲起，依次完成依赖准备、协议归一、流式输出、重试限流、运行验证和排查链路，最终得到一个可以同时调用四家模型、支持流式输出、能统计用量、出错时能定位到具体厂商的最小可用网关。

1. 多模型统一接入要解决的问题，比“换一个 base_url”复杂得多

很多团队最初的想法很朴素：既然这些厂商都宣称兼容 OpenAI 协议，那我把 base_url 和 api_key 换一下不就行了。真跑起来会发现，兼容是“大致兼容”，不是“完全一致”。有的厂商模型名必须填控制台创建的接入点 ID，有的厂商流式响应里不返回用量，有的厂商对 max_tokens 的取值范围有额外限制，还有的厂商在参数非法时返回的错误结构完全不同于 OpenAI 的 error.message 格式。这些差异单看都不大，但分散在业务代码里就会互相纠缠。

1.1 四家国产大模型的 API 到底哪里不一样

先把差异摆到桌面上。下表是接入时最常碰到的几个维度，具体路径和模型标识以各家官方文档为准，落地前务必核对一遍控制台。

这张表最值得注意的不是前四行，而是最后一行。非流式调用时，响应体里的 usage 一般都会返回；流式调用时，很多兼容实现默认不返回 usage，需要显式传 stream_options: {"include_usage": true}，而且即便传了，也要确认目标模型是否支持。如果用量统计做不对，后面按厂商核算成本就无从谈起。

1.2 为什么适配器模式比 if-else 更适合接入层

如果只有两家模型，写 if (provider.equals("deepseek")) { ... } else { ... } 完全能跑。问题出在第三家、第四家进来之后：分支开始嵌套，公共的重试和日志代码被复制粘贴，新增一个厂商要改动已有的分支判断。适配器模式的价值在于把“变化的部分”隔离出来，让“不变的部分”只写一次。

在这个场景里，不变的部分是：组装请求、发 HTTP、解析响应、处理超时、记录日志、统计用量。变化的部分是：base_url、模型名映射、个别字段的兼容处理。所以合理的做法是写一个通用客户端承载不变逻辑，再用配置表描述变化部分，只在确实不兼容的地方留扩展接口。这比给每家写一个独立类要省事得多，也比纯 if-else 更容易测试。

1.3 接入层应该收敛的五件事

一个能被业务方放心使用的模型接入层，至少要收敛下面五件事，否则业务代码迟早会绕过它自己调 HTTP。

1. 统一请求结构：消息列表、温度、最大 token 数、是否流式，用同一套对象表达。
2. 统一响应结构：正文、结束原因、用量、实际命中的厂商和模型，统一返回。
3. 统一错误语义：把四家的错误码归一成“鉴权失败、参数错误、限流、超时、服务端错误”几类。
4. 统一可观测性：每次调用都有 traceId、厂商、模型、耗时、token 数。
5. 统一配置入口：密钥、超时、并发上限集中管理，不散落在业务模块。

这五条决定了后面所有代码的组织方式。很多接入层的失败不是因为协议没对上，而是因为这五件事只做了第一条，剩下四条在业务代码里各写各的。

2. 项目骨架：依赖、目录和配置边界

在写第一行业务代码之前，先把依赖版本、包结构和配置边界定下来。这一步看起来是体力活，但它决定了后面加第五家、第六家模型时需不需要重构。实践中踩过的坑基本都集中在这里：依赖冲突导致 WebClient 的编解码器版本不一致、密钥硬编码进代码后无法在测试环境替换、模型清单散落在枚举和配置文件两处导致改一处忘一处。

2.1 JDK 与依赖版本选择

示例使用 JDK 17 加 Spring Boot 3.x。选择这个组合的原因是 Spring Boot 3 自带 WebClient 的响应式支持，处理 SSE 流式返回比传统阻塞式 HTTP 客户端更自然；JDK 17 是长期支持版本，虚拟线程在 JDK 21 才正式可用，这里不依赖它。

xml复制<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.2.x</spring-boot.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

这里选择 spring-boot-starter-webflux 而不是 spring-boot-starter-web，原因是流式接口需要把上游的 SSE 数据边收边转发。用阻塞式 MVC 也能做，但需要手动管理输出流和线程，代码会更绕。如果项目本身是 MVC 架构，可以只引入 spring-boot-starter-webflux 提供 WebClient，控制器仍然用 MVC 写，两者可以共存，但要注意不要在同一个应用里同时引入完整的 web 和 webflux starter，容易引发自动配置冲突。

版本号那一行写的是 3.2.x，实际落地时要换成团队统一管理的具体版本。不要在这个示例里锁死一个补丁版本号，因为不同小版本之间 WebClient 的编解码行为有过调整，照抄别人的版本反而容易出问题。

2.2 分包结构与职责边界

包结构按“对外契约、通用客户端、路由、门面、接口层”划分，避免所有类堆在一个包下。

text复制com.example.modelgateway
├── api                // 对外 Controller 和请求响应 DTO
├── config             // 配置属性、WebClient 构建、Bean 装配
├── core               // 统一请求响应模型、错误类型
├── client             // OpenAI 兼容协议客户端
├── router             // 模型到厂商的路由
├── service            // 门面服务：重试、用量统计、日志
└── support            // 工具类：密钥脱敏、JSON 解析

职责边界要守住两条线：client 包只负责“发请求、解析响应”，不掺业务逻辑；service 包负责“选模型、重试、统计”，不关心 HTTP 细节。这样后面给某一家加特殊参数时，改动只会落在 client 或配置层，不会波及业务。

2.3 密钥和模型清单必须外置

密钥不要写在代码里，也不要提交进仓库。用环境变量注入，配置文件里只写占位符。模型清单同理，新增模型不应该改代码。

yaml复制model-gateway:
  connect-timeout: 5s
  response-timeout: 60s
  max-concurrency: 32
  providers:
    deepseek:
      base-url: https://api.deepseek.com
      api-key: ${DEEPSEEK_API_KEY:}
      models:
        - deepseek-chat
        - deepseek-reasoner
    qwen:
      base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
      api-key: ${DASHSCOPE_API_KEY:}
      models:
        - qwen-plus
        - qwen-max
    glm:
      base-url: https://open.bigmodel.cn/api/paas/v4
      api-key: ${ZHIPU_API_KEY:}
      models:
        - glm-4-plus
        - glm-4-flash
    doubao:
      base-url: https://ark.cn-beijing.volces.com/api/v3
      api-key: ${ARK_API_KEY:}
      models:
        - ${ARK_ENDPOINT_ID:}

豆包这一项写的是环境变量占位，因为它的 model 字段通常要填控制台创建的推理接入点 ID，而不是通用模型名。这一点如果搞混，会直接返回模型不存在的错误，而且错误信息不一定直观。建议在配置加载阶段就把空值和空列表挡掉，让应用启动即失败，而不是等到第一次调用才发现密钥没配。

注意：配置里的占位符默认值写成空字符串，是为了让本地不配密钥也能启动看日志；如果希望强制校验，就在校验逻辑里把空值判为致命错误，按团队规范二选一，不要两种策略混用。

3. 协议归一：用一套 OpenAI 兼容客户端覆盖四家模型

协议归一的核心判断是：这四家在对话补全这个场景下，请求体和响应体的主体结构足够接近，可以共用一套客户端。差异集中在地址、模型标识和少数字段上，用配置和少量扩展点就能覆盖。这个判断成立的前提是只做“文本对话补全”，如果后面要接入工具调用、结构化输出、多模态，差异会显著变大，需要重新评估。

3.1 定义统一的请求与响应结构

统一模型是整个接入层的地基。请求里保留业务真正关心的字段，响应里补齐运维需要的字段。

java复制public record ChatMessage(String role, String content) {
}

public record ChatRequest(
        String model,
        List<ChatMessage> messages,
        Double temperature,
        Integer maxTokens,
        boolean stream) {

    public ChatRequest {
        if (model == null || model.isBlank()) {
            throw new IllegalArgumentException("model 不能为空");
        }
        if (messages == null || messages.isEmpty()) {
            throw new IllegalArgumentException("messages 不能为空");
        }
    }
}

public record Usage(int promptTokens, int completionTokens, int totalTokens) {
}

public record ChatResponse(
        String requestId,
        String provider,
        String model,
        String content,
        String finishReason,
        Usage usage,
        long costMillis) {
}

请求里没有放 top_p、presence_penalty 这些参数，原因是它们在不同厂商的默认值和支持度不一致，业务方乱传容易得到难以解释的结果。如果确实需要，建议单独开一个扩展参数 Map，并在客户端层做白名单过滤，而不是直接透传给上游。响应里加了 provider 和 costMillis，是为了后面排查“到底是哪家慢”时不用再去翻日志。

3.2 配置驱动的客户端注册

配置属性类负责把 YAML 映射成对象，并在启动时完成一次校验。

java复制@ConfigurationProperties(prefix = "model-gateway")
public class ModelGatewayProperties {

    private Duration connectTimeout = Duration.ofSeconds(5);
    private Duration responseTimeout = Duration.ofSeconds(60);
    private int maxConcurrency = 32;
    private Map<String, ProviderConfig> providers = new LinkedHashMap<>();

    public static class ProviderConfig {
        private String baseUrl;
        private String apiKey;
        private List<String> models = new ArrayList<>();
        // getter / setter 省略
    }
    // getter / setter 省略
}

路由组件在构造时建立“模型名到厂商”的反向索引，调用时 O(1) 命中。

java复制@Component
public class ModelRouter {

    private final Map<String, OpenAiCompatibleClient> clients = new HashMap<>();
    private final Map<String, String> modelToProvider = new HashMap<>();

    public ModelRouter(ModelGatewayProperties properties,
                       WebClient.Builder builder,
                       ObjectMapper objectMapper) {
        properties.getProviders().forEach((name, cfg) -> {
            if (cfg.getApiKey() == null || cfg.getApiKey().isBlank()) {
                throw new IllegalStateException("厂商 " + name + " 未配置 api-key");
            }
            if (cfg.getModels().isEmpty()) {
                throw new IllegalStateException("厂商 " + name + " 未配置模型清单");
            }
            clients.put(name, new OpenAiCompatibleClient(
                    name, cfg, builder, objectMapper,
                    properties.getConnectTimeout(), properties.getResponseTimeout()));
            cfg.getModels().forEach(m -> modelToProvider.put(m, name));
        });
    }

    public OpenAiCompatibleClient route(String model) {
        String provider = modelToProvider.get(model);
        if (provider == null) {
            throw new IllegalArgumentException("未注册的模型: " + model);
        }
        return clients.get(provider);
    }
}

这段代码的关键在于“启动期失败”。密钥没配、模型清单为空、模型名重复注册，都会在应用启动时抛异常。比起运行到一半才发现某个厂商调不通，启动即失败能让问题在发布流程里就暴露出来。不过要注意，如果团队希望某个厂商临时不可用时应用仍能启动，就要把这里改成记录告警并跳过该厂商，两种策略要提前约定。

3.3 哪些差异必须留扩展点

通用客户端覆盖大部分场景，但下面三类差异建议显式留出口子，不要试图用一套逻辑硬扛。

第一类是模型标识差异。豆包的接入点 ID、部分厂商的版本后缀，都不能靠简单拼接得到，应该在配置里原样声明。

第二类是请求字段差异。某些模型不支持 max_tokens 的某些取值，或者对 temperature 有范围限制。推荐在客户端里做一次参数规范化，超范围时截断并记录日志，而不是直接抛给上游返回一个含义模糊的 400。

第三类是错误结构差异。兼容实现大多返回 {"error": {"message": "..."}}，但也有返回 {"code": 401, "msg": "..."} 的情况。解析时应该优先取 error.message，取不到再回退到原始响应体，并截断长度写进日志。

java复制private String extractErrorMessage(String body, int status) {
    try {
        JsonNode root = objectMapper.readTree(body);
        JsonNode message = root.path("error").path("message");
        if (!message.isMissingNode() && !message.asText().isBlank()) {
            return message.asText();
        }
        JsonNode msg = root.path("msg");
        if (!msg.isMissingNode() && !msg.asText().isBlank()) {
            return msg.asText();
        }
    } catch (Exception ignored) {
        // 解析失败时退回原始文本
    }
    return "HTTP " + status + " " + (body == null ? "" : body.substring(0, Math.min(body.length(), 300)));
}

这里刻意保留了兜底分支，因为不同厂商在网关层、鉴权层、模型层返回的错误格式并不统一，有的错误甚至来自中间层而不是模型服务本身。

4. 流式输出、重试与限流：真正容易出问题的地方

非流式调用跑通只是开始，真正难的是流式输出。流式接口要同时处理三件事：上游分块返回、下游边收边发、中间任何一环超时都不能留下半截响应。再加上重试和并发控制，这部分代码写不好就会出现“前端一直在转圈”“内容重复输出”“偶发 502”这类很难复现的问题。

4.1 SSE 增量解析的写法

上游返回的是 text/event-stream，每个事件形如 data: {...}，最后以 data: [DONE] 结束。客户端要做的是逐块解析、提取增量文本、过滤空块。

java复制public Flux<String> stream(ChatRequest request, String traceId) {
    Map<String, Object> payload = buildPayload(request, true);
    return webClient.post()
            .uri("/chat/completions")
            .header(HttpHeaders.AUTHORIZATION, "Bearer " + config.getApiKey())
            .header("X-Trace-Id", traceId)
            .contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.TEXT_EVENT_STREAM)
            .bodyValue(payload)
            .retrieve()
            .bodyToFlux(String.class)
            .map(this::extractDelta)
            .filter(Objects::nonNull)
            .timeout(responseTimeout)
            .onErrorMap(this::wrapStreamError);
}

private String extractDelta(String raw) {
    String data = raw.startsWith("data:") ? raw.substring(5).trim() : raw.trim();
    if (data.isEmpty() || "[DONE]".equals(data)) {
        return null;
    }
    try {
        JsonNode root = objectMapper.readTree(data);
        JsonNode choices = root.path("choices");
        if (!choices.isArray() || choices.isEmpty()) {
            return null;
        }
        String content = choices.get(0).path("delta").path("content").asText(null);
        return (content == null || content.isEmpty()) ? null : content;
    } catch (Exception e) {
        log.warn("流式分块解析失败, traceId={}, raw={}", traceId, abbreviate(data));
        return null;
    }
}

关于 bodyToFlux(String.class) 的返回内容，不同 Spring 版本和不同 Content-Type 处理路径上可能拿到的是完整的 data: xxx 行，也可能已经剥离了 data: 前缀。上面这段代码对两种情况都做了兼容，startsWith("data:") 判断就是这个目的。如果线上发现内容缺字或被截断，第一步就要确认拿到的原始分块长什么样，而不是去改后面的解析逻辑。

下游转发时，Controller 直接把 Flux<String> 包成 SSE 事件返回。

java复制@PostMapping(value = "/v1/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> stream(@RequestBody ChatRequest request) {
    String traceId = UUID.randomUUID().toString();
    return gateway.stream(request, traceId)
            .map(chunk -> ServerSentEvent.builder(chunk).build())
            .concatWithValues(ServerSentEvent.builder("[DONE]").build());
}

produces 必须显式声明为 text/event-stream，否则浏览器和 Nginx 可能按普通文本处理，导致内容被缓冲到一起才返回，前端就看不到逐字效果。

4.2 错误分类和重试边界

不是所有错误都值得重试。把错误分成四类，重试策略才能写对。

java复制public ChatResponse chatWithRetry(ChatRequest request, String traceId) {
    return Mono.defer(() -> client.chat(request, traceId))
            .retryWhen(Retry.backoff(2, Duration.ofMillis(300))
                    .maxBackoff(Duration.ofSeconds(2))
                    .filter(this::isRetryable)
                    .doBeforeRetry(signal ->
                            log.warn("模型调用重试, traceId={}, attempt={}, error={}",
                                    traceId, signal.totalRetries() + 1,
                                    signal.failure().toString())))
            .timeout(responseTimeout)
            .block();
}

对流式场景，重试要谨慎。一旦已经开始向下游输出内容，就不应该再重试，否则会出现内容重复。常见做法是只在“尚未收到第一个分块”时允许重试，收到首块后转为快速失败，把错误通过 SSE 的错误事件传给前端。

4.3 并发控制和超时设置

并发控制不是可选项。模型接口的响应时间通常在秒级，上游一旦变慢，请求就会堆积，最终拖垮整个应用。用信号量做一次简单限流，比引入完整熔断组件更轻。

java复制private final Semaphore permits;

public ChatResponse chat(ChatRequest request, String traceId) {
    if (!permits.tryAcquire()) {
        throw new GatewayBusyException("网关繁忙，请稍后重试");
    }
    try {
        return doChat(request, traceId);
    } finally {
        permits.release();
    }
}

关键参数的含义和建议取值如下表。这里的数值只是起点，实际要根据上游的响应时间和业务能接受的失败率调整。

注意：超时时间要“大于上游的典型响应时间，小于业务方的等待上限”。如果业务侧网关的超时是 30 秒，接入层设成 60 秒就没有意义，因为请求在更早的一层已经被切断，日志里只会看到一堆没有结果的调用。

5. 运行验证：从健康检查到多模型对比

代码写完不等于接好了。模型接入层的验证要覆盖三个层次：应用能否正常启动、单个模型能否调通、多模型切换和流式输出是否符合预期。很多问题在第一步就会暴露，比如配置格式错误、密钥为空、模型名重复，这些都应该在启动阶段被拦住。

5.1 启动和配置校验

启动前先把密钥通过环境变量注入，不要在配置文件里明文写。

bash复制export DEEPSEEK_API_KEY="your-key"
export DASHSCOPE_API_KEY="your-key"
export ZHIPU_API_KEY="your-key"
export ARK_API_KEY="your-key"
export ARK_ENDPOINT_ID="your-endpoint-id"

mvn clean package -DskipTests
java -jar target/model-gateway.jar --server.port=8080

启动日志里应该能看到每个厂商注册的模型数量，例如“provider=deepseek, models=2”。如果没有这行日志，说明配置没被正确绑定，先检查 @EnableConfigurationProperties 是否加了，再检查 YAML 缩进。缩进错误在 YAML 里不会报错，只会静默少绑定几个字段，这是最常见的启动问题。

健康检查暴露一个只读接口，返回当前已注册的厂商和模型，不返回密钥。

java复制@GetMapping("/internal/models")
public Map<String, Object> models() {
    return router.describe();
}

返回内容大致如下，可以用来确认配置是否符合预期。

json复制{
  "deepseek": ["deepseek-chat", "deepseek-reasoner"],
  "qwen": ["qwen-plus", "qwen-max"],
  "glm": ["glm-4-plus", "glm-4-flash"],
  "doubao": ["ep-xxxxxxxx"]
}

5.2 用 curl 和单元测试验证单模型

先用 curl 打通非流式调用，把问题范围缩到最小。

bash复制curl -X POST http://localhost:8080/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "用一句话解释什么是幂等"}],
    "temperature": 0.3,
    "maxTokens": 200,
    "stream": false
  }'

预期返回包含 content、provider、usage 字段。如果 provider 为空，说明路由没命中，检查模型名是否和配置里完全一致，注意大小写和连字符。如果返回 401，先确认密钥是否有多余空格，环境变量在 shell 里被引号包裹时容易带上不可见字符。

流式调用换一个端点验证。

bash复制curl -N -X POST http://localhost:8080/v1/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "从 1 数到 10"}],
    "stream": true
  }'

-N 参数用于关闭 curl 自身的缓冲，不加这个参数可能看不到逐块输出，误以为是服务端没做流式。这一步很容易产生误判，建议把 -N 写进团队的接口调试文档。

5.3 多模型对比验证与结果落库

单模型通了之后，跑一轮多模型对比。对比不是为了评判谁更好，而是为了验证接入层在四个厂商之间切换时行为一致：同样的请求结构、同样的响应结构、同样的错误语义。

java复制@Test
void shouldReturnConsistentShapeAcrossProviders() {
    List<String> models = List.of("deepseek-chat", "qwen-plus", "glm-4-plus");
    for (String model : models) {
        ChatRequest request = new ChatRequest(model,
                List.of(new ChatMessage("user", "回复两个字：收到")),
                0.1, 50, false);
        ChatResponse response = gateway.chat(request, UUID.randomUUID().toString());
        assertNotNull(response.content(), model + " 返回内容为空");
        assertEquals(model, response.model(), model + " 模型标识不一致");
        assertNotNull(response.provider(), model + " 未记录厂商");
    }
}

批量验证时建议把结果落库，字段至少包括请求时间、厂商、模型、耗时、输入 token、输出 token、是否成功、错误类型。这张表后面会直接变成成本核算和容量规划的数据来源。不要在日志里打完整请求内容，涉及用户输入时要做脱敏或只保留摘要。

6. 排查链路：401、超时、流式中断分别怎么查

接入层的问题有一个共同特点：错误现象在下游，根因在上游。前端看到的是“一直在转圈”，实际可能是密钥失效；业务方看到的是“返回内容为空”，实际可能是流式分块解析把内容过滤掉了。排查要按固定顺序走，从输入到配置到网络到上游，不要一上来就怀疑代码逻辑。

6.1 鉴权失败与模型名错误

现象：接口返回 401 或 403，日志里可以看到上游返回的错误信息。

可能原因：密钥未注入、密钥带了空格或换行、用了别家厂商的密钥、密钥权限不足、模型未开通。

检查方式：先确认环境变量是否真的进了进程，用 env | grep API_KEY 检查；再打印密钥的前 4 位和后 4 位确认没有明显错位，不要打印完整密钥；最后用 curl 直连上游接口，绕过接入层验证密钥本身是否可用。

处理建议：密钥统一由配置中心或密钥管理服务下发，接入层只读不写；启动时做一次非空校验；错误日志里记录厂商名和密钥指纹，方便快速判断是不是配错了行。

现象：返回 400 或 404，错误信息包含 model not found 之类的内容。

可能原因：模型名拼写不一致、使用了控制台未开通的模型、豆包填了通用模型名而不是推理接入点 ID。

检查方式：把请求里的 model 字段和控制台里的模型列表逐字比对；确认豆包用的是 ep- 开头的接入点 ID；确认模型在对应区域已开通。

6.2 流式响应不完整

现象：前端只收到开头几个字就停了，或者内容重复出现。

可能原因：中间层做了响应缓冲、超时时间太短、重试逻辑在已经输出内容后又重新发起请求、分块解析把包含多个 delta 的块只取了一个。

检查方式：先用 curl 加 -N 直连接入层，确认接入层本身是否流式；再直连上游，确认上游是否流式；如果接入层不流而直连上游流，问题就在转发环节，检查 produces 是否声明了 text/event-stream，检查前置代理是否开启了缓冲。

处理建议：前置代理对流式接口要关闭缓冲；接入层的 response-timeout 要留足；重试只在收到首个分块前生效；解析时遍历 choices 数组而不是只取第 0 个元素，虽然当前大多只返回一个，但写死下标是脆弱实现。

text复制现象：前端逐字输出到一半停止，Network 面板显示请求仍在 pending
检查：curl -N 直连接入层 -> 若同样停止，再 curl -N 直连上游
结论：接入层转发正常、上游正常，问题在前置代理缓冲
处理：对 /v1/chat/stream 路径关闭代理缓冲，并延长读超时

6.3 用量统计对不上

现象：账单金额和自建统计差距较大，或者流式调用的 token 数一直是 0。

可能原因：流式响应默认不返回 usage、统计逻辑只覆盖了非流式分支、重试导致的重复调用没有去重、部分厂商的 token 计算方式不同。

检查方式：抓一次非流式响应，确认 usage 字段存在且有值；抓一次流式响应，看最后一个分块是否带 usage；检查统计代码是否只在成功分支累加，失败重试的消耗是否也被计入。

处理建议：流式调用显式传 stream_options 请求用量（是否支持以官方文档为准）；统计逻辑放在客户端层而不是业务层，保证所有调用路径都经过；重试次数单独计数，便于区分“业务量”和“实际请求量”。

7. 上线前的清单和后续扩展

从“本地能调通”到“生产敢用”，中间还差一段工程化的工作。这部分不涉及复杂算法，但决定了接入层能不能长期维护。很多团队在模型数量增加到五六家之后开始返工，原因基本都是前期没有把成本核算、配额管理和灰度切换设计进去。

7.1 发布前检查清单

下面这份清单可以直接拿去用，逐项确认后再上线。

• 密钥是否全部通过环境变量或密钥管理服务注入，仓库里是否有明文残留。
• 每个厂商的模型清单是否在启动时完成校验，空密钥和空清单是否会导致启动失败。
• connect-timeout 和 response-timeout 是否小于上游业务网关的超时。
• 流式接口的 produces 是否声明为 text/event-stream，前置代理是否关闭缓冲。
• 重试是否只覆盖可重试错误，是否在已输出内容后停止重试。
• 并发上限是否根据上游配额设置，是否有排队或快速失败的兜底策略。
• 日志是否记录 traceId、厂商、模型、耗时、错误类型，是否避免打印完整密钥和用户原文。
• 用量统计是否覆盖流式和非流式两条路径，失败调用是否单独计数。
• 是否有一个可以随时关闭某个厂商的开关，出问题时能快速摘除。
• 是否有针对模型接口的监控告警，错误率和延迟阈值是否明确。

7.2 成本与配额管理的落地方式

接入多家模型之后，成本会变成一个必须管理的指标。常见做法是按“厂商 + 模型 + 业务方”三个维度累计 token 数，再乘以各自的单价得到估算成本。单价会调整，所以不要把单价写死在代码里，放进配置表，定期核对。

配额管理要区分两种场景。一种是团队内部共享额度，需要防止某个业务方把额度用光，做法是给每个调用方分配配额，超限时返回明确的错误码而不是静默失败。另一种是单次请求的 token 上限，防止超长输入导致费用失控，做法是在接入层对 maxTokens 设一个硬上限，业务方传超了自动截断并记录日志。

java复制private int normalizeMaxTokens(Integer requested, int hardLimit) {
    if (requested == null || requested <= 0) {
        return Math.min(1024, hardLimit);
    }
    if (requested > hardLimit) {
        log.warn("maxTokens 超限，已截断, requested={}, limit={}", requested, hardLimit);
        return hardLimit;
    }
    return requested;
}

这种“截断并告警”的策略比直接拒绝更友好，但要把告警接入监控，否则截断会变成静默行为，业务方永远不知道自己传的参数没生效。

7.3 下一步可以扩展的方向

接入层稳定之后，有几个方向值得继续投入。第一个是灰度切换：同一逻辑模型配置多个候选厂商，按比例分流，出问题时快速调整权重。第二个是结果评测：固定一批测试问题，定期跑一遍各模型的输出，记录质量和延迟变化，为选型提供依据。第三个是缓存：对相同的问题和参数做短时缓存，减少重复调用，但要注意缓存键必须包含模型名和温度等参数，否则会返回错误结果。

第四个方向是把接入层和业务解耦得更彻底。现在业务方要指定具体模型名，未来可以改成指定“能力等级”，比如“快速响应”“高质量推理”，由接入层根据配置决定实际调用哪家。这样做的好处是切换模型不需要改业务代码，坏处是排查问题时多了一层映射，需要日志里同时记录逻辑模型和实际模型。

注意：扩展方向要按实际需求排优先级。没有评测数据之前不要做自动路由，没有真实的成本压力之前不要做复杂配额，先把基础的可观测性和错误处理做扎实，收益更大。

最后给一个练习建议：拿本文的最小实现，先只接一家模型跑通，再按配置表加第二家，观察哪些代码需要改动。如果加第二家时改了业务代码，说明抽象漏了；如果只改了 YAML，说明分层是合理的。这个练习比读十篇文章更能帮助理解接入层该怎么设计。