video-analyzer 视频内容分析：一条命令，把任何视频变成一份可搜索的文字报告

video-analyzer 视频内容分析：一条命令，把任何视频变成一份可搜索的文字报告

【免费下载链接】video-analyzerAnalyze videos using LLMs, Computer Vision and Automatic Speech Recognition项目地址: https://gitcode.com/gh_mirrors/vi/video-analyzer

video-analyzer 是一个开源的视频内容分析工具，只需一条命令，就能自动提取视频关键帧、转写全部语音，并借助视觉大模型生成结构化的内容报告。它把"看画面、听声音、组织语言"三件事全部交给 AI，让一段无法检索的视频，变成一份随时可读、可搜、可复用的文字档案。

先讲一个"找东西"的尴尬故事

去年夏天，某电商团队接到一个看似简单的任务：老板想确认，半年攒下的 60 多条产品演示视频里，究竟哪一条展示过"批量改价"功能。

听起来不难？把视频一条条拖进播放器、拖动进度条、快进、回放、再快进。两小时后，功能找到了，可这位同事已经再也不想点开任何视频。更让人窝火的是——这些素材她其实全都"看过"，画面里的每一个细节都真实存在，却像一盒没有目录的老磁带：内容都在，就是找不着。

这几乎是所有视频工作者的共同处境：视频记得一切，却说不出来。

它没法被搜索，没法被摘要，没法被快速理解。时间轴是它唯一的目录，而你要找的那一句话、那一帧画面，可能就藏在第 47 分钟和第 12 秒之间。

视频为什么总是"装傻"？差的就是一层"理解"

文档能检索、能划线、能摘录，是因为它生来就是文字。而视频是画面与声音交织的信息流，人看的时候能懂，机器却默认"看不懂"。

video-analyzer 想解决的，正是这层"懂"。它是一个视频内容分析工具，把一整段视频拆成两条线索：语音交给 Whisper 转写成带时间戳的文字，画面则提炼成若干关键帧；随后视觉大模型逐帧解读，每看一帧都带着前面所有帧的"笔记"，保证叙事连贯；最后把帧笔记和转录文本拼在一起，生成一段完整的视频描述。

整条流水线不需要你手动参与，一条命令跑到底：

看不懂这张图也没关系，你只需要记住结论：视频进去，报告出来。

10分钟跑通第一次视频内容分析：完整上手步骤

以一个本地运行的场景为例，全程三组命令。

第一步：拉代码、装依赖

git clone https://gitcode.com/gh_mirrors/vi/video-analyzer cd video-analyzer python3 -m venv .venv source .venv/bin/activate pip install .

别忘了先装好 FFmpeg（Ubuntu 执行sudo apt-get install ffmpeg，macOS 执行brew install ffmpeg），它是音频提取的底层依赖。

第二步：拉起本地视觉模型

ollama pull llama3.2-vision ollama serve

默认方案走 Ollama 本地推理，数据不出本机、无需任何 API Key。机器显存不够？后面有替代方案。

第三步：运行分析

video-analyzer demo_video.mp4

喝杯咖啡的工夫，output/analysis.json就会出现在你的目录下。

打开 analysis.json：看看 AI 替你"看"到了什么

这份报告是标准的 JSON，包含四个板块，完整示例可参考项目里的 docs/sample_analysis.json：

• 技术元数据：记录客户端、视觉模型、Whisper 模型、处理帧数等运行信息，方便复现与审计；
• 语音转录：全文文本加带时间戳的段落切分，能精确定位任意一句话发生的时刻；
• 逐帧解析：每一帧的场景、动作、新增信息与前后文衔接点，构成完整的画面叙事；
• 视频描述：综合画面与语音的最终结论，直接回答"这段视频到底讲了什么"。

这份产出既是给人读的摘要，也是能被其他程序消费的数据接口。做内容检索、素材归档、自动剪辑，它都能当现成的数据底座。📊

五个高频疑问，一次说清

Q1：没显卡、显存不够，还能用吗？能。切换到 OpenRouter 等 OpenAI 兼容接口即可，比如用 llama 3.2 11b vision 的免费档位，把"看画面"交给云端，本地只负责跑转写。

Q2：语音转写不准怎么办？--whisper-model large换更大模型，--device cuda用 GPU 加速。它的"质量自检"机制会在语音模糊时主动降低转录结果权重，而不是硬塞一段错误百出的文字进结论。

Q3：一小时的长视频，处理会不会很久？--max-frames可以限制分析帧数，候选帧会均匀铺满整段视频；--duration可以只分析前 N 秒，先看效果再决定要不要跑完整片。

Q4：跑到一半断了，要重新来吗？不用。--start-stage 2可以从帧分析阶段续跑，跳过已完成的部分，断点续跑很省心。

Q5：必须联网吗？二选一。Ollama 本地模式完全离线；需要速度时再走 OpenAI 兼容接口。详细参数对照表在 docs/USAGES.md。

进阶玩法：让分析长出"眼睛和耳朵"

默认配置适合大多数场景，但工具真正的功力在于可调。

想让它聚焦特定维度？加一个--prompt：

video-analyzer demo_video.mp4 --prompt "视频中有哪些关键决策？"

你的问题会被注入逐帧分析与最终描述两个环节，引导模型往你要的方向使劲。指定语言用--language zh，跳过自动检测；想要更快的云端分析，加--client openai_api --api-key 你的Key --api-url 云端地址 --model 模型名。

再进一步，项目还附带了一个提示词自动调优模块 video-analyzer-tune：你先跑几条视频、手动改一改报告里"理想答案"的样子，它就会用 DSPy 的 MIPROv2 优化器自动找出更好的提示词指令，产出的新提示词文件通过配置指向即可，主包完全不受影响。相当于给分析工具请了一位"教练"。

三个最值得动的配置旋钮

需要微调时，打开 video_analyzer/config/default_config.json，最常动的是这三处：

配置遵循"命令行参数 > 用户配置文件 > 默认配置"的级联优先级，想临时覆盖某个值，直接加命令行参数即可，改坏了随时回退。

最后提醒三句避坑口诀：内存管够（本地跑视觉模型至少 16GB 内存，GPU 建议 12GB 显存以上）、先短后长（第一次先用几分钟的短片验证效果）、FFmpeg 别漏（装不上会在音频阶段直接报错）。

视频不该是只进不出的黑盒。现在就把手边那段一直没时间看的视频拖进命令行，跑出第一份属于你的视频内容分析报告——AI 当你的看片速记员，随叫随到。

【免费下载链接】video-analyzerAnalyze videos using LLMs, Computer Vision and Automatic Speech Recognition项目地址: https://gitcode.com/gh_mirrors/vi/video-analyzer