DeepSeek V4-Flash Vision Video RAG
让 AI 真正”看懂” 一段视频，然后你对它提问：它告诉你答案、答案发生在 第几分几秒 ，并切出那一段的 可播放片段 和关键帧给你核对。
基于 DeepSeek 视觉大模型 deepseek-v4-flash-vision-exp 的视频理解与问答 （video RAG）agent skill。先按时间轴抽帧阅读、建立索引（一次性），再对问题做 本地粗筛 → 视觉精排 → 深读回答；回答带 [MM:SS] 时间戳引用，自动生成 自包含 HTML 预览页 （内嵌可播放片段 + 关键帧 + 答案），双击浏览器即看。
模型没有音频模态：一切理解基于画面，音轨会被忽略。
使用方法简单： 直接在 codex/workbuddy等下载，然后发送视频给 skill技能，命令完成理解视频 和回答各种问题则可以！
一、它能做什么
| 你说 | 它做 |
|---|---|
| ”帮我看看这段录像” | 抽帧阅读全片，建立时间轴索引（一次性，30 秒视频约 30 秒） |
| “这段视频讲了什么？“ | 按时间顺序总结剧情/事件 |
| ”爆炸是几点几分发生的？“（00:15） | 定位事件时刻 + 切出该时刻前后 5 秒可播放片段 |
| ”玩家瞄准有什么问题？“ | 深读 + 自动升级微观层 （12fps 中心放大）逐帧分析动作 |
| ”画面里出现过哪些文字？“ | 帧级 OCR 汇总（招牌/字幕/HUD） |
| “给我看 00:07 那一帧” | 高清渲染该时刻帧图 |
二、实测效果（两个自带 ground truth 的视频）
| 测试 | 结果 |
|---|---|
| 猫和老鼠 31.5s： “猫为什么被炸？“ | 完整还原因果链：老鼠从 GLUE 罐刮胶水涂在炸药上→放到猫身边→猫点燃→爆炸。与人工确认的剧情一致 |
| 猫和老鼠： “最后一幕猫什么状态？" | "被’种’在花盆里、头埋土中、顶着花、房子墙根草地上”——与 ground truth 吻合 |
| CS2 27s： “有几次击杀？“ | 3 次 ，与该仓库 coach_report.md 的人工结论一致；时刻 [00:03][00:13]（1fps 估计 ±2s） |
| CS2： “瞄准细节有什么问题？“ | 微观层自动触发，输出逐帧动作链：敌人 1.67s 露头→2.50s 开火→2.58s 击杀，并给出预瞄偏移、无目标扫射、移动开枪、弹匣管理 4 项问题 |
| 索引速度 | 32 帧/26 秒、27 帧/30 秒（含上传与 2 次批量分析） |
| 提问成本 | 常规 2 次调用；动作类问题 3 次（+微观） |
三、工作原理（通俗版）
和 PDF 版同一个思想： 先读一遍做笔记，之后按笔记翻书 ——只是”页”变成了 “时间段”，“页码”变成了”时间戳”。
第一阶段：看一遍视频，做卡片（ingest，一次性）
视频 ──ffmpeg 抽帧──> 按时间顺序的 JPEG 序列 ──上传──> DeepSeek 文件服务器
│
↓
视觉模型逐帧"观看"（25 帧/批，prompt 声明采样率与时间轴）
↓
index.json：每帧一张卡片 + 段卡片 + 场景切换时间点
第 2 秒的真实卡片：
{"t": 2.0, "scene": "室内鼠洞",
"summary": "老鼠正伸手去够一个绿色胶水罐，罐子上写着GLUE，旁边有一根红色蜡烛。",
"keywords": ["老鼠", "胶水", "GLUE"], "ocr": "GLUE",
"event": "老鼠开始触碰胶水罐", "motion": "中"}
每帧 6 个字段：场景、画面摘要、关键词、可见文字（OCR）、相对前帧的事件、 运动强度 。卡片按 30 秒一段聚合成”段卡片”，加上本地 ffmpeg 场景切换检测， 构成整个索引。 从此这段视频就被”看过了”，不用再看第二遍全片。
第二阶段：按卡片定位，回答问题（ask，每次 2~3 次调用）
你的问题
↓ ① 查卡片 本地 TF-IDF 筛出最可能的段（毫秒级、零费用）
↓ ② 看图确认 模型看候选段代表帧，选出真正相关的段（1 次调用，关推理）
↓ ③ 深读作答 选中段的全部帧按时间轴摊开，开推理观看，论点标 [MM:SS]（1 次调用）
↓ ④ 微观放大 （仅动作类问题）对运动最强的引用时刻抽 12fps 中心放大逐帧分析
↓
答案（带 [MM:SS] 引用）+ 该时刻关键帧 + ±5s 可播放片段 + HTML 预览
为什么微观层是视频特有的关键 ：一次甩枪只有 150–250 毫秒，1fps 的宏观帧 必然漏掉。所以平时省着看（1fps），遇到”瞄准/动作/瞬间”类问题，自动对该时刻 用 12fps + 中心放大重抽一遍——这是参考项目用真实 API 探针验证出的两级采样策略。
四、与 PDF 版（deepseek-v4-flash-vision-rag）的同构与差异
| PDF 版 | 视频版 | |
|---|---|---|
| 检索单元 | 物理页 | 时间段（30s/段） |
| 引用格式 | [第N页] | [MM:SS] （1fps 估计，±2s） |
| 免费文本层 | PyMuPDF 抽取 | 帧卡片 OCR 汇总 |
| 输入单元 | 每页一张渲染图 | 按时间轴抽帧（密度自适应） |
| 特有机制 | — | 两级采样 + 微观层自动升级 |
| 回显 | 页图 | 关键帧 + 可播放片段 + HTML 内嵌 <video> |
| 深读预算 | max_tokens 8192 | 32768 （实测 reasoning 更贪吃，8192 会空回复） |
五、快速上手
依赖： openai + ffmpeg/ffprobe 在 PATH 。API key 不内置在代码里（skill 可公开分发）： 设置环境变量 DEEPSEEK_API_KEY ，或把 key 写入 ~/.deepseek_api_key 文件首行（仅本机）。
1. 建索引（每份视频一次）
python scripts/ingest.py "比赛录像.mp4"
采样密度自动适配：≤1 分钟→1fps；≤10 分钟→0.5fps；≤30 分钟→0.25fps；更长→0.1fps。 --fps 2 手动指定； --limit-frames 30 先试水； --force 重建； --clean 清缓存。
2. 提问
python scripts/ask.py "比赛录像.mp4" "第二次团战是怎么输的？"
输出： === 答案 === （带 [MM:SS]）、 === 引用时刻 === 、 === 关键帧 === 、 === 可播放片段 === 、 === 预览 === （HTML 路径）。 参数： --top 3 深读段数｜ --micro 00:04-00:07 强制微观窗口｜ --no-micro 禁用。
3. 直接看某时刻
python scripts/show.py "比赛录像.mp4" --at 01:23 # 该时刻帧
python scripts/show.py "比赛录像.mp4" --clip 01:20-01:30 # 可播放片段
python scripts/show.py "比赛录像.mp4" --micro 01:25 # 12fps 中心放大序列
六、目录结构
deepseek-v4-flash-vision-video-rag/
├── SKILL.md # skill 入口：触发条件 + agent 工作流
├── README.md # 本文件
├── scripts/
│ ├── ds_client.py # API 客户端（推理开关/重试/JSON修复/上传）
│ ├── ingest.py # 阶段一：抽帧→上传→帧卡片→段聚合→缓存
│ ├── ask.py # 阶段二：粗筛→精排→深读→微观→HTML预览
│ └── show.py # 时刻帧/片段/微观序列导出
├── references/
│ ├── video-sampling.md # 两级采样与 API 踩坑（改代码前必读）
│ └── index-schema.md # 索引结构、提示词、实现约定
└── .cache/<sha>/ # 索引缓存（可随时删）
├── index.json files.json frames/ micro/
产出文件在运行目录 video-vision-out/ ： <名>_t0007.jpg （关键帧）、 <名>_clip0007.mp4 （片段）、 <名>_<问题>.html （自包含预览）。
七、成本账
| 操作 | API 调用 | 图片 token |
|---|---|---|
| 索引 30s@1fps | 2 批次 + 32 上传 | ≈6k |
| 常规提问 | 2 次 | ≈1~1.2 万 |
| 动作类提问（+微观） | 3 次 | ≈2 万 |
长片线性外推：10 分钟@0.5fps = 300 帧 ≈ 11.5 万 token，一次索引、永久复用。 同批帧二次发送命中 prompt 缓存（实测 71s→4.8s），迭代调优很便宜。
八、常见问题
Q：为什么不直接把视频文件传给模型？ 视觉模型没有”视频模态”。实测 GIF 只解码首帧（黑帧探针证实）；唯一正确方式是 按时间顺序的 JPEG 帧序列 + prompt 声明时间轴。这就是本 skill 存在的意义。
Q：能分析声音吗？ 不能。模型只看画面。音轨可用于本地定位（如枪声能量峰值），但”听到了什么” 回答不了——我们会如实说明而不是编造。
Q：事件时刻精确吗？ 宏观 1fps 的时间戳误差 ±2s；追问快速动作会自动升级 12fps 微观层（~0.08s 粒度）； 要绝对精确请直接播放切出的片段核对。
Q：监控录像几小时怎么办？ 自动降到 0.1fps（10s/帧）建宏观索引，事件级问题仍可定位到分钟； 关键时段用 --micro 或 show.py --clip 精查。超长视频建议分段 ingest。
Q：和 PDF 版 skill 什么关系？ 同构的姊妹项目（同一模型、同一”卡片索引”思想、同一套 API 封装），一个面向 文档页，一个面向视频时间轴。可以共存，触发词不同。
九、已知局限
- 无音频理解；OCR 对 <20px 的小字（如 killfeed 图标文字）不可靠，只作事件线索
- 1fps 采样漏 150ms 级瞬时事件（微观层可补救但需触发）
- HTML 预览内嵌片段上限 3 段（控制体积，单文件通常 5~15MB）
- 极长视频（>30min）宏观索引会明显变粗，建议分段处理