MiniCPM-o 4.5 PyTorch 简易演示系统

English Documentation | 详细文档

可直接使用的在线演示系统

本演示系统为 MiniCPM-o 4.5 模型训练团队官方提供的演示系统。本演示系统使用 PyTorch + CUDA 推理后端，结合简易的前后端设计，旨在以透明、简洁、无性能损失的方式，全面地演示 MiniCPM-o 4.5 的音视频全模态全双工能力。

目前支持的 3 种模式共享同一个模型实例，支持毫秒级热切换（< 0.1ms），近期将支持更多模式。

其他特性：

• 可自定义系统提示词
• 可自定义参考音频
• 代码简洁易读，便于二次开发
• 可作为 API 后端供第三方应用调用

Frontend (HTML/JS)
    |  HTTPS / WSS
Gateway (:8006, HTTPS)
    |  HTTP / WS (internal)
Worker Pool (:22400+)
    +-- Worker 0 (GPU 0)
    +-- Worker 1 (GPU 1)
    +-- ...

• Frontend — 模式选择首页、Turn-based Chat 轮次对话、Omni / Audio Duplex 全双工交互、Admin Dashboard 监控面板
• Gateway — 请求路由与分发、WebSocket 代理、请求排队与会话亲和
• Worker — 每 Worker 独占一张 GPU，支持 Turn-based Chat / Duplex 协议，Duplex 支持暂停/恢复（超时自动释放）

1. 确保你有一张显存大于 28GB 的 NVIDIA GPU。
2. 确保你的机器安装了 Linux 操作系统。

FFmpeg 用于视频帧提取 和 推理结果可视化。更多信息请访问 FFmpeg 官网。

macOS (Homebrew):

brew install ffmpeg

Ubuntu/Debian:

sudo apt update && sudo apt install ffmpeg

验证安装:

ffmpeg -version

1. 安装Python 3.10

推荐使用 miniconda 安装 Python 3.10。

mkdir -p ./miniconda3_install_tmp

# 下载 miniconda3 安装脚本
wget https://repo.anaconda.com/miniconda/Miniconda3-py310_25.11.1-1-Linux-x86_64.sh -O ./miniconda3_install_tmp/miniconda.sh 

# 将 miniconda3 安装到项目目录下
bash ./miniconda3_install_tmp/miniconda.sh -b -u -p ./miniconda3 

安装完成后，会得到一个空的 base 环境，激活这个 base 环境，base 环境中默认为 Python 3.10。

source ./miniconda3/bin/activate
python --version # 应显示 3.10.x

2. 安装 MiniCPM-o 4.5 所需的依赖

使用项目目录下的 install.sh 安装依赖是最快的，它会在项目目录下的 .venv 中创建一个名为 base 的venv虚拟环境，并在其中安装所有的依赖。

source ./miniconda3/bin/activate
bash ./install.sh

如果网络良好，整个安装过程大约花费 5 分钟。如果你处在中国，可以考虑使用第三方 PyPi 镜像源，例如清华镜像源。

# 首先准备好一个空的 python 3.10 环境
source ./miniconda3/bin/activate
python -m venv .venv/base
source .venv/base/bin/activate

# 安装 PyTorch。
pip install "torch==2.8.0" "torchaudio==2.8.0"

# 安装其余依赖。
pip install -r requirements.txt

3. 创建配置文件

将项目目录下的 config.example.json 复制为 config.json。

cp config.example.json config.json

模型路径（model_path），默认使用 openbmb/MiniCPM-o-4_5，如果你可以访问 huggingface，无需修改，将会自动从 huggingface 拉取模型。

# 安装huggingface cli
pip install -U huggingface_hub

# 下载模型
huggingface-cli download openbmb/MiniCPM-o-4_5 --local-dir /path/to/your/MiniCPM-o-4_5

pip install -U huggingface_hub

export HF_ENDPOINT=https://hf-mirror.com

huggingface-cli download openbmb/MiniCPM-o-4_5 --local-dir /path/to/your/MiniCPM-o-4_5

pip install modelscope

modelscope download --model OpenBMB/MiniCPM-o-4_5 --local_dir /path/to/your/MiniCPM-o-4_5

修改 "gateway_port": 8006 即可改变部署的端口，默认为 8006。

4. 启动服务

CUDA_VISIBLE_DEVICES=0,1,2,3 bash start_all.sh

服务启动后访问 https://localhost:8006 即可。自签名证书会触发浏览器警告，点"高级"→"继续访问"。

CUDA_VISIBLE_DEVICES=0,1 bash start_all.sh          # 指定 GPU
bash start_all.sh --compile                          # torch.compile 加速（实验性，效果尚不稳定）
bash start_all.sh --http                             # 降级 HTTP（不推荐，麦克风/摄像头 API 需要 HTTPS）

# Worker（每张 GPU 一个）
CUDA_VISIBLE_DEVICES=0 PYTHONPATH=. .venv/base/bin/python worker.py --worker-index 0 --gpu-id 0

# Gateway
PYTHONPATH=. .venv/base/bin/python gateway.py --port 10024 --workers localhost:22400

5. 停止服务：

pkill -f "gateway.py|worker.py"

• 轮次对话模式下，图片输入暂时不可用，仅支持音频和文本输入，近期会拆分出图片问答模式。
• 半双工的语音通话（无需按钮触发回复）正在开发中，近期合入。
• 语音全双工模式下，回声消除目前存在问题，影响到打断成功率，推荐使用耳机进行交互，近期将修复。
• 语音模式下，由于模型的训练策略，中文和英文通话下，需要使用对应语言的系统提示词。

项目代码结构

minicpmo45_service/
├── config.json               # 服务配置（从 config.example.json 复制，gitignored）
├── config.example.json       # 配置示例（完整字段 + 默认值）
├── config.py                 # 配置加载逻辑（Pydantic 定义 + JSON 加载）
├── requirements.txt          # Python 依赖
├── start_all.sh              # 一键启动脚本
│
├── gateway.py                # Gateway（路由、排队、WS 代理）
├── worker.py                 # Worker（推理服务）
├── gateway_modules/          # Gateway 业务模块
│
├── core/                     # 核心封装
│   ├── schemas/              # Pydantic Schema（请求/响应）
│   └── processors/           # 推理处理器（UnifiedProcessor）
│
├── MiniCPMO45/               # 模型核心推理代码
├── static/                   # 前端页面
├── resources/                # 资源文件（参考音频等）
├── tests/                    # 测试
└── tmp/                      # 运行时日志和 PID 文件

前端路由设定

所有配置集中在 config.json（从 config.example.json 复制）。 config.json 已 gitignore，不会被提交。

配置优先级：CLI 参数 > config.json > Pydantic 默认值

最小配置（只需模型路径）：

{"model": {"model_path": "/path/to/model"}}

# Worker
python worker.py --model-path /alt/model --pt-path /alt/weights.pt --ref-audio-path /alt/ref.wav --compile

# Gateway
python gateway.py --port 10025 --workers localhost:22400,localhost:22401 --http

compile 模式首次推理额外 ~60s 编译耗时。

# Schema 单元测试（无需 GPU）
PYTHONPATH=. .venv/base/bin/python -m pytest tests/test_schemas.py -v

# Processor 测试（需要 GPU）
CUDA_VISIBLE_DEVICES=0 PYTHONPATH=. .venv/base/bin/python -m pytest tests/test_chat.py tests/test_streaming.py tests/test_duplex.py -v -s

# API 集成测试（需要先启动服务）
PYTHONPATH=. .venv/base/bin/python -m pytest tests/test_api.py -v -s