zhuyongxin
99d4f6f216
Document the lookup_knowledge flow from L0 hints through L1 retrieval, post-processing, packing, and Agent projection so the boundaries and current limitations are easier to follow.
57 lines
2.2 KiB
Java
57 lines
2.2 KiB
Java
package com.superbiz.agent.service;
|
||
|
||
import com.superbiz.agent.dto.KnowledgeQuery;
|
||
import org.springframework.stereotype.Service;
|
||
|
||
import java.util.List;
|
||
|
||
/**
|
||
* 检索前的 query 理解层（L0 出口）。
|
||
*
|
||
* <p>输入是 Agent 的原始检索句，输出 {@link KnowledgeQuery}，供后续 L1 过滤与 rerank 使用。</p>
|
||
*
|
||
* <h3>当前能力边界</h3>
|
||
* <ul>
|
||
* <li>会做：关键词匹配、domain/entity/title hint、唯一 domain 时生成 categoryFilter</li>
|
||
* <li>不会做：真正的 query rewrite / 同义词扩展 / 多 query 改写
|
||
* （{@code rewrittenQuery} 目前等于 {@code originalQuery}）</li>
|
||
* <li>L0 命中文档正文不会直接当作 evidence；证据只来自 L1 向量召回</li>
|
||
* </ul>
|
||
*/
|
||
@Service
|
||
public class KnowledgeQueryTransformer {
|
||
|
||
private final KnowledgeIndexService knowledgeIndexService;
|
||
|
||
public KnowledgeQueryTransformer(KnowledgeIndexService knowledgeIndexService) {
|
||
this.knowledgeIndexService = knowledgeIndexService;
|
||
}
|
||
|
||
/**
|
||
* 将原始 query 转为检索控制结构。
|
||
*
|
||
* <p>{@code categoryFilter} 仅在 L0 恰好命中一个 domain 时非空；
|
||
* 多 domain 或零 domain 时为 null，避免错误收窄召回。</p>
|
||
*/
|
||
public KnowledgeQuery transform(String rawQuery) {
|
||
String normalized = rawQuery == null ? "" : rawQuery.trim();
|
||
KnowledgeIndexService.L0Hint hint = knowledgeIndexService.analyzeQuery(normalized);
|
||
return KnowledgeQuery.builder()
|
||
.originalQuery(normalized)
|
||
// 预留改写字段；当前未实现 rewrite，保持与 original 一致
|
||
.rewrittenQuery(normalized)
|
||
.domainHints(safeList(hint.domains()))
|
||
.matchedKeywords(safeList(hint.matchedKeywords()))
|
||
.entities(safeList(hint.entities()))
|
||
// 只有唯一 domain 才作为向量 metadata 的 category 过滤条件
|
||
.categoryFilter(hint.singleDomainOrNull())
|
||
.l0Titles(safeList(hint.titles()))
|
||
.l0MatchCount(hint.matches() == null ? 0 : hint.matches().size())
|
||
.build();
|
||
}
|
||
|
||
private List<String> safeList(List<String> values) {
|
||
return values == null ? List.of() : values;
|
||
}
|
||
}
|