Docker Compose 部署#

Xinference 提供官方的单机 Docker Compose 部署方案，位于 xinference/deploy/docker。它同时支持联网主机和完全离线（air-gapped）环境：离线场景下会随 Xinference 一起启动一个可选的私有 PyPI 服务，为模型启动时安装的依赖包提供内网源。

准备工作#

Docker Compose v2.24.4 及以上版本 ，compose 文件用到了 env_file: required: false 与 !reset 特性。
GPU 部署需要：配备 NVIDIA GPU 且安装了 CUDA 与 NVIDIA Container Toolkit 的主机。镜像要求参见 Docker 镜像。
获取完整的 xinference/deploy/docker 目录。Compose 文件会绑定挂载同一目录中的 pip.conf，因此仅下载 docker-compose.yml 并不够：

git clone https://github.com/xorbitsai/inference.git
cd inference/xinference/deploy/docker

快速开始（GPU）#

使用主机全部 GPU 启动 Xinference：

docker compose up -d

等服务进入 healthy 状态后验证：

docker compose ps
curl http://localhost:9997/status

Web UI 地址为 http://localhost:9997。

备注

自 v3.0 起，身份验证默认启用：首次访问 Web UI 时会要求创建初始管理员账号，之后的 API 调用需要登录或使用 API Key。若要在无身份验证的情况下运行，请在 docker-compose.yml 的 environment: 部分添加 XINFERENCE_AUTH_ADVANCED=false。参见身份验证系统（基于数据库）。

配置#

所有配置项都以带默认值的变量形式暴露，可以通过与 docker-compose.yml 同目录的 .env 文件覆盖。复制模板后按需修改：

cp .env.example .env

可用变量：

XINFERENCE_IMAGE：运行的镜像，默认 xprobe/xinference:latest。生产环境建议固定为发布版本，如 xprobe/xinference:v<version>。
XINFERENCE_PORT：RESTful API / Web UI 的主机端口，默认 9997。
XINFERENCE_MODEL_SRC：模型下载源， huggingface （默认）或 modelscope。
XINFERENCE_SHM_SIZE：共享内存大小，默认 8gb。多卡推理时建议调大。
XINFERENCE_LOG_LEVEL：日志级别，默认 info。
XINFERENCE_HOME_DIR / XINFERENCE_HF_CACHE_DIR / XINFERENCE_MODELSCOPE_CACHE_DIR：持久化位置。默认使用 Docker 命名卷；指向主机上的绝对路径即可复用已有的模型缓存，方式与 Docker 镜像中的说明相同。
XINFERENCE_WHEELS_DIR / XINFERENCE_PYPISERVER_PORT / XINFERENCE_PYPISERVER_IMAGE：离线 profile 相关配置，见下文。

其他运行时选项（认证、OpenTelemetry、健康检查调优等）可在 docker-compose.yml 的 environment: 段落中添加对应变量，完整列表见环境变量。

纯 CPU 部署#

在没有 NVIDIA GPU 的主机上，叠加 CPU override 文件即可：它会把镜像切换为 -cpu 变体并移除 GPU 预留配置：

docker compose -f docker-compose.yml -f docker-compose.cpu.yml up -d

健康检查与重启策略#

xinference 服务通过 /status 接口上报健康状态，且除非显式停止否则会自动重启（restart: unless-stopped）。 docker compose ps 可查看健康状态；基于 compose 的上层编排可以依赖该状态。

离线 / 内网（Air-gapped）部署#

默认情况下，Xinference 会在模型启动时把模型声明的额外 Python 依赖安装到独立的虚拟环境中（由 XINFERENCE_ENABLE_VIRTUAL_ENV 控制，见环境变量）。在无法访问互联网的主机上，这些安装会失败。

offline Compose profile 会在 Xinference 旁启动一个私有 PyPI 服务器来解决此问题。其镜像 xprobe/xinference-pypiserver 内置了运行时可能安装到各模型虚拟环境中的、兼容索引的 wheel，包括 vllm / sglang CUDA 软件栈；因此受支持的模型无需另行准备 wheel。离线配置会将 Xinference 容器内运行时的所有 pip / uv 调用指向该服务器。

备注

预构建镜像中的 GPU 软件栈面向 CUDA 13.0。这不会取消运行时原有的 CUDA 12.8/12.9 在线支持，但此镜像不包含这些软件栈。

第 1 步：传输 Docker 镜像#

将 Docker 镜像传输到离线主机（使用 docker save / docker load）：包括 Xinference 镜像和镜像源镜像。请将两者固定为**同一个发布标签**，以保证镜像源内容与该版本的模型规格及引擎依赖列表匹配，并在 .env 中记录这些固定版本：

XINFERENCE_IMAGE=xprobe/xinference:v2.9.0
XINFERENCE_PYPISERVER_IMAGE=xprobe/xinference-pypiserver:v2.9.0

第二步：启用离线配置#

cp offline.env.example offline.env

然后打开 pip.conf，取消离线配置块三行的注释：

[global]
index-url = http://xinference-pypiserver:8080/simple
extra-index-url = http://xinference-pypiserver:8080/simple
trusted-host = xinference-pypiserver

备注

这三项缺一不可，因为它们覆盖不同的代码路径。pip.conf 用于 Xinference 的 pip 配置继承，从而将私有索引显式传给各模型虚拟环境的安装器；offline.env 中的 UV_* 变量覆盖不携带索引参数的 uv 调用（例如依赖解析的试运行）；XINFERENCE_VIRTUAL_ENV_OFFLINE_INSTALL=1 则仅针对这个自包含镜像源启用直接 wheel 引用重写。在线用户配置普通 pip 镜像源时不会启用该行为。

第三步：以离线 profile 启动#

docker compose --profile offline up -d

也可以在 .env 中设置 COMPOSE_PROFILES=offline 以省略 --profile 参数。如有需要可与 CPU override 组合使用：

docker compose --profile offline -f docker-compose.yml -f docker-compose.cpu.yml up -d

私有源同时发布在主机上（默认端口 8080），同一网络内的其他机器可通过 pip install -i http://<host>:8080/simple ... 复用它。

备注

使用 vLLM 或 SGLang 引擎启动模型时，Xinference 默认会从硬编码的公共索引（wheels.vllm.ai、download.pytorch.org）和直接 wheel URL（sgl_kernel）解析部分依赖。上述离线 pip.conf 会同时覆盖二者：用私有索引替代公共索引，并将直接 wheel URL 依赖解析为 name==version。内置镜像源已经包含这些 CUDA wheel。也可以在 offline.env 中设置 XINFERENCE_ENABLE_VIRTUAL_ENV=0，完全跳过运行时安装，改用 Xinference 镜像中预装的软件包。

对于 llama.cpp 引擎，镜像源包含来自 PyPI 的 xllamacpp CPU 版本。其 GPU wheel 位于另一个 CUDA 专用索引中，离线时不可用，因此 GPU 主机会回退到 CPU 版本并记录警告。若要保留 llama.cpp GPU 加速，请在自定义运行时镜像中预装匹配的 xllamacpp GPU wheel。

警告

包含 git+ 或其他非 wheel 直接引用的模型规格无法由 Python simple index 完整表示。在显式离线安装模式下，Xinference 会在尝试访问网络前拒绝这些依赖，并报告有问题的 requirement。目前此类内置模型包括 HunyuanOCR、MiniCPM-V-4.6 和 MiniCPM-V-4.6-Thinking 的 Transformers 路径，以及 FLUX.2-klein。进行隔离网部署前，请在自定义镜像中预装所需源码版本，或将其替换为可从索引解析的软件包。显式离线模式也会跳过从公共 wheel 索引获取的 FlashInfer AOT 修复；需要该修复的 Blackwell 部署应将相应软件包预装进自定义镜像。

使用自己的 wheel（可选）#

若要提供自行整理的 wheel 目录而非内置镜像源（例如只包含特定模型所需的小型子集），请添加 docker-compose.byo-wheels.yml 覆盖文件。它会把镜像替换为官方 pypiserver/pypiserver:v2.3.2，并挂载 ./wheels：

如果已将该官方镜像同步到私有镜像仓库，请设置 XINFERENCE_BYO_PYPISERVER_IMAGE。该设置特意与 XINFERENCE_PYPISERVER_IMAGE 分开；后者用于选择常规离线 profile 中的 Xinference 预构建镜像源。

python3 -m pip download \
   --dest ./wheels \
   --only-binary=:all: \
   --python-version 312 \
   --platform manylinux2014_x86_64 \
   'transformers>=4.53.3' accelerate

chmod -R a+rwX ./wheels   # pypiserver runs as UID 9898
docker compose --profile offline \
   -f docker-compose.yml -f docker-compose.byo-wheels.yml up -d

离线模型权重#

离线配置设置了 HF_HUB_OFFLINE=1 和 TRANSFORMERS_OFFLINE=1，模型权重只会从本地缓存读取。请在离线前准备好缓存：既可以把 .env 中的缓存变量指向已包含模型的主机目录，也可以在联网主机上把每个模型启动一次后拷贝数据卷。此外，也可以通过注册自定义模型或传入 --model-path 从任意本地路径加载模型。

强制网络隔离（可选）#

离线配置只是把所有下载重定向到本地源，其本身并不能阻止容器在宿主机联网时访问互联网。若要在网络层面保证隔离，可叠加 air-gap override：它会把 Xinference 和私有 PyPI 服务移入一个没有外部路由的 internal Docker 网络：

docker compose --profile offline \
   -f docker-compose.yml -f docker-compose.airgap.yml up -d

由于 Docker 不会发布纯 internal 网络上的端口，该 override 增加了一个极简 TCP 网关（alpine/socat），把 API 端口从宿主机转发进隔离网络。网关只会把入站流量转发到 xinference:9997，容器无法把它当作出网通道。记得把 alpine/socat 镜像与其他镜像一起传输到离线主机。

备注

该模式下私有 PyPI 服务不再发布到宿主机，只有隔离网络内的容器可以访问。可在容器内验证隔离效果——外网请求必须失败，而私有源保持可达：

docker compose -f docker-compose.yml -f docker-compose.airgap.yml exec xinference \
   curl -s -m 5 https://pypi.org -o /dev/null || echo "external access blocked"
docker compose -f docker-compose.yml -f docker-compose.airgap.yml exec xinference \
   curl -s http://xinference-pypiserver:8080/health

冒烟验证#

# The private index serves your wheels:
curl http://localhost:8080/simple/

# Inside the container, installs resolve against the private index only:
docker compose exec xinference python3 -m pip config list
docker compose exec xinference uv pip install --dry-run --python /usr/bin/python3 <some-package-in-wheels>

然后启动一个模型并观察 docker compose logs -f xinference——依赖安装日志中应出现 http://xinference-pypiserver:8080/simple。