Docker 镜像#

Xinference 在 DockerHub 上提供官方镜像。

在 v2.0 版本发生变更: 从 Xinference v2.0 开始,如果要使用cuda版本的镜像,cuda版本最低要达到 CUDA 12.9 。

在 v3.0.0 版本发生变更: 从 Xinference v3.0.0 起,GPU 镜像是基于 nvidia/cuda:13.0.2-devel-ubuntu22.04 的 精简镜像。它不再预装 vLLM、SGLang 等推理引擎,而是在模型启动时,将引擎自动安装到各模型独立的虚拟环境中(参见 环境变量 中的 XINFERENCE_ENABLE_VIRTUAL_ENV)。因此,启动模型时需要访问 PyPI;对于离线或与外网隔离的主机,可使用 Docker Compose 离线配置中的私有 PyPI 镜像源,参见 Docker Compose 部署。该镜像支持的最低 CUDA 版本为 CUDA 13.0。

准备工作#

  • Xinference 使用 GPU 加速推理,该镜像需要在有 GPU 显卡并且安装 CUDA 的机器上运行。

  • 保证 CUDA 在机器上正确安装。可以使用 nvidia-smi 检查是否正确运行。

  • Docker 镜像中的 CUDA 版本为 13.0;宿主机上的 CUDA 版本应为 13.0 或更高,NVIDIA 驱动版本应为 580 或更高。

  • 请确保已安装 NVIDIA Container Toolkit 。

Docker 镜像#

Xinference 官方镜像已发布在 DockerHub 上的 xprobe/xinference 仓库中。当前可用的标签包括:

  • nightly-main:每天基于 GitHub main 分支 构建,通常不保证稳定性。

  • v<release version>: 这个镜像会在 Xinference 每次发布的时候制作,通常可以认为是稳定可靠的。

  • latest: 这个镜像会在 Xinference 发布时指向最新的发布版本

  • 对于 CPU 版本,增加 -cpu 后缀,如 nightly-main-cpu。

GPU 镜像包含哪些组件#

GPU 镜像包含 Python 3.12、CUDA 13.0 工具包、共享的 CUDA 版 PyTorch、Transformers 引擎(transformers / accelerate),以及带有 Web UI 的 Xinference。其他推理引擎(vLLM、SGLang、llama.cpp 等) 不会预装:启动模型时,Xinference 会为其创建虚拟环境,并安装模型配置中声明的引擎依赖包。因此,首次使用某个引擎启动模型时,需要从 PyPI(离线部署时从私有镜像源)下载依赖包,耗时会更长;后续启动会复用该虚拟环境。

备注

在离线环境中,如果需要在模型启动时自动向各模型的虚拟环境安装引擎依赖,请使用 Docker Compose 的 offline 配置提供私有 PyPI 镜像源。镜像准备和依赖源配置步骤见 Docker Compose 离线部署。

自定义镜像#

如果需要安装额外的依赖,可以参考 xinference/deploy/docker/Dockerfile 。请确保使用 Dockerfile 制作镜像时在 Xinference 项目的根目录下。比如:

git clone https://github.com/xorbitsai/inference.git
cd inference
docker build --progress=plain -t test -f xinference/deploy/docker/Dockerfile .

使用镜像#

可以通过以下命令在容器中启动 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

警告

  • --gpus 必须指定,正如前文描述,镜像必须运行在有 GPU 的机器上,否则会出现错误。

  • -H 0.0.0.0 也是必须指定的,否则在容器外无法连接到 Xinference 服务。

  • 可以指定多个 -e 选项赋值多个环境变量。

当然,也可以运行容器后,进入容器内手动拉起 Xinference。

备注

使用多张 GPU 时,请确保设置共享内存大小,例如:docker run --shm-size=128g ...。

挂载模型目录#

镜像默认不包含模型文件,使用时会将模型下载到容器内。通常需要将宿主机上的目录挂载到 Docker 容器中,让 Xinference 将模型下载到该目录,便于后续复用。为此,运行 Docker 镜像时需要指定挂载卷,并配置 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 环境变量指向容器内的该目录。这样,所有下载的模型文件将存储在您在主机上指定的目录中。您无需担心在 Docker 容器停止时丢失这些文件,下次运行容器时,您可以直接使用现有的模型,无需重复下载。

如果你在宿主机使用的默认路径下载的模型,由于 xinference cache 目录是用的软链的方式存储模型,需要将原文件所在的目录也挂载到容器内。例如你使用 huggingface 和 modelscope 作为模型仓库,那么需要将这两个对应的目录挂载到容器内,一般对应的 cache 目录分别在 <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