# qwen3_5_llama_cpp_docker

**Repository Path**: zjwan461/qwen3_5_llama_cpp_docker

## Basic Information

- **Project Name**: qwen3_5_llama_cpp_docker
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# llama.cpp + Qwen3.5 Docker部署指南
基于 Docker Compose 快速部署支持 CUDA 加速的 llama.cpp 服务，运行 Qwen3.5-9B-GGUF(可切换其他参数量) 多模态模型。

## 功能说明
- 基于 llama.cpp 构建 GPU 加速的推理服务
- 自动下载 Qwen3.5-9B-Q4_K_M.gguf 模型及多模态投影文件
- 暴露 HTTP API 接口，支持多模态推理
- 容器化部署，环境隔离，一键启停

## 环境要求
### 1. 系统要求
- Linux 系统（Ubuntu 20.04+/CentOS 8+ 推荐）
- 已安装 Docker (20.10.0+) 和 Docker Compose (1.28.0+)
- 已安装 NVIDIA 显卡驱动（≥ 525.x）
- 已配置 NVIDIA Container Toolkit（GPU 支持必备）

### 2. 硬件要求
- NVIDIA GPU（显存 ≥ 10GB，推荐 A10/T4/V100/A100 等，个人使用RTX5060TI 16G）
- 磁盘空间 ≥ 20GB（模型文件约 10GB）
- 网络通畅（首次部署需下载模型和镜像）

## 快速开始

### 1. 环境检查
```bash
# 检查 Docker 是否安装
docker --version

# 检查 Docker Compose 是否安装
docker-compose --version

# 检查 NVIDIA 驱动和 GPU 可用性
nvidia-smi

# 检查 NVIDIA Container Toolkit 是否配置成功
docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi
```

### 2. 部署步骤
```bash
# 1. 克隆/下载项目文件（确保目录包含以下文件）
git clone https://gitee.com/zjwan461/qwen3_5_llama_cpp_docker
# - Dockerfile
# - download.py
# - docker-compose.yml

# 2. 进入项目目录
cd qwen3_5_llama_cpp_docker

# 3. 构建并启动容器（首次运行会自动构建镜像+下载模型，耗时较长）
docker-compose up -d

# 4. 查看容器运行状态
docker-compose ps

# 5. 查看服务日志（确认模型加载和服务启动）
docker-compose logs -f llama-server-qwen3.5
```

### 3. 验证服务
服务启动成功后，可通过以下方式验证：
```bash
# 检查健康检查接口
curl http://localhost:8080/health

# 正常响应示例：
# {"status":"ok","model":"Qwen3.5-9B-Q4_K_M.gguf","threads":4,"gpu_layers":99}
```

## 常用命令
```bash
# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看实时日志
docker-compose logs -f llama-server-qwen3.5

# 重新构建镜像（修改 Dockerfile/download.py 后）
docker-compose up -d --build

# 进入容器内部
docker exec -it llama-server-qwen3.5 bash

# 查看容器资源占用
docker stats llama-server-qwen3.5
```

## 配置说明
### docker-compose.yml 关键配置
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `device_ids: ["0"]` | 指定使用的 GPU 编号（从 0 开始） | 0（第一个 GPU） |
| `ports: "8080:8080"` | 端口映射（主机端口:容器端口） | 8080:8080 |
| `./models:/models` | 模型目录持久化（主机目录:容器目录） | ./models:/models |
| `restart: unless-stopped` | 容器重启策略 | 异常退出自动重启 |

### 自定义配置
1. **更换 GPU 编号**：修改 `docker-compose.yml` 中 `device_ids` 字段，如使用第二个 GPU 则改为 `["1"]`
2. **修改端口**：如 8080 端口被占用，可改为 `8081:8080`
3. **调整 GPU 层数**：修改 Dockerfile 中 `-ngl 99` 参数（99 表示使用全部 GPU 层）

## 目录结构
```
./
├── Dockerfile          # 镜像构建脚本
├── download.py         # 模型下载脚本
├── docker-compose.yml  # 服务编排配置
├── models/             # 模型文件目录（自动创建，持久化存储）
│   ├── Qwen3.5-9B-Q4_K_M.gguf  # 主模型文件
│   └── mmproj-BF16.gguf         # 多模态投影文件
└── README.md           # 使用说明
```

## 常见问题
### 1. 容器启动失败，提示 GPU 不可用
- 确认已安装 NVIDIA Container Toolkit
- 执行 `nvidia-ctk runtime configure --runtime=docker` 配置运行时
- 重启 Docker 服务：`systemctl restart docker`

### 2. 模型下载缓慢/失败
- 检查网络连接，确保能访问 modelscope 仓库
- 手动下载模型文件到 `./models` 目录，重启容器即可

### 3. 服务启动后无响应
- 查看日志：`docker-compose logs llama-cpp-qwen`
- 确认 GPU 显存充足（至少 10GB 可用）
- 检查健康检查接口：`curl http://localhost:8080/health`

### 4. 端口被占用
- 修改 `docker-compose.yml` 中的 `ports` 字段，如改为 `8081:8080`
- 停止占用端口的进程：`sudo lsof -i :8080 | grep -v PID | awk '{print $2}' | xargs kill -9`

## 注意事项
1. 首次启动会下载约 10GB 的模型文件，耗时取决于网络速度
2. 模型文件会持久化到 `./models` 目录，删除容器不会丢失
3. 建议使用后台运行（`-d` 参数），避免终端关闭导致服务停止
4. 如无需多模态功能，可删除 `--mmproj` 参数
5. 生产环境建议限制容器资源占用，避免影响主机性能

## 参考链接
- llama.cpp 官方仓库：https://github.com/ggml-org/llama.cpp
- Qwen3.5 模型：https://modelscope.cn/models/unsloth/Qwen3.5-9B-GGUF
- NVIDIA Container Toolkit：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/