logo
qiuyurs/MiniCPM-V-4_5
Public
0
0
WeChat Login
CodeISSUEPull requestsEventsPackagesInsights
main
Branch
1
Tag
0
X.
更新README文档：FastAPI API服务全面升级
7f974c9c
27 commits
utils
.cnb.yml
.gitignore
1.txt
CLAUDE.md
api_server.py
download_model.py
install_env.sh
readme.md
requirements.txt
start_api_server.py
system_check.py

MiniCPM-V-4_5 本地部署指南

📋 项目简介

MiniCPM-V-4_5 是一个高效的多模态大模型，支持图像和视频理解对话。本指南提供详细的本地部署步骤，使用中国境内服务加速下载和部署。

模型特点:

  • 🖼️ 支持高分辨率图像理解
  • 🎬 支持视频理解（最大180帧）
  • 💬 多轮对话能力
  • 🚀 INT4量化版本，资源占用更少
  • 🇨🇳 商用免费需填写问卷
  • ⚡ FastAPI API服务：高性能、现代化的Web API框架

项目特性:

  • 🌐 现代化FastAPI Web服务
  • 🔧 智能环境检测和适配
  • 🐳 容器环境完整支持
  • 📦 多套依赖包配置
  • 🎯 多模式启动配置
  • 📊 完整系统监控工具

🏗️ 系统要求

硬件要求

  • GPU: 推荐8GB显存以上（如RTX 3080/4080/A100）
  • 内存: 推荐16GB以上
  • 磁盘空间: 至少10GB可用空间
  • CPU: 支持AVX2指令集

软件要求

  • Python: 3.8+ (推荐3.10)
  • FastAPI: 0.104.0+
  • Uvicorn: 0.24.0+
  • PyTorch: 2.0+
  • CUDA: 12.1+ (如使用GPU)
  • 操作系统: Linux/Windows/macOS

🚀 快速开始

第一步：克隆/下载项目

# 如果是git仓库
git clone <repository-url>
cd MiniCPM-V-4_5

# 或者直接下载文件到本地目录

第二步：安装环境（手动运行脚本）

⚠️ 注意：此步骤需要手动执行

# 给脚本执行权限
chmod +x install_env.sh

# 运行环境安装脚本
./install_env.sh

脚本会自动：

  • 检测操作系统并安装系统依赖
  • 创建Python虚拟环境
  • 配置国内镜像源加速下载
  • 安装所有Python依赖包（包括FastAPI、Uvicorn等）
  • 验证安装结果
  • 创建项目目录结构

脚本功能：

  • 支持Ubuntu/Debian/CentOS/Rocky/AlmaLinux
  • 自动安装Python 3.8+和开发工具
  • 配置清华镜像源
  • 安装PyTorch + CUDA支持
  • 安装FastAPI Web服务依赖
  • 创建环境激活脚本

环境激活：

# 方法1：使用自动激活脚本
source activate_env.sh

# 方法2：手动激活虚拟环境
source venv/bin/activate

第三步：下载模型

⚠️ 注意：此步骤需要手动执行

# 确保环境已激活
source activate_env.sh

# 下载模型
python download_model.py

脚本会自动：

  • 安装必要依赖包
  • 从ModelScope下载模型文件
  • 使用阿里云镜像源加速下载

下载说明：

  • 模型大小约7-8GB
  • 网络状况决定下载时间（通常10-30分钟）
  • 模型保存在 ./model/OpenBMB/MiniCPM-V-4_5-int4/ 目录

第四步：启动FastAPI API服务

⚠️ 注意：此步骤需要手动执行

开发模式启动（推荐用于测试）

# 确保环境已激活
source activate_env.sh

# 方法1：使用Python脚本启动
python start_api_server.py

# 方法2：使用Shell脚本启动（Linux/macOS）
./start_api_server.sh

# 方法3：使用批处理脚本启动（Windows）
start_api_server.bat

生产模式启动

# 生产模式，多工作进程
python start_api_server.py --config production

# 或者使用Shell脚本
./start_api_server.sh --production

# 自定义配置启动
python start_api_server.py --custom --host 0.0.0.0 --port 8080 --workers 4

其他启动模式

# 测试模式启动
python start_api_server.py --config testing

# 低内存模式启动
python start_api_server.py --config low_memory

# 启动并执行健康检查
python start_api_server.py --config development --health-check

# 列出所有可用配置
python start_api_server.py --list-configs

自定义配置启动

# 自定义端口和主机
python start_api_server.py --custom --host 127.0.0.1 --port 8080

# 热重载开发模式
python start_api_server.py --custom --reload

# 跳过环境检查
python start_api_server.py --skip-env-check

FastAPI API服务功能：

  • 🚀 高性能FastAPI推理引擎
  • 🔌 OpenAI兼容API接口
  • 🖼️ 多模态处理（图像、视频、文本）
  • 📡 实时流式响应
  • 💚 健康检查和监控
  • 📚 自动API文档

第五步：使用API服务

API服务地址

基础文本对话

curl -X POST "http://localhost:8000/v1/chat/completions" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MiniCPM-V-4_5",
       "messages": [
         {
           "role": "user",
           "content": "请介绍一下MiniCPM-V模型的特点"
         }
       ],
       "max_tokens": 512,
       "temperature": 0.7
     }'

图像对话

curl -X POST "http://localhost:8000/v1/chat/completions" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MiniCPM-V-4_5",
       "messages": [
         {
           "role": "user",
           "content": "请详细描述这张图片中的内容"
         }
       ],
       "image_url": "https://example.com/image.jpg",
       "max_tokens": 512,
       "temperature": 0.7
     }'

图像对话（Base64）

curl -X POST "http://localhost:8000/v1/chat/completions" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MiniCPM-V-4_5",
       "messages": [
         {
           "role": "user",
           "content": "请描述这张图片"
         }
       ],
       "image_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
       "max_tokens": 512
     }'

视频对话

curl -X POST "http://localhost:8000/v1/chat/completions" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MiniCPM-V-4_5",
       "messages": [
         {
           "role": "user",
           "content": "请描述这个视频中发生了什么"
         }
       ],
       "video_url": "https://example.com/video.mp4",
       "max_tokens": 512
     }'

流式响应

curl -X POST "http://localhost:8000/v1/chat/completions" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MiniCPM-V-4_5",
       "messages": [
         {
           "role": "user",
           "content": "请讲一个短故事"
         }
       ],
       "stream": true,
       "max_tokens": 512
     }'

Python客户端示例

import requests

# 基础文本对话
response = requests.post(
    "http://localhost:8000/v1/chat/completions",
    json={
        "model": "MiniCPM-V-4_5",
        "messages": [
            {"role": "user", "content": "请介绍一下MiniCPM-V模型的特点"}
        ],
        "max_tokens": 512,
        "temperature": 0.7
    }
)

print(response.json())

# 图像对话
response = requests.post(
    "http://localhost:8000/v1/chat/completions",
    json={
        "model": "MiniCPM-V-4_5",
        "messages": [
            {"role": "user", "content": "请详细描述这张图片中的内容"}
        ],
        "image_url": "https://example.com/image.jpg",
        "max_tokens": 512
    }
)

print(response.json())

📁 目录结构

MiniCPM-V-4_5/
├── .cnb.yml                 # CNB开发环境配置
├── install_env.sh           # 环境安装脚本（手动执行）
├── activate_env.sh          # 环境激活脚本（安装后生成）
├── download_model.py        # 模型下载脚本（手动执行）
├── system_check.py         # 系统环境检测脚本（增强版）
│
├── FastAPI API服务核心文件/
├── api_server.py           # FastAPI API服务器核心文件
├── start_api_server.py     # FastAPI服务启动脚本
│
├── utils/                  # 工具模块
│   ├── __init__.py        # 工具模块初始化
│   ├── image_utils.py     # 图像处理工具
│   └── video_utils.py     # 视频处理工具
│
├── 启动脚本/
├── start_api_server.py      # Python启动脚本
├── start_api_server.sh      # Shell启动脚本（Linux/macOS）
├── start_api_server.bat     # 批处理启动脚本（Windows）
│
├── 依赖包配置/
├── requirements.txt        # 完整依赖包列表
├── requirements-prod.txt   # 生产环境依赖包
├── requirements-dev.txt    # 开发环境依赖包
│
├── readme.md               # 项目文档（原部署文档.md）
├── venv/                   # Python虚拟环境（安装后生成）
├── model/                  # 模型文件目录（下载后生成）
│   └── OpenBMB/MiniCPM-V-4_5-int4/
├── data/                   # 数据目录（安装后生成）
│   ├── logs/               # 日志目录
│   └── scripts/            # 脚本目录
└── test_image.png          # 测试图片（测试后生成）

🔧 详细配置

CNB开发环境配置

.cnb.yml 文件配置：

# 启动一个能使用 gpu 的远程开发环境
$:
  vscode:
    - runner:
        tags: cnb:arch:amd64:gpu
      services:
        - vscode
      stages:
        - name: 查看开发环境
          script: python system_check.py

配置说明：

  • 使用GPU镜像（L40）
  • 启用GPU支持（AMD64架构）
  • 自动运行系统环境检测

系统环境检测脚本

system_check.py 增强功能：

🔍 系统硬件检测

  • CPU详细信息：
    • 物理和逻辑核心数
    • CPU使用率和频率信息（当前/最大/最小）
    • CPU型号信息（Linux系统）
  • 内存详细信息：
    • 虚拟内存监控（总量/已用/空闲/使用率）
    • 交换分区分区信息和使用状态
  • 磁盘详细信息：
    • 所有磁盘分区信息
    • 文件系统类型、容量、使用率
  • GPU详细信息：
    • NVIDIA GPU检测（nvidia-smi）
    • GPU内存使用率和使用率
    • 驱动版本和CUDA版本
    • PyTorch CUDA支持和设备信息

🌐 网络环境检测

  • 外网IP信息：使用cip.cc获取IP地址和地理位置
  • 内网IP地址：所有网络接口的IP地址
  • 网络连接信息：所有活动网络连接详情
  • 主机名信息：系统主机名和网络标识

💻 系统软件检测

  • 操作系统信息：
    • 系统版本、内核版本
    • 硬件架构、处理器信息
    • Linux发行版信息
    • 系统运行时间和负载情况
    • Windows版本信息（如适用）
  • Python环境信息：
    • Python版本和详细版本号
    • Python可执行文件路径
    • pip版本和conda版本（如安装）
    • 已安装包数量统计
    • 站点包路径信息

📊 智能分析和建议

  • 性能监控：CPU、内存、GPU使用率监控
  • 存储预警：磁盘空间不足预警（>90%）
  • GPU优化：GPU使用率过高建议
  • 环境评估：Python版本合规性检查
  • 系统健康：综合系统状态评估和建议

使用方法：

# 基础系统检查
python system_check.py

# 输出包含：
# - 完整硬件信息汇总
# - 网络连接分析
# - Python环境评估
# - GPU状态检测
# - 智能优化建议

FastAPI API服务配置

api_server.py 核心功能：

🚀 高性能FastAPI推理引擎

  • FastAPI集成：基于FastAPI的现代快速API框架
  • 多模态支持：支持图像、视频、文本多模态输入
  • 异步处理：高效的异步请求处理
  • 自动批处理：请求动态合并，提高吞吐量

🔌 OpenAI兼容API接口

  • 标准接口：完全兼容OpenAI Chat Completions API
  • 多模态扩展：支持图像和视频输入的扩展API
  • 流式响应：支持Server-Sent Events流式输出
  • 错误处理：完善的错误处理和状态码

📡 实时流式响应

  • SSE支持：Server-Sent Events实时流式输出
  • 分块传输：响应内容分块传输，减少延迟
  • 断点续传：支持流式传输中断恢复
  • 性能优化：流式传输内存和CPU优化

💚 健康检查和监控

  • 健康检查：/v1/health端点实时健康状态
  • 系统监控：CPU、内存、GPU使用率监控
  • 日志记录：完整的请求和响应日志

📚 自动API文档

  • Swagger UI：/docs端点交互式API文档
  • ReDoc：/redoc端点专业API文档
  • OpenAPI规范：完整的OpenAPI JSON规范
  • 示例请求：详细的请求示例和响应格式

使用方法：

# 启动API服务
python start_api_server.py

# 访问API文档
open http://localhost:8000/docs

# 健康检查
curl http://localhost:8000/v1/health

FastAPI服务启动配置

start_api_server.py 配置功能：

⚙️ 灵活的配置系统

  • 预设配置：开发、生产、测试、低内存四种预设配置
  • 自定义配置：支持自定义主机、端口、工作进程等参数
  • 环境变量支持：支持环境变量动态配置
  • 实时更新：支持配置的实时更新和重载

🎯 智能环境检测

  • 依赖检查：自动检查Python、FastAPI、uvicorn等依赖
  • 系统监控：CPU、内存、GPU使用率监控
  • 模型检测：自动检测模型文件是否存在
  • 健康检查：启动后自动执行健康检查

📋 预设配置模板

  • 开发配置：开发环境优化配置（热重载、调试日志）
  • 生产配置：生产环境高性能配置（多进程、优化日志）
  • 测试配置：测试环境配置（单进程、调试日志）
  • 低内存配置：内存受限环境配置（单进程、优化内存）

使用方法：

# 开发模式启动
python start_api_server.py --config development

# 生产模式启动
python start_api_server.py --config production

# 自定义配置启动
python start_api_server.py --custom --host 0.0.0.0 --port 8080

# 列出所有可用配置
python start_api_server.py --list-configs

多模态处理工具

utils/ 工具模块：

🖼️ 图像处理工具 (image_utils.py)

  • 格式支持：支持JPEG、PNG、BMP、WebP、TIFF、GIF
  • 图像处理：缩放、裁剪、旋转、翻转、滤镜
  • 图像增强：亮度、对比度、锐度调整
  • 格式转换：RGB转换、Base64编码、PIL格式互转
  • 批处理：批量图像处理和优化

🎬 视频处理工具 (video_utils.py)

  • 格式支持：支持MP4、AVI、MOV、MKV、WebM、FLV、WMV
  • 帧提取：智能帧提取，支持时间间隔和最大帧数
  • 视频处理：压缩、格式转换、缩略图生成
  • 多引擎支持：decord和OpenCV双引擎支持
  • 批处理：批量视频处理和优化

使用方法：

from utils.image_utils import ImageProcessor
from utils.video_utils import VideoProcessor

# 图像处理
img_processor = ImageProcessor()
image = img_processor.load_image("input.jpg")
processed = img_processor.resize_image(image, (512, 512))

# 视频处理
video_processor = VideoProcessor()
frames = video_processor.extract_frames("input.mp4", max_frames=16)

环境安装脚本（推荐使用）

install_env.sh 最新特性：

🔧 容器环境适配

  • 自动检测容器环境：支持Docker、LXC等容器环境的自动识别
  • 智能权限管理：容器环境自动跳过sudo命令，直接执行系统命令
  • 权限检查优化：容器环境跳过root权限警告，避免交互确认

🐍 Python自动安装

  • 版本检测：自动检测Python是否存在或版本低于3.8
  • 多版本支持：支持Python 3.11/3.10/3.9/3.8降级安装策略
  • 系统区分：
    • Ubuntu系统：使用dead snakes PPA源
    • Debian系统：使用官方包管理器，避免PPA兼容性问题
    • CentOS/Rocky/AlmaLinux：使用EPEL仓库

📦 包管理策略

  • 依赖管理：根据系统类型自动选择合适的包管理器
  • 编译环境：为容器环境预装编译工具链
  • 源码安装：包管理器安装失败时自动从源码编译安装

🎯 安装流程

# 1. 给脚本执行权限
chmod +x install_env.sh

# 2. 运行安装脚本（自动适配环境）
./install_env.sh

# 3. 激活环境
source activate_env.sh

🚀 支持的环境

  • Ubuntu/Debian：自动适配，区分处理
  • CentOS/Rocky/AlmaLinux：完整yum支持
  • 容器环境：Docker、LXC、k8s等
  • 物理机/虚拟机：支持权限管理和sudo

原始特性：

  • 自动检测操作系统类型
  • 支持多系统：Ubuntu/Debian/CentOS/Rocky/AlmaLinux
  • 自动安装Python 3.8+和系统依赖
  • 创建独立的Python虚拟环境
  • 配置清华镜像源加速下载
  • 安装PyTorch + CUDA支持
  • 自动验证安装结果

使用方法：

# 1. 给脚本执行权限
chmod +x install_env.sh

# 2. 运行安装脚本
./install_env.sh

# 3. 激活环境
source activate_env.sh

依赖包管理

本项目提供多套依赖包配置文件：

requirements.txt (完整依赖包)

# 核心依赖
torch>=2.0.0
torchvision>=0.15.0
transformers>=4.35.0

# 模型和数据处理
modelscope>=1.8.0
decord>=0.6.0
numpy>=1.24.0
Pillow>=9.5.0

# vLLM API服务依赖
vllm>=0.4.0
fastapi>=0.104.0
uvicorn[standard]>=0.24.0
pydantic>=2.5.0

# 图像和视频处理
opencv-python>=4.8.0
imageio[ffmpeg]>=2.31.0

# 网络和IO
requests>=2.31.0
aiofiles>=23.2.0

# 系统监控和工具
psutil>=5.9.0
tqdm>=4.66.0

requirements-prod.txt (生产环境)

  • 精简版依赖包，仅包含生产环境运行所需的包
  • 移除开发工具和调试依赖
  • 优化部署包大小

requirements-dev.txt (开发环境)

  • 包含所有基础依赖
  • 添加开发工具：pytest、black、flake8、mypy
  • 包含代码质量工具：bandit、safety
  • 添加文档生成工具：sphinx
  • 包含性能分析工具

安装方法：

# 基础依赖安装
pip install -r requirements.txt

# 生产环境安装
pip install -r requirements-prod.txt

# 开发环境安装
pip install -r requirements-dev.txt

镜像源配置

为加速下载，建议配置国内镜像源：

pip镜像源：

# 阿里云镜像
pip install -i https://mirrors.aliyun.com/pypi/simple/ [package_name]

# 清华镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ [package_name]

PyTorch安装：

# CUDA 12.1版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

💻 API客户端示例

Python客户端

基础文本对话客户端

import requests
import json

class MiniCPMClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
        
    def chat_completion(self, messages, max_tokens=512, temperature=0.7, stream=False):
        """发送聊天完成请求"""
        endpoint = f"{self.base_url}/v1/chat/completions"
        
        payload = {
            "model": "MiniCPM-V-4_5",
            "messages": messages,
            "max_tokens": max_tokens,
            "temperature": temperature,
            "stream": stream
        }
        
        headers = {
            "Content-Type": "application/json"
        }
        
        try:
            response = requests.post(endpoint, json=payload, headers=headers)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            return {"error": str(e)}
    
    def chat_with_image(self, messages, image_url, max_tokens=512, temperature=0.7):
        """发送图像对话请求"""
        endpoint = f"{self.base_url}/v1/chat/completions"
        
        payload = {
            "model": "MiniCPM-V-4_5",
            "messages": messages,
            "image_url": image_url,
            "max_tokens": max_tokens,
            "temperature": temperature
        }
        
        headers = {
            "Content-Type": "application/json"
        }
        
        try:
            response = requests.post(endpoint, json=payload, headers=headers)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            return {"error": str(e)}
    
    def chat_with_video(self, messages, video_url, max_tokens=512, temperature=0.7):
        """发送视频对话请求"""
        endpoint = f"{self.base_url}/v1/chat/completions"
        
        payload = {
            "model": "MiniCPM-V-4_5",
            "messages": messages,
            "video_url": video_url,
            "max_tokens": max_tokens,
            "temperature": temperature
        }
        
        headers = {
            "Content-Type": "application/json"
        }
        
        try:
            response = requests.post(endpoint, json=payload, headers=headers)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            return {"error": str(e)}

# 使用示例
client = MiniCPMClient()

# 文本对话
messages = [{"role": "user", "content": "请介绍一下MiniCPM-V模型的特点"}]
response = client.chat_completion(messages)
print("文本对话回复:", response['choices'][0]['message']['content'])

# 图像对话
messages = [{"role": "user", "content": "请详细描述这张图片中的内容"}]
image_url = "https://example.com/image.jpg"
response = client.chat_with_image(messages, image_url)
print("图像对话回复:", response['choices'][0]['message']['content'])

# 视频对话
messages = [{"role": "user", "content": "请描述这个视频中发生了什么"}]
video_url = "https://example.com/video.mp4"
response = client.chat_with_video(messages, video_url)
print("视频对话回复:", response['choices'][0]['message']['content'])

JavaScript/浏览器客户端

基础文本对话

class MiniCPMClient {
    constructor(baseUrl = 'http://localhost:8000') {
        this.baseUrl = baseUrl;
    }
    
    async chatCompletion(messages, maxTokens = 512, temperature = 0.7, stream = false) {
        const endpoint = `${this.baseUrl}/v1/chat/completions`;
        
        const payload = {
            model: 'MiniCPM-V-4_5',
            messages: messages,
            max_tokens: maxTokens,
            temperature: temperature,
            stream: stream
        };
        
        try {
            const response = await fetch(endpoint, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
            });
            
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            
            return await response.json();
        } catch (error) {
            return { error: error.message };
        }
    }
    
    async chatWithImage(messages, imageUrl, maxTokens = 512, temperature = 0.7) {
        const endpoint = `${this.baseUrl}/v1/chat/completions`;
        
        const payload = {
            model: 'MiniCPM-V-4_5',
            messages: messages,
            image_url: imageUrl,
            max_tokens: maxTokens,
            temperature: temperature
        };
        
        try {
            const response = await fetch(endpoint, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
            });
            
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            
            return await response.json();
        } catch (error) {
            return { error: error.message };
        }
    }
    
    async chatWithVideo(messages, videoUrl, maxTokens = 512, temperature = 0.7) {
        const endpoint = `${this.baseUrl}/v1/chat/completions`;
        
        const payload = {
            model: 'MiniCPM-V-4_5',
            messages: messages,
            video_url: videoUrl,
            max_tokens: maxTokens,
            temperature: temperature
        };
        
        try {
            const response = await fetch(endpoint, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
            });
            
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            
            return await response.json();
        } catch (error) {
            return { error: error.message };
        }
    }
}

// 使用示例
const client = new MiniCPMClient();

// 文本对话
const messages = [{ role: 'user', content: '请介绍一下MiniCPM-V模型的特点' }];
client.chatCompletion(messages)
    .then(response => {
        console.log('文本对话回复:', response.choices[0].message.content);
    })
    .catch(error => {
        console.error('请求失败:', error);
    });

// 图像对话
const imageMessages = [{ role: 'user', content: '请详细描述这张图片中的内容' }];
const imageUrl = 'https://example.com/image.jpg';
client.chatWithImage(imageMessages, imageUrl)
    .then(response => {
        console.log('图像对话回复:', response.choices[0].message.content);
    })
    .catch(error => {
        console.error('请求失败:', error);
    });

流式响应客户端

Python流式处理

import requests
import json

class StreamingMiniCPMClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
        
    def stream_chat_completion(self, messages, max_tokens=512, temperature=0.7):
        """流式聊天完成"""
        endpoint = f"{self.base_url}/v1/chat/completions"
        
        payload = {
            "model": "MiniCPM-V-4_5",
            "messages": messages,
            "max_tokens": max_tokens,
            "temperature": temperature,
            "stream": True
        }
        
        headers = {
            "Content-Type": "application/json"
        }
        
        try:
            response = requests.post(endpoint, json=payload, headers=headers, stream=True)
            response.raise_for_status()
            
            # 处理SSE流
            for line in response.iter_lines():
                if line:
                    line = line.decode('utf-8')
                    if line.startswith('data: '):
                        data = line[6:]  # 移除 'data: ' 前缀
                        if data == '[DONE]':
                            break
                        try:
                            chunk = json.loads(data)
                            if 'choices' in chunk and len(chunk['choices']) > 0:
                                delta = chunk['choices'][0].get('delta', {})
                                content = delta.get('content', '')
                                if content:
                                    yield content
                        except json.JSONDecodeError:
                            continue
                            
        except requests.exceptions.RequestException as e:
            yield f"Error: {str(e)}"

# 使用示例
client = StreamingMiniCPMClient()
messages = [{"role": "user", "content": "请讲一个短故事"}]

print("流式响应:")
for chunk in client.stream_chat_completion(messages):
    print(chunk, end='', flush=True)
print()

图像上传和处理

Python图像处理客户端

import requests
import base64
from PIL import Image
import io

class ImageMiniCPMClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
        
    def image_to_base64(self, image_path):
        """将图像文件转换为Base64"""
        with open(image_path, "rb") as image_file:
            encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
            return f"data:image/jpeg;base64,{encoded_string}"
    
    def chat_with_image_file(self, messages, image_path, max_tokens=512, temperature=0.7):
        """使用本地图像文件进行对话"""
        image_base64 = self.image_to_base64(image_path)
        
        endpoint = f"{self.base_url}/v1/chat/completions"
        
        payload = {
            "model": "MiniCPM-V-4_5",
            "messages": messages,
            "image_base64": image_base64,
            "max_tokens": max_tokens,
            "temperature": temperature
        }
        
        headers = {
            "Content-Type": "application/json"
        }
        
        try:
            response = requests.post(endpoint, json=payload, headers=headers)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            return {"error": str(e)}
    
    def upload_image(self, image_path):
        """上传图像文件"""
        endpoint = f"{self.base_url}/v1/image/upload"
        
        with open(image_path, 'rb') as image_file:
            files = {'file': (image_path, image_file, 'image/jpeg')}
            
            try:
                response = requests.post(endpoint, files=files)
                response.raise_for_status()
                return response.json()
            except requests.exceptions.RequestException as e:
                return {"error": str(e)}

# 使用示例
client = ImageMiniCPMClient()

# 上传图像
upload_result = client.upload_image("test_image.jpg")
print("上传结果:", upload_result)

# 使用本地图像对话
messages = [{"role": "user", "content": "请详细描述这张图片中的内容"}]
response = client.chat_with_image_file(messages, "test_image.jpg")
print("图像对话回复:", response['choices'][0]['message']['content'])

🔍 常见问题

Q1: 下载速度太慢怎么办？

解决方案：

  1. 使用阿里云镜像源：pip install -i https://mirrors.aliyun.com/pypi/simple/ modelscope
  2. 尝试不同时间段下载
  3. 使用代理或切换网络环境
  4. 考虑使用ModelScope CLI工具下载

Q2: 模型加载失败怎么办？

解决方案：

  1. 检查模型文件是否完整下载
  2. 确认PyTorch和CUDA版本兼容
  3. 检查GPU内存是否充足
  4. 尝试使用CPU模式：.to("cpu")

Q3: CUDA相关错误

解决方案：

# 检查CUDA版本
nvcc --version

# 检查PyTorch CUDA支持
python -c "import torch; print(torch.cuda.is_available())"

# 安装匹配的PyTorch版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Q4: 内存不足怎么办？

解决方案：

  1. 使用INT4量化版本（已配置）
  2. 减少batch_size
  3. 启用梯度检查点
  4. 使用更小的max_new_tokens

Q5: 图像处理失败

解决方案：

# 检查图像格式
image = Image.open("your_image.jpg").convert("RGB")

# 调整图像大小
image = image.resize((448, 448))

# 检查图像通道
if image.mode != 'RGB':
    image = image.convert('RGB')

📊 性能优化

GPU优化

# 启用半精度
model = model.half()

# 启用梯度检查点
model.gradient_checkpointing_enable()

# 批量处理
def batch_inference(images, batch_size=4):
    for i in range(0, len(images), batch_size):
        batch = images[i:i+batch_size]
        # 处理批次
        yield process_batch(batch)

内存优化

# 清理缓存
torch.cuda.empty_cache()

# 使用生成器
def stream_response(model, tokenizer, image, msgs):
    for chunk in model.stream_chat(
        image=image,
        msgs=msgs,
        tokenizer=tokenizer
    ):
        yield chunk

🔒 许可证说明

  • 代码许可证: Apache 2.0
  • 模型权重: MiniCPM Model License
  • 商用使用: 需填写问卷

📞 技术支持

官方资源

问题反馈

  1. 检查本文档的常见问题部分
  2. 查看GitHub Issues
  3. 提交新的Issue描述问题

📝 更新日志

v1.2.0 (2024-09-05)

  • FastAPI API服务全面升级：替换vLLM为FastAPI提供更现代化、高效的Web API服务
    • 新增高性能FastAPI推理引擎和异步处理
    • 更灵活的服务启动配置（开发、生产、测试、低内存四种模式）
    • 增强的健康检查和系统监控功能
    • 完整的环境检测和依赖验证
    • 更好的错误处理和日志记录
  • 启动脚本系统重构：新增start_api_server.py智能启动工具
    • 支持预设配置和自定义配置
    • 自动环境检查和问题诊断
    • 内置健康检查和服务监控
    • 命令行参数和配置文件支持
    • 跨平台兼容（Linux/macOS/Windows）
  • 项目架构优化：
    • 简化依赖管理，移除复杂的vLLM配置
    • 增强多模态处理工具的一致性
    • 改进容器环境支持和权限管理
    • 优化系统资源使用和性能
  • 文档全面更新：
    • 更新所有API服务相关的使用说明
    • 新增FastAPI服务配置详解
    • 修正目录结构和启动脚本说明
    • 增强常见问题和性能优化指南

v1.0.3 (2024-09-01)

  • 系统检测脚本全面升级：增强system_check.py功能
    • 新增CPU频率信息检测（当前/最大/最小频率）
    • 新增详细内存和交换分区监控
    • 新增完整磁盘分区信息（文件系统、容量、使用率）
    • 新增网络连接详情监控和统计
    • 新增强GPU检测（NVIDIA驱动、CUDA版本、PyTorch支持）
    • 新增外网IP信息获取（使用cip.cc）
    • 新增系统运行时间和负载信息
    • 新增Python环境详细检测（包数量、站点路径等）
    • 智能系统分析和优化建议（性能预警、存储预警等）

v1.0.2 (2024-09-01)

  • 容器环境适配：修复Docker容器中sudo命令不存在的错误
  • 权限管理优化：添加智能权限管理，自动判断是否需要sudo
  • 系统区分处理：Ubuntu和Debian系统使用不同的Python安装策略
  • Python自动安装：当检测到Python不存在或版本低于3.8时自动安装
  • 文档重构：将部署文档改名为readme.md，标准化项目文档

v1.0.1 (2024-09-01)

  • 容器环境检测：新增容器环境自动识别功能
  • 错误修复：修复Debian系统下add-apt-repository兼容性问题
  • 降级安装：支持Python 3.11→3.10→3.9→3.8递降级安装策略

v1.0.0 (2024-09-01)

  • 初始部署文档
  • 支持ModelScope镜像源下载
  • 完整的测试脚本
  • CNB开发环境配置
  • 自动化环境安装脚本

⚠️ 重要提醒

  1. 手动执行: 所有标注⚠️的脚本需要手动执行，不会自动运行
  2. 磁盘空间: 确保有足够磁盘空间（≥10GB）
  3. 网络稳定: 下载过程中保持网络稳定
  4. 环境检查: 运行测试前确保环境配置正确
  5. 许可证: 商用使用请遵守相关许可证要求

部署完成后，你将拥有一个功能完整的MiniCPM-V-4_5-int4多模态对话系统！ 🎉

About

MiniCPM-V-4_5模型本地部署指南

724.00 KiB
0 forks0 stars1 branches0 TagREADME
Language
Python50%
Markdown29.5%
Shell16.1%
gitignore3.5%
Others0.9%
© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
SKILL
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号