> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# mJev

> 用 mJev 对同一张图片、同一段视频或音频提出多个问题，并从你定义的候选答案中做出选择。

**mJev** 是一个开源的多模态推理工具。你提供一份媒体和共享上下文，为每道题定义候选答案。mJev 返回选中的答案和各候选项的得分，供应用做分类、标注或后续处理。

> [card] [GitHub 仓库](https://github.com/SoMarkAI/mJev/blob/main/README.zh-CN.md)
>
> 查看中文 README、示例和源代码。

> [card] [mJev-Qwen3-VL-4B-RLCD](https://huggingface.co/SoMarkAI/mJev-Qwen3-VL-4B-RLCD)
>
> 查看基于 Qwen3-VL-4B-Instruct 微调的模型并下载权重。

## 六秒视频示例

项目用 `Qwen3-VL-4B-Instruct` 和 Transformers 后端回答了六秒动画中的三个问题。下方命令使用公开记录中的同一模型版本、输入和采样设置。

| 问题 | 模型选择 | 候选项概率 |
| - | - | -: |
| 红球怎么移动？ | 从左向右 | 71.34% |
| 哪个物体向上移动？ | 蓝色方块 | 97.29% |
| 哪个动作先发生？ | 红球向右移动 | 89.62% |

[原始视频](https://github.com/SoMarkAI/mJev/blob/main/examples/motion-demo/motion.mp4) · [完整输出](https://github.com/SoMarkAI/mJev/blob/main/examples/motion-demo/recorded-output.json)

## 准备环境

准备 Linux、Python 3.11 或更高版本、兼容的 NVIDIA 驱动和系统 FFmpeg。项目公布的六秒视频推理记录来自单张 24 GB NVIDIA GPU。

```bash theme={null}
git clone https://github.com/SoMarkAI/mJev.git
cd mJev
python3 -m venv .venv
source .venv/bin/activate
python -m pip install torchcodec==0.11.0+cpu --index-url https://download.pytorch.org/whl/cpu
python -m pip install -e '.[hf-vl]' huggingface_hub

hf download Qwen/Qwen3-VL-4B-Instruct \
  --revision ebb281ec70b05090aa6165b016eac8ec08e71b17 \
  --local-dir models/Qwen3-VL-4B-Instruct
```

`torchcodec` 的 CPU 软件包负责视频解码，推理由 GPU 上的 PyTorch 执行。

## 运行视频示例

在仓库根目录运行以下命令。示例 JSON 包含视频路径、采样参数和三道题。命令使用编号为 `0` 的 GPU，开启前缀缓存并对三个问题做批处理。

```bash theme={null}
CUDA_VISIBLE_DEVICES=0 python demo_hf.py \
  --model models/Qwen3-VL-4B-Instruct \
  --input examples/motion-demo/input.json \
  --mode causal --numerics stable --projection full \
  --prefix-cache --question-batch-size 3 \
  --output outputs/motion-demo.json
```

完成后，打开 `outputs/motion-demo.json` 查看结果。[仓库中的视频示例输入](https://github.com/SoMarkAI/mJev/blob/main/examples/motion-demo/input.json)

要用微调版 mJev 跑同一个视频，请下载 `SoMarkAI/mJev-Qwen3-VL-4B-RLCD`，将上方命令的 `--model` 指向该模型的本地目录，并换一个 `--output` 路径，方便对照两份结果。[微调模型下载和运行说明](https://huggingface.co/SoMarkAI/mJev-Qwen3-VL-4B-RLCD#quick-start)

## 使用自己的媒体

把下面的 JSON 保存为 `task.json`，把 `clip.mp4` 放在同一目录，并将命令中的 `--input` 指向 `task.json`。`media_path` 相对于输入 JSON 所在目录解析。视频任务建议设置采样频率和帧数上限，以便复现结果。

```json theme={null}
{
  "modality": "video",
  "media_path": "clip.mp4",
  "context": "观察画面中的交通工具及其移动方向。",
  "video_options": { "fps": 2, "min_pixels": 3136, "max_pixels": 100352, "max_frames": 16 },
  "questions": [
    {
      "id": "vehicle",
      "question": "主要移动物体是哪种交通工具？",
      "candidates": ["自行车", "汽车", "公交车", "无法判断"]
    },
    {
      "id": "direction",
      "question": "它在画面中的主要移动方向是什么？",
      "candidates": ["向左", "向右", "其他方向", "无法判断"]
    }
  ]
}
```

图片输入使用 `"modality": "image"`，将 `media_path` 改为图片路径，并移除 `video_options`。纯音频使用 `audio`，需要同时分析画面和音轨时使用 `audio_video`。这两种音频输入使用 Qwen3-Omni 模型，依赖和启动步骤见 [Transformers 部署指南](https://github.com/SoMarkAI/mJev/blob/main/docs/hf.zh-CN.md#demo)。

## 读取结果

输出 JSON 是一个数组，每道题对应一条结果。`decision` 是模型选择的候选项。`candidates` 列出所有候选项及其 `raw_logit` 和 `probability`。这些概率按本题提供的候选集合归一化，`probability_sum` 记录它们的总和。

每道题的候选答案须为非空且互不重复的文本。Transformers 示例脚本默认限制完整输入为 4,000 个 token，超过限制时会报错。如需在加载模型权重前检查输入长度和候选标签，加入 `--check-only` 并省略 `--output`，将检查结果输出到终端。

得分并列时，mJev 选择输入顺序中靠前的候选项。

## 模型与输入

| 模型 | 可用输入 | 适用场景 |
| - | - | - |
| `mJev-Qwen3-VL-4B-RLCD` | 图片或视频，以及文本问题和选项 | 识别画面内容、判断动作及其顺序 |
| `Qwen3-Omni-30B-A3B-Instruct` | 图片、音频、视频或带音轨的视频，以及文本问题和选项 | 判断音频里有无说话声，或结合声音和画面做选择 |

两个模型使用相同的问题和候选项格式。

* 在两种模型之间选择，查看依赖和支持的输入。[模型选择指南](https://github.com/SoMarkAI/mJev/blob/main/docs/models.zh-CN.md)
* 使用 vLLM 后端时，按项目文档准备固定版本及对应的 GPU 配置。[vLLM 部署指南](https://github.com/SoMarkAI/mJev/blob/main/docs/vllm.zh-CN.md)

## 公开评测

* **准确率**：在 `mJev-Compositional-VQA` 的同一组 195 道题上，基础模型答对 152 题（77.95%），微调后的 mJev 模型答对 156 题（80.00%）。这组题未用于强化学习训练。[模型卡与评测结果](https://huggingface.co/SoMarkAI/mJev-Qwen3-VL-4B-RLCD#evaluation)
* **前缀缓存**：项目用单张 24 GB NVIDIA GPU 对同一段视频测试 16 道题，开启缓存后整组耗时从 32.62 秒降至 6.29 秒，峰值已分配显存从 15.80 GiB 升至 20.60 GiB。项目也记录了短输入和单题配置的结果。[缓存评测条件](https://github.com/SoMarkAI/mJev/blob/main/docs/cache_scaling.zh-CN.md)

代码采用 [Apache License 2.0](https://github.com/SoMarkAI/mJev/blob/main/LICENSE)。模型权重单独下载，许可见各自的模型卡。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.