企业官网建设流程全解析

Xinference Docker 镜像部署全指南：从 GPU 容器启动、模型持久化到离线运行

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference

Xinference 提供官方 Docker 镜像（仓库xprobe/xinference），让你无需手动安装推理引擎即可在 GPU 主机上以容器方式快速启动一个生产可用的统一推理服务。本文基于doc/source/getting_started/using_docker_image.rst完整梳理镜像版本演进、前置条件、启动命令与模型持久化方案，并结合 xinference/deploy/docker/Dockerfile 等源码说明镜像内部的真实构成与构建逻辑，帮助你在云主机、自有机房或离线环境中正确部署并复用镜像。

版本演进：从 CUDA 12.9 到 v3.0 的 slim 镜像

理解当前镜像形态之前，需要先看清两次关键变更：

• v2.0 起：使用 CUDA 版本镜像时，宿主机最低要求为CUDA 12.9。
• v3.0.0 起：GPU 镜像改为slim（精简）镜像，基于nvidia/cuda:13.0.2-devel-ubuntu22.04构建：
  • 镜像不再预装vLLM、SGLang 等推理引擎；
  • 引擎会在模型启动时自动安装进该模型专属的虚拟环境（由XINFERENCE_ENABLE_VIRTUAL_ENV控制，默认开启，详见 environments.rst）；
  • 这意味着模型首次启动时需要访问 PyPI 下载依赖；对于离线 / 内网主机，应使用 Docker Compose 离线配置自带的私有 PyPI 镜像（见 using_docker_compose.rst）；
  • 镜像支持的最低 CUDA 版本为CUDA 13.0。

这一设计把「引擎选型」从镜像构建期推迟到了模型启动期，模型规格（model spec）声明什么引擎就装什么引擎，避免镜像体积臃肿、也避免多个引擎的依赖互相冲突。

部署前置条件

镜像内的 Xinference 依赖 NVIDIA GPU 做加速，因此运行环境必须满足：

• 宿主机装有GPU 且已安装 CUDA；
• 可通过nvidia-smi命令正常输出（这是判断 CUDA 是否可用的直接手段）；
• 镜像内 CUDA 版本为13.0，宿主机 CUDA 版本应为13.0 及以上，NVIDIA 驱动版本应为580 及以上；
• 已安装NVIDIA Container Toolkit（Docker 才能把宿主机 GPU 透传给容器）。

前置条件不满足时，容器启动会直接报错，因此部署前务必先执行nvidia-smi与nvidia-smi -L核对驱动与 CUDA 版本。

官方镜像与可用标签

官方镜像发布在 DockerHub 的xprobe/xinference仓库下，可用标签包括：

生产环境建议固定使用v<release version>形式的发行标签，避免latest或nightly的变动影响服务。

GPU 镜像内部构成

从 xinference/deploy/docker/Dockerfile 可以看到，GPU 镜像内预置的内容是精心挑选的「最小可运行集合」：

• Python 3.12 工具链（通过 deadsnakes PPA 安装，同时包含python3.12-dev，供模型虚拟环境内编译 CUDA 扩展 / sdist 包使用）；
• CUDA 13.0 工具链（基于devel基础镜像，保留 nvcc 与 CUDA 头文件，作为模型虚拟环境内即时编译 CUDA 扩展的兜底）；
• 共享的 CUDA 版 PyTorch 全家桶：torch/torchvision/torchaudio/torchcodec（cu130），以及numpy、pandas。模型规格中形如#system_torch#的占位符会引用父环境的版本，预装一份共享 CUDA torch 栈可以让各模型虚拟环境通过XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED复用，而不是每个模型都重新下载数 GB 的 wheel；
• transformers+accelerate：默认 Transformers 引擎的虚拟环境依赖，预装后最常见的引擎开箱即用；
• Xinference 本体及其核心依赖 + 预构建的 Web UI（由多阶段构建的web-builder阶段先用 Node 20 构建前端静态导出，再打包进运行时镜像）；
• 运行时工具：ffmpeg、libsndfile1、git、curl等，供音频解码、VCS 安装、健康检查使用。

运行时各核心依赖的精确版本由 xinference/deploy/docker/requirements-runtime.txt 统一定义（如torch==2.11.0、transformers==5.13.1、accelerate==1.14.0），这份文件同时也是离线 pypiserver 镜像构建时的版本约束来源，保证离线镜像与运行时镜像不漂移。

镜像没有设置 entrypoint，默认命令是/bin/bash；部署时显式传入xinference-local/supervisor/worker等启动命令。

按需自定义构建镜像

如果你需要按自己的要求定制镜像，可直接使用仓库内的 Dockerfile：xinference/deploy/docker/Dockerfile。构建时必须位于 Xinference 仓库的顶层目录，例如：

git clone <本仓库地址> cd inference docker build --progress=plain -t test -f xinference/deploy/docker/Dockerfile .

--progress=plain会输出完整的构建日志，便于排查多阶段构建中每一步的执行情况。该 Dockerfile 同时支持 linux/amd64 与 linux/arm64 两种架构。

快速启动 Xinference 容器

以「将容器内 9997 端口映射到宿主机 9998、开启 debug 日志、从 modelscope 下载模型」为例：

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:v<your_version> xinference-local -H 0.0.0.0 --log-level debug

命令参数说明：

• -e XINFERENCE_MODEL_SRC=modelscope：设置模型下载源为 ModelScope（可选值huggingface、modelscope、auto）；
• -p 9998:9997：把容器内 9997 端口映射到宿主机 9998 端口；
• --gpus all：把宿主机全部 GPU 透传给容器；
• xinference-local -H 0.0.0.0 --log-level debug：以本地模式启动，监听所有网卡并输出 debug 级别日志。

启动时有三个要点（原文档明确强调）：

1. --gpus选项不可省略。镜像依赖宿主机 GPU，省略会导致错误；
2. -H 0.0.0.0参数不可省略。否则宿主机可能无法访问容器内的端口；
3. 可以通过多个-e选项引入多个环境变量。

多 GPU 场景下还需要注意共享内存大小，建议显式指定，例如：

docker run --shm-size=128g ...

当然，你也可以手动进入容器，以任意方式启动 Xinference：

docker exec -it <container_id> bash

挂载卷：让模型文件持久化并复用

镜像默认不含任何模型文件，模型会下载到容器内部，容器停止后即丢失。典型做法是把宿主机目录挂载进容器，再通过XINFERENCE_HOME环境变量让 Xinference 把下载路径指向容器内的挂载点：

docker run -v </on/your/host>:</on/the/container> -e XINFERENCE_HOME=</on/the/container> -p 9998:9997 --gpus all xprobe/xinference:v<your_version> xinference-local -H 0.0.0.0

原理：把宿主机指定目录挂载进容器，并将XINFERENCE_HOME指向容器内该目录。这样所有下载的模型文件都会落到宿主机目录中，容器停止不会丢失；下次启动可直接复用已有模型，无需重复下载。

符号链接场景的额外挂载：如果模型文件此前是通过宿主机默认路径下载的，而 Xinference 缓存目录使用符号链接存放模型，那么还需要把原始文件所在目录一并挂载进容器。以 HuggingFace 和 ModelScope 双 hub 为例，它们的缓存目录通常位于<home_path>/.cache/huggingface与<home_path>/.cache/modelscope，完整命令如下：

docker run \ -v </your/home/path>/.xinference:/root/.xinference \ -v </your/home/path>/.cache/huggingface:/root/.cache/huggingface \ -v </your/home/path>/.cache/modelscope:/root/.cache/modelscope \ -p 9997:9997 \ --gpus all \ xprobe/xinference:v<your_version> \ xinference-local -H 0.0.0.0

这里把宿主机.xinference、HuggingFace 缓存、ModelScope 缓存分别挂到容器内/root/.xinference、/root/.cache/huggingface、/root/.cache/modelscope，确保符号链接解析到的真实文件在容器内同样可见。

与部署强相关的关键环境变量

以下变量在容器部署中高频使用（完整列表见 environments.rst）：

• XINFERENCE_MODEL_SRC：模型下载源，取值为huggingface/modelscope/auto。auto模式下 Xinference 会探测 Hugging Face 端点（含HF_ENDPOINT与NO_PROXY配置）是否可达，不可达则回退到 ModelScope；也可在单次启动时用--download_hub覆盖显式值。
• XINFERENCE_HOME：Xinference 存储日志、模型等文件的根目录，默认是<HOME>/.xinference；容器部署时用它指向挂载卷（见上文）。
• XINFERENCE_ENABLE_VIRTUAL_ENV：全局开关模型虚拟环境，自 v2.0 起默认值为1（开启）。v3.0 slim 镜像正是依赖该机制在模型启动时装引擎。
• XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED：创建虚拟环境时跳过系统 site-packages 中已存在的包，默认1，配合镜像内预装的共享 CUDA torch 栈可避免重复下载。

离线 / 内网环境的配套方案

由于 v3.0 GPU 镜像在模型启动时需要从 PyPI 安装引擎，无外网主机必须改用Docker Compose 离线配置（详见 using_docker_compose.rst）：通过--profile offline额外拉起一个私有 PyPI 服务器（镜像xprobe/xinference-pypiserver，构建与自检逻辑见 xinference/deploy/docker/pypiserver/README.md），并将运行时所有pip/uv调用指向它。关键配置点包括：

• docker-compose.yml中以env_file挂载offline.env（存在才加载），并以只读方式挂载 pip.conf 到/etc/pip.conf；
• 在offline.env中设置XINFERENCE_VIRTUAL_ENV_OFFLINE_INSTALL=1、UV_DEFAULT_INDEX等变量，并将XINFERENCE_IMAGE与XINFERENCE_PYPISERVER_IMAGE固定到同一发行版本，保证镜像内容与模型规格、引擎依赖列表匹配；
• 常用可调变量可参考 xinference/deploy/docker/.env.example：XINFERENCE_PORT（默认 9997）、XINFERENCE_SHM_SIZE（默认 8gb）、XINFERENCE_HOME_DIR/XINFERENCE_HF_CACHE_DIR/XINFERENCE_MODELSCOPE_CACHE_DIR（默认均为具名卷，可改为宿主机绝对路径以复用已有模型缓存）等。

需要说明的是，该私有镜像的 GPU 栈针对 CUDA 13.0 构建，不影响运行时在线安装对 CUDA 12.8 / 12.9 的既有支持，只是这些旧版本栈不在预构建镜像中。

小结

本文从using_docker_image.rst出发，完整覆盖了 Xinference 官方 Docker 镜像的版本演进（v2.0 的 CUDA 12.9 门槛与 v3.0 的 slim 化改造）、GPU 前置条件、镜像标签体系、GPU 镜像内部构成、自定义构建、容器启动命令（含--gpus、-H 0.0.0.0、多-e与--shm-size等要点），以及基于XINFERENCE_HOME和 HuggingFace / ModelScope 缓存目录的模型持久化挂载方案，并简要衔接了离线部署的 Compose 配套。按此指南操作，你可以在一台满足 CUDA 13.0 / 驱动 580 的 GPU 主机上，用几行docker run完成 Xinference 推理服务的部署，并让模型文件在容器生命周期之外持续复用。

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference