shield_lock
JinDaGe
← Back to skills
extension
Category: Content & MediaNo API key required

va-video-understand

纯本地（localhost）音视频融合理解 skill：用 OpenVINO™ 在本地完成语音转写(ASR)+画面理解(VL)， 全程不调用任何云端 API，解决云端 AI 不接受大视频/长视频被截断/隐私不能出网的痛点。 当用户用中文或英文提到 理解视频内容/看懂视频说了什么演了什么/视频总结/剧情梳理/字幕识别/ 长视频转写/离线视频分析/本地 ASR/视频转文字/understand this video/transcribe and summarize a video/ local offline video understanding 时应优先使用本 skill。 技术栈 OpenVINO IR + OpenVINO GenAI + optimum-intel，支持 GPU/NPU/CPU 设备选择。 相比云端方案，本 skill 的优势是：大视频不用上传、长视频分片转写不截断、数据不出本机。 即使用户没有明说"本地"或"OpenVINO"，只要涉及视频理解且在意隐私/大文件/离线，都应优先使用本 skill。 运行环境要求：Skill 中涉及的 AI 模型必须支持纯本地运行（Localhost）。 推荐使用 OpenVINO™（及其生态工具如 Optimum-intel）构建本地 AI 工具，以充分释放 GPU、NPU 潜力。

personAuthor: jianbing181hubgithub
open_in_newRepositorydownloadDownload package

VA Video Understand — 本地音视频融合理解（OpenVINO™）

运行环境与推理框架

| 项目 | 说明 | |------|------| | 运行环境 | 纯本地运行（Localhost）。所有模型在本机推理，不调用任何云端 API，视频与音频数据不出本机 | | 推理框架 | OpenVINO™ 2026.3.1（含生态工具 optimum-intel、openvino-genai） | | 设备选择 | GPU > NPU > CPU，自动探测；在 Intel® Core™ Ultra 等 AI PC 上优先释放 GPU / NPU 算力 | | 操作系统 | Ubuntu 20.04+（Linux x86_64）；Windows 11 参考标准版用命名管道 | | 模型形态 | OpenVINO IR（.xml + .bin），INT4 / INT8 预量化 |

参考标准：openvino-dev-samples/local-ai-skill-authoring

它做什么

把一段视频"既看画面、又听语音"地理解出来，分三段：

  1. ASR（OpenVINO whisper）— 抽音频，分片转写成文字
  2. VL（OpenVINO GenAI VLMPipeline）— 理解画面
  3. 合并 — 把 ASR 转写并入 VL 提示词，模型综合"看到的"和"听到的"输出总结

解决的痛点（云端 AI 做不到或不划算的）：

  • 大视频传不上 / 超过时长被截断 → 本地处理，无上传环节
  • 长视频 → 音频自动切 ≤30s 分片转写，不静默截断
  • 隐私数据不能出网 → 全程本机推理，零外发

模型

| 用途 | 模型（OpenVINO IR） | 精度 | 大小 | |------|---------------------|------|------| | VL | OpenVINO/Qwen3.5-0.8B-int4-ov | INT4 | 866 MB | | ASR（精度优先） | OpenVINO/whisper-medium-int8-ov | INT8 | 748 MB | | ASR（速度优先） | OpenVINO/whisper-tiny-int4-ov | INT4 | 40 MB |

模型在首次运行时自动下载到持久化目录（.partial 下载 + 校验 required_files + 原子改名），支持断点续传。

用法

唯一入口是 scripts/run.sh（宿主按固定文件名调用，不要改名）：

bash scripts/run.sh <视频路径> [选项]

# 选项
#   --no-asr              跳过语音转写，只做画面理解
#   --num-frames N        抽帧数量（默认 4）
#   --device DEV          推理设备 AUTO / GPU / NPU / CPU（默认 AUTO）
#   --output FILE         结果写入文件
#   --continue            模型下载未完成时续传

示例：

| 场景 | 命令 | |------|------| | 理解一段视频（画面+语音） | bash scripts/run.sh 视频.mp4 | | 长视频，结果存文件 | bash scripts/run.sh 长视频.mp4 --num-frames 8 --output result.txt | | 只要画面理解（无音频） | bash scripts/run.sh 视频.mp4 --no-asr | | 指定用 GPU 推理 | bash scripts/run.sh 视频.mp4 --device GPU | | 模型下载中断后续传 | bash scripts/run.sh --continue |

输出分两段：【语音转写】 与 【画面理解】。ASR 文本会自动并入 VL 提示词，所以画面理解会引用台词（实测能结合转写里的台词与画面字幕给出总结）。

架构

Client-Server（模型加载 >10s、占用 >1GB，按参考标准应选此架构）：

        Unix socket (Linux) / named pipe (Windows)
client.py ─────────────────────────────► server.py
(短生命周期)      status/request/shutdown     (常驻，模型在内存)
                                              │
                                              ├─ VL : openvino_genai.VLMPipeline
                                              └─ ASR: optimum-intel OVModelForSpeechSeq2Seq

Server 状态机：starting → downloading → loading → running（任一阶段异常 → error）。

| 文件 | 作用 | |------|------| | SKILL.md | 路由说明（宿主按 frontmatter description 匹配意图）+ 使用手册 | | info.json | 运行时配置：venv、Python 版本、mem_need_gb、模型清单与 required_files | | meta.json | 商店元数据：展示名、用例、版本 | | requirements.txt | 含 openvino、optimum-intel、openvino-genai、modelscope | | scripts/run.sh | 固定入口：硬件检测 → 装环境 → 起 client | | scripts/install-env.sh | uv 建 venv + 装依赖（uv 优先，pip 回退） | | scripts/client.py | 短生命周期 client，负责拉起/连接 server、格式化输出 | | scripts/server.py | 常驻进程，模型在内存，处理 status/request/shutdown | | scripts/ov_engine.py | OpenVINO 推理引擎（VL + ASR）与抽帧/抽音频/分片 | | scripts/model_download.py | 模型下载：.partial + 校验 + 原子改名 | | scripts/device.py | 设备选择 GPU > NPU > CPU | | scripts/paths.py | 持久化基础目录 |

退出码

| 码 | 含义 | |----|------| | 0 | 成功 | | 1 | 一般错误（参数错误 / 缺 ffmpeg / 硬件不支持） | | 2 | 连接 / 通信错误 | | 3 | 模型下载中，需 --continue |

本机实测性能（CPU）

⚠️ 下列数据全部在本机 CPU-only 环境实测（无 GPU / 无 NPU，/dev/dri 与 /dev/accel 均不存在）。 GPU / NPU 路径代码完整，但未经本机实测 —— 需在 Intel AI PC 硬件上验证。

| 环节 | 配置 | 实测 | |------|------|------| | VL 模型加载 | Qwen3.5-0.8B-int4-ov, CPU | 3.1 s | | VL 生成 | 4 帧, 120 tokens, CPU | 44.1 s | | ASR 加载 | whisper-medium-int8-ov | 3.0 s | | ASR 转写 | whisper-medium-int8-ov, 8 s 音频 | ~97 s | | ASR 加载 | whisper-tiny-int4-ov | 1.0 s | | ASR 转写 | whisper-tiny-int4-ov, 8 s 音频 | 0.4 s |

VL 质量实测（8s 短剧片段，4 帧）：能读出画面字幕（"姐姐别划走"、"老婆在评论区盯着我"）， 按片段结构化描述人物表情与动作，输出带层级标题。

OpenVINO 加速潜力说明

本机只有 CPU，因此上表是性能下限。在 Intel® Core™ Ultra（CPU + GPU + NPU）上， 同样 workload 应显著更快，原因：

  1. 设备卸载：--device GPU 把 vision encoder 与 LLM decode 放到集成 GPU（设备选择逻辑已就绪，GPU 可见时自动优先）。
  2. NPU 低功耗常驻：--device NPU 适合长时间转写，功耗远低于 CPU。
  3. INT4 / INT8 预量化 IR：模型已是 OpenVINO IR 低位宽格式，在 GPU/NPU 上可直接吃下量化加速，无需运行时转换。

⚠️ 上述加速为基于架构的预期，非本机实测数据 —— 本机无 GPU/NPU，无法给出实测数字。

重要说明（设计取舍与已知限制）

  1. 纯本地，无云端回退。任何环节都不会把视频/音频/转写内容发到外部服务；网络仅用于首次下载模型权重。
  2. ONNX INT4 模型不能直接转 OpenVINO。实测 onnx-community/Qwen3.5-0.8B-ONNX 的 q4 权重 用了微软自定义算子 com.microsoft.GatherBlockQuantized，OpenVINO 无转换规则，会报 Model wasn't fully converted。因此本 skill 直接用官方 OpenVINO IR （OpenVINO/Qwen3.5-0.8B-int4-ov），而不是转换 ONNX 权重。
  3. ASR 精度与速度可切换。默认 whisper-medium-int8-ov（更准，CPU 上慢）； 改 ov_engine.ASR_CANDIDATES 顺序可用 whisper-tiny-int4-ov（快 ~240 倍，精度下降）。
  4. Qwen3-ASR-0.6B-fp16-ov 暂不可用。该仓库是 Qwen3-Omni 风格的 thinker/ 子目录布局， 与 OVModelForSpeechSeq2Seq 期望的顶层 openvino_encoder_model.xml 不匹配， 会被误判为"无 OpenVINO 文件"并尝试 export（挂起）。已下载但默认不启用，待接入 Qwen3-Omni 专用 pipeline。
  5. 长音频必须分片。Whisper 特征处理器单次只处理 30 s 且不报错（静默截断）， 所以 ov_engine.chunk_audio() 按 30 s 切片后逐段转写。
  6. 持久化目录。模型与 venv 落在 /mnt/workspace/.openvino/（可用 OPENVINO_BASE_DIR 覆盖）。 不要用 $HOME/.openvino —— 容器/沙箱里 $HOME 通常在非持久化 overlay 层，重启会丢。
  7. UTF-8。所有 Python 脚本在启动时对 stdout/stderr 做 reconfigure(encoding="utf-8")，否则中文输出乱码。
  8. 日志写在 $OPENVINO_BASE_DIR/log/，格式 [时间] [角色 pid=N] 消息，绝对路径。

与其他方案对比

| | 云端大模型 API | 本 skill | |---|---|---| | 视频上传 | 需上传，大文件常受限 | 无需上传 | | 长视频 | 常超时/截断 | 分片转写，不截断 | | 数据出网 | 是 | 否 | | 费用 | 按量计费 | 一次性硬件电费 | | GPU/NPU 利用 | 云端侧 | 本地 AI PC 异构算力 | | 离线可用 | 否 | 是 |