MOSS-VL Realtime-Demo 是基于开源多模态模型 MOSS-VL（11B 开放权重，专为长视频与实时视频理解设计）打造的实时视频+语音 AI 助手。它通过浏览器与摄像头、屏幕或视频文件对话，支持流式字幕、语音提问与回答打断，并可选配备语音识别（ASR）、本地语音合成（TTS）和会话长期记忆。本文提供一份完整的 MOSS-VL Realtime-Demo 部署指南，帮你在自有 GPU 上从零搭建这个全栈应用。

一、它能做什么：实时视频理解 + 语音助手

Realtime-Demo 不是简单的"看图说话"，而是一个持续运行的流式会话系统。核心能力包括：

• 多路输入：摄像头、屏幕共享、图片、视频文件
• 流式交互：实时字幕、文字/语音提问、随时打断回答
• 可选增强：SenseVoice ASR 语音识别、MOSS-TTS-Nano 本地语音合成（无需云端凭据）
• 会话记忆：文本与图像记忆、上下文用量观测、长会话自动 rollover
• 对外接口：REST 会话管理 + WebSocket 网关，方便外部客户端接入

它最核心的设计是"证据驱动"的实时响应——模型会跟随场景变化持续观察画面，在证据不足时选择等待，而不是抢答。下面这张图展示了三种典型交互模式（直接回答、实时适应场景变化、等待证据后回答）：

在模型层面，MOSS-VL 通过 Vision Encoder 将带时间戳的视频帧编码后送入 Gated-XAttention LLM Decoder，实现跨模态的流式推理：

完整功能说明可参考 third_party/realtime-demo/README_zh.md 与 third_party/realtime-demo/README.md。

二、部署前准备：硬件与系统环境检查

Realtime-Demo 的完整配置需要两张独立 GPU（主 VLM + Memory 4B），仅部署视频/文本链路则一张 GPU 即可。

Ubuntu 系统依赖可由管理员安装：

sudo apt-get update sudo apt-get install -y git build-essential cmake ffmpeg libsndfile1 libnuma1 libibverbs1 python3-venv

💡 注意：安装器只负责应用依赖，不会替你安装系统软件包或 GPU 驱动。完整的前置条件说明见 third_party/realtime-demo/deployment/repro/README.md。

三、一键安装：bootstrap.sh 快速配置

先获取代码并进入 Demo 目录：

git clone https://gitcode.com/gh_mirrors/mo/MOSS-VL cd MOSS-VL/third_party/realtime-demo

在 Demo 根目录执行三步安装：

bash bootstrap.sh --doctor-only # 第 1 步：环境自检 bash bootstrap.sh --with-memory --with-asr --with-tts # 第 2 步：安装全组件

安装器会自动完成：

• 准备 Python/Node 工具链，创建独立的 Demo.venv与后端.repro/.venv-main环境（两者刻意隔离，避免依赖冲突）
• 拉取后端源码与模型权重
• 安装 npm 依赖并构建前端

📌按需裁剪：不传任何--with-*参数时，只安装视频/文本配置，单 GPU 即可运行，磁盘占用也更低。若你拿到的是同时包含demo/和backend/的源码包，改用：

bash bootstrap.sh --backend-source ../backend --with-memory --with-asr --with-tts

四、启动与验证：从模型加载到健康检查

安装完成后，指定 GPU 启动整套服务：

.venv/bin/python scripts/repro/run.py up --main-gpu 0 --memory-gpu 1

⏳ 首次启动需要加载模型并编译 GPU 内核，耗时明显长于后续启动，请耐心等待就绪。

随后用三条命令验证运行状态：

.venv/bin/python scripts/repro/run.py status # 查看各组件状态 .venv/bin/python scripts/repro/smoke.py # 冒烟测试 curl --fail http://127.0.0.1:18501/api/status # 健康检查

停止服务使用 scripts/repro/run.py 的down子命令，或直接运行 stop_demo.sh：

.venv/bin/python scripts/repro/run.py down

若端口冲突，用--base-port 19500整体切换端口组，浏览器端口相应变为19502。

五、浏览器体验：接入摄像头、语音与上下文指令

打开http://localhost:18502，切换到视频通话模式，选择媒体源（摄像头/屏幕/视频文件）并连接即可开始对话。

• 语音输入：默认"按住说话"（PTT），可切换 VAD 自动收音
• 回答打断：模型说话时随时可以插话，编排器会保留 KV 缓存做软中断
• 远程访问：摄像头与麦克风需要 HTTPS 环境
• 上下文管理：在会话中发送/compact（生成摘要并重建上下文）或/clear（清空模型上下文，保留系统提示与聊天记录）

带时间戳的帧流式输入是 MOSS-VL 实时能力的关键——每一帧都携带时间信息，让模型理解"画面变化"而非孤立截图：

六、端口规划与资源参数速查表

推荐安装的默认配置如下，可按硬件调整：

常用调参：--main-memory-fraction/--memory-fraction调整显存占比，--cpu-threads调整 CPU 线程数。日志位于.repro/logs，运行数据在.repro/data。

七、常见部署问题排查

🔒安全提醒：所有服务默认只绑定 loopback 回环地址。若要公开部署，必须自行补充鉴权、会话归属校验、TLS 和限流。

八、核心文件导航

继续深入学习时，这些文件值得收藏：

从一键安装到浏览器语音对话，MOSS-VL Realtime-Demo 把"实时视频 + 语音 AI 助手"的完整链路压缩成了三条命令。现在就可以打开终端，开始搭建你的实时多模态助手了 🚀