项目：CodeQ 代码大模型训练语料质量评估平台

开发模块：OpenAI 兼容接口的 LLM 服务实现、DashScope 重试机制、QualityController 自动 DB 读取评估模式

当前进度：OpenAIServiceImpl 实现 3 次指数退避重试、QualityController 支持手动 / 自动双模式评估、Prompt 构建规范化，AI 评估链路完整打通。

---

一、任务与目标

平台的核心价值在于"代码质量自动评估"——ETL 采集的指标数据需要经过大模型的自然语言理解，生成结构化评分与报告。本次任务是实现一个生产可用的 LLM 调用层：对接 DashScope 通义千问 API（OpenAI 兼容协议），内置请求重试机制应对瞬态异常，并在 QualityController 中实现从数据库自动读取指标数据的评估模式，使整个流程从"手动传参"升级为"自动查库→调 AI→返回结果"。

---

二、OpenAI 兼容接口实现

DashScope 提供 OpenAI 兼容的 chat completions 端点，因此使用 Java 11 内置的 java.net.http.HttpClient 即可完成调用，无需引入额外 SDK：

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(apiUrl))
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer " + apiKey)
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

请求体结构遵循 OpenAI Chat Completions 规范：

{
  "model": "qwen-plus",
  "messages": [
    {"role": "system", "content": "你是一个代码质量评估专家，只返回 JSON 格式的结果。"},
    {"role": "user", "content": "<prompt>"}
  ],
  "temperature": 0.3
}

temperature=0.3 保证输出稳定性，适合质量评估这种需要一致性的场景。

---

三、重试机制设计

大模型 API 在高并发或网络抖动时可能出现瞬态错误，直接抛异常会中断整个评估流程。本次实现指数退避重试：

private static final int MAX_RETRIES = 3;
private static final long BASE_DELAY_MS = 1000;

for (int attempt = 1; attempt <= MAX_RETRIES; attempt++) {
    try {
        // 调用 API...
        return parseResult(response.body());
    } catch (Exception e) {
        lastException = e;
        if (attempt < MAX_RETRIES) {
            long delay = BASE_DELAY_MS * (1L << (attempt - 1)); // 1s, 2s, 4s
            Thread.sleep(delay);
        }
    }
}
throw new RuntimeException("LLM evaluation failed after " + MAX_RETRIES + " retries", lastException);

重试策略：第 1 次失败等 1s，第 2 次等 2s，第 3 次等 4s，总计最多等待 7s 后彻底失败。比简单粗暴的固定间隔重试更合理，给上游服务充分的恢复时间。

---

四、QualityController 双模式评估

升级原有接口，支持两种调用方式：

手动模式 （前端传参）：

POST /api/quality/evaluate
{
  "repository": "alibaba/arthas",
  "info": "代码行数: 10000\n注释密度: 15%..."
}

自动模式 （从数据库读指标）：

POST /api/quality/evaluate
{
  "repository": "arthas",
  "taskId": "54"
}

自动模式的核心逻辑在 buildRepoInfoFromDb 方法中：

1. 根据 taskId 从 metric_result 表查询汇总指标
2. 从 file_metric 表读取文件级详情（按圈复杂度排序取 Top 5）
3. 组装为结构化 prompt 文本，包含代码规模、质量指标、高复杂度文件列表
4. 如果数据不存在，返回明确的错误提示而非空字符串

---

五、EvaluationResult 响应结构

LLM 返回的 JSON 通过 Jackson 反序列化为统一结构：

---

六、技术理解

本次开发让我深入理解了 LLM 集成的工程化要点：prompt 工程（构造结构化评估指令）、容错设计（指数退避重试）、数据流编排（DB → prompt → API → 结构化结果）。大模型不是"调一次就行"的玩具接口，在生产环境中必须考虑超时、限流、格式异常、网络抖动等边界情况。

---

七、当前项目进度

- OpenAIServiceImpl 完整实现，支持 DashScope OpenAI 兼容接口
- 3 次指数退避重试（1s / 2s / 4s）
- QualityController 支持手动传参 / 自动查库双模式
- Prompt 构建规范化，system + user 角色分离
- AI 评估返回结构化评分，前端可直接渲染
下一篇将实现 ETL 自动化调度与质量报告持久化，打通"提交分析 → ETL 执行 → AI 评估 → 报告入库"全链路。