企业官网建设流程全解析

• 人工智能
• 大模型
• 模型推理服务
• 本地部署
• 后端

导读

本文以 README-DOCKER.md 为核心，完整讲解 Shimmy——一个纯 Rust 实现、支持 WebGPU 推理、OpenAI API 兼容、原生加载 GGUF 模型的单二进制推理引擎——在 Docker 与 Docker Compose 环境下的部署全流程。读完本文，你将掌握：从零挂载模型目录到启动服务、验证 OpenAI 兼容 API 的完整操作链路，SHIMMY_*系列环境变量的真实作用与底层实现，NVIDIA GPU 直通配置，以及多模型自动发现、镜像自构建、生产级反向代理加固等进阶方案。

部署形态概览

仓库根目录提供了两套开箱即用的容器化资产：

• 根级 docker-compose.yml：面向本地快速启动，默认拉取ghcr.io/michael-a-kuykendall/shimmy:latest预构建镜像，一条命令即可运行；
• 根级 Dockerfile：多阶段构建脚本，用于从源码编译属于自己的镜像；
• 另有 deploy/ 目录下的 deploy/Dockerfile、deploy/docker-compose.yml 与 deploy/nginx.conf，面向云端/生产部署，内置非 root 用户、健康检查与 Nginx 反向代理。

无论哪种形态，核心思路一致：把本地模型目录挂载进容器，其余交给 Shimmy 自动发现与加载。

快速开始：四步拉起一个推理服务

第一步：创建模型目录

mkdir models

Shimmy 的模型自动发现模块默认把./models作为首个搜索路径（见 src/auto_discovery/mod.rs 中ModelAutoDiscovery::new()的实现），因此这一目录就是容器的"模型仓库"。

第二步：下载 GGUF 模型

以下载微软 Phi-3-mini 的 Q4 量化版为例：

curl -L "https://huggingface.co/microsoft/Phi-3-mini-4k-instruct-gguf/resolve/main/Phi-3-mini-4k-instruct-q4.gguf" -o models/phi-3-mini.gguf

注意：仓库镜像约定模型文件为.gguf格式（safetensors 与 LoRA 亦受支持，见 src/main.rs 中对SHIMMY_LORA_GGUF的处理）。下载时请确保目标模型存在对应的 GGUF 量化文件。

第三步：启动容器

docker-compose up -d

启动后，Shimmy 容器内的shimmy serve进程会监听 11434 端口，并从挂载的/app/models目录自动发现全部.gguf模型。

第四步：验证 API

curl http://localhost:11434/v1/models

若返回模型列表 JSON，即表示部署成功。该端点与后续的聊天补全、文本补全、健康检查端点均在 src/server.rs 中注册（路由定义位于 src/server.rs 的route(...)调用处）。

环境变量：配置项与源码级解析

README-DOCKER 给出三个核心环境变量，容器镜像 Dockerfile 也通过ENV指令设置了对应默认值：

结合源码，这三个变量有更精确的底层语义：

• SHIMMY_BASE_GGUF决定模型注册与发现：在 src/main.rs 中，若显式设置了该变量，则会把其指向的路径注册为默认模型条目；在 src/auto_discovery/mod.rs 中，该变量的父目录会被追加进自动发现搜索路径（例如设置/app/models时，/app也会进入扫描范围，便于兼容 Ollama 风格的目录结构）。因此，把模型放进/app/models下任意子目录，均可被自动发现。
• 端口与地址的实际解析：从源码结构看，SHIMMY_PORT/SHIMMY_HOST是镜像层约定（EXPOSE 11434+ENV），而运行时更通用的控制入口是shimmy serve命令的--bind参数与SHIMMY_BIND_ADDRESS环境变量（见 src/cli.rs 的Serve子命令定义与 src/port_manager.rs 的地址解析逻辑，支持auto、127.0.0.1:11435、0.0.0.0:8080等形式）。容器内通过-p "11434:11434"做端口映射，宿主机端口号可以自由调整。

除上述三者外，docker-compose.yml 还给出了 TurboShimmy 系列进阶变量（注释形式展示，按需取消注释）：

environment: - SHIMMY_BASE_GGUF=/app/models # 指向挂载的模型目录 - SHIMMY_PORT=11434 # 服务端口 - SHIMMY_HOST=0.0.0.0 # 监听所有网卡 # TurboShimmy v2.1 — 削减 KV cache 显存约 60%（推荐 4 GB 显存 GPU 使用） # - SHIMMY_KV_QUANT=int4 # 启用 INT4 KV 量化 # - SHIMMY_PREFILL_CHUNK=8 # 调小预填充分块，防止长提示词下 Windows TDR 崩溃 # - SHIMMY_MAX_CTX=4096 # 覆盖最大上下文长度（默认取 GGUF 原生上下文）

这些变量的底层行为在 src/main.rs 中可见：CLI 的--kv-quant int4、--prefill-chunk N、--ctx N参数会被写入对应的SHIMMY_*环境变量，交由 Airframe 引擎读取，从而实现"CLI 参数优先、环境变量兜底"的双通道配置。例如SHIMMY_KV_QUANT=int4对应 KV 缓存从f32全精度切换为 INT4 量化（src/cli.rs 中kv_quant参数的取值限定为f32/int4，默认f32）；SHIMMY_MAX_CTX则被 src/model_registry.rs 读取并做上下文窗口校验。日志级别可通过RUST_LOG（如RUST_LOG=debug）控制，src/main.rs 使用tracing_subscriber按环境变量过滤日志输出。

数据卷与模型持久化

根级 docker-compose.yml 声明了两个卷：

volumes: - ./models:/app/models # 挂载本地模型目录 - shimmy-cache:/root/.cache # 下载缓存持久化

• ./models:/app/models：把宿主机models/目录与容器内/app/models绑定，模型文件改动即时对容器内生效；
• shimmy-cache:/root/.cache：命名卷，持久化 HuggingFace Hub 下载缓存（仓库在 src/main.rs 的启动诊断中提示过~/.cache/huggingface/hub/目录会被纳入模型搜索范围），避免容器重建后重复下载。

若在云端部署且模型只读，可参考 deploy/docker-compose.yml 使用只读挂载./models:/app/models:ro，进一步降低误写风险。

GPU 支持：NVIDIA 显卡直通

前置条件（来自 README-DOCKER）：

• 宿主机已安装 NVIDIA Container Toolkit；
• Docker Compose 版本 ≥ 2.3，且支持 GPU 资源预留。

根级 docker-compose.yml 已内置 GPU 配置，无需额外改动：

deploy: resources: reservations: devices: - driver: nvidia # GPU 支持（可选） count: all capabilities: [gpu]

启动前可用以下命令验证宿主机 GPU 运行时是否就绪：

docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi docker-compose config # 验证 Compose 解析后的 GPU 配置

注意：deploy.resources段在docker-compose up（非 swarm 模式）下即可生效；若在旧版 Docker 上使用，可改用--gpus all运行参数。Shimmy 的推理后端选择在 src/cli.rs 中通过--gpu-backend（auto/cpu/cuda/vulkan/opencl）控制，默认auto会自动探测可用 GPU。

日常运维：日志、停止与自定义覆盖

基础运维命令

# 启动服务 docker-compose up -d # 跟踪日志 docker-compose logs -f shimmy # 停止服务 docker-compose down

自定义端口与环境（override 文件）

通过docker-compose.override.yml覆盖默认配置，无需改动原文件：

# docker-compose.override.yml services: shimmy: ports: - "8080:11434" # 宿主机 8080 → 容器 11434 environment: - SHIMMY_PORT=11434 - SHIMMY_LOG_LEVEL=debug

说明：容器内SHIMMY_PORT需保持与EXPOSE 11434一致，宿主机的对外端口由ports左侧数值决定。

多模型自动发现

Shimmy 会自动扫描挂载目录下的全部.gguf模型，目录结构示例如下：

models/ ├── phi-3-mini.gguf ├── llama-2-7b.gguf └── mistral-7b.gguf

自动发现的实现位于 src/auto_discovery/mod.rs（DiscoveredModel结构体会记录名称、路径、大小、模型类型、参数量、量化格式等元数据）。除了默认的./models，SHIMMY_BASE_GGUF的父目录与SHIMMY_MODEL_PATHS（分号分隔的额外目录列表，可经--model-dirs全局 CLI 参数注入，见 src/main.rs）也会被纳入扫描。因此放入容器models/子目录、Ollama 风格目录中的模型都能被自动发现并直接通过 API 调用。

API 端点速查

容器启动后即提供 OpenAI 兼容接口（路由注册见 src/server.rs）：

此外 src/server.rs 还注册了/metrics（监控指标）、/diag（诊断信息）以及/api/generate、/api/models、/api/models/discover等内部端点，可用于运维观测。

验证示例：

curl http://localhost:11434/v1/models curl http://localhost:11434/health

故障排查手册

容器无法启动

# 查看日志 docker-compose logs shimmy # 检查端口是否被占用 netstat -tulpn | grep 11434

若端口被占用，改用-p "8080:11434"映射或调整SHIMMY_BIND_ADDRESS。

模型无法加载

# 确认模型目录已挂载进容器 docker-compose exec shimmy ls -la /app/models # 检查宿主机目录权限 ls -la models/

同时确认模型文件名以.gguf结尾，且文件完整（可先执行docker-compose exec shimmy shimmy list或shimmy discover查看自动发现结果，这两个子命令在 src/cli.rs 中有定义）。

GPU 未被识别

# 验证 NVIDIA runtime 可用 docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi # 检查 Compose 中的 GPU 配置是否解析成功 docker-compose config

若容器内 GPU 不可见，请确认 NVIDIA Container Toolkit 安装正确，且 Docker 守护进程配置了nvidiaruntime。

从源码构建自定义镜像

标准构建（仓库根目录）

# 构建镜像 docker build -t shimmy:local . # 在 docker-compose.yml 中使用本地镜像 # 替换：image: ghcr.io/michael-a-kuykendall/shimmy:latest # 改为：image: shimmy:local

根级 Dockerfile 采用多阶段构建：

• 构建阶段：基于rust:1.85-slim，安装pkg-config、libssl-dev、build-essential、libclang-dev、cmake等编译依赖，随后cargo build --release --features airframe,huggingface编译出带 Airframe GPU 引擎与 HuggingFace 下载能力的 release 二进制；
• 运行阶段：基于debian:bookworm-slim，仅安装ca-certificates、libssl3运行时依赖，把编译产物复制到/usr/local/bin/shimmy，创建/app/models目录，EXPOSE 11434并预设SHIMMY_PORT/SHIMMY_HOST/SHIMMY_BASE_GGUF三个环境变量，最终以CMD ["shimmy", "serve"]启动。

面向生产的云端构建（deploy 变体）

若目标是云端部署，可改用 deploy/Dockerfile：它以rust:slim构建、以debian:trixie-slim作为运行基础（glibc 2.39+，与构建器 glibc 版本匹配），创建非 root 用户shimmy并以该用户运行，EXPOSE 11435，内置HEALTHCHECK（每 30 秒探测http://localhost:11435/health），启动命令为shimmy serve --bind 0.0.0.0:11435。对应编排见 deploy/docker-compose.yml，其中包含健康检查配置，并可通过profiles: [production]激活 Nginx 反向代理服务。

生产加固：Nginx 反向代理

deploy/nginx.conf 提供了可选的 Nginx 配置，适用于需要对外暴露 HTTP/HTTPS 的正式环境，包含：

• upstream shimmy指向容器服务名shimmy:11434；
• 基于limit_req_zone的限流（默认 10 r/s，burst 20）；
• WebSocket 升级头支持（供流式补全使用，proxy_http_version 1.1+Upgrade/Connection头）；
• 针对大模型推理放宽的超时设置（proxy_read_timeout 300s等）；
• 独立的/health路由（关闭访问日志）。

启用方式：在 deploy/docker-compose.yml 中为nginx服务挂载 deploy/nginx.conf，并以docker-compose --profile production up -d启动。

小结

通过本文，你可以完整掌握 Shimmy 的容器化部署链路：用mkdir models+curl准备模型、用docker-compose up -d一键启动、用curl http://localhost:11434/v1/models验证服务；同时理解了SHIMMY_BASE_GGUF等环境变量在 src/main.rs、src/auto_discovery/mod.rs 中的真实作用，掌握了 TurboShimmy 的SHIMMY_KV_QUANT/SHIMMY_PREFILL_CHUNK/SHIMMY_MAX_CTX调优变量、NVIDIA GPU 直通配置、多模型自动发现机制，以及基于 Dockerfile 自构建镜像与基于 deploy/ 生产化部署（非 root 用户 + 健康检查 + Nginx 反代）的进阶方案。更多细节可参考 README.md 与 docs/CONFIGURATION.md。

• 人工智能
• 大模型
• 模型推理服务
• 本地部署
• 后端