# minicpm

**Repository Path**: masonwu21/minicpm

## Basic Information

- **Project Name**: minicpm
- **Description**: No description available
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniCPM 本地运行环境

> 基于 llama.cpp 的 MiniCPM 本地部署方案，支持 CPU 推理，无需 GPU。

## 目录

- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [代码结构](#代码结构)
- [llama.cpp 编译](#llamacpp-编译)
- [功能说明](#功能说明)
- [API 使用](#api-使用)
- [PySide6 对话界面](#pyside6-对话界面)
- [量化版本选择](#量化版本选择)
- [常见问题](#常见问题)

---

## 环境要求

| 依赖 | 版本 | 说明 |
|------|------|------|
| Python | 3.11+ | 运行脚本和 transformers |
| Git | 2.40+ | 克隆 llama.cpp |
| CMake | 3.0+ | 编译 llama.cpp |
| Visual Studio | 2022 | MSVC 编译器 |
| PyTorch | 2.9+ (CPU) | transformers 方式运行 |
| PySide6 | 6.10+ | GUI 界面 (可选) |

## 快速开始

```bash
# 1. 克隆仓库 (已完成)
cd D:\Work\CPlusPlus\minicpm

# 2. 编译 llama.cpp (如已编译可跳过)
cd llama.cpp && mkdir build && cd build
cmake .. -DGGML_NATIVE=ON
cmake --build . --config Release
cd ../..

# 3. 下载模型 (推荐使用镜像)
python download_model.py
# 或
download_mirror.bat

# 4. 启动服务
run_server.bat
```

---

## 代码结构

```
minicpm/
│
├── llama.cpp/                          # llama.cpp 源码 (git clone)
│   ├── src/                            # 核心源码
│   ├── common/                         # 通用工具库
│   ├── ggml/                           # 张量计算库
│   ├── tools/                          # 工具程序
│   │   ├── cli/                        # llama-cli
│   │   ├── server/                     # llama-server
│   │   └── quantize/                   # llama-quantize
│   ├── build/                          # 编译输出目录
│   │   └── bin/Release/                # 可执行文件
│   │       ├── llama-server.exe        # API 服务器
│   │       ├── llama-cli.exe           # 命令行交互
│   │       ├── llama-quantize.exe      # 模型量化工具
│   │       └── *.dll                   # 运行时库
│   └── CMakeLists.txt                  # CMake 构建配置
│
├── models/                             # 模型存放目录
│   └── *.gguf                          # GGUF 格式模型文件
│
├── download_model.py                   # 模型下载脚本
├── download_mirror.bat                 # 镜像源下载脚本
│
├── run_server.bat                      # 启动 API 服务器
├── run_chat.bat                        # 启动命令行对话
├── run_transformers.py                 # transformers 方式运行
│
├── chat_app.py                         # PySide6 图形界面
├── test_api.py                         # API 测试脚本
├── test_api.bat                        # API 测试 (批处理)
│
└── README.md                           # 本文档
```

---

## llama.cpp 编译

### 编译步骤

```bash
# 1. 进入 llama.cpp 目录
cd D:\Work\CPlusPlus\minicpm\llama.cpp

# 2. 创建构建目录
mkdir build
cd build

# 3. 配置 CMake
cmake .. -DGGML_NATIVE=ON

# 4. 编译 (Release 模式)
cmake --build . --config Release
```

### 编译选项

| 选项 | 说明 |
|------|------|
| `-DGGML_NATIVE=ON` | 启用原生指令集优化 (AVX2等) |
| `-DLLAMA_CUDA=ON` | 启用 CUDA 加速 (需要 NVIDIA GPU) |
| `-DLLAMA_VULKAN=ON` | 启用 Vulkan 加速 |
| `-DCMAKE_BUILD_TYPE=Release` | Release 模式编译 |

### 编译输出

编译完成后，可执行文件位于：
```
llama.cpp/build/bin/Release/
├── llama-server.exe      # API 服务器 (主要使用)
├── llama-cli.exe         # 命令行交互
├── llama-quantize.exe    # 模型量化工具
├── llama-bench.exe       # 性能测试工具
└── *.dll                 # 动态链接库
```

---

## 功能说明

### 1. download_model.py - 模型下载

支持下载两种格式的模型：

| 格式 | 用途 | 说明 |
|------|------|------|
| GGUF | llama.cpp | 单文件，推荐 |
| HuggingFace | transformers | 多文件，便于微调 |

支持功能：
- HuggingFace 官方源 / 镜像源选择
- MiniCPM5-1B / MiniCPM-2B 模型选择
- 多种量化版本选择

### 2. run_server.bat - API 服务器

启动 OpenAI 兼容的 API 服务器。

**参数说明：**
```
-m <model>          模型文件路径
-t <threads>        线程数 (默认 4)
--host <ip>         监听地址 (默认 0.0.0.0)
--port <port>       监听端口 (默认 8080)
--ctx-size <n>      上下文长度 (默认 2048)
```

**启动后提供接口：**
- `POST /v1/chat/completions` - 对话补全
- `POST /v1/completions` - 文本补全
- `GET /v1/models` - 模型列表

### 3. run_chat.bat - 命令行对话

启动交互式命令行对话界面。

**参数说明：**
```
-m <model>          模型文件路径
-t <threads>        线程数
-n <n_predict>      最大生成 token 数
--ctx-size <n>      上下文长度
--interactive       启用交互模式
```

### 4. run_transformers.py - transformers 方式

使用 HuggingFace transformers 库运行模型。

**特点：**
- 无需编译 llama.cpp
- 直接加载 PyTorch 模型
- 推理速度较慢

### 5. chat_app.py - PySide6 图形界面

基于 PySide6 的对话 GUI 程序。

**功能特性：**
- 流式输出 (逐字显示)
- Markdown 格式支持
- 代码块自动格式化 (深色背景 + 等宽字体)
- 行内代码高亮
- 气泡式对话界面
- AI 头像显示
- 一键清空对话

**启动方式：**
```bash
python chat_app.py
```

### 6. test_api.py / test_api.bat - API 测试

测试 API 服务器是否正常工作。

---

## API 使用

### 启动服务器

```bash
run_server.bat
```

### 请求格式

**对话补全：**
```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minicpm",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "max_tokens": 512,
    "temperature": 0.7
  }'
```

**流式输出：**
```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minicpm",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

### Python 调用示例

```python
import requests

url = "http://localhost:8080/v1/chat/completions"

data = {
    "model": "minicpm",
    "messages": [
        {"role": "user", "content": "用Python写一个快速排序"}
    ],
    "max_tokens": 1024
}

response = requests.post(url, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])
```

---

## PySide6 对话界面

### 安装依赖

```bash
pip install PySide6
```

### 启动

```bash
# 先启动服务器
run_server.bat

# 再启动界面
python chat_app.py
```

### 界面截图效果

```
┌─────────────────────────────────────────────┐
│  MiniCPM5-1B         http://localhost:8080  │
│                              [清空对话]     │
├─────────────────────────────────────────────┤
│                                             │
│         ┌─────────────────────┐             │
│         │ 你好，请介绍一下你自己 │  ← 用户   │
│         └─────────────────────┘             │
│                                             │
│  ┌──┐                                       │
│  │AI│ ┌──────────────────────────┐          │
│  └──┘ │ 我是MiniCPM模型...       │  ← AI    │
│       └──────────────────────────┘          │
│                                             │
│         ┌─────────────────────┐             │
│         │ 写一个快速排序       │  ← 用户    │
│         └─────────────────────┘             │
│                                             │
│  ┌──┐ ┌──────────────────────────┐          │
│  │AI│ │ ┌─python──────────────┐  │          │
│  └──┘ │ │ def quick_sort(arr): │  │  ← AI  │
│       │ │     ...              │  │          │
│       │ └──────────────────────┘  │          │
│       └──────────────────────────┘          │
│                                             │
├─────────────────────────────────────────────┤
│ [输入消息...                    ] [发送]    │
│ 支持 Markdown 格式 | 代码块自动高亮         │
└─────────────────────────────────────────────┘
```

### 功能说明

| 功能 | 说明 |
|------|------|
| 流式输出 | AI 回复逐字显示 |
| 代码块 | 深色背景 + 语法高亮 |
| 行内代码 | `code` 红色高亮 |
| Markdown | 支持粗体、斜体、标题 |
| 气泡界面 | 用户/AI 分侧显示 |

---

## 量化版本选择

### MiniCPM5-1B (推荐)

| 量化 | 大小 | 说明 |
|------|------|------|
| **Q4_K_M** | 656MB | 推荐，平衡速度和质量 |
| Q8_0 | 1.1GB | 质量更好 |
| F16 | 2.0GB | 全精度，质量最好 |

### MiniCPM-2B

| 量化 | 大小 | 说明 |
|------|------|------|
| Q3_K_S | 1.2GB | 速度快，质量一般 |
| **Q4_K_M** | 1.6GB | 推荐 |
| Q5_K_M | 1.9GB | 质量较好 |
| Q8_0 | 2.7GB | 质量最好 |

---

## 常见问题

### Q: 编译 llama.cpp 失败？

A: 确保安装了：
- Visual Studio 2022 (带 C++ 开发工具)
- CMake 3.0+
- Git

### Q: 模型下载很慢？

A: 使用镜像源：
```bash
download_mirror.bat
```

### Q: 服务器启动失败？

A: 检查端口是否被占用：
```bash
netstat -ano | findstr :8080
```

### Q: 中文输出乱码？

A: 这是终端编码问题，API 返回是正常的。使用 chat_app.py 图形界面可正常显示。

### Q: 如何使用 GPU 加速？

A: 需要 NVIDIA GPU + CUDA，重新编译 llama.cpp：
```bash
cmake .. -DLLAMA_CUDA=ON
cmake --build . --config Release
```

---

## 模型来源

- [openbmb/MiniCPM5-1B](https://huggingface.co/openbmb/MiniCPM5-1B)
- [openbmb/MiniCPM5-1B-GGUF](https://huggingface.co/openbmb/MiniCPM5-1B-GGUF)
- [openbmb/MiniCPM-2B-sft-bf16](https://huggingface.co/openbmb/MiniCPM-2B-sft-bf16)

## 相关项目

- [llama.cpp](https://github.com/ggerganov/llama.cpp) - C/C++ 推理引擎
- [MiniCPM](https://github.com/OpenBMB/MiniCPM) - 面壁智能开源模型
- [HuggingFace](https://huggingface.co/) - 模型托管平台