OpenMOSS-Team/MOSS-VL-Realtime · Hugging Face 来源：https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime MOSS-VL ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#overview概述 MOSS-VL-Realtime 是 MOSS-VL 版本的实时流式检查点，属于 OpenMOSS 生态系统中用于开放视觉理解的一部分。与需要先读取完整视频再回答的离线视频-语言模型不同，MOSS-VL-Realtime 专为连续视频流设计。它能够并行地感知传入帧并生成文本，支持在流中任意时刻提问，并且在视觉证据不足时可以决定是回复还是继续观察。本版本保留了 MOSS-VL 的交叉注意力设计和 256K 文本上下文窗口，同时增加了实时流式数据和用于时间戳逐帧输入的推理接口。 ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#key-features关键特性 - 实时流式理解：持续处理传入帧，无需等待完整视频。 - 可打断交互：用户可在运行流中的任意时间戳提问，模型基于已观察到的帧进行回答。 - 主动静默：当没有有意义的视觉更新或上下文不足时，模型可以发出 <|silence|> 并继续观察。 - 动态修正：随着新帧到来，模型可以修正先前的回答，而不是固守初始解释。 - 时间戳感知帧：每个流式帧都关联一个绝对时间戳，帮助模型推理事件顺序、持续时间、节奏以及细粒度的时间定位。 - 统一的 MOSS-VL 系列：与 MOSS-VL-Instruct 和 MOSS-VL-Base 一同发布，支持离线使用、继续预训练、微调和应用研究。 ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#model-design模型设计 ### https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#architecture架构 MOSS-VL-Realtime 采用基于交叉注意力的视觉-语言架构，将视觉编码与语言推理解耦。这一设计对于实时使用至关重要，因为传入的视觉内容可以集成到正在运行的生成上下文中，而无需强制模型执行严格的离线“先加载所有帧，再回答”的工作流程。 MOSS-VL 架构 ### https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#timestamp-aware-video-encoding时间戳感知视频编码 对于视频和实时帧输入，MOSS-VL 在采样帧旁边注入绝对时间戳。这有助于模型推理事件发生的时间、持续时间以及场景随时间的变化，而不仅仅依赖帧顺序。MOSS-VL 还使用交叉注意力旋转位置编码（XRoPE），将文本 token 和视觉 patch 映射到由时间（t）、高度（h）和宽度（w）定义的三维坐标空间。这为图像、离线视频和实时流式视频推理提供了一致的位置表示。 ### https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#configuration配置 | 项目 | 值 | | — | — | | 参数 | 11B | | 张量类型 | BF16 | | 上下文长度 | 256K | | 视觉 patch 大小 | 16 | | 时间维度 patch 大小 | 1 | | 默认视频 FPS | 1.0 | | 默认最大视频帧数 | 256 | | 实时帧格式 | 兼容 PIL 的图像加时间戳 | | 实时会话范围 | 每个模型实例一个活跃实时会话 | ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#performance性能 MOSS-VL-Realtime 专为流式视频理解基准而设计，在这些基准中，问题可能在完整视频被观察到之前就已到来，正确答案也可能随着场景演变而变化。除了标准视频理解准确性外，它还针对实时交互质量、主动静默和动态响应更新进行了优化。 MOSS-VL 流式基准测试 详细的基准测试表格和本次发布的对比将维护在 MOSS-VL 项目资源中。 ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#quickstart快速开始 ### https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#installation安装 克隆 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 ### https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#load-the-model加载模型 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"。 ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#inference-examples推理示例 ### https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#online-inference在线推理 会话式在线推理 推荐的直接 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 在第一个帧到达之前被 token 化为初始的系统/用户轮次。后续的用户轮次可以通过 push_prompt(...) 添加，而同一会话继续观察帧。 有关完整的实时推理用法（包括本地视频回放和服务部署），请参见 MOSS-VL GitHub 仓库中的 realtime_inference (https://github.com/OpenMOSS/MOSS-VL/tree/main/realtime_inference)。 import time from PIL import Image session = model.create_realtime_session( processor, initial_prompt=( "随着视频逐帧流式传输，描述发生时的重要变化。 " "当没有相关更新时保持静默。" ), 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("最近帧有什么变化？") # 实时会话保持活动状态以等待未来输入，因此使用有限 # 的耗尽窗口，并在生成器完成后显式关闭会话。 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": "仅在流式视频提供足够证据时才回答。", }) 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": "现在发生了什么？"}) 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）。 ### https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#offline-inference离线推理 MOSS-VL-Realtime 也保留了用于图像和视频提示的离线辅助 API。对于纯离线使用，通常首选 MOSS-VL-Instruct 检查点，但实时检查点仍然可以处理完整的图像和视频输入。 单视频离线推理 video_path = "data/example_video.mp4" prompt = "描述这个视频。" 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": "描述样本 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": "描述样本 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) ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#related-checkpoints相关检查点 ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#limitations-and-roadmap局限性与路线图 MOSS-VL-Realtime 针对带时间戳的逐帧流式传输进行了优化，但生产延迟取决于 GPU 硬件、帧采样率、传输开销和解码速度。一个模型实例支持一个活跃的实时会话。默认帧队列通过在需要时丢弃较旧的待处理帧来限制延迟。根据应用协议，模型可能发出实时控制 token，例如 <|silence|>、<|round_start|> 和 <|round_end|>。下游服务应根据其 UI 需求过滤或渲染这些 token。 我们正在继续改进实时响应时机、动态修正、更广泛的流式评估、RL 后训练以及针对未来 MOSS-VL 版本的任务特定部署方案。 ## https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime#citation引用 @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} }