检索观测数据记录(通道级观测)
上一篇我们看到，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);
}
逐段拆解
这个方法虽然代码量不小，但逻辑结构很清晰。我们按执行顺序来拆解。
付费内容提示
该文档的全部内容仅对「码力全开」项目实战&技术讲解 知识星球用户开放
加入星球，一次获得完整项目资料、全栈技术知识库和长期答疑服务。
100万+字全栈技术知识库深入讲解技术核心、数据库、中间件和分布式等内容
8套热门的实战项目持续更新的企业级项目覆盖高并发、微服务、数据中台 和 AI Agent 等方向
AI 技术知识大模型面试详解覆盖 AI 模型原理、Agent、RAG、MCP、Skills、Harness 等核心知识点
文档 + 视频两种讲解形式既能系统阅读，也能跟随视频理解核心业务
完整项目实战资料
每套项目均包含从 0 到 1 讲解文档核心业务讲解视频从基础项目到复杂业务场景，项目资料会持续更新。
- 01Nexus Agent AI 智能体
- 02Nexus Agent Pro 完全版
- 03黑马点评Plus
- 04大麦
- 05大麦Pro
- 06大麦AI
- 07流量切换
- 08数据中台
加入后还能获得
进入星球后，即可享受上述所有服务，保证不会再有其他隐藏费用。从学习、面试到项目启动，都可以继续获得支持。
- 1 对 1 解答项目和技术问题都可以提问
- 针对性补充没有讲清楚的内容会继续补充
- 面试与简历指导梳理回答技巧和项目亮点
- 中间件云环境项目依赖可以直接接入使用
- 面试后复盘被问住的问题可以继续交流
- 远程问题解决项目启动问题可协助排查
