跳到主要内容

检索观测数据记录(通道级观测)

上一篇我们看到，FinalTopK 裁剪完成后会触发两个观测记录方法。这一篇我们先来看第一个：recordChannelObservations——它负责记录通道级的执行观测数据。

简单来说，这个方法回答的问题是：每个检索通道表现怎么样？召回了多少？最终留下了多少？分数分布如何？

recordChannelObservations 完整实现​

/**
 * 记录通道级检索观测数据。
 *
 * <p>该方法把每个通道的原始召回数、闸门后采纳数、最终选择数以及分数统计写入 trace，
 * 用来回答"哪个通道召回了多少，为什么后面剩这么少"。</p>
 */
private void recordChannelObservations(ConversationTraceRecorder traceRecorder,
                                       int subQuestionIndex,
                                       String subQuestion,
                                       List<RetrievalChannelResult> rawResults,
                                       List<RetrievalChannelResult> filteredResults,
                                       List<SubQuestionChannelTrace> channelTraces) {
    // 没有原始通道结果时，说明没有可记录的通道执行。
    if (rawResults == null || rawResults.isEmpty()) {
        return;
    }

    // 收集每个通道对应的一条 ChannelExecutionView，最后批量写入 traceRecorder。
    List<ChannelExecutionView> executions = new ArrayList<>();
    for (RetrievalChannelResult rawResult : rawResults) {
        // 通道名用于后续关联过滤结果和通道 trace。
        String channelName = rawResult.getChannelName();
        // recalledCount 是通道原始返回数量，代表召回阶段的广度。
        int recalledCount = rawResult.getDocuments() == null ? 0 : rawResult.getDocuments().size();

        // 在过滤后的结果中找到同名通道，用于计算证据闸门后的采纳数量。
        RetrievalChannelResult filteredResult = filteredResults == null ? null :
            filteredResults.stream().filter(r -> channelName.equals(r.getChannelName())).findFirst().orElse(null);
        int acceptedCount = filteredResult == null || filteredResult.getDocuments() == null ? 0 : filteredResult.getDocuments().size();

        // channelTraces 里也保存了召回/采纳关系，这里用于补 finalSelectedCount 字段。
        SubQuestionChannelTrace trace = channelTraces == null ? null :
            channelTraces.stream().filter(t -> channelName.equals(t.getChannelName())).findFirst().orElse(null);
        // 当前实现里 finalSelectedCount 与闸门后 acceptedCount 对齐，表示通过当前通道过滤的数量。
        int finalSelectedCount = trace == null ? 0 : trace.getAcceptedCount();

        // 组装通道执行观测对象，关联当前 trace、子问题和通道类型。
        ChannelExecutionView execution = new ChannelExecutionView();
        execution.setId(traceRecorder.exchangeId());
        execution.setTraceId(traceRecorder.traceId());
        execution.setSubQuestionIndex(subQuestionIndex);
        execution.setSubQuestion(subQuestion);
        execution.setChannelType(channelName);
        // executionState=1 表示本通道执行完成；失败通道在 exceptionally 中会变成空结果。
        execution.setExecutionState(1);
        execution.setRecalledCount(recalledCount);
        execution.setAcceptedCount(acceptedCount);
        execution.setFinalSelectedCount(finalSelectedCount);

        // 如果通道原始结果有分数，计算平均分、最高分、最低分，便于观察召回质量。
        if (rawResult.getDocuments() != null && !rawResult.getDocuments().isEmpty()) {
            List<Double> scores = rawResult.getDocuments().stream()
                .map(doc -> {
                    // 分数来自统一 metadata key；没有分数时按 0 处理，后面会过滤掉。
                    Object scoreObj = doc.getMetadata().get(DocumentKnowledgeMetadataKeys.SCORE);
                    if (scoreObj instanceof Number) {
                        return ((Number) scoreObj).doubleValue();
                    }
                    return 0.0;
                })
                // 只统计正分数，避免空分数或默认 0 拉低统计值。
                .filter(score -> score > 0)
                .toList();

            // 有有效分数时才写入 BigDecimal 统计，避免空集合导致误导性 0 值。
            if (!scores.isEmpty()) {
                execution.setAvgScore(BigDecimal.valueOf(scores.stream().mapToDouble(Double::doubleValue).average().orElse(0)));
                execution.setMaxScore(BigDecimal.valueOf(scores.stream().mapToDouble(Double::doubleValue).max().orElse(0)));
                execution.setMinScore(BigDecimal.valueOf(scores.stream().mapToDouble(Double::doubleValue).min().orElse(0)));
            }
        }

        // 当前通道观测对象组装完成，加入批量写入列表。
        executions.add(execution);
    }

    // 批量写入通道执行观测，持久化细节由 traceRecorder 封装。
    traceRecorder.recordChannelExecutions(executions);
}

逐段拆解​

这个方法虽然代码量不小，但逻辑结构很清晰。我们按执行顺序来拆解。

付费内容提示

该文档的全部内容仅对「JavaUp项目实战&技术讲解」知识星球用户开放

加入星球后，你可以获得：

  • 超级八股文：100万+字的全栈技术知识库，涵盖技术核心、数据库、中间件、分布式等深度剖析的讲解
  • 讲解文档：超级AI智能体、黑马点评Plus、大麦、大麦pro、大麦AI、流量切换、数据中台的从0到1的详细文档
  • 讲解视频：超级AI智能体、黑马点评Plus、大麦、大麦pro、大麦AI、流量切换、数据中台的核心业务详细讲解
  • 1 对 1 解答：可以对我进行1对1的问题提问，而不仅仅只限于项目
  • 针对性服务：有没理解的地方，文档或者视频还没有讲到可以提出，本人会补充
  • 面试与简历指导：提供面试回答技巧，项目怎样写才能在简历中具有独特的亮点
  • 中间件环境：对于项目中需要使用的中间件，可直接替换成我提供的云环境
  • 面试后复盘：小伙伴去面试后，如果哪里被面试官问住了，可以再找我解答
  • 远程的解决：如果在启动项目遇到问题，本人可以帮你远程解决
进入星球后，即可享受上述所有服务，保证不会再有其他隐藏费用。
知识星球二维码

1. 打开微信 -> 扫描左侧二维码 -> 加入「JavaUp项目实战&技术讲解」知识星球

2. 查看星球使用指导，获取完整项目讲解资料索引

👉 点击解锁全部付费内容
🎁优惠