docker-ai-ml

用途

本技能用于指导在 Docker 上运行 AI 模型与智能体（AI Agent）工作负载。当用户涉及以下关键词时使用：docker ai、docker model、model runner、本地 LLM、local model、offline model、docker agent、AI agent、GPU docker、nvidia docker、sandbox 沙箱、LLM 部署、模型部署。

主要能力

Docker Model Runner

提供本地模型的拉取、推理、交互式聊天与 API 服务模式：

列出可用模型：

docker model ls

拉取模型：

docker model pull ai/gemma3
docker model pull ai/qwen2.5

运行推理：

docker model run ai/gemma3 "Explain Docker in one sentence"

交互式聊天：

docker model run -i ai/gemma3

API 服务模式（访问地址 http://localhost:11434/v1）：

docker model serve ai/gemma3 --port 11434

为 AI 编程助手安装技能：

# Install skills for Claude Code
docker model skills --claude

# For Codex CLI
docker model skills --codex

GPU 配置

安装 NVIDIA Container Toolkit（一次性），Ubuntu/Debian：

sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

以 GPU 访问方式运行：

docker run --gpus all -it nvidia/cuda:12.6-base nvidia-smi

指定 GPU：

docker run --gpus device=0 -it nvidia/cuda:12.6-base

GPU 与 Model Runner 结合：

docker model run --gpus all ai/llama3.2

Docker Agent

通过 agent.yaml 定义多智能体系统：

name: my-coding-agent
model:
  provider: openai
  model: gpt-4o
tools:
  - write_file
  - execute_command
  - web_search
sandbox:
  image: node:22-alpine
  workdir: /workspace

运行智能体：

docker agent run -f agent.yaml "Fix the bug in src/app.js"

Docker Sandbox

为 AI 智能体提供隔离执行环境：

sandbox:
  image: python:3.12-slim
  network: none          # No network access
  read_only: true        # Read-only filesystem
  memory: 512m
  cpus: 1

本地 LLM 技术栈（Ollama 备选）

使用开源方案 Ollama 作为替代：

docker run -d --name ollama \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  --gpus all \
  ollama/ollama

# Download and run model
docker exec ollama ollama pull llama3.2
docker exec ollama ollama run llama3.2 "Hello"

使用方式（推荐流程）

选择推理方案：优先 Docker Model Runner（docker model），Ollama 作为备选。
检查硬件：GPU 需 Linux + nvidia-container-toolkit；CPU 推理需 8-32GB RAM。
拉取模型：docker model pull <model> 或 ollama pull <model>。
启动服务：docker model run 或 ollama serve + 客户端。
验证：发送测试 prompt 确认模型正常响应。

常见陷阱

GPU 不可用：Docker Desktop Mac/Windows 的 GPU 透传有限。完整 GPU 支持需 Linux 宿主 + nvidia-container-toolkit；Mac 上可使用 docker model 卸载推理。
模型下载体积：LLM 体积大（2-70 GB）。docker model pull 将模型缓存于 ~/.docker/models；拉取前用 df -h 检查磁盘；使用量化模型（Q4/Q8）以减小占用。
内存限制：LLM 推理需要显著 RAM（通常 8-32 GB）。可使用 docker run --memory=16g model-runner；用 free -h 检查内存；受限时使用更小模型（7B 而非 70B）。
Model Runner 与 Ollama：Docker Model Runner 是 Docker 原生；Ollama 生态更大。使用 docker model 获取 Docker 集成；使用 Ollama 获得更广模型选择；两者可共存。

能力边界（适用与不适用场景）

能做：

本地模型推理（Docker Model Runner / Ollama）：拉取并运行开源 LLM，无需 API key。
GPU 加速推理：Linux 宿主机 + nvidia-container-toolkit。
AI Agent 构建（Docker Agent / Sandboxes）：多 agent 协作、沙箱隔离。

需条件：

macOS GPU 推理：Docker Desktop 支持有限，优先用 docker model。
大模型（70B+）推理：需 32GB+ RAM，考虑量化模型。

超范围：

训练/微调模型：需专用框架（PyTorch/TensorFlow），不在本技能范围。
云端 API 调用（OpenAI/Claude）：非本地推理，使用对应 SDK。
生产模型 Serving（K8s）：使用 docker-production + K8s 部署。

何时不使用本技能

Docker 基础 → 使用 docker-basics。
构建自定义模型镜像 → 使用 docker-build。
生产模型 Serving（K8s）→ 使用 docker-production。
云端 AI API（无需 Docker）→ 直接 API 访问。

安全与稳定性

尽可能以 --read-only 运行模型容器——模型权重是只读的。
限制模型容器的网络访问，本地推理不需要互联网。
GPU 透传会让容器直接访问硬件，可结合 --security-opt 实现隔离。
监控 GPU 显存使用：nvidia-smi 查看利用率。

官方文档参考

Docker AI 概述：https://docs.docker.com/ai-overview/
Docker Model Runner：https://docs.docker.com/ai/model-runner/
Docker Model Runner 入门：https://docs.docker.com/ai/model-runner/get-started/
Docker Agent：https://docs.docker.com/ai/docker-agent/
Docker Sandboxes：https://docs.docker.com/ai/sandboxes/
AI/ML 示例：https://docs.docker.com/reference/samples/ai-ml/