AI服务器微服务配置用Docker Compose拆分推理与网关

在单台 AI 服务器上做微服务配置，核心是把推理模型、API 网关和监控拆成独立容器，用 Docker Compose 统一编排，而不是把所有进程塞进一个镜像。
下面按准备、编排、验证和排错顺序说明，适合已装好 GPU 驱动和 Docker 的 Linux 服务器。

先确认 GPU 容器能正常调用

微服务里最关键的容器是推理服务，它必须能访问显卡。
安装 NVIDIA Container Toolkit 后，用官方镜像做一次最小验证：

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

能看到显卡型号和驱动版本，才说明容器运行时配置正确。
如果提示 could not select device driver，先检查 nvidia-ctk runtime configure --runtime=docker 是否执行过，并重启 Docker。

准备目录时建议按服务拆分，避免配置文件互相覆盖：

mkdir -p /opt/ai-stack/{model,gateway,monitor}

用 Compose 定义三个微服务

一个可落地的拆分方式是：模型推理服务负责加载权重并暴露 HTTP 接口，网关负责统一入口和鉴权，监控容器负责采集指标。
在 /opt/ai-stack/docker-compose.yml 中写入：

services:
  inference:
    image: your-registry/inference:latest
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8000:8000"
    volumes:
      - ./model:/models:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      retries: 3

  gateway:
    image: nginx:1.27-alpine
    ports:
      - "80:80"
    volumes:
      - ./gateway/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - inference

  monitor:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"

这里 runtime: nvidia 和 deploy.resources 二选一即可，新版 Compose 推荐后者。
网关配置里把 /v1/ 转发到 inference:8000，容器之间直接用服务名通信，不需要写服务器 IP。

启动并逐层验证

先拉取镜像并后台启动：

cd /opt/ai-stack
docker compose up -d
docker compose ps

三个服务都应显示 running，推理服务的健康状态应为 healthy。
接着分别验证：

• 推理直连：curl http://127.0.0.1:8000/health 返回 200。
• 网关转发：curl http://127.0.0.1/v1/models 能拿到模型列表。
• 监控目标：访问 http://服务器IP:9090，在 Targets 页面确认推理服务已上线。

如果网关返回 502，先看 docker compose logs gateway，再确认 inference 容器是否真的监听在 8000 端口。

常见坑与处理方式

显存不足导致容器反复重启：用 docker stats 和 nvidia-smi 对照查看，推理容器启动时如果显存被其他进程占用，会直接退出。
先停掉无关的 Jupyter 或旧推理进程，再设置 NVIDIA_VISIBLE_DEVICES 限定使用的卡。

端口冲突：宿主机已有服务占用 80 或 8000 时，docker compose up 会报 port is already allocated。
用 ss -lntp | grep :80 找到占用进程，改 Compose 里的宿主机端口映射，例如 "8080:80"。

模型文件权限：挂载 ./model 为只读后，容器内用户可能无权限读取权重。
确认文件属主与容器运行用户一致，或在 Compose 中增加 user: "1000:1000" 统一身份。

网关配置改完不生效：Nginx 容器需要重载，执行 docker compose exec gateway nginx -s reload，不要直接重启整个栈。

配置是否生效的检查清单

完成上述步骤后，按下面几项复查：docker compose ps 全部为 running；
推理健康检查连续通过；
网关能返回推理接口结果；
Prometheus Targets 中推理服务为 UP；nvidia-smi 显示推理进程占用显存。
满足这些条件，说明 AI 服务器微服务配置已经具备基本可用性，后续再按业务增加副本或鉴权即可。