agent-memory 检索层(Retrieval Layer)API 与 PipelineRetriever 实战指南
agent-memory 检索层(Retrieval Layer)API 与 PipelineRetriever 实战指南
导读
本文以 openJiuwen agent-memory 仓库的 Retrieval Layer API 参考文档 为主体,完整讲解记忆检索层的五大可插拔算子(QueryParser、Recaller、Fuser、Discloser、Retriever)的接口契约、数据契约与配置化装配方式,并深入 PipelineRetriever 的真实编排链路与容错边界。读完本文,你将掌握:如何通过 Retriever.retrieve() 一条 API 完成从查询理解到渐进式披露的完整检索;如何用两级 YAML 命名空间配置替换/调参各算子(RRF/加权 RRF/CombMAX 融合、分层 L0/L1/L2 召回、ADAPTIVE 披露、multimodal 分支检索);以及 RetrievalResult 中 items/trajectory/errors 三通道返回与部分失败降级的正确用法。
1. 检索层全景:五类可插拔算子
检索层把"一次记忆检索"拆成五个职责单一、可插拔的算子类型(见 base.py):
| 算子 | 职责 | 对应接口文件 |
|---|---|---|
QueryParser |
把外部查询解析为结构化表示(改写/分词/实体/向量化/时间解析) | query_parser.py |
Recaller |
在单个逻辑通道内召回候选(已移入存储层数据面) | recaller.py |
Fuser |
合并并排序多路召回来源的候选 | fuser.py |
Discloser |
把排序后的记忆塑形成 L0/L1/L2 三级内容 | discloser.py |
Retriever |
面向调用方的统一检索入口,编排整条链路 | retriever.py |
所有算子都继承 RetrievalOperator(base.py),实现两个自描述方法:
| API | 返回值 | 说明 |
|---|---|---|
operator_type() |
RetrievalOperatorType |
返回算子类型 |
health() |
None |
健康时返回 None,异常时抛出 |
需要特别说明的是,RetrievalOperatorType 枚举(base.py)只包含 QUERY_PARSER、FUSER、DISCLOSER、RETRIEVER 四项,不含 RECALLER——单路召回是数据面(CompositeDomainStore)的内部件,由存储层工厂装配持有,不进检索算子表(详见 §5)。
从 base.py 的模块注释可以清晰看到整个链路的五步骨架:① scope/标签前置过滤 → ② 并行多路召回 → ③ 融合+重排 → ④ 渐进式披露 → ⑤ 返回结果与检索轨迹。
2. 统一入口:Retriever.retrieve()
应用代码只依赖一个入口,scope 与 query 永远分开传:
from jiuwen_memory.common.type_def import Scope
from jiuwen_memory.retrieval.retriever import Retriever
from jiuwen_memory.retrieval.types import RetrievalQuery, RetrievalResult
result: RetrievalResult = retriever.retrieve(
scope,
RetrievalQuery(text="Which database did the user mention earlier?", top_k=5),
)
scope是显式隔离轴,指明"在谁的范围内找";RetrievalQuery指明"找什么";- 两条轴分开传参,Scope 维度绝不允许被塞进
filters里(见 retriever.py 契约与 types.py 中对"scope 是找什么、query 是找什么,两轴分开传"的注释)。这个设计贯穿到数据面:Recaller 组装底层查询时把 scope 落到查询的专用 scope 字段做原生隔离,query.scalar_filters只做元数据硬过滤(见 recaller.py)。
RetrievalQuery 请求类型
@dataclass
class RetrievalQuery:
text: str = ""
filters: FilterExpr | None = None
as_of: datetime | None = None
top_k: int = 10
disclosure: DisclosureLevel = DisclosureLevel.L0
max_tokens: int | None = None
with_trajectory: bool = False
channels: list[RecallChannel] | None = None
rerank: bool | None = None
include_archived: bool = False
extensions: dict[str, Any] = field(default_factory=dict)
| 字段 | 说明 |
|---|---|
text |
原始自然语言查询 |
filters |
Scope 维度之外的硬性用户元数据谓词;对象创建时统一规范化为 FilterExpr |
as_of |
历史查询的有效时间点(valid-time);None 表示当前状态 |
top_k |
最终结果最大条数,必须大于 0 |
disclosure |
主披露层级:L0 / L1 / L2 / ADAPTIVE |
max_tokens |
自适应披露的 token 预算;若提供必须大于 0 |
with_trajectory |
是否在结果中包含检索轨迹 |
channels |
本次调用的召回通道覆盖;None 使用 parser 建议;空列表非法 |
rerank |
本次调用的重排开关覆盖;None 使用装配默认 |
include_archived |
当前态查询是否把已归档记忆纳入候选 |
extensions |
自定义透传选项,进入 ParsedQuery.extensions,内核不解释其键 |
一个易混点:as_of 问的是"系统在某个 valid-time 点能看到什么",而 ParsedQuery.time_from/time_to 描述的是"内容里的事件发生的时间范围(event-time)"——这是两条独立的时间轴,会在 §5 的 build_system_filters 中分别处理。
3. 查询理解:QueryParser
from jiuwen_memory.retrieval.query_parser import QueryParser
parsed = parser.parse(query)
parse(query: RetrievalQuery) -> ParsedQuery 把外部请求转成各召回通道可直接消费的结构化查询。实现可以执行:sanitization、改写、分词、关键词/实体抽取、向量化、时间解析。
ParsedQuery 主要字段(完整契约见 types.py 与 common/type_def/retrieval.py):
| 字段 | 含义 |
|---|---|
raw |
进入检索管道的规范化查询 |
rewritten |
改写后的查询 |
intent |
识别出的意图 |
tokens / keywords |
分词结果与关键词 |
entities |
供图召回等通道消费的实体 |
vector |
查询向量 |
scalar_filters |
下推到存储的硬谓词 |
recheck_filters |
用于真源复核的用户谓词 |
as_of |
valid-time 回溯点 |
time_from / time_to |
event-time 时间窗 |
channels |
parser 推荐的逻辑召回通道 |
include_archived |
是否纳入归档记忆 |
extensions |
自定义透传选项 |
关键约束:查询侧的 Tokenizer、Embedder、FeatureExtractor 必须与索引构建侧使用同一实例或兼容配置,否则词表、向量空间或特征语义会分叉——这是 simple_query_parser.py 装配时显式从同一 Producer 命名空间取实例的原因。
4. 多路召回:Recaller(数据面内部件)
Recaller 已不再是检索层算子,而是 CompositeDomainStore 的内部组件——生产链路里它的唯一消费方是数据面,Retriever 只按首选路径委托 recall / recall_and_get / retrieve,本身不持有任何召回路:
from jiuwen_memory.storage.domain_store_impl.recaller import Recaller
一个 Recaller 对应一条召回通道,消费 ParsedQuery 中本通道需要的字段,经 StoreManager 的对应命名端口召回候选;多路并行与结果合并由 CompositeDomainStore.recall 负责,通道之间互不感知(见 recaller.py)。
完整契约(channel() / recall() / health()、通道枚举、装配与选择器键)见 storage.md §20。YAML 命名空间仍是 recaller,迁移到数据面后无需任何配置改动。
RecallChannel 枚举(common/type_def/retrieval.py)包含 DOCUMENT、KEYWORD、VECTOR、ENTITY、GRAPH、TEMPORAL、SPACE。其中 SPACE 不是召回通道,而是跨空间检索中"某个空间整体召回失败"的标记位,只出现在 RetrievalResult.errors 里,不进候选与融合。L0/L1/L2 是同一逻辑通道下的不同物理索引来源,不新增通道枚举值。
5. Fuser API 与三种内置融合策略
from jiuwen_memory.retrieval.fuser import Fuser
fuse(
query: ParsedQuery,
candidates: list[list[ScoredCandidate]],
) -> list[ScoredCandidate]
candidates 是二维结构:每个物理召回来源一个列表。ScoredCandidate 可能是未物化的 ScoredUnit 或已物化的 ScoredMemoryUnit。当前生产环境的 Retriever 在 Fuser 之前完成真源点读与复核,因此传入的是 ScoredMemoryUnit 对象(见 pipeline_retriever.py 中三条路径都先 materialize 再 fuse)。
Fuser 负责候选去重、证据合并、分数融合与排序。共享的 Reranker 是更靠后的独立阶段,由 Retriever 编排,不会在 Fuser.fuse() 内部执行。
内置实现
target |
实现类 | 功能 | 主要参数 |
|---|---|---|---|
rrf |
RRFFuser |
默认的倒数排名融合:每路按名次贡献 1/(k+rank+1),跨路累加,不依赖原始分数量纲 |
k(默认 60) |
weighted_rrf |
WeightedRRFFuser |
每个 RRF 贡献再乘以逻辑通道权重 | fusion_rrf_k(默认 60)、fusion_channel_weights(默认 {},各通道权重 1.0) |
score_max |
ScoreMaxFuser |
通道内按最高分归一化,再对每个 unit 跨通道取最大值(CombMAX) | fusion_channel_weights(默认 {}) |
三个 Fuser 都会先对同一逻辑通道内的 L0/L1/L2 来源按 unit_id 做 MaxP 归并,再进行跨通道融合——这一步由 layered_merge.py 统一完成。其设计动机在源码注释中讲得很透:分层是同一通道的多个索引入口而非独立信号源,若直接按"一个列表 = 一路信号"处理,计分类融合会把同 unit 的多层命中重复累加、归一化类融合会按层各自取基准,二者都是"索引覆盖差异"被误当成"相关性差异"。
ScoreMaxFuser 的实现还解释了为什么取 max 而非求和(CombSUM):加法天然偏好多通道命中,会结构性折价"语义极强但字面未命中"的候选;而词法(BM25)与语义(向量)是异质通道且候选集为并集,combined(u) = max_c weight_c × (score_c(u) / max_score_c) 是更合适的选择(score_max_fuser.py)。
必须记住的分层先归并语义也有测试锁定:test_rrf_family_merges_same_channel_layers_before_scoring 断言同通道 L2/L0 多层命中的 u1 融合后 evidence 只有一条(MaxP 取最高分 0.9),不会重复投票(test_fuser.py)。
6. 渐进式披露:Discloser API
from jiuwen_memory.retrieval.discloser import Discloser
disclose(
query: ParsedQuery,
candidates: list[ScoredCandidate],
units: dict[str, MemoryUnit],
level: DisclosureLevel,
max_tokens: int | None = None,
) -> list[RetrievedItem]
| 参数 | 说明 |
|---|---|
query |
提供改写后的查询、关键词等内容选择信号 |
candidates |
读取、过滤、融合、(可选)重排后的最终候选顺序 |
units |
unit_id -> MemoryUnit 内容查找表 |
level |
本次请求的主披露层级 |
max_tokens |
ADAPTIVE 模式的预算输入 |
Discloser 只做内容塑形:不做 Store 点读、过滤、融合或重排(见 discloser.py 的契约说明)。
DisclosureLevel 语义:
| 枚举值 | 主内容 |
|---|---|
L0 |
摘要 |
L1 |
相关片段/概览 |
L2 |
全文 |
ADAPTIVE |
依据 max_tokens 选择实际层级 |
两种内置实现
target |
实现类 | 功能 | 配置 |
|---|---|---|---|
truncating |
TruncatingDiscloser |
默认无状态实现:优先取预生成的 unit.layers.l0/l1;缺失时 L0 截断到 80 字符、L1 取首个关键词周围 240 字符窗口。ADAPTIVE 目前固定 L0 为主层级,不消费 max_tokens |
无 params |
structured |
StructuredDiscloser |
面向 Agent 消费:产出稳定的行式 L0 记忆卡片、L1 证据片段、L2 全文,优先取预生成层。ADAPTIVE 按 max_tokens 逐条升级披露层级 |
无 params |
TruncatingDiscloser 的兜底逻辑在 truncating_discloser.py:L0 兜底截断 80 字符并加省略号;L1 围绕首个命中关键词取前 30 字符、宽 240 字符的窗口,无命中则直接截断。StructuredDiscloser 则给出带标签的行式输出,例如 L1 兜底渲染为 <a href="https://link.gitcode.com/i/08ecbaa6f5079a5a9322a897792ade97" target="_blank">summary]、[evidence]、[matched]、[why] 四行,[why] 直接附上每条通道证据的 rank/score/weight/contribution,方便 Agent 理解"为什么返回这条"([structured_discloser.py)。其 ADAPTIVE 升级策略还带置信度保护:仅当 top1 分数 ≥ 次高分 × 1.5 时才把 top1 升级到 L2(structured_discloser.py)。
7. Retriever API 与 PipelineRetriever 编排链路
from jiuwen_memory.retrieval.retriever import Retriever
retrieve(scope: Scope, query: RetrievalQuery) -> RetrievalResult
在 scope 内执行完整检索并返回最终结果。当前标准的 PipelineRetriever 主序列(pipeline_retriever.py):
RetrievalQuery
-> QueryParser.parse
-> Storage recall/materialization path
-> source-of-truth recheck
-> Fuser.fuse
-> candidate-budget truncation
-> optional Reranker
-> relevance thresholds and top_k
-> Discloser.disclose
-> RetrievalResult
其中 build_system_filters 负责把 lifecycle × as_of(valid-time)、event-time 时间窗、include_archived 等系统谓词与用户表达式 AND 外包后一并下推;用户表达式作为整体 child 绝不摊平,防止其 OR 稀释生命周期等安全谓词(predicate_builder.py,调用见 pipeline_retriever.py)。
Storage 三条首选检索路径
Storage 召回路径由 Storage.preferred_retrieval_pipeline() 选择(见 storage.md §20):
RECALL_GET_RANK:只召回 ID;Retriever 再做点读与融合(默认路径);RECALL_AND_GET_RANK:Storage 返回物化候选;Retriever 做融合;RETRIEVE:Storage 内部完成召回、物化与 Fuser 排序。
无论走哪条路径,真源复核必须在 Fuser 之前完成,包括 lifecycle、valid-time、event-time 与完整 FilterExpr(is_retrieval_candidate 是唯一放行判定,见 retrieval_filter.py)。
边界行为
query.text为空,或 parser 清洗后ParsedQuery.raw为空:直接返回空结果,不调用后端召回(空查询短路,见 pipeline_retriever.py);top_k <= 0、max_tokens <= 0或channels=[]:标准PipelineRetriever抛ValidationError;- 部分召回源失败:成功的
items与结构化的errors同时返回; - 所有被选源都失败:抛
StorageRetrievalError; with_trajectory=False只省略trajectory,不省略errors。
超采样、精排预算与阈值旋钮
PipelineRetriever 将"召回超采样(撒宽网)"与"精排预算(控成本)"解耦(见构造参数与 retrieve 中的 recall_k / budget_n 计算,pipeline_retriever.py):
recall_k = max(top_k × over_fetch_factor, over_fetch_floor),再被recall_max封顶;budget_n = max(rerank_max, top_k)作为点读复核 + 重排的候选预算,永不欠top_k;- 若
recall_max与over_fetch_floor矛盾,上限优先(保护优先),并打 warning 让运维可见(pipeline_retriever.py)。
阈值过滤由 apply_threshold 统一实现(pipeline_retriever.py):绝对阈值 min_score 仅在校准(已精排)路径生效;相对阈值在校准/未校准路径分别取严/松两套默认;min_results 允许从正分候选中回填保底。对应行为有测试锁定,例如 test_absolute_threshold_drops_below 与 test_ratio_default_selected_by_calibration(test_threshold.py)。
8. RetrievalResult 返回类型
RetrievalResult(
items: list[RetrievedItem],
trajectory: list[TrajectoryStep],
errors: list[ChannelError],
)
RetrievedItem
| 字段 | 说明 |
|---|---|
unit_id |
MemoryUnit ID |
score |
融合/重排后的分数 |
abstract |
L0 摘要 |
overview |
L1 片段/概览 |
content |
L2 全文 |
user_metadata |
返回给调用方的用户元数据 |
level |
本次请求的主披露层级 |
abstract、overview、content 在返回项中一次性全部填充(分别来自 unit.layers.l0、unit.layers.l1、unit.content),level 标记调用方主要请求的披露层级;调用方按需取用:紧预算用 abstract,中等用 overview,全文用 content(types.py)。RetrievedItem 还额外带 system_metadata 字段。
TrajectoryStep
| 字段 | 说明 |
|---|---|
stage |
阶段名,如 parse、recall、fuse、rerank、disclose |
channel |
召回通道;非召回阶段为 None |
candidate_count |
该步产出的候选数 |
cost_ms |
该步耗时(毫秒) |
detail |
参数、截断原因或降级信息 |
ChannelError
| 字段 | 说明 |
|---|---|
channel |
失败来源的逻辑通道 |
source |
物理召回来源名 |
error_type |
异常类型名 |
message |
安全处理后的错误摘要 |
9. 候选与证据数据类型
| 类型 | 说明 |
|---|---|
ScoredUnit |
未物化候选:unit_id + score + channel + evidence |
ScoredMemoryUnit |
物化候选:unit + score + channel + evidence,带 unit_id 属性 |
ChannelEvidence |
一条结果在某通道内的 rank、score、weight、contribution |
RecallBatch |
一个物理召回来源的候选列表;source 可区分同通道内 L0/L1/L2 索引 |
RecallResult |
batches + errors,表示多来源间的部分成功 |
完整字段表见 common/type_def/retrieval.py:
ChannelEvidence:channel: RecallChannel=VECTOR;rank: int=0;score: float=0.0;weight: float=1.0;contribution: float=0.0;ScoredUnit:unit_id: str="";score: float=0.0;channel: RecallChannel=VECTOR;evidence: list[ChannelEvidence]=[];ScoredMemoryUnit:unit: MemoryUnit=MemoryUnit()+ 同样的 score/channel/evidence 字段,其unit_id属性返回unit.id;RecallBatch[T]:channel: RecallChannel;source: str;candidates: list[T]=[];ChannelError:channel: RecallChannel;source: str;error_type: str;message: str;RecallResult[T]:batches: list[RecallBatch[T]]=[];errors: list[ChannelError]=[];RankedStorageResult:candidates: list[ScoredMemoryUnit]=[];errors: list[ChannelError]=[]——Storage 完成物化与 Fuser 处理后的结果。
注意:原始分数量纲由各 Recaller/Store 自行定义,不能假设是 [0, 1]。RRF 只用名次;score_max 在每次调用、每个通道内归一化后再比较。所有内置 Fuser 都按最终分数降序返回。
10. 配置化装配:两级命名空间
检索与存储共用同一套两级命名空间配置:顶层 = 各组件(Producer 的 TOP_NAME),其下 = 具名实例(target / params)。配置示例可对照 examples/config.yml 的注释("顶层 = 各组件,其下 = 具名实例;用户配置合并覆盖到内置默认之上,只需写要改动的部分")。
fuser: # FuserProducer.TOP_NAME
default: # Named instance
target: rrf # Registered implementation
params:
k: 60
params里的字符串依赖引用对应 Producer 命名空间下的具名实例;{target: ..., params: ...}映射则内联构建匿名实例;- 普通参数先从当前实例的
params读取,缺失时回退到globals; - 用户配置覆盖同名内置实例时,
params映射整体替换而非逐字段深合并——覆盖retriever.default或query_parser.default时,要把仍需要的具名依赖全部写上; - 在部署配置中,这些段落要放在
memory_api:之下。
无用户配置时的默认装配:simple QueryParser;keyword、vector、graph 三个 Recaller(含各自 L0/L1 变体);rrf Fuser;truncating Discloser;pipeline Retriever。vector、graph、分层索引与重排阶段是否真正启用由 vector_enabled、graph_enabled、layers_index_enabled、rerank_enabled 四个开关控制。
11. 内置实现配置详解
11.1 QueryParser:simple
target |
实现类 | 功能 | 依赖与参数 |
|---|---|---|---|
simple |
SimpleQueryParser |
唯一的内置 parser。可执行保守清洗、LLM 改写、Tokenizer 分词、FeatureExtractor 关键词/实体抽取、Embedder 向量化、规则时间解析 | 依赖 tokenizer、embedder、llm、feature_extractor;sanitize_enabled(默认 true)、sanitize_strip_code(默认 false);vector_enabled=false 时不装配 Embedder |
query_parser:
default:
target: simple
params:
tokenizer: default
embedder: default
# Anonymous inline echo: pass the query through without conversational-model rewriting
llm: {target: echo}
feature_extractor: default
sanitize_enabled: true
sanitize_strip_code: false
内置默认 target 就是 simple,其默认 LLM target 为 echo(不改写查询)。若引用其他 LLM,simple 直接把 llm.generate(text) 的结果作为 rewritten。
从 simple_query_parser.py 的实现可见其通道建议逻辑:默认给出 [KEYWORD, GRAPH];注入 Embedder 后追加 VECTOR;特征抽取抽到实体后追加 ENTITY;时间约束经 parse_time 规则解析为 event-time 窗口。
11.2 Recaller 实现
target |
实现类 | 通道/层级 | 功能 | 主要依赖与参数 |
|---|---|---|---|---|
keyword |
KeywordRecaller |
KEYWORD / L2 |
查询 storage.fulltext 索引并把索引记录聚合成 MemoryUnit;实体路径启用时支持实体关联扩展 |
storage;可选 entity_store;entity_enabled(默认 false) |
keyword_l0 |
KeywordRecaller |
KEYWORD / L0 |
查询 storage.fulltext_port("layers_l0") 概要索引 |
storage;由全局 layers_index_enabled 开关控制 |
keyword_l1 |
KeywordRecaller |
KEYWORD / L1 |
查询 storage.fulltext_port("layers_l1") 片段索引 |
storage;由全局 layers_index_enabled 开关控制 |
vector |
VectorRecaller |
VECTOR / L2 |
对内容 chunk 做 ANN,按元数据把 chunk 聚合回 MemoryUnit,同 unit 多 chunk 应用 MaxP | storage;min_similarity(默认 0.0,即关闭召回前阈值) |
vector_l0 |
VectorRecaller |
VECTOR / L0 |
查询 storage.vector_port("layers_l0") 概要向量 |
storage;由全局 layers_index_enabled 开关控制 |
vector_l1 |
VectorRecaller |
VECTOR / L1 |
查询 storage.vector_port("layers_l1") 片段向量 |
storage;由全局 layers_index_enabled 开关控制 |
graph |
GraphRecaller |
GRAPH / L2 |
从关键词和实体文本找种子节点,再做多跳图遍历 | storage;depth(默认 1) |
globals:
vector_enabled: true
graph_enabled: true
layers_index_enabled: true
entity_enabled: false
recaller:
keyword:
target: keyword
params:
storage: default
keyword_l0: {target: keyword_l0, params: {storage: default}}
keyword_l1: {target: keyword_l1, params: {storage: default}}
vector:
target: vector
params:
storage: default
min_similarity: 0.0
vector_l0: {target: vector_l0, params: {storage: default}}
vector_l1: {target: vector_l1, params: {storage: default}}
graph:
target: graph
params:
storage: default
depth: 1
实现层面的几个要点:
- 分层端口缺失即优雅降级:
keyword_l0/l1、vector_l0/l1找不到对应命名 Store 端口时返回空召回结果,不影响其他通道(keyword_recaller.py 与 vector_recaller.py 的None约定)。 - L2 实体关联扩展:
KeywordRecaller从 batch1 候选的entities元数据反查关联 unit,打分用中位数锚定 + IDF 抑制高频泛化实体 + cap 软封顶,保证关联记忆分不会过低也不会压过 batch1 原生命中,并把点读真源的 IO 上限压到_ENTITY_EXPANSION_TOP_K=20(keyword_recaller.py)。 - 向量度量约束:
VectorRecaller装配期会校验score_higher_is_better(),距离型度量(如 L2,越小越相关)会被ValidationError拒绝,因为无法用于 MaxP 聚合与降序融合(vector_recaller.py)。 - 图召回:
GraphRecaller的种子词项 = 关键词 ∪ 实体文本,BFS 深度由depth控制(graph_recaller.py)。
RecallChannel.DOCUMENT 与 RecallChannel.TEMPORAL 已在公共枚举中定义,但目前没有对应的内置 RecallerProducer target。
11.3 Fuser 实现
fuser:
default:
target: weighted_rrf
params:
fusion_rrf_k: 60
fusion_channel_weights:
keyword: 1.0
vector: 2.0
graph: 0.5
切回无权重 RRF 时用 params.k,不是 fusion_rrf_k:
fuser:
default: {target: rrf, params: {k: 80}}
WeightedRRFFuser 会保留每个候选的融合证据(rank/score/weight/contribution),其 explain() 返回策略与权重快照供轨迹使用(weighted_rrf_fuser.py)。测试 test_weighted_rrf_fuser_applies_channel_weights 验证了权重对排序和 contribution 的直接影响(test_fuser.py)。
11.4 Discloser 实现
discloser:
default: structured
11.5 Retriever 实现
target |
实现类 | 功能 | 主要参数 |
|---|---|---|---|
pipeline |
PipelineRetriever |
默认检索编排。按 Storage 首选路径执行查询解析、多路召回/物化、真源复核、Fuser 处理、(可选)Reranker、阈值过滤、披露 | 依赖 storage、query_parser、fuser、discloser、reranker 与各 *_recaller 实例;开关:vector_enabled、graph_enabled、layers_index_enabled、rerank_enabled;数值旋钮见下表 |
multimodal |
MultimodalRetriever |
在基础 Retriever 上并行运行 native、CLM、ELM 三个过滤分支,再以 RRF 合并 | base_retriever(默认匿名 pipeline)、clip_top_k(默认 10)、event_top_k(默认 10)、rrf_k(默认 60) |
pipeline 的数值调参表:
| 参数 | 默认值 | 功能 |
|---|---|---|
over_fetch_factor |
4 |
每路召回数相对 top_k 的放大倍数 |
over_fetch_floor |
60 |
每路召回数下限 |
recall_max |
100 |
每路召回数硬上限;<=0 表示不限 |
rerank_max |
60 |
复核/重排候选预算,绝不低于 top_k |
min_score |
0.0 |
校准分数路径的绝对阈值;0 关闭 |
min_score_ratio |
0.0 |
相对最高校准分数的比例阈值;0 关闭 |
min_score_ratio_uncalibrated |
0.0 |
未校准融合分数的比例阈值;0 关闭 |
min_results |
0 |
阈值过滤后从正分候选回填的最少结果数;0 关闭 |
globals:
vector_enabled: true
graph_enabled: false
layers_index_enabled: true
rerank_enabled: true
retriever:
default:
target: pipeline
params:
query_parser: default
fuser: default
discloser: default
reranker: default
# Recaller selector keys (keyword_recaller / vector_recaller / graph_recaller /
# *_l0 / *_l1) do NOT live here: they are data-plane parameters declared under
# store_manager.<inst>.params.domain_stores.<name>. Retriever resolves the global
# manager via globals.store_manager and holds its domain_store(); it owns no
# recall channels.
over_fetch_factor: 4
over_fetch_floor: 60
recall_max: 100
rerank_max: 60
min_score: 0.0
min_score_ratio: 0.0
min_score_ratio_uncalibrated: 0.0
min_results: 0
注意配置注释中的关键点:Recaller 选择器键不活在 retriever 命名空间,它们是数据面参数,声明在 store_manager.<inst>.params.domain_stores.<name> 下;Retriever 通过 globals.store_manager 解析全局 manager 并持有其 domain_store(),本身不拥有召回路。这一点与 pipeline_retriever.py 的 _build 注册实现完全对应:它从 StoreManagerProducer.resolve(config) 取 manager,再从 manager 取 domain_store 注入。
rerank_enabled 关掉时(pipeline_retriever.py)Reranker 装配为 None;若调用方仍显式要求精排,会在轨迹中记录 no_reranker_configured 并走未校准阈值路径(同文件 #L324-L328)。
multimodal 分支:
retriever:
base:
target: pipeline
params:
storage: default
query_parser: default
fuser: default
discloser: default
default:
target: multimodal
params:
base_retriever: base
clip_top_k: 10
event_top_k: 10
rrf_k: 60
从 multimodal_retriever.py 的实现看,三个分支通过 _with_filters 加元数据谓词并发执行:native 分支排除 source=video,CLM/ELM 分支按 system_metadata.modal_type 与 system_metadata.memory_level 过滤,最后 _rrf_merge 按 1/(rrf_k+rank) 累加合并。注意:multimodal 自己不做视频理解、也不构建 CLM/ELM 数据,只按 system_metadata.modal_type 与 memory_level 派发给基础 Retriever;对应的多模态写入路径与元数据必须已存在。
12. 完整使用示例
from jiuwen_memory.common.type_def import RecallChannel, Scope
from jiuwen_memory.retrieval.retriever import Retriever
from jiuwen_memory.retrieval.types import DisclosureLevel, RetrievalQuery
def search_memory(retriever: Retriever, scope: Scope) -> list[str]:
result = retriever.retrieve(
scope,
RetrievalQuery(
text="What retrieval approach did we discuss last time?",
top_k=5,
channels=[RecallChannel.KEYWORD, RecallChannel.VECTOR],
disclosure=DisclosureLevel.L1,
with_trajectory=True,
),
)
return [item.overview for item in result.items]
应用代码应优先用 Retriever.retrieve(),而不是自己拼装 QueryParser、Recaller、Fuser、Discloser。直接组合的适用场景是:实现新的检索流水线、替换算法,或做组件级测试。
13. 中间数据契约详解
13.1 ParsedQuery
ParsedQuery 是 QueryParser 产出、由 Storage/Recaller/Fuser 共享的结构化查询:
| 字段 | 类型 | 默认 | 语义 |
|---|---|---|---|
raw |
str |
"" |
规范化原始查询;Retriever 在它为空时短路 |
rewritten |
str |
"" |
改写后的查询 |
intent |
str |
"" |
查询意图 |
tokens |
list[str] |
[] |
Tokenizer 输出 |
keywords |
list[str] |
[] |
关键词特征 |
entities |
list[Entity] |
[] |
实体特征 |
vector |
list[float] |
[] |
查询向量;维度必须与写入侧 Embedder 一致 |
scalar_filters |
FilterExpr | None |
None |
已并入系统边界的预过滤 |
recheck_filters |
FilterExpr | None |
None |
用于真源复核的用户表达式 |
as_of |
datetime | None |
None |
valid-time 历史点 |
time_from / time_to |
datetime | None |
None |
event-time 范围边界 |
channels |
list[RecallChannel] |
[] |
Parser 建议的逻辑通道 |
include_archived |
bool |
false |
当前态查询是否纳入 ARCHIVED 单元 |
extensions |
dict[str, Any] |
{} |
传给自定义检索组件的扩展参数 |
PipelineRetriever 会把 lifecycle、valid-time、event-time 系统谓词追加到 scalar_filters,recheck_filters 保留用户过滤器用于真源复核。自定义 Parser 绝不能把两者合并成一个可能被 OR 削弱系统边界的表达式。
13.2 候选、证据与单源结果
| 类型 | 字段(类型;默认) | 用途 |
|---|---|---|
ChannelEvidence |
channel: RecallChannel=VECTOR;rank: int=0;score: float=0.0;weight: float=1.0;contribution: float=0.0 |
记录每通道名次、原始分、权重与融合贡献 |
ScoredUnit |
unit_id: str="";score: float=0.0;channel: RecallChannel=VECTOR;evidence: list[ChannelEvidence]=[] |
未物化候选 |
ScoredMemoryUnit |
unit: MemoryUnit=MemoryUnit();其余同 score/channel/evidence |
物化候选;unit_id 属性返回 unit.id |
ScoredCandidate |
ScoredUnit | ScoredMemoryUnit |
Fuser 与 Discloser 共用的联合类型 |
RecallBatch[T] |
channel: RecallChannel;source: str;candidates: list[T]=[] |
一个物理召回来源的结果;source 区分 L0/L1/L2 索引 |
ChannelError |
channel: RecallChannel;source: str;error_type: str;message: str |
一个物理来源的失败;message 应为安全清洗后的摘要 |
RecallResult[T] |
batches: list[RecallBatch[T]]=[];errors: list[ChannelError]=[] |
多来源的部分成功 |
RankedStorageResult |
candidates: list[ScoredMemoryUnit]=[];errors: list[ChannelError]=[] |
Storage 完成物化与 Fuser 处理后的结果 |
13.3 最终结果类型与默认值
| 类型.字段 | 类型 | 默认 |
|---|---|---|
RetrievedItem.unit_id |
str |
"" |
RetrievedItem.score |
float |
0.0 |
RetrievedItem.abstract / overview / content |
str |
"" |
RetrievedItem.user_metadata |
dict[str, MetadataValueType] |
{} |
RetrievedItem.level |
DisclosureLevel |
L0 |
TrajectoryStep.stage |
str |
"" |
TrajectoryStep.channel |
RecallChannel | None |
None |
TrajectoryStep.candidate_count |
int |
0 |
TrajectoryStep.cost_ms |
float |
0.0 |
TrajectoryStep.detail |
dict[str, str] |
{} |
RetrievalResult.items |
list[RetrievedItem] |
[] |
RetrievalResult.trajectory |
list[TrajectoryStep] |
[] |
RetrievalResult.errors |
list[ChannelError] |
[] |
14. 算子方法契约与不可变约束
| API | 输入要求 | 输出要求 | 副作用/边界 |
|---|---|---|---|
QueryParser.parse(query) |
接收一个 RetrievalQuery,不接收 Scope |
返回 ParsedQuery;raw 是实际进入召回层的规范化文本 |
不读 Storage;自定义实现应保留 filters、as_of、extensions |
Recaller.recall(scope, query, top_k) |
top_k 应为正数;Scope 与 filters 是独立边界 |
返回本物理来源的 ScoredUnit;内置实现高分在前 |
只召回 ID,绝不更新真源 |
Fuser.fuse(query, candidates) |
candidates 是每物理召回源一个列表的二维结构 |
把每个 unit 融合为一条候选并保留代表数据与证据;内置实现高分在前 | 不点读、不过滤、不调用 Reranker |
Discloser.disclose(...) |
units 是 unit_id 到 MemoryUnit 的真源查找表 |
为有可用 unit 的候选产出 RetrievedItem |
不点读、不重排;内置实现跳过 units 中缺失的 ID |
Retriever.retrieve(scope, query) |
top_k > 0;max_tokens 为 None 或正数;channels 不能为空列表 |
返回按最终分降序的 RetrievalResult |
空查询短路;绝不写 Storage |
Fuser 不得原地修改输入列表或 MemoryUnit 对象。内置实现需要改变分数或证据时创建替代候选(三种 Fuser 的实现全部通过 dataclasses.replace 构造新对象)。同一逻辑通道的 L0/L1/L2 候选在跨通道融合前先做 MaxP 归并(见 §5)。
15. 错误传播矩阵
| 阶段 | 可局部降级 | 记入 RetrievalResult.errors |
直接抛出 |
|---|---|---|---|
| 请求校验 | 否 | 否 | top_k <= 0、max_tokens <= 0、channels=[] 抛 ValidationError |
| QueryParser | 否 | 否 | Parser 异常原样传播 |
| 单个物理召回源 | 是(其他源成功时) | 是(作为 ChannelError) |
无源成功时 Storage 抛 StorageRetrievalError |
| 真源物化/复核 | 缺失或无效的 unit 被过滤 | 保留先前的召回错误 | 意外的 Storage 失败向上传播 |
| Fuser | 否 | 否 | Fuser 异常传播 |
| Reranker | 显式请求但未装配时跳过,轨迹记录 no_reranker_configured |
否 | 已装配 Reranker 的异常传播 |
| Discloser | 缺失的 unit 被跳过 | 否 | 格式化实现异常传播 |
errors 与 with_trajectory 相互独立:关闭轨迹只得到 trajectory=[],不会丢弃部分召回错误。
16. 完整结果示例
from jiuwen_memory.common.type_def import ChannelError, RecallChannel
from jiuwen_memory.retrieval.types import (
DisclosureLevel,
RetrievedItem,
RetrievalResult,
TrajectoryStep,
)
result = RetrievalResult(
items=[
RetrievedItem(
unit_id="memory-1",
score=0.0325,
abstract="The user prefers PostgreSQL.",
overview="The user explicitly prefers PostgreSQL when selecting storage.",
content="The user said PostgreSQL should be preferred as the production persistence backend.",
user_metadata={"topic": "storage"},
level=DisclosureLevel.L1,
)
],
trajectory=[
TrajectoryStep(stage="parse", candidate_count=3, cost_ms=1.2),
TrajectoryStep(
stage="recall",
channel=RecallChannel.VECTOR,
candidate_count=8,
cost_ms=12.4,
),
TrajectoryStep(stage="fuse", candidate_count=5, cost_ms=0.3),
],
errors=[
ChannelError(
channel=RecallChannel.KEYWORD,
source="keyword_l1",
error_type="BackendError",
message="fulltext backend unavailable",
)
],
)
这个结果的含义:向量等其他来源成功,因此查询返回 items 的同时保留了失败的 keyword_l1 物理来源。只有当所有被选来源都失败时,调用才会抛 StorageRetrievalError 而非返回该结构。
17. 自定义实现与测试路径指引
若要注册新的算子实现,遵循 retrieval/bootstrap.py 的自注册机制:
@XxxProducer.register("name")
def _build(config):
...
retrieval.bootstrap.register_operators() 通过 import 实现模块触发注册(幂等,重复调用近乎零成本),由装配入口 build_kernel 在组装前调用一次,与 storage.bootstrap 的 register_backends 同构。一个抽象的算子实现至少需要:
- 实现算子特定的抽象业务方法;
- 实现
operator_type()并返回与接口对应的枚举值; - 实现
health(); - 若是 Recaller,还要实现
channel(); - 预期失败使用共享异常类型,而不是向上泄漏后端特有异常。
相关单元测试可直接作为契约的活文档:Fuser 融合与证据(test_fuser.py)、QueryParser 的 filters/as_of/extensions/时间解析与清洗(test_query_parser.py)、阈值行为(test_threshold.py)、Storage 路径选择与装配(test_storage_pipelines.py、test_storage_factory_wiring.py),以及检索装配配置样例(examples/config.yml)。