MOSS-VL-Realtime

概述

MOSS-VL-Realtime 是 MOSS-VL 版本的实时流检查点，是 OpenMOSS 开放视觉理解生态系统的一部分。

不同于先读取完整视频再进行回答的离线视频语言模型，MOSS-VL-Realtime 专为连续视频流设计。它能并行感知输入帧并生成文本，支持在流中任意时刻提问，且在视觉证据不足时可决定是响应还是继续观察。

此版本保留了 MOSS-VL 的交叉注意力设计和 256K 文本上下文窗口，同时新增了实时流数据和带时间戳的逐帧输入推理接口。

核心特性

实时流理解：持续处理输入帧，无需等待完整视频。
可中断交互：用户可在运行中的流任意时间戳提问，模型基于当前已观察帧进行回答。
主动静默：当无有意义的视觉更新或上下文不充分时，模型可输出 <|silence|> 并继续观察。
动态修正：随着新帧到来，模型可修正先前响应，而非局限于初始解读。
时间戳感知帧：每个流帧都关联绝对时间戳，帮助模型推理事件顺序、持续时间、节奏及细粒度时间定位。
统一 MOSS-VL 系列：与 MOSS-VL-Instruct 和 MOSS-VL-Base 一同发布，支持离线使用、持续预训练、微调及应用研究。

模型设计

架构

MOSS-VL-Realtime 采用基于交叉注意力的视觉语言架构，将视觉编码与语言推理解耦。该设计对实时应用至关重要，因为输入的视觉内容可整合到正在进行的生成上下文中，无需强制模型采用严格的离线“加载所有帧后再回答”工作流。

MOSS-VL Architecture

时间戳感知视频编码

对于视频和实时帧输入，MOSS-VL 会在采样帧旁注入绝对时间戳。这有助于模型推断事件发生的时间、持续时长以及场景随时间的变化，而非仅依赖帧顺序。

MOSS-VL 还采用了交叉注意力旋转位置编码（XRoPE），将文本标记和视觉补丁映射到由时间（t）、高度（h）和宽度（w）定义的统一三维坐标空间。这为模型提供了一致的位置表示，适用于图像、离线视频和实时流视频推理。

配置

项目	值
Parameters	11B
Tensor type	BF16
Context length	256K
Vision patch size	16
Temporal patch size	1
Default video FPS	1.0
Default max video frames	256
Realtime frame format	PIL-compatible image plus timestamp
Realtime session scope	One active realtime session per model instance

性能

MOSS-VL-Realtime 专为流视频理解基准测试而设计，在这类测试中，问题可能在完整视频被观察前出现，且正确答案可能随场景演变而变化。除标准视频理解准确性外，它还以实时交互质量、主动静默以及动态响应更新为目标。

MOSS-VL Streaming Benchmark

此版本的详细基准测试表格和对比将在 MOSS-VL 项目资源中持续更新。

快速开始

安装

克隆 MOSS-VL 仓库并安装项目依赖：

git clone https://github.com/OpenMOSS/MOSS-VL.git
cd MOSS-VL
conda create -n moss_vl python=3.12 pip -y
conda activate moss_vl
pip install -i https://pypi.org/simple --no-build-isolation -r requirements.txt

加载模型

import torch
from transformers import AutoModelForCausalLM, AutoProcessor

checkpoint = "OpenMOSS-Team/MOSS-VL-Realtime"

processor = AutoProcessor.from_pretrained(
    checkpoint,
    trust_remote_code=True,
    frame_extract_num_threads=1,
)
model = AutoModelForCausalLM.from_pretrained(
    checkpoint,
    trust_remote_code=True,
    device_map="auto",
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)
model.eval()

如果您的环境中无法使用 FlashAttention，加载模型时请传入 attn_implementation="eager"。

推理示例

在线推理

会话式在线推理

推荐直接使用的 API 是 create_realtime_session(...)。服务或应用程序需自行管理视频捕获管道，将摄像头、屏幕或视频文件输入转换为与 PIL 兼容的帧，并按非递减的时间戳推送每一帧。

常用的会话操作：

session.push_frame(image, timestamp=...) 用于添加单张视觉帧。
session.push_prompt("...") 用于在流运行期间添加用户问题。
session.push_prompt_frame(prompt, image, timestamp=...) 用于将提示与特定帧对齐。
session.poll_output(...) 或 session.stream_outputs(...) 返回增量文本块。

system_prompt 和 initial_prompt 会在第一帧到达前被分词为初始的系统/用户对话轮次。在同一会话持续观察帧的过程中，后续的用户对话轮次可通过 push_prompt(...) 添加。

关于完整的实时推理用法，包括本地视频回放和服务部署，请参见 MOSS-VL GitHub 仓库中的 realtime_inference。

import time
from PIL import Image

session = model.create_realtime_session(
    processor,
    initial_prompt=(
        "As the video streams frame by frame, describe important changes as they happen. "
        "Stay silent when there is no relevant update."
    ),
    frame_queue_size=256,
    max_tokens_per_turn=12,
    max_new_tokens=4096,
    do_sample=False,
)

frame_paths = [
    "data/frame_0001.jpg",
    "data/frame_0002.jpg",
    "data/frame_0003.jpg",
]

try:
    session.start()

    for index, frame_path in enumerate(frame_paths):
        image = Image.open(frame_path).convert("RGB")
        session.push_frame(image, timestamp=index / 1.0)

        while True:
            chunk = session.poll_output(timeout=0.0)
            if chunk is None:
                break
            print(chunk, end="", flush=True)

        time.sleep(1.0)

    session.push_prompt("What changed in the latest frames?")

    # Realtime sessions stay alive waiting for future input, so use a bounded
    # drain window and close the session explicitly when the producer is done.
    drain_deadline = time.monotonic() + 5.0
    while time.monotonic() < drain_deadline:
        chunk = session.poll_output(timeout=0.1)
        if chunk is not None:
            print(chunk, end="", flush=True)
finally:
    session.close()

帧时间戳以秒为单位，且在一个会话内必须是非递减的。输入生成器可以是摄像头、屏幕捕获、解码的视频文件、浏览器帧采样器，或任何其他能生成带时间戳图像的来源。

队列式在线推理

online_generate(...) 适用于通过队列分离帧生成和模型推理的后端系统。它接受包含帧、提示词、事件、重置控制和停止控制的字典。

import queue
import threading
from PIL import Image

input_queue = queue.Queue()
output_queue = queue.Queue()

worker = threading.Thread(
    target=model.online_generate,
    args=(processor, input_queue, output_queue),
    kwargs={
        "frame_queue_size": 256,
        "max_tokens_per_turn": 12,
        "max_new_tokens": 4096,
        "do_sample": False,
    },
    daemon=True,
)
worker.start()

input_queue.put({
    "initial_prompt": "Answer only when the streamed video provides enough evidence.",
})

input_queue.put({"frame": Image.open("data/frame_0001.jpg").convert("RGB"), "timestamp": 0.0})
input_queue.put({"frame": Image.open("data/frame_0002.jpg").convert("RGB"), "timestamp": 1.0})
input_queue.put({"prompt": "What is happening now?"})

try:
    while True:
        chunk = output_queue.get(timeout=0.5)
        print(chunk, end="", flush=True)
except queue.Empty:
    pass

input_queue.put({"stop_online_generate": True})
worker.join()

每个队列项可包含 frame 或 image、timestamp、prompt、frames、event、events、initial_prompt、system_prompt、generate_kwargs、reset_session，或诸如 stop_online_generate 之类的停止控制。

离线推理

MOSS-VL-Realtime 还保留了用于图像和视频提示的离线辅助 API。对于纯离线使用场景，MOSS-VL-Instruct 通常是首选的模型 checkpoint，但实时 checkpoint 仍能处理完整的图像和视频输入。

单视频离线推理

video_path = "data/example_video.mp4"
prompt = "Describe this video."

text = model.offline_video_generate(
    processor,
    prompt=prompt,
    video=video_path,
    shortest_edge=4096,
    longest_edge=16777216,
    video_max_pixels=201326592,
    patch_size=16,
    temporal_patch_size=1,
    merge_size=2,
    video_fps=1.0,
    min_frames=1,
    max_frames=256,
    num_extract_threads=4,
    image_mean=[0.5, 0.5, 0.5],
    image_std=[0.5, 0.5, 0.5],
    max_new_tokens=256,
    temperature=1.0,
    top_k=50,
    top_p=1.0,
    repetition_penalty=1.0,
    do_sample=False,
    vision_chunked_length=64,
)

print(text)

批量离线推理

offline_batch_generate 接受独立的图像/视频/文本查询。同一批次中的查询应共享相同的 media_kwargs 和 generate_kwargs。

queries = [
    {
        "prompt": "Describe sample A.",
        "images": [],
        "videos": ["data/sample_a.mp4"],
        "media_kwargs": {
            "video_fps": 1.0,
            "min_frames": 8,
            "max_frames": 256,
        },
        "generate_kwargs": {
            "temperature": 1.0,
            "top_k": 50,
            "top_p": 1.0,
            "max_new_tokens": 256,
            "repetition_penalty": 1.0,
            "do_sample": False,
        },
    },
    {
        "prompt": "Describe sample B.",
        "images": [],
        "videos": ["data/sample_b.mp4"],
        "media_kwargs": {
            "video_fps": 1.0,
            "min_frames": 8,
            "max_frames": 256,
        },
        "generate_kwargs": {
            "temperature": 1.0,
            "top_k": 50,
            "top_p": 1.0,
            "max_new_tokens": 256,
            "repetition_penalty": 1.0,
            "do_sample": False,
        },
    },
]

with torch.no_grad():
    result = model.offline_batch_generate(
        processor,
        queries,
        vision_chunked_length=64,
    )

texts = [item["text"] for item in result["results"]]
print(texts)

模型	参数规模	上下文长度	用途	Hugging Face
MOSS-VL-Realtime	11B	256K	实时流式视频交互	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime
MOSS-VL-Instruct	11B	256K	离线多模态指令跟随	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Instruct
MOSS-VL-Base	11B	256K	持续预训练与微调	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Base
MOSS-VL-Instruct-0408	11B	256K	历史指令微调 checkpoint	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Instruct-0408
MOSS-VL-Base-0408	11B	256K	历史基础模型 checkpoint	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Base-0408

局限性与发展路线

MOSS-VL-Realtime 针对带时间戳的逐帧流式处理进行了优化，但实际生产环境中的延迟取决于 GPU 硬件、帧采样率、传输开销和解码速度。单个模型实例仅支持一个活跃的实时会话。默认的帧队列会在必要时通过丢弃较旧的待处理帧来控制延迟。

我们将持续改进实时响应速度、动态纠错能力、更广泛的流式评估、强化学习后训练，以及针对未来 MOSS-VL 版本的特定任务部署方案。

引用

@misc{moss_vl_2026,
  title         = {{MOSS-VL Technical Report}},
  author        = {OpenMOSS Team},
  year          = {2026},
  howpublished  = {\url{https://github.com/OpenMOSS/MOSS-VL}},
  note          = {GitHub repository}
}

MOSS-VL-Realtime

概述

MOSS-VL-Realtime 是 MOSS-VL 版本的实时流检查点，是 OpenMOSS 开放视觉理解生态系统的一部分。

此版本保留了 MOSS-VL 的交叉注意力设计和 256K 文本上下文窗口，同时新增了实时流数据和带时间戳的逐帧输入推理接口。

核心特性

实时流理解：持续处理输入帧，无需等待完整视频。
可中断交互：用户可在运行中的流任意时间戳提问，模型基于当前已观察帧进行回答。
主动静默：当无有意义的视觉更新或上下文不充分时，模型可输出 <|silence|> 并继续观察。
动态修正：随着新帧到来，模型可修正先前响应，而非局限于初始解读。
时间戳感知帧：每个流帧都关联绝对时间戳，帮助模型推理事件顺序、持续时间、节奏及细粒度时间定位。
统一 MOSS-VL 系列：与 MOSS-VL-Instruct 和 MOSS-VL-Base 一同发布，支持离线使用、持续预训练、微调及应用研究。

模型设计

架构

MOSS-VL Architecture

时间戳感知视频编码

配置

项目	值
Parameters	11B
Tensor type	BF16
Context length	256K
Vision patch size	16
Temporal patch size	1
Default video FPS	1.0
Default max video frames	256
Realtime frame format	PIL-compatible image plus timestamp
Realtime session scope	One active realtime session per model instance

性能

MOSS-VL Streaming Benchmark

此版本的详细基准测试表格和对比将在 MOSS-VL 项目资源中持续更新。

快速开始

安装

克隆 MOSS-VL 仓库并安装项目依赖：

git clone https://github.com/OpenMOSS/MOSS-VL.git
cd MOSS-VL
conda create -n moss_vl python=3.12 pip -y
conda activate moss_vl
pip install -i https://pypi.org/simple --no-build-isolation -r requirements.txt

加载模型

import torch
from transformers import AutoModelForCausalLM, AutoProcessor

checkpoint = "OpenMOSS-Team/MOSS-VL-Realtime"

processor = AutoProcessor.from_pretrained(
    checkpoint,
    trust_remote_code=True,
    frame_extract_num_threads=1,
)
model = AutoModelForCausalLM.from_pretrained(
    checkpoint,
    trust_remote_code=True,
    device_map="auto",
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)
model.eval()

如果您的环境中无法使用 FlashAttention，加载模型时请传入 attn_implementation="eager"。

推理示例

在线推理

会话式在线推理

常用的会话操作：

session.push_frame(image, timestamp=...) 用于添加单张视觉帧。
session.push_prompt("...") 用于在流运行期间添加用户问题。
session.push_prompt_frame(prompt, image, timestamp=...) 用于将提示与特定帧对齐。
session.poll_output(...) 或 session.stream_outputs(...) 返回增量文本块。

关于完整的实时推理用法，包括本地视频回放和服务部署，请参见 MOSS-VL GitHub 仓库中的 realtime_inference。

import time
from PIL import Image

session = model.create_realtime_session(
    processor,
    initial_prompt=(
        "As the video streams frame by frame, describe important changes as they happen. "
        "Stay silent when there is no relevant update."
    ),
    frame_queue_size=256,
    max_tokens_per_turn=12,
    max_new_tokens=4096,
    do_sample=False,
)

frame_paths = [
    "data/frame_0001.jpg",
    "data/frame_0002.jpg",
    "data/frame_0003.jpg",
]

try:
    session.start()

    for index, frame_path in enumerate(frame_paths):
        image = Image.open(frame_path).convert("RGB")
        session.push_frame(image, timestamp=index / 1.0)

        while True:
            chunk = session.poll_output(timeout=0.0)
            if chunk is None:
                break
            print(chunk, end="", flush=True)

        time.sleep(1.0)

    session.push_prompt("What changed in the latest frames?")

    # Realtime sessions stay alive waiting for future input, so use a bounded
    # drain window and close the session explicitly when the producer is done.
    drain_deadline = time.monotonic() + 5.0
    while time.monotonic() < drain_deadline:
        chunk = session.poll_output(timeout=0.1)
        if chunk is not None:
            print(chunk, end="", flush=True)
finally:
    session.close()

队列式在线推理

online_generate(...) 适用于通过队列分离帧生成和模型推理的后端系统。它接受包含帧、提示词、事件、重置控制和停止控制的字典。

import queue
import threading
from PIL import Image

input_queue = queue.Queue()
output_queue = queue.Queue()

worker = threading.Thread(
    target=model.online_generate,
    args=(processor, input_queue, output_queue),
    kwargs={
        "frame_queue_size": 256,
        "max_tokens_per_turn": 12,
        "max_new_tokens": 4096,
        "do_sample": False,
    },
    daemon=True,
)
worker.start()

input_queue.put({
    "initial_prompt": "Answer only when the streamed video provides enough evidence.",
})

input_queue.put({"frame": Image.open("data/frame_0001.jpg").convert("RGB"), "timestamp": 0.0})
input_queue.put({"frame": Image.open("data/frame_0002.jpg").convert("RGB"), "timestamp": 1.0})
input_queue.put({"prompt": "What is happening now?"})

try:
    while True:
        chunk = output_queue.get(timeout=0.5)
        print(chunk, end="", flush=True)
except queue.Empty:
    pass

input_queue.put({"stop_online_generate": True})
worker.join()

离线推理

单视频离线推理

video_path = "data/example_video.mp4"
prompt = "Describe this video."

text = model.offline_video_generate(
    processor,
    prompt=prompt,
    video=video_path,
    shortest_edge=4096,
    longest_edge=16777216,
    video_max_pixels=201326592,
    patch_size=16,
    temporal_patch_size=1,
    merge_size=2,
    video_fps=1.0,
    min_frames=1,
    max_frames=256,
    num_extract_threads=4,
    image_mean=[0.5, 0.5, 0.5],
    image_std=[0.5, 0.5, 0.5],
    max_new_tokens=256,
    temperature=1.0,
    top_k=50,
    top_p=1.0,
    repetition_penalty=1.0,
    do_sample=False,
    vision_chunked_length=64,
)

print(text)

批量离线推理

offline_batch_generate 接受独立的图像/视频/文本查询。同一批次中的查询应共享相同的 media_kwargs 和 generate_kwargs。

queries = [
    {
        "prompt": "Describe sample A.",
        "images": [],
        "videos": ["data/sample_a.mp4"],
        "media_kwargs": {
            "video_fps": 1.0,
            "min_frames": 8,
            "max_frames": 256,
        },
        "generate_kwargs": {
            "temperature": 1.0,
            "top_k": 50,
            "top_p": 1.0,
            "max_new_tokens": 256,
            "repetition_penalty": 1.0,
            "do_sample": False,
        },
    },
    {
        "prompt": "Describe sample B.",
        "images": [],
        "videos": ["data/sample_b.mp4"],
        "media_kwargs": {
            "video_fps": 1.0,
            "min_frames": 8,
            "max_frames": 256,
        },
        "generate_kwargs": {
            "temperature": 1.0,
            "top_k": 50,
            "top_p": 1.0,
            "max_new_tokens": 256,
            "repetition_penalty": 1.0,
            "do_sample": False,
        },
    },
]

with torch.no_grad():
    result = model.offline_batch_generate(
        processor,
        queries,
        vision_chunked_length=64,
    )

texts = [item["text"] for item in result["results"]]
print(texts)

模型	参数规模	上下文长度	用途	Hugging Face
MOSS-VL-Realtime	11B	256K	实时流式视频交互	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime
MOSS-VL-Instruct	11B	256K	离线多模态指令跟随	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Instruct
MOSS-VL-Base	11B	256K	持续预训练与微调	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Base
MOSS-VL-Instruct-0408	11B	256K	历史指令微调 checkpoint	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Instruct-0408
MOSS-VL-Base-0408	11B	256K	历史基础模型 checkpoint	https://huggingface.co/OpenMOSS-Team/MOSS-VL-Base-0408

局限性与发展路线

我们将持续改进实时响应速度、动态纠错能力、更广泛的流式评估、强化学习后训练，以及针对未来 MOSS-VL 版本的特定任务部署方案。

引用

@misc{moss_vl_2026,
  title         = {{MOSS-VL Technical Report}},
  author        = {OpenMOSS Team},
  year          = {2026},
  howpublished  = {\url{https://github.com/OpenMOSS/MOSS-VL}},
  note          = {GitHub repository}
}

MOSS-VL-Realtime

概述

核心特性

模型设计

架构

时间戳感知视频编码

配置

性能

快速开始

安装

加载模型

推理示例

在线推理

离线推理

相关模型 checkpoint

局限性与发展路线

引用

MOSS-VL-Realtime

概述

核心特性

模型设计

架构

时间戳感知视频编码

配置

性能

快速开始

安装

加载模型

推理示例

在线推理

离线推理

相关模型 checkpoint

局限性与发展路线

引用