agent-memory 接入层边界重构:RawPayload.assets 映射与 Normalizer 模态能力契约

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

agent-memory 接入层边界重构:RawPayload.assets 映射与 Normalizer 模态能力契约

本文围绕 F02-assets-ingestor-boundary 设计文档,深入讲解 agent-memory 在“Assets 映射与 Normalizer 能力边界”上的架构决策:为什么资产引用必须由 Ingestor 自行映射、为什么模态支持能力只能由 Normalizer 自己声明,以及这些契约在源码、配置与测试中的具体落地方式。读完本文,你将掌握 RawPayload.assets → MemoryUnit.segments 的完整流转链路、modalities() 单一能力声明的含义,以及如何为 TEXT/VIDEO 等模态正确装配 Normalizer 并在缺失能力时获得可诊断的统一错误。

背景:旧流程为什么必须重构

在引入本设计之前,MemoryEngine.write 虽然接收 assets 参数,但旧流程没有把它们交给 Ingestor,而是在 ingest 完成后由 Engine 统一把 assets 回填到首个 Segment。这带来两个问题:

  1. Engine 隐式假设了 Ingestor 的产出结构:Engine 假定 Ingestor 一定产出“首 Segment”,并把资产塞进去,从而与具体实现耦合;
  2. 自定义 Ingestor 的映射结果会被二次改写:一个已经按自身策略完成 assets 映射的自定义 Ingestor,其产出仍会被 Engine 覆盖或污染,映射策略形同虚设。

重构的核心思路是:把资产映射的责任彻底下放到 Ingestor,Engine 只做防御性传递,不再触碰 Ingestor 的产出结构。这一改动的影响范围覆盖 RawPayload、Ingestor、Normalizer、InMemoryEngine、CloudEngine 以及入口错误映射,并配套建立了统一的“能力错误”语义。

决策 1~2:RawPayload.assets 成为资产引用载体,Engine 只做防御性复制

决策 1:RawPayload 增加 assets: list[str],作为从调用边界传入 Ingestor 的资产引用载体。

在源码中,该字段定义于 jiuwen_memory/common/type_def/raw.py#L18-L28:

@dataclass
class RawPayload:
    id: str = ""                    # 负载 id
    scope: Scope = field(default_factory=Scope)
    modality: Modality = Modality.TEXT   # 来源模态
    data: bytes = b""                # 原始字节;与 uri 二选一
    uri: str = ""                    # 原始数据的外部引用(文件路径/URL/对象存储 key)
    ...
    assets: list[str] = field(default_factory=list)  # 待 Ingestor 映射的资产引用

决策 2:InMemoryEngine 与 CloudEngine 只对 write 入参做防御性复制,并将副本放入 RawPayload.assets。以 in_memory_engine.py#L298-L308 为例:

payload = RawPayload(
    id=payload_id or str(uuid.uuid4()),
    scope=scope,
    modality=source,
    data=b"" if is_video else content.encode("utf-8"),
    uri=content if is_video else "",
    assets=list(assets or []),          # 防御性复制,不共享可变 list 实例
    system_metadata=meta,
    user_metadata=dict(user_metadata or {}),
    occurred_at=occurred_at,
)

list(assets or <a href="https://link.gitcode.com/i/683d316dbe8a636cc821af886da70a08" target="_blank">]) 这一防御性复制非常关键:它保证调用方在 write 之后继续修改自己的 assets 列表,不会影响已经构造的 RawPayload(也不影响后续 Segment 中的资产)。测试 [test_simple_ingestor.py#L38-L53 专门断言了“payload assets 被等值复制到当前 Segment,且不共享可变 list 实例”(units[0].segments[0].assets is not payload.assets)。

决策 3~4:Ingestor 拥有 assets → segments 的映射责任

决策 3 是最核心的职责划分:Ingestor 拥有 assets 到 MemoryUnit.segments 的映射责任。Engine 在 ingest 返回后:

  • 不再新建 Segment;
  • 不再回填首 Segment;
  • 不再改写任何 Segment.assets。

这从制度上杜绝了 Engine 对 Ingestor 产出结构的二次干涉。Segment 的三元结构(content + assets + source)定义于 memory.py#L110-L122:content 是可治理的文本投影(索引与检索的对象),assets 是本段对应的原模态资产引用,source 是本段来源模态。

决策 4 明确了一个重要边界:当前 SimpleIngestor 产出“单 MemoryUnit / 单 Segment”,并把一个 payload 的全部 assets 复制到该 Segment——这只是具体实现行为,不上升为 Ingestor 接口的数量契约。后续的分块、多模态或聚合型 Ingestor 完全可以产出多 MemoryUnit / 多 Segment。

SimpleIngestor 的实现清晰体现了“记录资产引用 → Normalizer 规约投影 → 转换为 MemoryUnit(不落盘)”三步:

def ingest(self, payloads: list[RawPayload]) -> list[MemoryUnit]:
    units: list[MemoryUnit] = []
    for payload in payloads:
        ensure_normalizer_supports(self._normalizer, payload.modality)
        now = _now()
        units.append(
            MemoryUnit(
                id=str(uuid.uuid4()),
                scope=payload.scope,
                segments=[
                    Segment(
                        content=self._normalizer.normalize(payload),
                        assets=list(payload.assets),       # 等值复制资产
                        source=payload.modality,
                    )
                ],
                source_ref=payload.id,
                temporal=Temporal(...),
                system_metadata=dict(payload.system_metadata),
                user_metadata=dict(payload.user_metadata),
            )
        )
    return units

注意 assets=list(payload.assets) 同样是防御性复制。Ingestor 接口契约本身定义于 jiuwen_memory/ingest/ingestor.py:ingest(payloads) -> list[MemoryUnit],不落盘(落盘与建索引由构建层负责)。

决策 5:modalities() 是“能不能进”的单一能力声明,不代表“数据放哪里”

决策 5 澄清了一个极易混淆的概念:

  • Normalizer.modalities() 只负责声明“是否支持该模态”(能不能进);
  • 它不负责决定原始数据应放入 RawPayload.data 还是 RawPayload.uri(数据放哪里是另一份契约)。

接口定义见 normalizer/base.py#L33-L41:

class Normalizer(Plugin):
    @abstractmethod
    def modalities(self) -> list[Modality]:
        """返回本规约器支持的模态。"""

    @abstractmethod
    def normalize(self, payload: RawPayload) -> str:
        """将原模态负载规约为可治理的文本/结构投影(content)。"""

同时,RoutingNormalizer 在构造时校验显式 route 的 delegate:如果某个 route 声明的模态不在其 delegate 的 modalities() 支持集合内,直接抛 ValidationError。见 routing_normalizer.py#L21-L35:

def __init__(self, fallback, routes):
    self._fallback = fallback
    self._routes = dict(routes)
    for modality, normalizer in self._routes.items():
        supported = normalizer.modalities()
        if modality not in supported:
            supported_names = sorted(item.value for item in supported)
            raise ValidationError(
                f"routing normalizer route {modality.value!r} targets "
                f"{type(normalizer).__name__!r}, which supports {supported_names}"
            )

例如配置 routes: {video: passthrough}(把视频路由给文本直通规约器)就会在装配期直接失败——PassthroughNormalizer 并不声明支持 VIDEO。测试 test_normalizer_capabilities.py#L58-L63 验证直接构造会抛错,test_multimodal_adapter.py#L364-L379 验证 build_kernel() 装配路径同样拒绝该配置。

RoutingNormalizer.normalize() 的运行时路由逻辑也值得注意:self._routes.get(payload.modality, self._fallback),即按模态命中 delegate,未命中时回退到 fallback,且命中后仍会 ensure_normalizer_supports 二次校验。

决策 6:Ingestor 在 normalize 前校验真实 payload,失败即“统一能力错误”

决策 6 规范了错误语义:Ingestor 在 normalize 之前校验真实 payload 的模态;不支持时抛 UnsupportedCapabilityError,该异常携带 capability / value / component 三段结构化信息,且不产生 MemoryUnit、不落盘、不建索引。

异常类型定义于 errors.py#L127-L145:

class UnsupportedCapabilityError(AgentMemoryError):
    def __init__(self, capability: str, value: str, component: str, message: str = ""):
        self.capability = capability
        self.value = value
        self.component = component
        super().__init__(message or f"{component or 'component'!r} does not support "
                          f"{capability or 'capability'} {value!r}")

校验入口是 normalizer/base.py#L43-L51 的 ensure_normalizer_supports,由 SimpleIngestor 在每个 payload 处理前调用:

def ensure_normalizer_supports(normalizer: Normalizer, modality: Modality) -> None:
    if modality in normalizer.modalities():
        return
    raise UnsupportedCapabilityError(
        capability="modality",
        value=modality.value,
        component=type(normalizer).__name__,
    )

这一“统一能力错误”语义在三条路径上保持一致:

  • Ingestor 侧:SimpleIngestor 对不支持模态直接抛错(测试 test_simple_ingestor.py#L56-L68 断言 capability == "modality"、value == "image"、component == "PassthroughNormalizer");
  • Normalizer 侧:PassthroughNormalizer / RoutingNormalizer / VideoNormalizer 在 normalize() 内同样先 ensure_normalizer_supports;
  • HTTP 视频入口:缺少视频 Normalizer 时,handler.py#L344-L376 的 _ensure_video_chain 采用 fail-closed 策略,同样抛 UnsupportedCapabilityError(capability="modality", value="video", component=...)。

HTTP 与 CLI 的错误映射:在直接调用 MemoryAPI 的协议边界,共享错误映射将 UnsupportedCapabilityError 与 ValidationError 统一返回 HTTP 400。映射表见 error_response.py#L8-L26,handler 的状态码绑定见 handler.py#L66-L81。CLI 侧在 commands.py#L114 对 ValidationError 同样返回 400。

另一个容易混淆的边界:已配置 Normalizer 但缺少 video Evolver 时,属于装配问题,抛 ValidationError 而非能力错误——因为能力链本身是配齐的,缺的是下游自演进组件。

决策 7:PassthroughNormalizer 的能力边界——哪些模态能“直通”,哪些不能

决策 7 精确划定了文本直通规约器的能力边界。实现见 passthrough_normalizer.py#L31-L46:

@staticmethod
def modalities() -> list[Modality]:
    return [Modality.TEXT, Modality.CODE]

def normalize(self, payload: RawPayload) -> str:
    ensure_normalizer_supports(self, payload.modality)
    if payload.data:
        try:
            return payload.data.decode("utf-8")
        except UnicodeDecodeError as exc:
            raise ValidationError("passthrough normalizer requires UTF-8 text data") from exc
    if payload.uri and payload.modality == Modality.TEXT:
        return payload.uri                       # 仅 TEXT 保留 URI 兼容回退
    if payload.uri:
        raise ValidationError("passthrough normalizer only supports URI fallback for TEXT")
    raise ValidationError("RawPayload 既无 data 也无 uri,无法规约出文本投影")

可以总结为一张清晰的边界表:

模态 是否支持 行为
TEXT ✅ 有 data 时 UTF-8 解码;无 data 时有 uri 则保留 URI 兼容回退
CODE ✅ 读取 data 中的 UTF-8 文本直通;不读取源码文件(CODE 的 uri 不触发回退,直接抛 ValidationError)
DOCUMENT ❌ 需要专用解析型 Normalizer,passthrough 不会把文档原件当普通 content
IMAGE / AUDIO / VIDEO ❌ 不得把 URI 当作普通 content,一律 UnsupportedCapabilityError

配套测试覆盖了所有边界分支(test_normalizer_capabilities.py):

  • IMAGE + uri → UnsupportedCapabilityError(match "modality 'image'");
  • TEXT + uri → 保留 URI 回退(返回 "file:///note.txt");
  • CODE + data → UTF-8 文本直通;
  • DOCUMENT + data → UnsupportedCapabilityError;
  • CODE + uri → ValidationError(match "URI fallback for TEXT");
  • 非 UTF-8 文本(b"\xff")→ ValidationError(“非法文本投影”)。

注意 UTF-8 解码失败被投影为 ValidationError,而不是能力错误——这符合“能力已声明,但数据本身非法”的语义。

决策 8:不在 Engine/API 维护模态支持列表

决策 8 是一条重要的“反设计”约束:不在 Engine 或 API 层维护任何模态支持列表,也不增加 assets 数量限制、payload/MemoryUnit/Segment 数量限制。

理由是:支持集合完全由可插拔的 Normalizer 自身声明;而原始数据的载体字段选择(data 还是 uri)是另一份契约,两者不能混为一谈。这也是为什么新增模态无需改动 Engine/API——只要注册一个新的 Normalizer 并在 modalities() 中声明即可。

当前 Engine 的载体字段映射限制(仅对 Modality.VIDEO 将 content 写入 RawPayload.uri,其他模态写入 data)被单独记录为已知遗留(见下文),不通过硬编码列表扩散。

拒绝的方案:三条反面教训

设计文档明确拒绝了三个候选方案,各有充分理由:

  1. 继续由 Engine 回填首 Segment:拒绝。Engine 不了解 Ingestor 的分段策略,首段假设会覆盖或污染自定义映射结果;
  2. 在接口上固定 1 RawPayload -> 1 MemoryUnit -> 1 Segment:拒绝。当前 SimpleIngestor 的最小实现不应限制后续分块、多模态或聚合型 Ingestor 的空间;
  3. 在 Engine/API 硬编码全局模态允许列表:拒绝。支持集合应由可插拔 Normalizer 自身声明,且载体字段选择是独立契约。

这三条拒绝与决策 1~8 互为表里,共同构成了“职责下放 + 声明式能力 + 不固化最小实现”的架构取向。

验证:从单元测试到装配层回归

设计文档的验证条目全部有对应测试落地,可以按图索骥:

验证点 测试位置
SimpleIngestor 将 payload assets 等值复制到当前 Segment,且不共享可变 list tests/unit/ingest/test_simple_ingestor.py#L38-L53
InMemoryEngine / CloudEngine 注入“把 assets 放入第二个 Segment”的测试 Ingestor,验证 Engine 传入 assets 且保留分段结果 对应 Engine 写入路径的定向回归(设计基线记录 59 passed)
错误 video -> passthrough route 在直接构造与 build_kernel() 装配中均失败 tests/unit/common/test_normalizer_capabilities.py#L58-L63、tests/unit/multimodal/test_multimodal_adapter.py#L364-L379
SimpleIngestor / PassthroughNormalizer / RoutingNormalizer / VideoNormalizer 覆盖统一运行时能力错误 tests/unit/common/test_normalizer_capabilities.py#L66-L73(VideoNormalizer 对 TEXT 报 capability=modality, value=text, component=VideoNormalizer)
HTTP 与 CLI 通过共享错误映射返回 400 jiuwen_memory_entry/core/error_response.py、jiuwen_memory_entry/core/handler.py#L66-L81
TEXT URI 回退、UTF-8 CODE 直通、DOCUMENT/媒体拒绝、非法 UTF-8 转 ValidationError tests/unit/common/test_normalizer_capabilities.py 全量用例

实操:为视频模态装配完整的 Normalizer 链

以 examples/config_multimodal.yml 为参照,可以看出一条完整的多模态装配:RoutingNormalizer(fallback 为 passthrough)+ video route 指向 VideoNormalizer,后者依赖 ASR(DashScope 文件转写)与 LLM(文本总结 / 视觉理解)两个下游端口:

memory_api:
  globals:
    ingest_max_workers: 1
    ingest_max_pending_jobs: 2

  normalizer:
    default:
      target: routing
      params:
        routes:
          video:
            target: video
            params:
              asr_port: video                 # ASR 端口:dashscope_filetrans
              asr_chunk_seconds: 600
              llm_port: video_text            # 文本总结 LLM
              vlm_port: video_vision          # 视觉理解 LLM
              vlm_max_inline_video_bytes: 52428800   # 默认 50 MiB
              temp_root: /tmp/agent-memory-video

  asr:
    video:
      target: dashscope_filetrans
      params:
        asr_model: qwen3-asr-flash-filetrans
        asr_base_url: ${DASHSCOPE_ASR_BASE_URL}
        asr_api_key: ${DASHSCOPE_API_KEY}
        config_namespace: asr.video

  llm:
    video_text:
      target: openai
      params:
        llm_model: qwen-text
        llm_base_url: http://127.0.0.1:8000/v1
        llm_api_key: dummy
        llm_temperature: 0.0
        config_namespace: llm.video_text
    video_vision:
      target: openai
      # ... 同理,指向视觉模型

与本文主题相关的参数含义:

  • chunk_seconds(默认 30):视频按秒分片,供 VLM 逐片产出视觉摘要;
  • asr_chunk_seconds(默认 600):ASR 转录的分片时长;
  • vlm_max_inline_video_bytes(默认 50 * 1024 * 1024):允许内联进 VLM 的原始视频字节上限,见 video_normalizer.py#L30;
  • temp_root:视频流水线的临时工作目录,缺省走系统临时目录;
  • asr_port / llm_port / vlm_port:通过 VideoAsrProducer.dep / LlmProducer.dep 按名字解析下游插件,装配期缺依赖即报错。

VideoNormalizer 的产出是一段结构化的 JSON 文本投影(clips + events 两部分),包含 visual_summary、detailed_caption、ASR、environment 等字段(见 video_normalizer.py#L192-L220),同时 asset_uri 保留原始视频引用——这正是“规约投影 + 资产引用”双轨设计的落地形态。

已知遗留:当前边界与未来扩展点

设计文档诚实地记录了四个遗留项,也标明了未来演进方向:

  1. RawPayload.assets 仅是 list[str] 引用,不表达资产类型、存储状态或与 Segment 的结构化关系——后续可考虑引入结构化资产描述;
  2. 当前只有 SimpleIngestor,多 MemoryUnit / 多 Segment 的具体映射能力交给后续 Ingestor 实现,不在本次预先固化接口;
  3. data/uri 载体契约未完整覆盖:MemoryEngine.write 目前只对 Modality.VIDEO 把 content 写入 RawPayload.uri,其他模态写入 data——因此 modalities() 只决定“能不能进”,不能解决“数据放哪里”;新增其他外部 URI 模态前,需要单独补充显式的 data/uri 载体契约;
  4. 当前没有 DocumentNormalizer:PDF/Office 等文档原件不能通过 passthrough 解析,需在专用实现落地后再声明 DOCUMENT 能力。

小结

Assets 映射与 Normalizer 能力边界的设计,本质上是一次职责下放与契约澄清:资产如何进入记忆单元由 Ingestor 决定,模态是否被支持由 Normalizer 声明,Engine 退化为纯粹的防御性传递者,错误语义统一收敛到可诊断的 UnsupportedCapabilityError / ValidationError。这套边界既保护了自定义 Ingestor 的映射自由,也为后续多模态、分块、聚合型接入能力保留了清晰的扩展位。

登录后查看全文
agent-memory