模域 ModelSphere 是一套可自托管的 AI 模型部署平台，思路和常见的“推理框架 + 网关 + 控制台”组合类似：用容器把推理运行时（例如 vLLM、TGI 这类）跑起来，再由平台统一做模型注册、服务编排、密钥与配额管理，最后对外暴露一套 OpenAI 兼容的 HTTP API。本文按“一台带 GPU 的 Linux 服务器 + Docker Compose”这条路径走一遍，从零到能用自己的 API Key 调通一次对话请求。
需要先说明一点：这类项目迭代较快，目录结构、环境变量名、控制台菜单都可能随版本调整。下文命令尽量写成通用形式，凡是涉及具体版本号、镜像 tag、下载地址的地方，都以官方仓库和官方文档当前版本为准；如果某个变量名和你看到的 .env.example 对不上，按文件里的实际写法来，逻辑是一样的。
适用场景
适合已经有几张 GPU 卡、想把开源模型（7B、14B 这类）稳定地跑成内部或对外 API 的团队：希望多模型共存、能给不同业务方发不同的 Key、能限制并发和上下文长度，但不打算自己从零拼推理框架、网关、监控三套东西。也适合单机先做 PoC：一台机器上把控制面和推理跑通，验证效果后再迁到 Kubernetes。
如果只是临时跑一次模型看效果，直接 docker run 一个推理镜像更省事；如果要做多租户、要审计、要按 Key 计费，才值得上这类平台。
环境与前置条件
操作系统：主流 Linux 发行版（Ubuntu 22.04 LTS 及以上、Debian 12、Rocky 9 等）都可以，建议内核 5.15 以上以支持 cgroup v2。macOS 能跑通控制面用于熟悉界面，但推理必须落在带 NVIDIA GPU 的机器上。
运行时：
- Docker Engine 24 以上 + Docker Compose v2（
docker compose version能输出版本号） - NVIDIA 驱动，
nvidia-smi能正常输出 - NVIDIA Container Toolkit，让容器能拿到 GPU
硬件建议（仅作量级参考，实际以模型卡和官方文档为准）：
- 7B 级模型 FP16 推理大约需要十几 GB 显存，量化后可以压到更低；建议单卡 24GB 显存起步（如 A10、L4、4090 级别）
- 控制面组件（API、控制台、数据库、缓存）4 核 8GB 内存起步
- 推理节点内存建议不低于模型权重大小的 1.5 倍，因为加载和转换阶段会有额外占用
- 磁盘：系统盘 50GB；模型盘按“模型体积 × 2”预留，下载缓存和格式转换会各占一份
- 端口规划：控制台 8080、API 网关 8000、模型服务内部端口 8001 起；PostgreSQL、Redis、MinIO 只监听内网，不要直接暴露公网
前置知识：会改 .env 文件、会用 docker logs 看日志、知道什么是反向代理。不需要写代码。
分步骤部署
第 1 步：确认 GPU 与容器工具链就绪
先确认驱动正常：
```bash
nvidia-smi
```
输出里能看到显卡型号、驱动版本、显存占用，说明驱动没问题。接着确认容器能拿到 GPU：
```bash
docker run --rm --gpus all nvidia/cuda:<按官方文档选择的基础镜像> nvidia-smi
```
这里能打印出和宿主机一样的显卡信息，才算真正打通。如果报 could not select device driver，说明 Container Toolkit 还没装好，见后面的报错章节。
第 2 步：规划目录
把所有持久化数据集中放在一个盘上，后面备份会轻松很多：
```bash
sudo mkdir -p /data/modelsphere/{postgres,redis,minio,models,logs}
sudo chown -R $USER:$USER /data/modelsphere
```
models 放模型权重，postgres 放平台元数据，minio 放数据集和导出文件。这一步没有输出就是成功。
第 3 步：获取部署清单
从官方仓库拉取代码或 Compose 清单（地址以官方文档为准）：
```bash
git clone <官方仓库地址> modelsphere
cd modelsphere
ls
```
通常能看到 docker-compose.yml、.env.example、deploy/ 之类的文件。先看一眼 Compose 文件里定义了哪些服务，心里有个数：一般包含 api（控制面）、web（控制台）、postgres、redis、minio，以及可选的 runtime（推理运行时）。
第 4 步：写配置文件
```bash
cp .env.example .env
```
然后逐项改。需要重点确认的几类：
```bash
数据库
POSTGRES_USER=modelsphere
POSTGRES_PASSWORD=<换成强密码>
POSTGRES_DB=modelsphere
会话与签名密钥，用随机串，不要用默认值
SECRET_KEY=<openssl rand -hex 32 的输出>
对象存储（内置 MinIO 或外部 S3 兼容服务）
S3_ENDPOINT=http://minio:9000
S3_ACCESS_KEY=<访问密钥>
S3_SECRET_KEY=<访问密钥>
模型权重根目录，宿主机路径挂载进容器
MODEL_ROOT=/data/modelsphere/models
对外访问地址，影响控制台生成的回调与文档链接
PUBLIC_BASE_URL=https://ai.example.com
```
密钥类字段建议直接生成：openssl rand -hex 32。改完后不要提交到 Git。
第 5 步：先起依赖组件
按依赖顺序启动，出问题好定位：
```bash
docker compose up -d postgres redis minio
docker compose ps
```
docker compose ps 里这三个服务状态应为 running（healthy 更好）。如果 Postgres 一直重启，先看 docker compose logs postgres，多半是密码里有特殊字符没转义，或者数据目录权限不对。
第 6 步：启动控制面
```bash
docker compose up -d api web
docker compose logs -f api
```
第一次启动会执行数据库迁移，日志里能看到建表、执行 migration 的记录，最后出现监听端口的行（类似 listening on 0.0.0.0:8000）。看到这行就按 Ctrl+C 退出日志跟踪，容器仍在后台运行。
随后初始化管理员账号，具体命令以官方文档为准，通常是执行容器内的一条 CLI：
```bash
docker compose exec api <初始化管理员的命令>
```
记下输出的账号和初始密码，首次登录后立刻改掉。
第 7 步：接入模型
平台一般支持两种接入方式，按需选：
方式 A：由平台托管推理运行时。把权重放到 MODEL_ROOT 下（或用控制台的“从仓库拉取”功能），在控制台“模型”页面新增模型，填写模型名称、权重路径、上下文长度上限、量化方式。平台会拉起一个推理容器并把内部端口注册进来。
方式 B：接入已有推理服务。如果你已经用别的框架跑着 OpenAI 兼容接口，直接把它登记为上游：填写服务地址（如 http://10.0.0.12:8001）、模型标识、健康检查路径。这样平台只做网关和治理，不动推理本身。
用 docker compose logs -f 跟一下运行时容器，看到权重加载完成、Uvicorn running 或类似字样，说明模型起来了。首次加载大模型可能要几分钟，属正常。
第 8 步：上线推理服务
在控制台把“模型”发布成“服务”：
- 选择刚接入的模型
- 副本数：单卡先设 1，压测后再加
- GPU 绑定：指定卡号，避免和其他服务抢同一张卡
- 最大并发与排队上限：按显存和实测吞吐给，宁小勿大
- 上下文长度：不要一上来就拉满，长上下文非常吃显存
- 健康检查路径与超时：保持默认即可，除非你的运行时响应特别慢
保存后服务状态会从“部署中”变成“运行中”。这一步的本质是把模型包装成一个有副本数、有健康检查、可被网关路由的后端。
第 9 步：签发 API Key
在“密钥”页面新建一个 Key，绑定到具体服务上，同时设置：
- 速率限制（每分钟请求数、每分钟 token 数）
- 每日或每月配额
- 可访问的模型列表
创建后密钥只显示一次，务必当场保存。
第 10 步：加反向代理和 HTTPS
生产环境不要直接暴露 8000 端口。用 Nginx 或 Caddy 在前面挡一层，把域名指到网关，并配置：
- TLS 证书（Let's Encrypt 自动签发即可）
- 请求体大小上限（长上下文请求体会比较大，默认 1MB 往往不够）
- 读超时（流式输出可能持续几十秒，超时给到 300 秒以上）
- 透传真实客户端 IP，便于限流和审计
Nginx 里至少要有：
```nginx
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_buffering off; # 流式输出必须关
proxy_read_timeout 300s;
client_max_body_size 20m;
}
```
验证部署是否成功
按顺序验证，每一步都能定位到不同层的问题。
1. 容器状态
```bash
docker compose ps
```
预期：所有服务 running，带健康检查的显示 healthy。
2. 控制面健康检查
```bash
curl -s http://127.0.0.1:8000/healthz
```
预期返回类似 {"status":"ok"}。具体路径以官方文档为准。返回 200 且内容正常，说明 API 和数据库连通。
3. 控制台可访问
浏览器打开 http://<服务器IP>:8080，能用管理员账号登录，模型列表为空或已有默认项。
4. 模型列表
```bash
curl -s http://127.0.0.1:8000/v1/models \
-H "Authorization: Bearer <你的API Key>"
```
预期返回一个 JSON，data 数组里有你刚发布的模型标识。如果返回 401，是 Key 不对；返回空数组，是服务没发布成功。
5. 真实推理请求
```bash
curl -s http://127.0.0.1:8000/v1/chat/completions \
-H "Authorization: Bearer <你的API Key>" \
-H "Content-Type: application/json" \
-d '{
"model": "<模型标识>",
"messages": [{"role": "user", "content": "用一句话解释什么是AI 词典：向量数据库">向量数据库"}],
"max_tokens": 128
}'
```
预期返回标准结构，choices[0].message.content 里有中文回答，usage 里有 token 计数。这一步通了，整条链路（网关 → 鉴权 → 路由 → 推理运行时 → 返回）就是完整的。
6. 显存与负载
```bash
nvidia-smi
```
预期：对应 GPU 上能看到推理进程占用显存，数值接近你设置的显存利用率上限，而不是 0。
7. 流式输出
把上面的请求加上 "stream": true，用 curl -N 观察。预期能看到逐块返回的 data: {...} 行，最后以 data: [DONE] 结束。如果一次性全部返回，多半是反向代理开了 proxy_buffering。
常见报错与解决
报错：docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]]
原因：宿主机装了 NVIDIA 驱动，但没装 NVIDIA Container Toolkit，Docker 不认识 --gpus 参数。
解决：
```bash
按官方文档添加软件源后安装
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda:<基础镜像> nvidia-smi
```
报错：推理容器启动后立刻退出，日志里有 CUDA out of memory
原因：模型权重 + KV Cache 超过了卡上可用显存。常见于上下文长度设太大、并发上限设太高，或者模型没做量化。
解决：先把参数降下来再逐步加。
```bash
降低上下文长度与显存占用比例（参数名以运行时官方文档为准）
例如 vLLM：--max-model-len 4096 --gpu-memory-utilization 0.85
docker compose logs --tail=100 <推理服务名>
nvidia-smi # 确认没有别的进程占着卡
```
如果降完仍不够，换更小的模型或用量化版本，别硬撑。
报错：控制面日志出现 relation "xxx" does not exist 或 no such table
原因：数据库迁移没执行，或者连到了一个空库/旧版本的库。
解决：
```bash
docker compose logs api | grep -i migrat
执行官方提供的迁移命令，通常是：
docker compose exec api <迁移命令>
```
执行前先备份数据库，尤其是已经有数据的环境。
报错：下载模型权重时 403 Forbidden 或长时间卡住不动
原因：模型仓库需要访问令牌，或者网络到源站不通。
解决：在 .env 里配置访问令牌和可用镜像源（变量名以官方文档为准），重启相关服务后重试：
```bash
示例，变量名请对照官方文档
HF_TOKEN=<你的访问令牌>
HF_ENDPOINT=<可用的镜像源地址>
docker compose up -d --force-recreate <推理服务名>
```
报错：调用 API 返回 502 Bad Gateway
原因：网关到推理后端的连接失败，通常是后端还没加载完、端口填错，或者健康检查没通过。
解决：
```bash
docker compose ps # 看后端是否 running/healthy
docker compose logs --tail=200 <后端服务名>
curl -v http://<后端地址>:<端口>/health # 直接打后端，绕过网关
```
先把后端打通，再回头看网关配置。
后续维护
备份。三样东西必须定期备：PostgreSQL（平台元数据、用户、密钥）、对象存储（数据集、日志归档）、.env（密钥，单独加密存放）。数据库用 pg_dump 做每日全量，保留 7 到 30 天；模型权重体积大，一般不做备份，记录好来源和版本即可重新拉取。
```bash
docker compose exec -T postgres pg_dump -U modelsphere modelsphere \
| gzip > /data/backup/modelsphere-$(date +%F).sql.gz
```
备份文件要异地存一份，并且定期做恢复演练，没验证过的备份等于没有备份。
升级。顺序固定：备份 → 读官方发布说明（是否有破坏性变更、是否需要手动迁移）→ 拉新镜像 → 停控制面 → 执行迁移 → 启动 → 验证。推理服务可以滚动更新，先起一个新副本，健康检查通过后再摘掉旧的，避免请求中断。
日志。给容器配置日志轮转，别让日志把磁盘写满：
```yaml
logging:
driver: json-file
options:
max-size: "100m"
max-file: "5"
```
有条件的话把日志集中收走（Loki、ELK 之类），按服务名和请求 ID 检索，排查线上问题会快很多。
监控。至少盯四个指标：网关的 QPS 与错误率、请求的首 token 延迟与总耗时、每张卡的显存占用与利用率、队列长度。GPU 指标可以用 DCGM Exporter 导出到 Prometheus，再配 Grafana 面板。告警阈值建议设在“显存长期高于 90%”“错误率连续五分钟超过 1%”“队列持续积压”这几条上，比等到服务不可用再处理要好。
密钥与权限。按业务方分发不同的 Key，一个 Key 只绑必要的模型；人员离职或 Key 泄露时立刻吊销重建。定期清理长期不用的 Key，减少泄露面。
容量。新模型上线前先做一轮压测，记录单卡能扛的并发和对应延迟，把结果写进文档。后面加模型、加副本时，用这份数据判断是加卡还是换更小的模型，比拍脑袋靠谱。