| name | deepseek-v4-flash-vision-video-rag |
| description | 基于DeepSeek视觉大模型(deepseek-v4-flash-vision-exp)的视频理解与问答(video RAG)。当用户提到视频、录像、mp4、监控、游戏录像、影片、动画,并想提问、查找、定位、总结或理解其内容,或问"什么时候发生的""某一秒在干什么"、要时间戳定位、片段回放时,使用本skill。支持剧情理解、事件时间线、OCR字幕/HUD识别;回答带 [MM:SS] 时间戳引用,并生成可播放片段与关键帧展示给用户。无音频分析能力。 |
DeepSeek V4-Flash Vision Video RAG
让视觉大模型"看懂"一段视频:先把视频按时间轴抽帧阅读、建立索引(一次性、缓存
复用),再对用户问题做 本地粗筛 → 视觉精排 → 深读回答,回答带 [MM:SS] 时间戳
引用,并自动切出可播放片段、关键帧和自包含 HTML 预览。
模型没有音频模态——所有理解基于画面;音频轨会被忽略(如实告知用户)。
环境要求
- Python 依赖:
openai(本机已装)
- ffmpeg / ffprobe 必须在 PATH(本机已装;缺了先安装)
- API key:从环境变量
DEEPSEEK_API_KEY 或本机 ~/.deepseek_api_key 文件(首行)读取,
代码中不内置任何密钥;缺失时报错并给出设置指引
- 脚本在
scripts/ 下,Windows 直接 python scripts/xxx.py
工作流
第 1 步:建立索引(每份视频一次,之后走缓存)
python scripts/ingest.py "<视频路径>"
- ffprobe 元数据 → 宏观抽帧(≤60s→1fps,≤10min→0.5fps,≤30min→0.25fps,更长→0.1fps,
--fps 可覆盖)→ Files API 上传 → 25 帧/批视觉卡片 → 段聚合(30s/段)→ 本地场景切换检测
- 30s 视频约 30 秒完成;重复运行直接命中缓存
- 常用参数:
--force 重建|--limit-frames N 先试前 N 帧|--clean 清缓存
- 输出打印帧卡片数/段数/场景切换/运动统计,可据此向用户简报视频概况
第 2 步:回答用户问题
python scripts/ask.py "<视频路径>" "用户的问题"
- 本地粗筛(TF-IDF,零费用)→ 视觉精排选 top3 段(1 次调用,关推理)→ 深读选中段
全部帧(1 次调用,开推理,max_tokens=32768)→ 带
[MM:SS] 引用的回答
- 微观层自动触发:问题含动作类词(瞄准/击杀/瞬间/轨迹…)且深读有引用时,
对运动最强的引用时刻抽 12fps 中心放大帧追加一次分析(+1 次调用);
--micro 00:04-00:07 强制指定窗口,--no-micro 禁用
stdout 分段:=== 答案 ===、=== 引用时刻 ===、=== 关键帧 ===、
=== 可播放片段 ===(均为 ./video-vision-out/ 下文件)、=== 预览 ===。
第 3 步:向用户展示(必须做)
终端里用户未必能看到 inline 图片/视频,必须给出可自行打开的路径,按优先级:
- HTML 预览(首选):
./video-vision-out/<视频名>_<问题>.html —— 自包含单文件,
答案 + 引用时刻的可播放片段(base64 内嵌 <video>)+ 关键帧,双击浏览器打开。
Windows 下可代用户执行 start "<路径>"
- 单独的片段 mp4 / 关键帧 jpg 路径:用户只要某个时刻时逐个给出
- 支持 inline 的环境可再 Read 图片作补充,但不得只依赖它
用户想直接看某个时刻/片段:
python scripts/show.py "<视频路径>" --at 00:07
python scripts/show.py "<视频路径>" --clip 00:05-00:12
python scripts/show.py "<视频路径>" --micro 00:04
回答规范
- 以脚本产出的答案为事实基础,保留
[MM:SS] 时间戳引用标记
- 时刻引用是 1fps 采样的估计值(误差 ±2s),涉及精确时机时提醒用户以片段回放为准
- 答案说"帧内容不足"时如实转告,不要编造;音频相关请求明确说明无音频能力
- 展示时必须给 HTML 预览或媒体文件路径,不能只靠 inline 展示
注意事项
- 首次 ingest 慢是正常的;之后每次提问 2~3 次调用
- 深读/微观用 max_tokens=32768(开推理时 reasoning 计入预算,小了会得到空回复)
- 视频抽帧与采样依据实测最佳实践(GIF 不可用、两级采样、detail=low 禁用等),
详见
references/video-sampling.md;索引结构见 references/index-schema.md
- 改
scripts/ds_client.py 前先读 references/video-sampling.md 的踩坑清单