HMS多模态记忆深度解析:图片与视频长期记忆实战指南

原创2026-10-28 12:27:38155 阅读

HMS多模态记忆深度解析:图片与视频长期记忆实战指南

HMS(Holographic Memory System,全息记忆系统)是一款面向 AI 应用的长期记忆引擎,其多模态记忆能力可以把图片和视频转换成可召回的结构化记忆。本文带你吃透 HMS 多模态记忆的工作原理、启用配置,以及图片、视频长期记忆从上传到召回的完整实战路径。

HMS多模态记忆系统官方标识与全息记忆层结构示意图

一、HMS 多模态记忆是什么?

大多数 AI 应用的"记忆"只停留在文本层面:对话和文档可以被记住,但一张报错截图、一段操作录屏里的关键信息却随会话消失。HMS 的 openai_multimodal 文件解析器(默认关闭,属于可选启用的工程预览能力)解决了这个问题——它把图片或视频描述为带证据引用的标准化 Markdown 文档,再送入 HMS 既有的文档、分块、向量嵌入、标签与召回主链。

ShadowWeave 无限记忆网络意象图,象征 HMS 多模态记忆与文本记忆的连续链接

需要记住的四个关键结论:

  • 📷 它不是第二套记忆系统,而是一个"输入规范化层"。视觉描述进入与文本完全相同的存储和召回路径,既有的租户、标签、文档替换语义全部沿用;
  • 🎬 原始视频永远不会发给描述模型。HMS 在本地用 PyAV 解码、抽帧,只把选中的规范化图片帧 + 提示词交给 gpt-5-mini;
  • 🔒 音频轨道只记录"存在性"(provenance),不会转写、不会外发;
  • 🗄️ 当前运行时支持矩阵为 PostgreSQL。若配置 Oracle 后端并强制启用多模态,服务会快速失败(fail-fast),普通文本记忆能力不受影响。

二、从上传到召回:多模态记忆处理流水线

整条链路可以用下面这张流程图理解(引自 docs/multimodal_memory.md):

multipart 上传
  -> 有界读取、SHA-256 指纹、写入 FileStorage
  -> 本地媒体校验
       图片:EXIF 方向/色彩/尺寸归一化
       视频:PyAV 解码 + 确定性"场景切换 + 时间覆盖"抽帧
  -> OpenAI Responses API(gpt-5-mini,结构化输出)
  -> 严格 grounding 校验 + 系统级溯源
  -> 确定性 canonical Markdown
  -> 既有 HMS 分块 retain 管线
  -> 文档、嵌入、标签、链接、召回全部就位

HMS 全息记忆系统品牌图,展示多模态记忆的分层结构

设计上最值得学习的一点:所有不确定的事(模型描述)发生在"证据固定之后"。图片和帧先被本地规范化、哈希固定,之后无论模型怎么说,HMS 都能追溯到具体是哪一帧、哪个哈希支撑了哪条陈述。

三、图片长期记忆:本地校验与确定性归一化

图片管线在 core/dataplane/hms_api/engine/multimodal/images.py 中实现,流程对新手非常友好:

  1. 魔数识别:按文件头(magic bytes)识别 PNG / JPEG / WebP / GIF,绝不相信扩展名;声明的 MIME 或扩展名与解码结果不符时直接报 media.mime_mismatch / media.extension_mismatch;
  2. 安全预算:默认单图 20 MB、解码像素 4000 万,超限报 media.image_*_exceeded;
  3. 确定性归一化:应用 EXIF 方向、剥离全部源元数据、最长边压到 2048 像素,透明图保留 PNG、不透明图输出 JPEG。同样的字节 + 同样的配置,永远产出同样的归一化结果;
  4. 动图明确拒绝:动画 GIF 会被拒绝(media.animated_image_unsupported),而不是悄悄只描述第一帧——避免"记忆"静默失真。

归一化后的单张图片以 data URL 形式随提示词发送给描述模型,输出必须通过严格 JSON Schema,且每条陈述都要引用给定的证据 ID,无法凭空编造文件名、时间戳或人物关系。

四、视频长期记忆:本地抽帧与时间线覆盖

视频管线(core/dataplane/hms_api/engine/multimodal/video.py)是本模块最有意思的部分:

  • 抽帧预算 B:默认最多选 24 帧(HMS_API_MULTIMODAL_VIDEO_MAX_FRAMES)。采样器会按比例预留一部分槽位做时间线均匀覆盖(保住开头/中间/结尾),其余槽位按"视觉变化分 + 时间多样性"选出场景切换点——纯等间隔采样容易漏掉结尾一闪而过的报错,纯关键帧采样又会漏掉长镜头里的细节,混合策略两者兼顾;
  • 分批描述 + 文本归并:选中的帧按时间顺序切成每 8 帧一批,逐批生成带时间戳的 grounding 片段;随后一次纯文本 reducer 调用合并、排序这些已验证片段。reducer 不允许新增无依据的事实或捏造时间范围;
  • 输出一份带时间码的 Markdown 文档,时间区间与证据 ID 直接进入 chunk 文本,召回时天然可解释。

视频解码依赖 PyAV(可选依赖),需要额外安装:

cd core/dataplane
uv sync --extra multimodal-video

在 Docker 部署中,构建 API 镜像时需显式传入 --build-arg INCLUDE_MULTIMODAL_VIDEO=true,并保证 worker 与 API 使用同一镜像,否则解码能力可能不一致。

五、如何启用 HMS 多模态记忆:最小配置清单

所有多模态配置都是服务器静态配置,不能通过 bank 配置或上传请求绕过。核心环境变量如下(完整参考 docs/multimodal_memory.md):

HMS_API_ENABLE_FILE_UPLOAD_API=true
HMS_API_MULTIMODAL_ENABLED=true
HMS_API_MULTIMODAL_PROVIDER=openai
HMS_API_MULTIMODAL_MODEL=gpt-5-mini
HMS_API_MULTIMODAL_API_KEY=replace_with_secret
HMS_API_MULTIMODAL_IMAGE_ENABLED=true
HMS_API_MULTIMODAL_VIDEO_ENABLED=false   # 确认 PyAV 解码可用后再打开

⚙️ 三个新手最容易踩的坑:

  1. 不要用文本 LLM 的 key 顺手复用。描述器是独立数据出境角色,请单独审批媒体外发并配置专用密钥;
  2. 不要把 openai_multimodal 设为默认 parser。安全做法是把它加入 HMS_API_FILE_PARSER_ALLOWLIST,由客户端显式选择——否则服务器升级后,普通图片上传会突然开始产生模型费用;
  3. 修改这些配置后要重启 API 和全部 worker,然后用 GET /version?include_multimodal=true 协商能力,确认 multimodal_image / multimodal_video / multimodal_live_verified 三个字段的状态。

六、实战:上传图片/视频并轮询操作状态

上传走既有的 multipart 文件接口,只是多指定了一个 parser。以一张 IDE 截图为例:

curl -sS -X POST \
  "$HMS_BASE_URL/v1/default/banks/$HMS_BANK_ID/files/retain" \
  -H "Authorization: Bearer $HMS_API_KEY" \
  -F 'files=@./ide-session.png;type=image/png' \
  -F 'request={"parser":"openai_multimodal","files_metadata":[{"document_id":"ide-image-001","context":"IDE implementation session","tags":["ide","image"]}]}'

响应返回一个文件转换操作 ID,之后轮询该操作即可。多模态操作的 result_metadata.multimodal 命名空间里有几个对自动化非常友好的类型化字段:

字段 含义
stage 当前阶段(如 retain_queued、recall_ready、retain_failed)
child_retain_status 子 retain 操作状态
recall_ready 只有为 true 才能停止轮询——父操作 completed 仅代表转换成功、子 retain 已入队
sanitized_error_code / retryable 面向自动化的错误码与可重试标记,不要解析人类可读错误消息
logical_calls / physical_attempts / input_tokens / output_tokens 实际消耗,便于对账

如果上传时不提供 document_id,HMS 会基于租户/bank + 原始资产 SHA-256 派生一个不透明 ID:同一银行内字节级重试会收敛到同一个逻辑文档,跨银行则互不干扰——天然的去重语义。

七、实战:召回图片与视频记忆

recall_ready=true 之后,用普通召回接口即可,无需任何特殊参数:

curl -sS -X POST "$HMS_BASE_URL/v1/default/banks/$HMS_BANK_ID/memories/recall" \
  -H "Authorization: Bearer $HMS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"Which test failed in the IDE session, and what changed afterward?",
       "include":{"chunks":{}},
       "tags":["ide","video"],"tags_match":"all_strict"}'

召回结果的元数据中会携带一组有界、扁平的系统溯源字段(media_kind、media_pipeline_version、media_pipeline_fingerprint、media_source_available 等),视频的时间范围与证据 ID 则直接位于 chunk 文本中。用户自定义 metadata 不要占用 media_* 前缀——冲突时以服务器生成的溯源为准。

八、成本、隐私与安全边界

  • 💰 成本有确定性上界:默认配置下单张图最坏 6 次物理尝试、24,576 输出 token;24 帧视频为 3 次 map + 1 次 reduce,最坏 24 次尝试、98,304 输出 token。这是安全上界而非预期用量,成功请求通常远低于此。相同资产在 7 天 TTL 内命中描述检查点可免去重复调用;
  • 🔐 隐私设计:每个 Responses 请求都设置 store:false;data URL 绝不进入任务负载、操作元数据、日志或通用 tracing;不做人脸识别与受保护属性推断。注意 store:false 不等于 OpenAI 零数据保留,启用前请按 docs/multimodal_memory.md 的清单完成数据出境审批;
  • 🧹 源文件生命周期:默认 HMS_API_FILE_DELETE_AFTER_RETAIN=true,转换完成后删除原始字节(召回元数据记 media_source_available=false),但派生记忆与溯源永久保留;
  • ⚠️ 常见错误码:media.animated_image_unsupported(动图)、media.video_decoder_unavailable(缺 PyAV 解码器)、provider.rate_limited(可重试的限流)、provider.refusal(安全拒答,不要当 JSON 错误处理)。一个视频的任一必需片段失败即整体失败,HMS 不会保留残缺的视频描述。

九、延伸阅读:文档与源码路径

资料 路径
多模态运维合同(配置/错误/验证全量参考) docs/multimodal_memory.md
系统架构与多模态主链详解 docs/system_architecture_and_multimodal.md
多模态引擎源码(图片/视频/Provider/账本/安全) core/dataplane/hms_api/engine/multimodal/
canonical OpenAPI(含多模态能力字段) knowledge/site/static/openapi.json
离线契约测试 core/dataplane/tests/test_multimodal_image.py、core/dataplane/tests/test_multimodal_video.py

一句话总结:HMS 多模态记忆的本质是**"先把视觉证据固定成可审计的文本,再复用整个长期记忆主链"**。理解了这一点,你就能快速判断哪些素材适合长期记忆、哪些配置项影响成本与召回质量,并在新项目中稳妥地落地图片与视频的长期记忆能力。

登录后查看全文
HMS