agent-memory 检索层(Retrieval Layer)API 与 PipelineRetriever 实战指南

原创2026-10-13 09:02:381,641 阅读
文章标签:Agent 记忆人工智能MCP 服务RAGAI Agent

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 同构。一个抽象的算子实现至少需要:

  1. 实现算子特定的抽象业务方法;
  2. 实现 operator_type() 并返回与接口对应的枚举值;
  3. 实现 health();
  4. 若是 Recaller,还要实现 channel();
  5. 预期失败使用共享异常类型,而不是向上泄漏后端特有异常。

相关单元测试可直接作为契约的活文档: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)。

登录后查看全文
agent-memory