AI 后端架构设计与大模型服务集成实践：别让演示效果骗了你

本地开发如果每次都调用远程模型，测试结果会跟着网络、服务负载和模型输出波动：同一个用例可能因为响应慢、额度消耗或一段不完整 JSON 而失败。把已审查的响应录下来，按契约回放，能让大部分接口测试稳定下来；真实模型调用则留给少量集成验证。

---

1. 大模型服务集成的非确定性挑战与环境隔离

传统后端单元测试依赖稳定的输入输出，而模型服务会受网络、配额、版本和采样参数影响。下面的延迟和异常只是演练参数，用来检查超时、连接池和降级逻辑；它们不能替代真实环境的观测数据。

大模型接入层在本地开发阶段面临三重约束：
第一，测试成本与配额消耗。频繁运行包含大模型调用的全量测试套件会快速耗尽 API 配额，拉高研发测试成本。
第二，自动化断言失效。大模型生成的文本包含随机采样属性，即使设置固定的随机种子，不同版本的模型依然可能改变字段命名或语法结构，导致基于正则或 JSON 路径提取的测试断言无法稳定通过。
第三，流式响应（SSE）调试困难。服务端发送事件（Server-Sent Events）在本地传输过程中，网卡分包与 Chunk 边界切片行为难以手动模拟，增加了针对推流逻辑的排障难度。

为此，引入本地 Mock 代理服务作为契约中介，通过定义稳定的契约数据结构，实现上游依赖的物理隔离。

---

2. 流量录制与确定性回放架构设计

在本地开发脚手架的设计中，系统架构被划分为业务服务层、代理拦截层与本地契约存储库。客户端请求不再直连外部服务，而是由本地代理进行统一分发。

flowchart TD
    A[Spring Boot 业务服务] -->|1. 发送 Prompt 与参数| B{本地代理拦截器}
    B -->|2a. RECORD 模式| C[远程大模型服务 / 本地 vLLM]
    C -->|3. 返回 Raw Stream 或 JSON| B
    B -->|4. 计算 Payload Hash 并写入| D[(本地 JSON 契约库)]
    B -->|2b. REPLAY 模式| D
    D -->|5. 加载确定性 Payload 与配置| B
    B -->|6. 注入网络延迟与异常状态码| A

当代理运行于录制（RECORD）模式时，拦截器将业务请求透传至真实大模型服务，同时捕捉请求体中的 Prompt 模版、Temperature 参数以及返回的完整 Chunk 流，以请求签名 Hash 为文件名持久化至本地 JSON 文件。

当切换至回放（REPLAY）模式时，代理拦截器通过请求哈希定位本地契约，跳过实际网络请求，直接返回预置的响应报文，并支持按配置注入高延迟或格式损坏的数据流，以校验系统的抗脆弱性。

---

3. 本地调试与排障诊断命令

在本地脚手架的部署与运行过程中，开发人员需要快速验证代理拦截状态与流式响应 Chunk 的切片行为。以下命令常用于本地环境的排障诊断：

使用 curl 模拟客户端验证 SSE 流式回放

# 验证本地 8080 端口代理在 REPLAY 模式下的 SSE 流式推流与切片时延
curl -i -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Mock-Mode: REPLAY" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "ping"}],
    "stream": true
  }'

使用 tcpdump 抓取环回网卡报文

# 抓取本地环回网卡 8080 端口的数据包，排查 HTTP 请求头中的跨域与流式传输标记
sudo tcpdump -i lo0 -X -s 0 'tcp port 8080' -w llm_stub_debug.pcap

清理与重置本地过期契约文件

# 清理超过 7 天未变更的本地 Mock 契约缓存，确保测试用例对应最新契约
find ./src/test/resources/contracts -name "*.json" -mtime +7 -exec rm -f {} \;

---

4. 代理脚手架核心代码实现

基于 Spring WebClient 与 Reactor 框架，实现具备请求哈希计算、契约文件匹配以及确定性延迟注入的代理过滤器组件：

package com.example.llm.stub;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.core.io.Resource;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.client.ClientRequest;
import org.springframework.web.reactive.function.client.ClientResponse;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.ExchangeFunction;
import reactor.core.publisher.Mono;

import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.HexFormat;

@Component
public class LlmContractStubFilter implements ExchangeFilterFunction {

    private final ObjectMapper mapper = new ObjectMapper();
    private final String contractDir = "classpath:contracts/";

    @Override
    public Mono<ClientResponse> filter(ClientRequest request, ExchangeFunction next) {
        String mockMode = request.headers().getFirst("X-Mock-Mode");
        if ("REPLAY".equalsIgnoreCase(mockMode)) {
            return handleReplay(request);
        }
        return next.exchange(request);
    }

    private Mono<ClientResponse> handleReplay(ClientRequest request) {
        try {
            String requestDigest = computeHash(request.url().toString());
            String fileName = "contract_" + requestDigest + ".json";
            PathMatchingResourcePatternResolver resolver = new PathMatchingResourcePatternResolver();
            Resource resource = resolver.getResource(contractDir + fileName);

            if (!resource.exists()) {
                return Mono.just(ClientResponse.create(HttpStatus.NOT_FOUND)
                        .header("Content-Type", MediaType.APPLICATION_JSON_VALUE)
                        .body("{\"error\": \"Contract snapshot not found\"}")
                        .build());
            }

            try (InputStream is = resource.getInputStream()) {
                JsonNode root = mapper.readTree(is);
                long delayMs = root.has("injected_delay_ms") ? root.get("injected_delay_ms").asLong() : 0L;
                String responseBody = root.get("response_body").toString();

                return Mono.just(ClientResponse.create(HttpStatus.OK)
                        .header("Content-Type", MediaType.APPLICATION_JSON_VALUE)
                        .body(responseBody)
                        .build())
                        .delayElement(Duration.ofMillis(delayMs));
            }
        } catch (Exception e) {
            return Mono.error(e);
        }
    }

    private String computeHash(String input) throws Exception {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
        return HexFormat.of().formatHex(hash).substring(0, 16);
    }
}

上述过滤器在检测到标头 X-Mock-Mode: REPLAY 后，拦截远程 HTTP 转发逻辑，基于请求 URL 计算 16 位十六进制 SHA-256 签名，再读取本地 classpath:contracts/ 中的 JSON 契约并注入可调时延。它把外部依赖的波动隔离在契约层外，便于前端和单元测试稳定验证。录制内容仍应脱敏，并在模型或提示词变化后重新审查。

---

5. 设计方案的权衡分析（Trade-offs）

在实施大模型本地开发脚手架的过程中，架构设计必须在测试真实性与环境稳定性之间做出权衡：

第一，契约覆盖率与维护成本的权衡。高精度的录制能够完全还原特定时刻的 LLM 输出，但大模型版本的迭代容易导致录制的数据快照过时。过分追求全量录制会增加本地契约文件的管理难度；建议仅对核心业务链路的代表性场景进行录制，非核心场景使用泛化 Schema 生成 Mock 格式。

第二，模拟延迟与测试执行效率的权衡。为了模拟真实网络环境下的尾部延迟，脚手架支持注入延时。但在持续集成（CI）流水线中，过高的延时会导致构建任务排队阻塞。因此，CI 环境下应强制覆盖延时参数为 0，仅在本地容错演练时开启延迟注入。

第三，静态 Mock 与动态推理的权衡。静态 JSON 无法模拟多轮对话中上下文累加的动态变更。若需要测试长上下文管理逻辑，需辅以轻量级的本地小模型（如 Ollama / vLLM）作为二级备选节点，形成“静态契约快照 + 本地轻量推理”的双轨验证机制。

---

6. 演练证据链与排障审查要点

在自动化测试流程中，若发现回放断言异常，可循着以下证据链进行排查定位：

1. 报文签名比对：确认测试用例发送的 Prompt 文本中是否包含动态生成的随机数或时间戳，导致生成的 SHA-256 哈希值无法命中预设的契约文件。
2. 延迟注入阈值检查：审查请求响应时间是否超出了 Spring WebClient 配置的连接超时时间限制，确保测试容器中的超时设定高于 Mock 注入的延时。
3. SSE 数据帧完备性：检查录制的 JSON 文件中针对 data: [DONE] 终止符的序列化是否符合 SSE 规范，避免客户端解析流式结尾时陷入无限等待。

回放机制适合验证协议、异常处理和界面状态；模型效果、长上下文和安全策略仍需要少量真实集成测试补位。