1-6 Dify本地私有化部署—Xinference部署和模型启动

# 确保宿主机已安装 NVIDIA 驱动
$ nvidia-smi
Mon Jul  7 14:01:36 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 561.19                 Driver Version: 561.19         CUDA Version: 12.6     |
|-----------------------------------------+------------------------+----------------------+

镜像中的 CUDA 版本为 12.4 。为了不出现预期之外的问题，请将宿主机的 CUDA 版本和 NVIDIA Driver 版本分别升级到 12.4 和 550 以上。
请确保已安装 NVIDIA Container Toolkit 。

3、xinference镜像介绍

3.1、使用Docker Hub 拉取镜像

您可以直接通过 Docker Hub 来获取最新的或特定版本的 Xinference 镜像。

对于常规用户(国内需要魔法上网)：
- 如果您能够访问 Docker Hub，可以直接使用以下命令拉取官方镜像：
```
docker pull xprobe/xinference:<tag>
```
- 可用标签包括 nightly-main, v<release version>, 和 latest。
对于受限于网络环境的用户：
- 如果您遇到访问 Docker Hub 的困难，可以使用阿里云提供的镜像地址来拉取。例如：
```
docker pull crpi-49yei0hvmhr144pw.cn-hangzhou.personal.cr.aliyuncs.com/xprobe_xinference2/xinference:<tag>
```

3.2、镜像标签说明

nightly-main: 这个镜像是每天从 GitHub main 分支构建的，不保证稳定性和可靠性。
v<release version>: 在 Xinference 每次发布时制作的版本，通常被认为是稳定的。
latest: 该标签指向最新的正式发布的版本。

3.3、CPU 版本

如果您需要特定于 CPU 的镜像，可以在标签后加上 -cpu 后缀。例如：

docker pull xprobe/xinference:nightly-main-cpu

或者使用阿里云提供的地址：

docker pull crpi-49yei0hvmhr144pw.cn-hangzhou.personal.cr.aliyuncs.com/xprobe_xinference2/xinference:nightly-main-cpu

4、Xinference单机部署

基于Xinference v1.7.0.post1版本或更新版本，以下是单机部署的详细步骤：

4.1、拉取 Xinference 镜像

# CPU 模式 
$ docker pull xprobe/xinference:v1.7.0.post1-cpu
# 启用 GPU 加速（需 NVIDIA 驱动）
$ docker pull xprobe/xinference:v1.7.0.post1
$ docker images
REPOSITORY                TAG                 IMAGE ID       CREATED        SIZE
xprobe/xinference         v1.7.0.post1        0949777d1ea9   8 days ago     27GB

4.2、启动容器语法

# CPU 模式（根据硬件选择命令）
docker run -d -p 9998:9997 --name xinference xprobe/xinference:v1.7.0.post1-cpu

# 启用 GPU 加速（需 NVIDIA 驱动，根据硬件选择命令）
docker run -d --gpus all -p 9998:9997 --name xinference xprobe/xinference:v1.7.0.post1-cpu

# 限制 GPU 显存，为容器分配指定 GPU 资源
docker run -d --gpus '"device=0,1"' -p 9998:9998 \
  -e NVIDIA_VISIBLE_DEVICES=0,1 \
  xprobe/xinference:latest

# 调整容器资源限制，限制 CPU 和内存使用
docker run -d -p 9998:9998 \
  --cpus 4 \
  --memory 16g \
  xprobe/xinference:latest
  
# 启用 HTTPS
docker run -d -p 443:9998 \
    -v /etc/ssl/certs:/etc/ssl/certs \
    xprobe/xinference:latest  \
    --tls-certfile=/etc/ssl/certs/server.crt  \
    --tls-keyfile=/etc/ssl/certs/server.key

4.3、挂载模型目录

默认情况下，镜像中不包含任何模型文件，使用过程中会在容器内下载模型。如果需要使用已经下载好的模型，需要将宿主机的目录挂载到容器内。这种情况下，需要在运行容器时指定本地卷，并且为 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

4.4、单机部署完整命令

Windows下powershell中执行：

docker run --restart=always -d `
    --log-driver json-file --log-opt max-size=100m --log-opt max-file=2 `
    --name xinference `
    -v E:/sys/xinference/.xinference:/root/.xinference `
    -v E:/sys/xinference/.cache/huggingface:/root/.cache/huggingface `
    -v E:/sys/xinference/.cache/modelscope:/root/.cache/modelscope `
    -p 9998:9997 `
    --gpus all `
    xprobe/xinference:v1.7.0.post1 `
    xinference-local -H 0.0.0.0 --log-level info

启动成功等待1分钟左右在访问xinference：http://localhost:9998 或 http://192.168.2.100:9998/

参数详解：

--gpus 必须指定，表示镜像必须运行在有 GPU 的机器上，否则会出现错误。
-d 以守护进程（后台）模式运行容器，避免阻塞终端。
--name xinference 为容器指定名称为 xinference，便于后续管理（如停止、重启）
-H 0.0.0.0 也是必须指定的，否则在容器外无法连接到 Xinference 服务。
E:/sys/xinference/.xinference:/root/.xinference 持久化存储 Xinference 的配置文件（如模型元数据、服务配置）。
E:/sys/xinference/.cache/huggingface:/root/.cache/huggingface 缓存从 Hugging Face 下载的模型文件，避免重复下载。
E:/sys/xinference/.cache/modelscope:/root/.cache/modelscope 缓存从 ModelScope 下载的模型文件，避免重复下载。

4.5、验证部署状态

访问 Web UI：http://localhost:9998，若看到管理界面则部署成功。

5、Xinference模型部署方法

5.1、UI操作启动模型(方法1)

访问http://localhost:9998 → 进入"Launch Model"标签
选择模型（如qwen-chat）→ 设置参数（如量化等级、引擎类型）→ 点击启动
‌首次启动‌会自动下载模型文件并缓存至~/.xinference/cache‌。

5.2、命令行启动模型(方法2)

进入容器内docker exec -it xinference bash启动模型，执行如下命令：

xinference launch --model-name bge-large-zh-v1.5 --model-type embedding
# 启动 Rerank 模型（如 bge-reranker-large）
xinference launch --model-name bge-reranker-large --model-type rerank

# 启动 Embedding 模型（如 bge-large-en）
xinference launch --model-name bge-large-en --model-type embedding

# 启动 LLM（如 Llama3-8B）
xinference launch --model-name llama-3-8b-instruct --model-type LLM --size-in-billions 8 --quantization 4

docker exec -it xinference bash -c "xinference launch --model-name bge-reranker-large --model-type rerank"

5.3、通过 API 启动模型

直接通过 REST API 动态加载模型：

# 启动 Rerank 模型
curl -X POST "http://localhost:9998/v1/models" \
  -H "Content-Type: application/json" \
  -d '{
    "model_type": "rerank",
    "model_name": "bge-reranker-large",
    "model_format": "pytorch"
  }'

5.4、查看正在运行的模型

访问http://localhost:9998 → 进入"Running Models"标签.

# 方式一
http://localhost:9998/v1/models

# 方式二
$ docker exec -it xinference bash
$ root@c3e9add70d72:/opt/inference# xinference list
UID                 Type    Name
------------------  ------  ------------------
bge-reranker-large  rerank  bge-reranker-large

# 方式三
访问Xinference：http://localhost:9998/
点击“Running Models”，查看已加载模型

本文章已经生成可运行项目