Xinference：分布式模型推理平台安装与使用指南
一、官方信息
| 项目名称 | Xinference |
| 仓库地址 | https://github.com/xorbitsai/inference |
| 官方网站 | https://inference.readthedocs.io |
| 最新更新 | 持续高频迭代（2026-10-22） |
| Star 数 | 8k+ |
| 项目定位 | Xorbits 团队出品的分布式模型推理平台，支持 LLM、嵌入向量、Rerank、多模态模型，内置 WebUI 与 OpenAI 兼容 API |
二、项目背景
Xinference 由 Xorbits（原蚂蚁集团大数据团队）开发，定位是"AI 时代的模型 Kubernetes"。它把多种推理后端（vLLM、llama.cpp、Transformers、Text Generation Inference）抽象成统一的模型服务，支持分布式集群调度：一台 Master 管理多台 Worker，根据 GPU 资源自动路由请求到对应节点。
与 Ollama、LocalAI 单机方案不同，Xinference 天生为多机多卡设计，支持动态加载/卸载模型、模型副本、自动故障转移，并且覆盖 LLM、Embedding、Rerank、图像生成、语音等全品类模型。它的 WebUI 可以可视化管理模型、查看日志、监控 GPU 占用，是中小团队私有化部署大模型的优秀选择。
三、核心特性
- 分布式架构：Master-Worker 模式，多机多卡统一调度，支持水平扩展。
- 全品类模型：LLM、Embedding、Rerank、Image、Audio、Video 一站式。
- 多后端引擎：支持 vLLM、llama.cpp、Transformers、GGML 等后端自动切换。
- OpenAI 兼容 API：/v1/chat/completions、/v1/embeddings 直接对接 OpenAI SDK。
- WebUI 管理台：浏览器可视化部署、监控、日志查看。
- 模型 Marketplace：内置数百款主流模型一键下载。
- 负载均衡：同模型多副本自动路由，支持灰度发布。
四、环境要求
- 操作系统：Linux / macOS
- Python：3.9 ~ 3.12
- GPU（可选）：NVIDIA 显卡，显存按模型大小
- 网络：Master 与 Worker 之间需互通（默认端口 9997）
五、详细部署步骤
方式一：pip 安装（单机最快）
conda create -n xinference python=3.10 -y
conda activate xinference
pip install "xinference[all]"
# 验证
xinference --version方式二：Docker
# CPU 版
docker pull xprobe/xinference:latest
docker run -d \
--name xinference \
-p 9997:9997 \
-v ~/.xinference:/root/.xinference \
xprobe/xinference:latest \
xinference-local --host 0.0.0.0 --port 9997
# GPU 版
docker run -d \
--name xinference \
--gpus all \
-p 9997:9997 \
-v ~/.xinference:/root/.xinference \
xprobe/xinference:latest \
xinference-local --host 0.0.0.0 --port 9997启动本地服务
# 单机模式（Master + Worker 合一）
xinference-local --host 0.0.0.0 --port 9997
# 启动后：
# WebUI: http://IP:9997
# API: http://IP:9997/v1分布式集群模式
# 1. Master 节点（只需调度，不需 GPU）
xinference-supervisor -H 0.0.0.0 -p 9997
# 2. Worker 节点（每台 GPU 机器执行）
xinference-worker -e http://MASTER_IP:9997 \
-H 0.0.0.0 \
-p 33333
# 3. 在 WebUI 或 CLI 部署模型时自动调度到空闲 Worker部署模型
# 列出可用模型
xinference list --all
# 命令行启动一个 LLM
xinference launch \
--model-name qwen2.5-chat \
--model-format pytorch \
--size-in-billions 7 \
--model-scope 中文
# 启动 Embedding 模型
xinference launch --model-name bge-large-zh-v1.5 --model-type embedding
# 列出已部署模型
xinference list
# 停止模型
xinference terminate --model-uid qwen2.5-chat调用 API
# 对话
curl http://localhost:9997/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "qwen2.5-chat",
"messages": [{"role":"user","content":"你好"}]
}'
# Embedding
curl http://localhost:9997/v1/embeddings \
-H "Content-Type: application/json" \
-d '{
"model": "bge-large-zh-v1.5",
"input": "Xinference 是一个分布式推理平台"
}'
# Python SDK
python3 -c "
from openai import OpenAI
c = OpenAI(base_url='http://localhost:9997/v1', api_key='not-needed')
print(c.chat.completions.create(model='qwen2.5-chat',
messages=[{'role':'user','content':'hi'}]).choices[0].message.content)
"六、常见问题（FAQ）
Q1：模型下载慢？
A：设置 export XINFERENCE_MODEL_SRC=modelscope，自动从国内 ModelScope 拉取。
Q2：Worker 连不上 Master？
A：检查 Master 防火墙 9997 端口，Worker 需能访问 Master；Worker 之间也需互通（用于张量并行）。
Q3：如何指定 GPU？
A：启动 Worker 前设 CUDA_VISIBLE_DEVICES=0,1，或在 WebUI 部署模型时选择 GPU 索引。
Q4：支持 vLLM 后端吗？
A：安装时 pip install "xinference[vllm]"，部署模型时选 vLLM 后端即可获得更高吞吐。
Q5：如何对接 Dify / FastGPT 等 RAG 平台？
A：把 Xinference 的 /v1 地址作为 OpenAI 兼容端点填入即可，支持 LLM + Embedding + Rerank 全套。
七、跳转链接
- GitHub 仓库：https://github.com/xorbitsai/inference
- 官方文档：https://inference.readthedocs.io
- Docker 镜像：https://hub.docker.com/r/xprobe/xinference
- Xorbits 主页：https://xorbits.io