cdaf

这是什么？适合谁？

CDAF（UditAkhourii/cdaf，Cached Descriptive Asset Files）是一个开源视频侧车文件格式，解决 AI Agent 处理视频时「反复重分析同一段视频」造成的 token 浪费。

问题：当多个 Agent 或同一个 Agent 的多次会话都要理解同一段视频时，每次都重新把视频喂给视觉模型做帧分析——既慢又烧钱。CDAF 的做法是：第一次分析视频后，把描述性结果缓存成一份侧车文件，之后任何 Agent 直接读缓存，不必重新解析视频。

核心价值：把「视频理解」从重复计算变成一次计算、多次复用，显著降低视频场景的 token 与延迟成本。

适合人群：

• 构建视频理解 / 视频问答 Agent 的开发者
• 需要批量处理大量视频、又不想为每个视频反复付费的团队
• 关注「Agent 基础设施标准化」的研究者（含可复现基准）

使用前提：Python 环境；有视频处理 / 视觉模型调用需求；理解「侧车文件」= 与视频并存的描述性元数据文件。

准备工作

1. Python 3.10+：CLI 用 Python 编写。
2. 成本：MIT 开源，完全免费；真正的开销来自你调用的视觉模型。
3. 视频素材：准备一段用于测试的视频文件。
4. 时间预算：安装 + 跑通第一个缓存流程约 15 分钟。
5. 学术关联：仓库附 Zenodo 记录（zenodo.org/records/22110594），便于引用与复现。

快速上手（3 步）

第一步：安装

git clone https://github.com/UditAkhourii/cdaf
cd cdaf
pip install -r requirements.txt   # 具体依赖以 README 为准

第二步：为视频生成侧车文件

python cdaf.py analyze video.mp4 --output video.cdaf

工具调用视觉模型分析视频，产出描述性缓存文件（关键帧、场景、对象、时间戳等结构化描述）。

第三步：让 Agent 读缓存而非重分析

后续任何 Agent 任务直接读取 video.cdaf，跳过重复的视频重分析。

成功判定：同一段视频第二次处理时，不再发起视觉模型调用，而是从 .cdaf 缓存直接加载描述，耗时与 token 显著下降。

初级用法

侧车文件里有什么

• 结构化描述：场景、对象、动作、对话等语义信息
• 时间戳对齐：描述与视频时间轴对应，便于按片段检索
• 可复用元数据：一次生成，多个 Agent 共享

Spec + CLI + Skill 三件套

仓库提供格式规范（Spec）、命令行工具（CLI）与 Agent Skill 封装，方便把「生成缓存 → 读取缓存」接入现有 Agent 工作流。

高级玩法

批量视频预处理

对视频库批量跑 analyze，一次性建好全部侧车文件，后续所有 Agent 任务都走缓存路径，成本只付一次。

可复现基准

仓库带可复现基准（配合 Zenodo 记录），可以量化「用缓存 vs 不用缓存」在 token / 延迟上的差异，用于说服团队采纳。

接入 Agent Skill

用仓库提供的 Skill 封装，让 Claude Code / Codex 等 Agent 自动在需要时生成与读取 .cdaf 文件，无需人工干预。

小技巧

1. 缓存粒度按需：侧车文件可按「整段视频」或「按片段」粒度生成，根据检索需求选择。
2. 先测基准再推广：用仓库基准先量出节省比例，再决定覆盖范围。
3. 时间戳对齐很关键：确保描述带时间戳，按片段检索才有效。
4. Zenodo 引用：学术用途可引用 Zenodo 记录保证可复现性。
5. 版本管理：视频更新后需重新生成缓存，避免描述与画面漂移。

常见踩坑

踩坑 1：视频变了但缓存没更新

• 现象：Agent 读到的描述与视频实际内容不符。
• 原因：视频文件被替换/剪辑后，旧 .cdaf 仍指向旧描述。
• 解决：视频内容变更后必须重新 analyze 生成新缓存。

踩坑 2：以为缓存零成本

• 现象：首次生成缓存仍要付视觉模型调用费。
• 原因：缓存省的是「重复分析」，不是「第一次分析」。
• 解决：只有多次复用同一视频时收益才明显；一次性处理无节省。

踩坑 3：格式不兼容

• 现象：别的工具读不了 .cdaf。
• 原因：这是新格式，生态尚未普及。
• 解决：确认下游工具支持；必要时按 Spec 自行转换。

踩坑 4：大视频缓存文件膨胀

• 现象：侧车文件过大拖慢加载。
• 原因：描述粒度太细、关键帧太多。
• 解决：按需求调整粒度，只保留必要的关键帧与语义。

踩坑 5：忽略视觉模型差异

• 现象：换模型后缓存质量/格式漂移。
• 原因：不同视觉模型输出风格不同。
• 解决：固定模型版本，或重新生成缓存保持一致性。

常见问题 FAQ

Q1: CDAF 和普通视频转写（transcription）有什么区别？

A: 转写只覆盖语音文本；CDAF 侧车文件是更广的「描述性资产」，可包含视觉场景、对象、动作等多模态语义，并带时间戳对齐。

Q2: 它省的是什么钱？

A: 省的是「重复视频理解」的视觉模型 token 与延迟。同一视频被多个 Agent / 多次会话复用时收益最大。

Q3: 需要联网吗？

A: 生成缓存需要调用视觉模型（可能联网）；读取缓存是本地操作。

Q4: 支持哪些视频格式？

A: 具体支持列表以仓库 Spec 为准，常见视频格式通常可处理。

Q5: 现在是稳定版吗？

A: 项目较新（2026-08 创建），带可复现基准但尚未大规模生产验证，生产使用前先跑通端到端。

进阶学习建议

掌握基础后，建议深入：

1. 视频库缓存流水线：把「批量 analyze → 缓存入库 → Agent 读缓存」做成定时 pipeline，视频理解成本只付一次。
2. 缓存失效策略：建立「视频 hash → 缓存版本」的映射，视频变更自动触发重新分析。
3. 可复现成本报告：用仓库基准方法产出「缓存前后 token/延迟对比」报告，量化 ROI。

参考链接

• 官方仓库
• Zenodo 记录

最后更新：2026-08-28 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成