Proact-VL-Washing/mage_vl_demo

Mage-VL Proactive Streaming Commentary Demo

基于 Microsoft Mage-VL 的 Proactive Streaming Alignment（主动流式对齐）功能：一边播放视频，一边由 StreamMind Gate（System 1）决策何时触发 Qwen3-4B 生成解说（System 2）。

论文：arXiv:2607.24904

---

架构

视频流 → Mage-ViT (Codec-Native 16×16 patch 编码)
            │
            ├──→ StreamMind Gate (System 1, Mamba-SSM)
            │         │
            │         └──→ p(speak) 每段概率
            │                   │
            │              若 p ≥ threshold → 触发 System 2
            │
            └──→ Qwen3-4B Decoder (System 2) → 生成解说文本

---

本地运行

conda activate py311
pip install torch torchvision transformers accelerate \
            decord opencv-python-headless moviepy Pillow scipy safetensors
pip install mamba-ssm   # StreamMind gate 需要 CUDA 编译

python streaming_commentary.py \
  --video /path/to/video.mp4 \
  --checkpoint microsoft/Mage-VL \
  --backend codec \
  --segment-sec 8 \
  --threshold 0.5 \
  --gpu

---

Google Colab 运行

可以运行。 完整 notebook 见 colab_setup.ipynb，步骤如下：

1. 打开 Google Colab，新建 Notebook
2. 将本项目三个文件上传到 /content/（或复制粘贴代码单元格）
3. 按顺序运行：
   • Cell 1：确认 GPU（Runtime → Change runtime type → GPU）
   • Cell 2：pip install 依赖（mamba-ssm 需编译，约 2-3 分钟）
   • Cell 3：上传视频（files.upload()）
   • Cell 4：运行 streaming_commentary.py

Colab 免费额度提供 T4 GPU（16GB VRAM），足以运行 microsoft/Mage-VL（bf16 约 8GB）。

注意：Colab 无 GUI，输出为纯文本（不依赖 cv2.imshow）。

---

参数

参数	默认	说明
--video	(必填)	视频路径
--checkpoint	microsoft/Mage-VL	HF 模型 ID 或本地路径
--backend	codec	codec=Codec-Native；frames=均匀帧采样
--segment-sec	8.0	每段长度（秒）
--threshold	0.5	Gate 触发阈值
--max-tokens	120	每次生成最大 token 数
--gpu	关	启用 CUDA（推荐）

---

无 mamba-ssm 时的行为

若未安装 mamba-ssm，Gate 不可用，程序自动降级为非门控模式：每个视频片段都触发生成解说。逻辑流程不变。