MiniCPM-o 4.5 部署指南

本技能将引导 Agent 完成 MiniCPM-o 4.5 的部署。请根据您的部署方式选择对应章节。

步骤 0：检查设备并选择部署方式

部署前，请先确认您的设备类型与可用资源。请参考以下决策树：

您的设备是什么？
│
├─ NVIDIA GPU
│   ├─ VRAM >= 28GB（A100 / H100 / RTX A6000）
│   │   └─→ Web Demo（完整 bf16）✅
│   │
│   ├─ VRAM 12–24GB（RTX 3060 12G / RTX 4070 / RTX 4090）
│   │   └─→ Web Demo（AWQ/BNB int4 量化）✅
│   │
│   └─ VRAM < 12GB
│       └─→ ⚠ 尚未支持（计划支持 llamacpp-omni / vLLM）
│
├─ Apple Silicon（M1/M2/M3/M4/M5 Mac）
│   └─→ ⚠ 尚未支持（计划支持 llamacpp-omni，敬请关注）
│
├─ 纯 CPU（无 GPU）
│   └─→ ⚠ 尚未支持（计划支持 llamacpp-omni，敬请关注）
│
└─ 其他平台（AMD GPU / Intel Arc / Ascend NPU 等）
    └─→ ⚠ 尚未测试，暂不支持

Agent 指南：当前仅支持 VRAM >= 12GB 的 NVIDIA GPU（Web Demo）。 对于所有其他设备——Apple Silicon、纯 CPU、NVIDIA VRAM < 12GB、AMD、Intel Arc、Ascend NPU 等——请向用户明确说明： “该设备暂不支持 MiniCPM-o 4.5 部署。我们计划通过 llamacpp-omni 支持 Apple Silicon 及低资源设备。请持续关注后续更新。” 切勿为不支持的设备提供任何部署操作指引。

部署方式概览

参考资料

• 文档: https://minicpm-o.readthedocs.io/
• HuggingFace: https://huggingface.co/openbmb/MiniCPM-o-4_5
• ModelScope: https://modelscope.cn/models/OpenBMB/MiniCPM-o-4_5

硬件要求

• 预量化 AWQ 模型：openbmb/MiniCPM-o-4_5-awq
• llama.cpp-omni 全双工需 Apple M4 Max >= 24GB 内存 或 NVIDIA >= 12GB

Web Demo 部署

步骤 1：环境准备

1.1 Python 3.10+

若系统已安装 Python 3.10+，可跳过此步；否则请安装 Miniconda：

mkdir -p ./miniconda3_install_tmp
wget https://repo.anaconda.com/miniconda/Miniconda3-py310_25.11.1-1-Linux-x86_64.sh 
    -O ./miniconda3_install_tmp/miniconda.sh
bash ./miniconda3_install_tmp/miniconda.sh -b -u -p ./miniconda3
source ./miniconda3/bin/activate

install.sh 默认使用 python3.10。如需指定其他版本，请运行：PYTHON=python3.11 bash install.sh。

1.2 FFmpeg

sudo apt update && sudo apt install -y ffmpeg

1.3 克隆仓库并安装依赖

git clone https://github.com/OpenBMB/MiniCPM-o-Demo.git
cd MiniCPM-o-Demo
bash ./install.sh

install.sh 将自动执行以下操作：创建 .venv/base 虚拟环境 → 安装 PyTorch 2.8.0 → 安装 requirements.txt 中的依赖 → 验证环境完整性。

手动安装替代方案：

python -m venv .venv/base && source .venv/base/bin/activate
pip install "torch==2.8.0" "torchaudio==2.8.0"
pip install -r requirements.txt

步骤 2：模型下载

模型体积约 18GB。建议使用自动源选择脚本，通过 SDK 对各下载源进行基准测试并选择最快源：

# 自动基准测试各源（通过 SDK 从 HuggingFace / ModelScope 下载 config.json）
python scripts/download_model.py --local-dir ./model/MiniCPM-o-4_5

# 手动指定源：huggingface / modelscope
python scripts/download_model.py --source modelscope --local-dir ./model/MiniCPM-o-4_5

脚本将在下载完成后自动验证模型完整性。若用户已存在本地模型，请单独验证：

# 验证本地模型目录
python scripts/download_model.py --verify /path/to/MiniCPM-o-4_5

# 验证 HuggingFace Hub ID（下载 config.json 进行校验）
python scripts/download_model.py --verify openbmb/MiniCPM-o-4_5

校验项包括：model_type == "minicpmo"、architectures 包含 "MiniCPMO"、version == "4.5"。

脚本位于 scripts/download_model.py。也可直接导入使用：from download_model import verify_model

手动下载替代方案：

# HuggingFace CLI
huggingface-cli download openbmb/MiniCPM-o-4_5 --local-dir /path/to/MiniCPM-o-4_5

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

您也可跳过手动下载——首次启动时，系统将自动从 HuggingFace Hub 下载模型（需网络稳定）。

Agent 指南：当用户提供自定义模型路径时，请先运行 python scripts/download_model.py --verify 验证模型有效性，再进入配置环节。

步骤 3：配置

cp config.example.json config.json

最小化配置（若使用自动下载则无需修改）：

{
  "model": { "model_path": "openbmb/MiniCPM-o-4_5" }
}

本地模型配置：

{
  "model": { "model_path": "/path/to/MiniCPM-o-4_5" }
}

配置优先级：命令行参数 > config.json > 默认值。全部配置字段详见 web-demo-reference.md。

步骤 4：生成 SSL 证书

浏览器麦克风/摄像头 API 要求 HTTPS，SSL 证书为必需项：

mkdir -p certs
openssl req -x509 -newkey rsa:2048 
    -keyout certs/key.pem -out certs/cert.pem 
    -days 365 -nodes -subj '/CN=dev'

自签名证书将触发浏览器安全警告——点击“继续前往”即可。获取正式证书后，请替换 certs/ 目录下的文件。

步骤 5：启动服务

# 单 GPU
CUDA_VISIBLE_DEVICES=0 bash start_all.sh

# 多 GPU（每 GPU 启动一个 Worker，支持并行请求处理）
CUDA_VISIBLE_DEVICES=0,1,2,3 bash start_all.sh

# HTTP 模式（不可用麦克风/摄像头，不推荐）
bash start_all.sh --http

启动脚本将自动执行：GPU 检测 → 启动 Worker（每 GPU 一个）→ 等待模型加载（约 30–90 秒）→ 启动 Gateway → 输出访问 URL。

步骤 6：验证与使用

成功启动输出示例：

Service is running!
Chat Demo:  https://localhost:8006
Admin:      https://localhost:8006/admin
API Docs:   https://localhost:8006/docs

可通过 curl 验证服务状态：

curl -k https://localhost:8006/health

四种交互模式：

停止服务

kill $(cat tmp/*.pid 2>/dev/null) 2>/dev/null
# 或
pkill -f "gateway.py|worker.py"

进阶：torch.compile 加速

在 config.json 中设置 "service": { "compile": true }。

预编译（推荐，避免首次运行约 15 分钟冷启动编译）：

CUDA_VISIBLE_DEVICES=0 TORCHINDUCTOR_CACHE_DIR=./torch_compile_cache 
    .venv/base/bin/python precompile.py

启用缓存后，启动开销降至约 5 分钟；Omni 全双工单次延迟由 ~0.9s 降至 ~0.5s（A100）。

故障排查

详细排错指南请参阅 web-demo-reference.md。快速参考：

vLLM Serve 部署

⚠ 尚未提供 — vLLM Serve 部署功能正在开发中，暂不可用。

Agent 指南：当用户选择或被引导至 vLLM Serve 方式时，请直接回复： “vLLM Serve 部署功能暂未开放。目前请使用 Web Demo 方式作为替代方案。vLLM Serve 支持即将上线——敬请关注后续更新。” 切勿引导用户执行任何 vLLM 部署步骤。

计划内容大纲（开发中）

1. 环境准备与 vLLM 安装
2. 模型加载配置
3. vLLM 服务启动
4. API 调用示例（OpenAI 兼容格式）
5. 多模态输入（图像 / 音频 / 视频）
6. 性能调优（张量并行 / 量化 / 前缀缓存）
7. 故障排查

llamacpp-omni 部署

⚠ 尚未提供 — llamacpp-omni 部署功能正在开发中，暂不可用。

Agent 指南：当用户选择或被引导至 llamacpp-omni（包括 Apple 设备、低显存 NVIDIA、纯 CPU 或其他平台）时，请直接回复： “llamacpp-omni 部署功能暂未开放。若您拥有 NVIDIA GPU（VRAM >= 12GB），可暂用 Web Demo 方式（int4 量化）进行部署。llamacpp-omni 支持即将上线——敬请关注后续更新。” 切勿引导用户执行任何 llamacpp-omni 部署步骤。

计划内容大纲（开发中）

1. 环境准备与 llama.cpp 编译
2. GGUF 模型转换与下载
3. 推理服务启动
4. API 调用示例
5. 多模态输入支持
6. 量化精度与性能对比
7. 故障排查