85 lines
2.6 KiB
Markdown
85 lines
2.6 KiB
Markdown
# Docker Compose
|
||
|
||
ToolHub 提供 Docker Compose 入口，适合 Linux 主机部署，或不想在 Windows 宿主机安装 Python 的用户。这是一条可选路线，不替代 Windows 原生脚本主线。
|
||
|
||
---
|
||
|
||
## 前提条件
|
||
|
||
- Docker 和 Docker Compose 已安装
|
||
- NVIDIA GPU 驱动已安装，且 NVIDIA Container Toolkit 可用
|
||
|
||
验证 GPU 容器环境：
|
||
|
||
```bash
|
||
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
|
||
```
|
||
|
||
---
|
||
|
||
## 启动与停止
|
||
|
||
```bash
|
||
docker compose up --build # 前台启动
|
||
docker compose up --build -d # 后台启动
|
||
docker compose down # 停止
|
||
```
|
||
|
||
首次启动时后端容器会自动下载模型文件，之后缓存在 Docker 命名卷 `toolhub-models` 中。
|
||
|
||
启动后浏览器访问 [http://127.0.0.1:8080](http://127.0.0.1:8080)。
|
||
|
||
如果后端还在下载模型或加载模型到 GPU，浏览器会先显示准备中页面。此时直接查看：
|
||
|
||
```bash
|
||
docker compose logs -f backend
|
||
```
|
||
|
||
确认下载和加载进度即可。
|
||
|
||
---
|
||
|
||
## 容器结构
|
||
|
||
Compose 启动两个服务：
|
||
|
||
| 服务 | 镜像基础 | 职责 |
|
||
| --- | --- | --- |
|
||
| `gateway` | `python:3.11-slim` | 网关层，提供网页入口和 OpenAI 兼容 API（端口 8080） |
|
||
| `backend` | `ghcr.io/ggml-org/llama.cpp:server-cuda` | 模型后端，GPU 推理（端口 8081） |
|
||
|
||
架构与 Windows 原生路线一致：浏览器访问网关，网关将推理请求转发给后端。网关容器通过只读方式挂载项目目录（`/workspace`），文件系统访问行为与 Windows 路线保持一致。
|
||
|
||
---
|
||
|
||
## 模型管理
|
||
|
||
模型不会打进镜像，由后端容器首次启动时从 Hugging Face 下载，缓存在命名卷 `toolhub-models` 中。默认下载 Q4_K_M 量化。
|
||
|
||
如需切换到 Q8，在 `.env` 中将 `MODEL_GGUF_URL` 改为 Q8 下载地址，也可以先在宿主机执行 `.\install_q8.cmd` 让它自动修改，然后重启容器：
|
||
|
||
```bash
|
||
docker compose down
|
||
docker compose up --build -d
|
||
```
|
||
|
||
> 容器内模型缓存（命名卷）和 Windows 路线的本地缓存（`.tmp/models/`）是两套独立缓存，互不影响。
|
||
|
||
---
|
||
|
||
## 配置
|
||
|
||
Compose 通过 `.env` 文件读取配置。以下变量会影响容器行为：
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `GATEWAY_PORT` | `8080` | 网关对外端口 |
|
||
| `BACKEND_PORT` | `8081` | 后端对外端口 |
|
||
| `THINK_MODE` | `think-on` | 思考模式 |
|
||
| `CTX_SIZE` | `16384` | 上下文窗口大小 |
|
||
| `IMAGE_MIN_TOKENS` | `256` | 图像最小 token 数 |
|
||
| `IMAGE_MAX_TOKENS` | `1024` | 图像最大 token 数 |
|
||
| `MMPROJ_OFFLOAD` | `off` | 视觉投影卸载开关 |
|
||
|
||
修改 `.env` 后重启容器生效。
|