HMS多模态记忆深度解析:图片与视频长期记忆实战指南
HMS多模态记忆深度解析:图片与视频长期记忆实战指南
HMS(Holographic Memory System,全息记忆系统)是一款面向 AI 应用的长期记忆引擎,其多模态记忆能力可以把图片和视频转换成可召回的结构化记忆。本文带你吃透 HMS 多模态记忆的工作原理、启用配置,以及图片、视频长期记忆从上传到召回的完整实战路径。
一、HMS 多模态记忆是什么?
大多数 AI 应用的"记忆"只停留在文本层面:对话和文档可以被记住,但一张报错截图、一段操作录屏里的关键信息却随会话消失。HMS 的 openai_multimodal 文件解析器(默认关闭,属于可选启用的工程预览能力)解决了这个问题——它把图片或视频描述为带证据引用的标准化 Markdown 文档,再送入 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 都能追溯到具体是哪一帧、哪个哈希支撑了哪条陈述。
三、图片长期记忆:本地校验与确定性归一化
图片管线在 core/dataplane/hms_api/engine/multimodal/images.py 中实现,流程对新手非常友好:
- 魔数识别:按文件头(magic bytes)识别 PNG / JPEG / WebP / GIF,绝不相信扩展名;声明的 MIME 或扩展名与解码结果不符时直接报
media.mime_mismatch/media.extension_mismatch; - 安全预算:默认单图 20 MB、解码像素 4000 万,超限报
media.image_*_exceeded; - 确定性归一化:应用 EXIF 方向、剥离全部源元数据、最长边压到 2048 像素,透明图保留 PNG、不透明图输出 JPEG。同样的字节 + 同样的配置,永远产出同样的归一化结果;
- 动图明确拒绝:动画 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 解码可用后再打开
⚙️ 三个新手最容易踩的坑:
- 不要用文本 LLM 的 key 顺手复用。描述器是独立数据出境角色,请单独审批媒体外发并配置专用密钥;
- 不要把
openai_multimodal设为默认 parser。安全做法是把它加入HMS_API_FILE_PARSER_ALLOWLIST,由客户端显式选择——否则服务器升级后,普通图片上传会突然开始产生模型费用; - 修改这些配置后要重启 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 多模态记忆的本质是**"先把视觉证据固定成可审计的文本,再复用整个长期记忆主链"**。理解了这一点,你就能快速判断哪些素材适合长期记忆、哪些配置项影响成本与召回质量,并在新项目中稳妥地落地图片与视频的长期记忆能力。


