模型管理平台之 Xinference 部署

一、Xinference 平台概述

Xinference 是由 Xorbits 团队开发的开源企业级大模型推理与管理平台，专注于解决私有化场景下 LLM 部署难、管理乱、接入复杂的问题。它可以在 CPU/GPU/异构芯片环境下一键启动各类开源大模型，并自动提供标准 API 接口，无缝对接 Dify 平台。

核心优势

• • 一键部署：支持 Docker、pip、Docker Compose、Kubernetes 多种部署方式
• • 模型丰富：兼容 100+ 主流开源模型（Qwen、ChatGLM、Llama、DeepSeek 等）
• • 标准接口：提供 OpenAI 完全兼容 API，可直接接入 Dify
• • 资源智能调度：自动检测可用硬件，支持多模型并发、GPU/CPU 自动适配
• • 量化推理：支持 4bit/8bit/FP8 量化，大幅降低显存占用
• • 企业级特性：API 密钥认证、多租户隔离、日志监控、高可用部署
• • 纯内网运行：数据不落地外网，满足企业安全合规要求

二、部署前环境准备

2.1 硬件要求

2.2 软件环境要求

• • 操作系统：Linux（推荐 Ubuntu 22.04 LTS / CentOS 7+）
• • Docker：≥24.0.0
• • Docker Compose：≥2.20.0
• • NVIDIA 驱动：≥535.104.05（GPU 必需）
• • NVIDIA Container Toolkit：≥1.14.0（Docker GPU 支持）
• • Python：3.9-3.11（pip 部署方式）

三、多种部署方式详解

3.1 Docker 方式部署（推荐生产环境）

这是最稳定、最推荐的部署方式，环境隔离性好，维护简单。

3.1.1 基础部署命令

# 拉取最新稳定版镜像
docker pull xorbitsai/inference:v1.17.1

# 创建数据挂载目录
mkdir -p /data/xinference/models
mkdir -p /data/xinference/logs

# GPU 版本启动（推荐）
docker run -d \
  --name xinference \
  --gpus all \
  --shm-size=128g \
  -p 9997:9997 \
  -v /data/xinference/models:/root/.xinference \
  -v /data/xinference/logs:/var/log/xinference \
  -e XINFERENCE_MODEL_SRC=modelscope \
  -e TZ=Asia/Shanghai \
  --restart always \
  xorbitsai/inference:v1.17.1 \
  xinference-local -H 0.0.0.0 --port 9997 --log-level info

# CPU 版本启动（无 GPU 时使用）
docker run -d \
  --name xinference \
  -p 9997:9997 \
  -v /data/xinference/models:/root/.xinference \
  -v /data/xinference/logs:/var/log/xinference \
  -e XINFERENCE_MODEL_SRC=modelscope \
  -e TZ=Asia/Shanghai \
  --restart always \
  xorbitsai/inference:v1.17.1-cpu \
  xinference-local -H 0.0.0.0 --port 9997 --log-level info

重要参数说明：

• • --shm-size=128g：多 GPU 部署必需，设置共享内存大小
• • XINFERENCE_MODEL_SRC=modelscope：使用国内魔搭社区下载模型，速度更快
• • -H 0.0.0.0：允许外部访问，不可省略

3.1.2 Docker Compose 部署（更易管理）

创建 docker-compose.yml 文件：

version:'3.8'

services:
xinference:
image:xorbitsai/inference:v1.17.1
container_name:xinference
restart:always
ports:
-"9997:9997"
volumes:
-./models:/root/.xinference
-./logs:/var/log/xinference
environment:
-XINFERENCE_MODEL_SRC=modelscope
-TZ=Asia/Shanghai
-XINFERENCE_API_KEY=your_strong_api_key_here
deploy:
resources:
reservations:
devices:
-driver:nvidia
count:all
capabilities: [gpu]
shm_size:'128g'
command:xinference-local-H0.0.0.0--port9997--log-levelinfo

启动服务：

docker-compose up -d

3.2 pip 方式部署（适合开发测试）

# 创建虚拟环境
conda create -n xinference python=3.10
conda activate xinference

# 安装完整版本
pip install "xinference[all]==1.17.1" -i https://pypi.tuna.tsinghua.edu.cn/simple

# 启动服务
xinference-local --host 0.0.0.0 --port 9997 --log-level info

3.3 Kubernetes 部署（大规模生产环境）

使用官方 Helm Chart 部署：

# 添加 Helm 仓库
helm repo add xinference https://xorbitsai.github.io/xinference-helm-charts
helm repo update

# 创建命名空间
kubectl create namespace xinference

# 安装（GPU 版本）
helm install xinference xinference/xinference \
  -n xinference \
  --version 1.17.1 \
  --set config.model_src="modelscope" \
  --set config.worker_num=2 \
  --set config.gpu_per_worker="1" \
  --set persistence.enabled=true \
  --set persistence.size=200Gi \
  --set service.type=LoadBalancer

# 查看部署状态
kubectl get pods -n xinference

四、模型管理与运行

4.1 在线模型下载与启动

方式一：WebUI 管理（推荐）

1. 1. 访问 http://服务器IP:9997 进入 Xinference 管理界面
2. 2. 在左侧导航栏选择「Models」
3. 3. 在模型列表中找到需要的模型（如 qwen2.5-7b-instruct）
4. 4. 点击「Launch」按钮
5. 5. 在弹出的对话框中选择：
• • 模型格式：推荐 gguf（速度快、兼容性好）
• • 量化级别：推荐 q5_k_m（7B模型平衡精度与速度）
• • 上下文长度：根据需求设置（如 8192）
6. 6. 点击「Launch」开始下载并启动模型

方式二：命令行管理

# 查看所有可用模型
xinference list

# 启动 Qwen2.5-7B-Instruct（推荐配置）
xinference launch \
  --model-name qwen2.5-7b-instruct \
  --model-format gguf \
  --quantization q5_k_m \
  --n-ctx 8192 \
  --model-uid qwen2.5-7b-prod

# 查看已启动的模型
xinference list-running

# 停止模型
xinference terminate --model-uid qwen2.5-7b-prod

4.2 量化级别选择指南（2025年实测）

4.3 离线模型导入（完全内网环境）

如果服务器无法访问公网，可提前下载模型文件后导入：

1. 1. 从 Hugging Face 或 ModelScope 下载 GGUF 格式模型文件
2. 2. 将文件上传到 /data/xinference/models/gguf 目录
3. 3. 在 Xinference WebUI 中点击「Import Model」
4. 4. 填写以下信息：
• • 模型类型：LLM
• • 模型名称：qwen2.5-7b-instruct
• • 模型格式：gguf
• • 模型路径：/root/.xinference/gguf/qwen2.5-7b-instruct-q5_k_m.gguf
5. 5. 点击「Import」完成导入

五、与 Dify 平台完整对接

Xinference 提供与 OpenAI 完全兼容的 API 接口，可无缝接入 Dify 平台。

5.1 在 Dify 中添加模型提供商

1. 1. 登录 Dify 管理后台
2. 2. 进入「系统设置」→「模型提供商」
3. 3. 点击「添加模型提供商」→「OpenAI」
4. 4. 填写以下信息：
• • 名称：Xinference
• • API Key：your_strong_api_key_here（与 Xinference 启动时设置的一致）
• • API 地址：http://Xinference服务器IP:9997/v1
5. 5. 点击「保存」

5.2 添加具体模型

1. 1. 在模型提供商列表中找到「Xinference」
2. 2. 点击「添加模型」
3. 3. 选择模型类型：「文本生成模型」
4. 4. 填写模型名称：必须与 Xinference 中启动的模型名称完全一致（如 qwen2.5-7b-instruct）
5. 5. 配置模型参数：
• • 最大上下文长度：8192
• • 最大 Token 数：4096
• • 支持的功能：勾选「流式输出」「工具调用」
6. 6. 点击「保存」

5.3 测试连通性

1. 1. 点击模型右侧的「测试」按钮
2. 2. 在弹出的对话框中输入："你好，请介绍一下自己"
3. 3. 如果能正常返回回答，说明对接成功
4. 4. 测试流式输出和工具调用功能

六、生产环境高级配置

6.1 安全加固

6.1.1 启用 API 密钥认证

# Docker 启动时添加环境变量
-e XINFERENCE_API_KEY=your_strong_api_key_here

# 或在命令行启动时添加参数
xinference-local --host 0.0.0.0 --api-key your_strong_api_key_here

6.1.2 配置 IP 白名单

# 只允许指定 IP 访问
-e XINFERENCE_ALLOWED_IPS="192.168.1.0/24,10.0.0.0/8"

6.2 多 GPU 支持

6.2.1 指定特定 GPU 设备

# 只使用 GPU 0 和 GPU 1
docker run -d \
  --name xinference \
  --gpus '"device=0,1"' \
  --shm-size=128g \
  -p 9997:9997 \
  xorbitsai/inference:v1.17.1

6.2.2 分布式集群部署

# Supervisor 节点
xinference-supervisor --host 192.168.1.100 --port 9997

# Worker 节点 1
xinference-worker --endpoint http://192.168.1.100:9997 --gpus 0,1

# Worker 节点 2
xinference-worker --endpoint http://192.168.1.100:9997 --gpus 0,1

6.3 性能优化

# 优化启动参数
docker run -d \
  --name xinference \
  --gpus all \
  --shm-size=128g \
  -p 9997:9997 \
  xorbitsai/inference:v1.17.1 \
  xinference-local \
    -H 0.0.0.0 \
    --port 9997 \
    --model-limit 3 \
    --gpu-memory-utilization 0.8 \
    --batch-size 8 \
    --max-tokens 8192

关键优化参数：

• • --model-limit 3：最多同时运行 3 个模型
• • --gpu-memory-utilization 0.8：GPU 内存使用率上限 80%，防止 OOM
• • --batch-size 8：批处理大小，提升高并发场景吞吐量

6.4 日志与监控

6.4.1 日志配置

• • 日志默认存储在 /data/xinference/logs 目录
• • 支持自动滚动：单个日志文件达到 100MB 时自动分割，保留最近 30 个备份
• • 调整日志级别：--log-level debug（调试）/ info（生产）/ warning（错误）

6.4.2 Prometheus 监控

Xinference 内置 Prometheus 指标端点：http://服务器IP:9997/metrics，可采集以下指标：

• • 模型请求数、响应时间、错误率
• • GPU 显存使用率、CPU 使用率
• • 模型运行状态、并发数

七、常见问题排查与解决方案

7.1 模型下载失败

• • 问题：网络超时或速度慢
• • 解决方案：
1. 1. 设置国内镜像源：-e XINFERENCE_MODEL_SRC=modelscope
2. 2. 增加下载重试次数：-e XINFERENCE_DOWNLOAD_MAX_ATTEMPTS=5
3. 3. 使用离线导入方式

7.2 模型启动失败（OOM）

• • 问题：GPU 显存不足
• • 解决方案：
1. 1. 使用更低量化级别的模型（如从 Q5_K_M 改为 Q4_K_M）
2. 2. 减少上下文长度：--n-ctx 4096
3. 3. 降低 GPU 内存使用率上限：--gpu-memory-utilization 0.7
4. 4. 停止其他占用 GPU 的进程

7.3 Dify 无法调用 Xinference

• • 问题：连接超时或认证失败
• • 解决方案：
1. 1. 检查防火墙是否开放 9997 端口
2. 2. 确认 API 地址和端口是否正确
3. 3. 检查 API Key 是否一致
4. 4. 确认模型名称在 Dify 和 Xinference 中完全一致
5. 5. 测试直接调用 Xinference API：

   curl http://Xinference服务器IP:9997/v1/models \
     -H "Authorization: Bearer your_api_key"

7.4 推理速度慢

• • 问题：响应延迟高、吞吐低
• • 解决方案：
1. 1. 确认使用了 GPU 加速（检查日志中是否有 "Using GPU" 字样）
2. 2. 使用 GGUF 格式模型，速度比 PyTorch 格式快 2-3 倍
3. 3. 启用量化推理
4. 4. 调整批处理大小：--batch-size 16
5. 5. 升级硬件配置