MiniCPM-V 4.5

MiniCPM-V 多模态系列

把模型接入自己的服务：vLLM 与 SGLang 面向高吞吐的 GPU 服务，llama.cpp 与 Ollama 面向本地与端侧运行，Gradio 与 iOS 则是开箱即用的演示应用。按硬件与场景选择其一，本页给出各自的安装、启动与调用步骤。

方案	适用场景	要点
vLLM	高吞吐 GPU 服务	`pip install vllm==0.10.2`，视频推理需 `vllm[video]`
SGLang	高吞吐 GPU 服务	需源码安装，另需 flashinfer 依赖
llama.cpp	本地 CPU / Metal	需先转 GGUF
Ollama	本地快速体验	`ollama run openbmb/minicpm-v4.5`，自行构建需用 OpenBMB 分支
Gradio	Web 演示（图像 / 视频对话）	服务端 + 客户端两部分
iOS	端侧 App（含 Android / HarmonyOS）	基于 `llama.cpp` submodule 编译

vLLM

1. 环境准备

1.1 安装 vLLM

Bash

pip install vllm==0.10.2

进行视频推理时，需要安装相应的视频模块：

Bash

pip install vllm[video]

2. API 服务部署

2.1 启动 API 服务

Bash

vllm serve <模型路径>  --dtype auto --max-model-len 2048 --api-key token-abc123 --gpu_memory_utilization 0.9 --trust-remote-code --max-num-batched-tokens 2048

参数说明：

<模型路径>：指定 MiniCPM-V 4.5 模型的本地路径
--api-key：设置 API 访问密钥
--max-model-len：设置最大模型长度
--gpu_memory_utilization：GPU 内存使用率

2.2 图片推理

Python

from openai import OpenAI
import base64

# API 配置
openai_api_key = "token-abc123"  # API 密钥需与启动服务时设置的密钥保持一致
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

# 读取本地图片并编码
with open('./assets/airplane.jpeg', 'rb') as file:
    image = "data:image/jpeg;base64," + base64.b64encode(file.read()).decode('utf-8')

chat_response = client.chat.completions.create(
    model="<模型路径>",  # 指定模型路径或 HuggingFace ID
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请描述这张图片"},
            {
                "type": "image_url",
                "image_url": {
                    "url": image,  # 支持网络图片 URL
                },
            },
        ],
    }],
    extra_body={
        "stop_token_ids": [1, 151645]
    }
)

print("Chat response:", chat_response)
print("Chat response content:", chat_response.choices[0].message.content)

2.3 视频推理

Python

from openai import OpenAI
import base64

# API 配置
openai_api_key = "token-abc123"
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

# 读取视频文件并编码为 base64
with open('./videos/video.mp4', 'rb') as video_file:
    video_base64 = base64.b64encode(video_file.read()).decode('utf-8')

chat_response = client.chat.completions.create(
    model="<模型路径>",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请描述这个视频"},
                {
                    "type": "video_url",
                    "video_url": {
                        "url": f"data:video/mp4;base64,{video_base64}",
                    },
                },
            ],
        },
    ],
    extra_body={
        "stop_token_ids": [1, 151645]
    }
)

print("Chat response:", chat_response)
print("Chat response content:", chat_response.choices[0].message.content)

2.4 思考与非思考模式

MiniCPM-V 4.5模型支持在回复前进行思考，可通过设置opanai请求参数来开启和关闭思考模式

"chat_template_kwargs": {"enable_thinking": True}

在回复中会通过</think>标签将思考与回复进行分隔

Python

from openai import OpenAI
import base64

# API 配置
openai_api_key = "token-abc123"  # API 密钥需与启动服务时设置的密钥保持一致
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

# 读取本地图片并编码
with open('./assets/airplane.jpeg', 'rb') as file:
    image = "data:image/jpeg;base64," + base64.b64encode(file.read()).decode('utf-8')

chat_response = client.chat.completions.create(
    model="<模型路径>",  # 指定模型路径或 HuggingFace ID
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请描述这张图片"},
            {
                "type": "image_url",
                "image_url": {
                    "url": image,  # 支持网络图片 URL
                },
            },
        ],
    }],
    extra_body={
        "stop_token_ids": [1, 151645],
        "chat_template_kwargs": {"enable_thinking": True},
    }
)

print("Chat response:", chat_response)
print("Chat response content:", chat_response.choices[0].message.content)

2.5 高帧率与长视频理解模式

MiniCPM-V 4.5模型支持高效的高帧率与长视频理解

需要设置环境变量，指定对应的视频加载后端

VLLM_VIDEO_LOADER_BACKEND=enhanced_opencv

1、通过--media-io-kwargs参数设置choose_fps大小，例如：

Bash

VLLM_VIDEO_LOADER_BACKEND=enhanced_opencv vllm serve <模型路径>  --dtype auto --max-model-len 2048 --api-key token-abc123 --gpu_memory_utilization 0.9 --trust-remote-code --max-num-batched-tokens 2048 --media-io-kwargs '{"video": {"choose_fps": 5}}'

[!NOTE]

目前还没有合并到vllm仓库中，可以通过这个vllm仓库进行源代码安装和使用

由于新的视频加载后端加载的视频帧数较多，需要较大显存进行运行

在2 * 4090显卡上，gpu_memory_utilization设置成 0.8，max-model-len和max-num-batched-tokens都设置成 8192 可以成功运行，例如
Bash
VLLM_VIDEO_LOADER_BACKEND=enhanced_opencv CUDA_VISIBLE_DEVICES=1,2 vllm serve &lt;模型路径&gt; --dtype auto --max-model-len 8192 --api-key token-abc123 --gpu_memory_utilization 0.8 --trust-remote-code --tensor-parallel-size 2 --max-num-batched-tokens 8192  --media-io-kwargs '&#123;"video": &#123;"choose_fps": 5&#125;&#125;'

2、或者在openai请求中加入mm_processor_kwargs参数

"mm_processor_kwargs": {"choose_fps": 1}

Python

from openai import OpenAI
import base64

# API 配置
openai_api_key = "token-abc123"
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

# 读取视频文件并编码为 base64
with open('./videos/video.mp4', 'rb') as video_file:
    video_base64 = base64.b64encode(video_file.read()).decode('utf-8')

chat_response = client.chat.completions.create(
    model="<模型路径>",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请描述这个视频"},
                {
                    "type": "video_url",
                    "video_url": {
                        "url": f"data:video/mp4;base64,{video_base64}",
                    },
                },
            ],
        },
    ],
    extra_body={
        "stop_token_ids": [1, 151645],
        "mm_processor_kwargs": {"choose_fps": 1}
    }
)

print("Chat response:", chat_response)
print("Chat response content:", chat_response.choices[0].message.content)

2.6 多轮对话

启动参数配置

进行视频多轮对话时，需要在 vLLM 启动时添加 --limit-mm-per-prompt 参数：

视频多轮对话配置（支持最多3个视频）：

Bash

vllm serve <模型路径> --dtype auto --max-model-len 4096 --api-key token-abc123 --gpu_memory_utilization 0.9 --trust-remote-code --limit-mm-per-prompt '{"video": 3}'

图片和视频混合输入配置：

Bash

vllm serve <模型路径> --dtype auto --max-model-len 4096 --api-key token-abc123 --gpu_memory_utilization 0.9 --trust-remote-code --limit-mm-per-prompt '{"image":5, "video": 2}'

多轮对话示例代码

Python

from openai import OpenAI
import base64
import mimetypes
import os

# API 配置
openai_api_key = "token-abc123"
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

messages = [
    {
        "role": "system",
        "content": "You are a helpful assistant.",
    }
]

def file_to_base64(file_path):
    """将文件转换为 base64 编码"""
    with open(file_path, 'rb') as f:
        return base64.b64encode(f.read()).decode('utf-8')

def get_mime_type(file_path):
    """获取文件 MIME 类型"""
    mime, _ = mimetypes.guess_type(file_path)
    return mime or 'application/octet-stream'

def build_file_content(file_path):
    """构建多媒体文件内容"""
    mime_type = get_mime_type(file_path)
    base64_data = file_to_base64(file_path)
    url = f"data:{mime_type};base64,{base64_data}"

    if mime_type.startswith("image/"):
        return {"type": "image_url", "image_url": {"url": url}}
    elif mime_type.startswith("video/"):
        return {"type": "video_url", "video_url": {"url": url}}
    else:
        print(f"不支持的文件类型: {mime_type}")
        return None

# 交互式对话循环
while True:
    user_text = input("请输入问题（输入 'exit' 退出）：")
    if user_text.strip().lower() == "exit":
        break

    content = [{"type": "text", "text": user_text}]

    # 文件上传确认
    upload_file = input("是否上传文件？(y/n): ").strip().lower() == 'y'
    if upload_file:
        file_path = input("请输入文件路径: ").strip()
        if os.path.exists(file_path):
            file_content = build_file_content(file_path)
            if file_content:
                content.append(file_content)
        else:
            print("文件路径不存在，跳过文件上传。")

    messages.append({
        "role": "user",
        "content": content,
    })

    chat_response = client.chat.completions.create(
        model="<模型路径>",
        messages=messages,
        extra_body={
            "stop_token_ids": [1, 151645]
        }
    )

    ai_message = chat_response.choices[0].message
    print("MiniCPM-V 4.5:", ai_message.content)

    messages.append({
        "role": "assistant",
        "content": ai_message.content,
    })

3. 离线推理

Python

from transformers import AutoTokenizer
from PIL import Image
from vllm import LLM, SamplingParams

# 模型配置
MODEL_NAME = "<模型路径>"
# 可选择使用 HuggingFace 模型 ID
# MODEL_NAME = "openbmb/MiniCPM-V-4_5"

# 加载图片
image = Image.open("./assets/airplane.jpeg").convert("RGB")
tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, trust_remote_code=True)

# 初始化 LLM
llm = LLM(
    model=MODEL_NAME,
    max_model_len=2048,
    trust_remote_code=True,
    disable_mm_preprocessor_cache=True,
    limit_mm_per_prompt={"image": 5}
)

# 构建消息
messages = [{
    "role": "user",
    "content": "(<image>./</image>)\n请描述这张图片的内容"
}]

prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)

# 单次推理
inputs = {
    "prompt": prompt,
    "multi_modal_data": {
        "image": image
        # 多图片推理需使用列表格式：
        # "image": [image1, image2]
    },
}

# 批量推理示例
# inputs = [{
#     "prompt": prompt,
#     "multi_modal_data": {
#         "image": image
#     },
# } for _ in range(2)]

# 设置停止标记
stop_tokens = ['<|im_end|>', '<|endoftext|>']
stop_token_ids = [tokenizer.convert_tokens_to_ids(i) for i in stop_tokens]

# 采样参数
sampling_params = SamplingParams(
    stop_token_ids=stop_token_ids,
    temperature=0.7,
    top_p=0.7,
    max_tokens=1024
)

# 生成结果
outputs = llm.generate(inputs, sampling_params=sampling_params)
print(outputs[0].outputs[0].text)

注意事项

模型路径：需将所有示例中的 <模型路径> 替换为实际的 MiniCPM-V 4.5 模型路径
API 密钥：确保启动服务时的 API 密钥与客户端代码中的密钥保持一致
文件路径：需根据实际情况调整图片、视频文件的路径
内存配置：应根据 GPU 内存情况合理调整 --gpu_memory_utilization 参数
多模态限制：使用多轮对话时需设置合适的 --limit-mm-per-prompt 参数

SGLang

1. SGLang安装

SGLang源码安装

Bash

git clone https://github.com/sgl-project/sglang.git
cd sglang

pip install --upgrade pip
pip install -e "python[all]"

flashinfer依赖安装

方法1:pip 安装（网速可能不行）

Bash

pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/

方法2: whl文件安装

网页访问：https://flashinfer.ai/whl/cu121/torch2.4/flashinfer/
找到适合自己服务器的版本并且下载whl文件:例如flashinfer-0.1.6+cu121torch2.4-cp310-cp310-linux_x86_64.whl

使用pip install ***.whl进行安装，比如:

Cpp

pip install flashinfer-0.1.6+cu121torch2.4-cp310-cp310-linux_x86_64.whl

如果在安装过程中遇到问题，请随时查阅官方安装文档

2. sglang发起推理服务

默认情况下，它将从 Hugging Face Hub 下载模型文件

Bash

python -m sglang.launch_server --model-path openbmb/MiniCPM-V-4_5 --port 30000

也可以在参数 --model-path 后指定本地路径

Bash

python -m sglang.launch_server --model-path your_model_path --port 30000 --trust-remote-code

3. 调用服务接口

bash调用

Python

curl -s http://localhost:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
    "model": "MiniCPM-V-4.5",
    "messages": [
    {
        "role": "user",
        "content": [
        {
            "type": "text",
            "text": "What’s in this image?"
        },
        {
            "type": "image_url",
            "image_url": {
            "url": "https://github.com/OpenSQZ/MiniCPM-V-CookBook/blob/main/inference/assets/airplane.jpeg?raw=true"
            }
        }
        ]
    }
    ],
    "max_tokens": 300
}'

python调用

Python

from openai import OpenAI

client = OpenAI(base_url=f"http://localhost:30000/v1", api_key="None")

response = client.chat.completions.create(
    model="MiniCPM-V-4.5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image?",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://github.com/OpenSQZ/MiniCPM-V-CookBook/blob/main/inference/assets/airplane.jpeg?raw=true",
                    },
                },
            ],
        }
    ],
    max_tokens=300,
)

print(response.choices[0].message.content)

image_url如果不能访问，可以替换成本地图片 更多调用方法可以参考sglang使用文档

llama.cpp

1. 编译安装 llama.cpp

克隆 llama.cpp 代码仓库:

Bash

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

使用 CMake 构建 llama.cpp: https://github.com/ggerganov/llama.cpp/blob/master/docs/build.md

CPU/Metal:

Bash

cmake -B build
cmake --build build --config Release

CUDA:

Bash

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

2. 获取模型 GGUF 权重

方法一: 下载官方 GGUF 文件

HuggingFace: https://huggingface.co/openbmb/MiniCPM-V-4_5-gguf
魔搭社区: https://modelscope.cn/models/OpenBMB/MiniCPM-V-4_5-gguf

从仓库中下载语言模型文件（如: ggml-model-Q4_K_M.gguf）与视觉模型文件（mmproj-model-f16.gguf）

方法二: 从 Pytorch 模型转换

下载 MiniCPM-V-4_5 PyTorch 模型到 "MiniCPM-V-4_5" 文件夹:

HuggingFace: https://huggingface.co/openbmb/MiniCPM-V-4_5
魔搭社区: https://modelscope.cn/models/OpenBMB/MiniCPM-V-4_5

将 PyTorch 模型转换为 GGUF 格式:

Bash

python ./tools/mtmd/legacy-models/minicpmv-surgery.py -m ../MiniCPM-V-4_5

python ./tools/mtmd/legacy-models/minicpmv-convert-image-encoder-to-gguf.py -m ../MiniCPM-V-4_5 --minicpmv-projector ../MiniCPM-V-4_5/minicpmv.projector --output-dir ../MiniCPM-V-4_5/ --minicpmv_version 6

python ./convert_hf_to_gguf.py ../MiniCPM-V-4_5/model

# int4 量化版本
./llama-quantize ../MiniCPM-V-4_5/model/Model-3.6B-F16.gguf ../MiniCPM-V-4_5/model/ggml-model-Q4_K_M.gguf Q4_K_M

3. 模型推理

Bash

cd build/bin/

# 运行 f16 版本
./llama-mtmd-cli -m ../MiniCPM-V-4_5/model/Model-3.6B-F16.gguf --mmproj ../MiniCPM-V-4_5/mmproj-model-f16.gguf -c 4096 --temp 0.7 --top-p 0.8 --top-k 100 --repeat-penalty 1.05 --image xx.jpg -p "What is in the image?"

# 运行 int4 量化版本
./llama-mtmd-cli -m ../MiniCPM-V-4_5/model/ggml-model-Q4_K_M.gguf --mmproj ../MiniCPM-V-4_5/mmproj-model-f16.gguf -c 4096 --temp 0.7 --top-p 0.8 --top-k 100 --repeat-penalty 1.05 --image xx.jpg -p "What is in the image?"

# 或以交互模式运行
./llama-mtmd-cli -m ../MiniCPM-V-4_5/model/ggml-model-Q4_K_M.gguf --mmproj ../MiniCPM-V-4_5/mmproj-model-f16.gguf -c 4096 --temp 0.7 --top-p 0.8 --top-k 100 --repeat-penalty 1.05 --image xx.jpg -i

# 或以思考模式运行(思考输出的token无限制)
./llama-mtmd-cli -m ../MiniCPM-V-4_5/model/ggml-model-Q4_K_M.gguf --mmproj ../MiniCPM-V-4_5/mmproj-model-f16.gguf -c 4096 --temp 0.7 --top-p 0.8 --top-k 100 --repeat-penalty 1.05 --image xx.jpg --jinja --reasoning-budget -1 -p "what is it?"

# 或以禁止思考模式运行
./llama-mtmd-cli -m ../MiniCPM-V-4_5/model/ggml-model-Q4_K_M.gguf --mmproj ../MiniCPM-V-4_5/mmproj-model-f16.gguf -c 4096 --temp 0.7 --top-p 0.8 --top-k 100 --repeat-penalty 1.05 --image xx.jpg --jinja --reasoning-budget 0 -p "what is it?"

命令行参数解析:

参数	`-m, --model`	`--mmproj`	`--image`	`-p, --prompt`	`-c, --ctx-size`	`--reasoning-budget`	`--jinja`
含义	语言模型路径	视觉模型路径	输入图片路径	提示词	输入上下文最大长度	最大思考输出token数量	使用jinja模板

Ollama

1. 安装 Ollama

macOS: 下载
Windows: 下载
Linux: curl -fsSL https://ollama.com/install.sh | sh, 或参照 Ollama 官方手动安装指南.
Docker: 官方的 Ollama Docker 镜像 ollama/ollama 已在 Docker Hub 上提供。

本地构建运行 Ollama

环境需求：

go version 1.22 or above
cmake version 3.24 or above
C/C++ Compiler e.g. Clang on macOS, TDM-GCC (Windows amd64) or llvm-mingw (Windows arm64), GCC/Clang on Linux.

获取 OpenBMB 官方 Ollama 分支：

Bash

git clone https://github.com/tc-mb/ollama.git
cd ollama
git checkout MiniCPM-V

在仓库根目录下编译并运行 Ollama：

Bash

go build .
./ollama serve

2. 快速使用

Ollama 可以直接使用:

Bash

./ollama run openbmb/minicpm-v4.5

命令行

用空格分割输入问题、图片路径

Plain Text

这张图片描述了什么？ xx.jpg

API

Python

with open(image_path, 'rb') as image_file:
    # 将图片文件转换为 base64 编码
    encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    data = {
    "model": "minicpm-v4.5",
    "prompt": query,
    "stream": False,
    "images": [encoded_string]# 列表可以放多张图，每张图用上面的方式转化为base64的格式
    }

    # 设置请求 URL
    url = "http://localhost:11434/api/generate"
    response = requests.post(url, json=data)

    return response

3. 自定义方式

若上述方式无法运行，请参考以下教程。

获取 GGUF 模型

HuggingFace: https://huggingface.co/openbmb/MiniCPM-V-4_5-gguf
魔搭社区: https://modelscope.cn/models/OpenBMB/MiniCPM-V-4_5-gguf

创建 ModelFile

编辑 ModelFile:

Bash

vim minicpmv4.5.Modelfile

ModelFile 的内容如下:

Plain Text

FROM ./MiniCPM-V-4_5/model/ggml-model-Q4_K_M.gguf
FROM ./MiniCPM-V-4_5/mmproj-model-f16.gguf

TEMPLATE """{{- if .Messages }}{{- range $i, $_ := .Messages }}{{- $last := eq (len (slice $.Messages $i)) 1 -}}<|im_start|>{{ .Role }}{{ .Content }}{{- if $last }}{{- if (ne .Role "assistant") }}<|im_end|><|im_start|>assistant{{ end }}{{- else }}<|im_end|>{{ end }}{{- end }}{{- else }}{{- if .System }}<|im_start|>system{{ .System }}<|im_end|>{{ end }}{{ if .Prompt }}<|im_start|>user{{ .Prompt }}<|im_end|>{{ end }}<|im_start|>assistant{{ end }}{{ .Response }}{{ if .Response }}<|im_end|>{{ end }}"""

SYSTEM """You are a helpful assistant."""

PARAMETER top_p 0.8
PARAMETER num_ctx 4096
PARAMETER stop ["<|im_start|>","<|im_end|>"]
PARAMETER temperature 0.7

参数说明:

first from	second from	num_ctx
Your language GGUF model path	Your vision GGUF model path	Max Model length

创建 Ollama 模型实例：

Bash

./ollama create minicpm-v4.5 -f minicpmv4.5.Modelfile

另起一个命令行窗口，运行 Ollama 模型实例：

Bash

./ollama run minicpm-v4.5

输入问题和图片 URL，以空格分隔

Bash

这张图片描述了什么？ xx.jpg

Gradio

为 MiniCPM-V 4.5（兼容 MiniCPM-V 4.0）提供 Web 界面演示服务，支持图像和视频的多模态对话。Demo 分为服务端和客户端两个部分。

📖 English Version

部署步骤

服务端

Bash

cd server
conda create -n gradio-server python=3.10
conda activate gradio-server
pip install -r requirements.txt
python gradio_server.py

自定义参数:

Bash

# 指定服务端口、日志目录、模型路径和类型（MiniCPM-V 4.5）
# 若显存有限，可将 /path/to/model 指向 INT4 量化模型，并自行安装相关依赖。
python gradio_server.py --port=9999 --log_dir=logs_v4_5 --model_path=/path/to/model --model_type=minicpmv4_5

客户端

Bash

cd client
conda create -n gradio-client python=3.10
conda activate gradio-client
pip install -r requirements.txt
python gradio_client_minicpmv4_5.py

自定义参数:

Bash

# 指定前端端口和后端服务地址（MiniCPM-V 4.5）
python gradio_client_minicpmv4_5.py --port=8889 --server=http://localhost:9999/api

访问地址

默认配置下，服务启动完成后，在浏览器中访问 http://localhost:8889 可以看到 web demo 页面（客户端默认端口为 8889，服务端默认端口为 9999）

demo

iOS

官方仓库： OpenBMB/MiniCPM-V-Apps

README：English · 简体中文 README_zh

同一仓库内含 iOS、Android、HarmonyOS NEXT 三端 demo，共享仓库根目录的 llama.cpp git submodule（分支 Support-iOS-Demo）。本文侧重 iOS；安卓与鸿蒙的编译说明请直接看 upstream README。

预编译安装包（TestFlight / APK / HAP）：DOWNLOAD.md / DOWNLOAD_zh.md。下面内容为从源码自行构建时使用。

1. 克隆仓库与子模块

Bash

git clone https://github.com/OpenBMB/MiniCPM-V-Apps.git
cd MiniCPM-V-Apps
git submodule update --init --recursive

2. 打开 Xcode 工程

说明：在真机（iPhone / iPad）上部署、调试通常需要有效的 Apple Developer 帐号。

安装 Xcode：

从 App Store 安装 Xcode
安装命令行工具：
Bash
```
xcode-select --install
```
同意许可协议：
Bash
```
sudo xcodebuild -license
```

使用 Xcode 打开 MiniCPM-V-demo/MiniCPM-V-demo.xcodeproj，等待 Xcode 自动下载所需依赖；在顶部选好运行目标设备，点击 Run（三角形）。

说明：若出现 thirdparty/llama.xcframework 相关报错，按第 3 节手动构建框架。

3. 手动构建 llama.xcframework

在仓库根目录（并已拉取 submodule）执行：

Bash

cd llama.cpp
./build-xcframework.sh
cp -r ./build-apple/llama.xcframework ../MiniCPM-V-demo/thirdparty

4. App 所用 GGUF 模型

当前 Demo 对齐 MiniCPM-V 2.6 / 4.0 / 4.6。每个版本都需要分别从官方 GGUF 仓下载 语言模型 GGUF + 视觉投影器 mmproj-model-f16.gguf（视觉塔保留 f16 精度，避免感知质量损失）。

推荐设备内存与总下载体量（详见 upstream README_zh 硬件说明）：

模型	LLM 参数量	推荐量化	总下载量	推荐设备内存
MiniCPM-V 2.6	8B	Q4_K_M	~5.4 GB	≥ 8 GB
MiniCPM-V 4.0	4.1B	Q4_K_M	~2.9 GB	≥ 6 GB
MiniCPM-V 4.6	1.3B	Q4_K_M	~1.6 GB	≥ 6 GB

三端 demo 默认上下文为 4K token，KV cache 占用近似随上下文线性增长，临界设备上可适当下调。

MiniCPM-V 2.6 — 官方 GGUF

Hugging Face：openbmb/MiniCPM-V-2_6-gguf
魔搭：OpenBMB/MiniCPM-V-2_6-gguf

下载语言模型文件（如 ggml-model-Q4_0.gguf）与视觉模型文件 mmproj-model-f16.gguf。

MiniCPM-V 4.0 — 官方 GGUF

Hugging Face：openbmb/MiniCPM-V-4-gguf
魔搭：OpenBMB/MiniCPM-V-4-gguf

下载语言模型文件（如 ggml-model-Q4_K_M.gguf）与视觉模型文件 mmproj-model-f16.gguf。

MiniCPM-V 4.6 — 官方 GGUF

Hugging Face：openbmb/MiniCPM-V-4.6-gguf
魔搭：OpenBMB/MiniCPM-V-4.6-gguf

下载语言模型文件（如 MiniCPM-V-4_6-Q4_K_M.gguf）与视觉模型文件 mmproj-model-f16.gguf。

5. 从 PyTorch 自行转换 GGUF（可选）

Cookbook 中的转换流程见：

MiniCPM-V 4.6 GGUF
MiniCPM-V 4.0 GGUF
其他版本：Cookbook 仓库 quantization/gguf/ 目录

vLLM​

1. 环境准备​

1.1 安装 vLLM​

2. API 服务部署​

2.1 启动 API 服务​

2.2 图片推理​

2.3 视频推理​

2.4 思考与非思考模式​

2.5 高帧率与长视频理解模式​

2.6 多轮对话​

启动参数配置​

多轮对话示例代码​

3. 离线推理​

注意事项​

SGLang​

1. SGLang安装​

SGLang源码安装​

flashinfer依赖安装​

2. sglang发起推理服务​

3. 调用服务接口​

llama.cpp​

1. 编译安装 llama.cpp​

2. 获取模型 GGUF 权重​

方法一: 下载官方 GGUF 文件​

方法二: 从 Pytorch 模型转换​

3. 模型推理​

Ollama​

1. 安装 Ollama​

本地构建运行 Ollama​

2. 快速使用​

命令行​

API​

3. 自定义方式​

获取 GGUF 模型​

创建 ModelFile​

创建 Ollama 模型实例：​

另起一个命令行窗口，运行 Ollama 模型实例：​

输入问题和图片 URL，以空格分隔​

Gradio​

部署步骤​

服务端​

客户端​

访问地址​

iOS​

1. 克隆仓库与子模块​

2. 打开 Xcode 工程​

3. 手动构建 llama.xcframework​

4. App 所用 GGUF 模型​

MiniCPM-V 2.6 — 官方 GGUF​

MiniCPM-V 4.0 — 官方 GGUF​

MiniCPM-V 4.6 — 官方 GGUF​

5. 从 PyTorch 自行转换 GGUF（可选）​

vLLM

1. 环境准备

1.1 安装 vLLM

2. API 服务部署

2.1 启动 API 服务

2.2 图片推理

2.3 视频推理

2.4 思考与非思考模式

2.5 高帧率与长视频理解模式

2.6 多轮对话

启动参数配置

多轮对话示例代码

3. 离线推理

注意事项

SGLang

1. SGLang安装

SGLang源码安装

flashinfer依赖安装

2. sglang发起推理服务

3. 调用服务接口

llama.cpp

1. 编译安装 llama.cpp

2. 获取模型 GGUF 权重

方法一: 下载官方 GGUF 文件

方法二: 从 Pytorch 模型转换

3. 模型推理

Ollama

1. 安装 Ollama

本地构建运行 Ollama

2. 快速使用

命令行

API

3. 自定义方式

获取 GGUF 模型

创建 ModelFile

创建 Ollama 模型实例：

另起一个命令行窗口，运行 Ollama 模型实例：

输入问题和图片 URL，以空格分隔

Gradio

部署步骤

服务端

客户端

访问地址

iOS

1. 克隆仓库与子模块

2. 打开 Xcode 工程

3. 手动构建 llama.xcframework

4. App 所用 GGUF 模型

MiniCPM-V 2.6 — 官方 GGUF

MiniCPM-V 4.0 — 官方 GGUF

MiniCPM-V 4.6 — 官方 GGUF

5. 从 PyTorch 自行转换 GGUF（可选）