基于 Docker快速在Ubuntu 系统上部署 Xinference
基于 Docker快速在Ubuntu 系统上部署 Xinference
- Xinference 基于 Docker 的 Ubuntu 部署指南
- 1. 安装 Docker
- 1.1 更新系统包
- 1.2 安装 Docker
- 1.3 验证 Docker 安装
- 1.4（可选）添加用户到 Docker 组（避免使用 `sudo`）
- 2. 拉取 Xinference 镜像
- 3. 部署 Xinference 容器
- 3.1 创建目录结构（推荐）
- 3.2 运行基础容器（CPU 版）
- 3.3 查看容器日志（调试用）
- 4. GPU 加速部署（需 NVIDIA GPU）
- 4.1 安装 NVIDIA 驱动和容器工具
- 安装 NVIDIA 驱动（根据显卡型号选择版本）
- 安装 NVIDIA Container Toolkit
- 4.2 运行 GPU 容器
- 5. 验证部署
- 5.1 检查容器状态
- 5.2 测试 API 接口
- 5.3 调用模型（示例）
- 6. 高级配置
- 6.1 自定义配置文件
- 7. 故障排除
- 7.1 常见问题及解决
- 8. 维护与更新
- 8.1 停止和删除容器
- 8.2 更新镜像
- 9. 扩展资源
- Xorbits Inference：模型推理， 轻而易举 🤖
- 🔥 近期热点
- 框架增强
- 新模型
- 集成
- 主要功能
- 为什么选择 Xinference
以下是针对 Ubuntu 系统 的 Xinference 基于 Docker 的部署文档，步骤更详细且适配 Ubuntu 环境：
Xinference 基于 Docker 的 Ubuntu 部署指南
1. 安装 Docker
1.1 更新系统包
sudo apt-get update
sudo apt-get upgrade -y
1.2 安装 Docker
# 安装依赖
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common -y
# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 添加 Docker APT 仓库
echo
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装 Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io -y
1.3 验证 Docker 安装
sudo docker --version # 应显示 Docker 版本
sudo docker run hello-world # 运行测试容器
1.4（可选）添加用户到 Docker 组（避免使用 sudo）
sudo usermod -aG docker $USER
newgrp docker # 重启终端或重新登录使生效
2. 拉取 Xinference 镜像
docker pull xinference/xinference:latest # 拉取最新版
# 或指定版本，如 docker pull xinference/xinference:v0.3.0
3. 部署 Xinference 容器
3.1 创建目录结构（推荐）
mkdir -p ~/xinference/{models,logs}
3.2 运行基础容器（CPU 版）
docker run -d
--name xinference
-p 8080:8080 # 映射 API 端口（宿主机 8080 → 容器 8080）
-v ~/xinference/models:/app/models # 挂载模型目录
-v ~/xinference/logs:/app/logs # 挂载日志目录
-e API_HOST=0.0.0.0 # 允许外部访问
xinference/xinference:latest
3.3 查看容器日志（调试用）
docker logs -f xinference
4. GPU 加速部署（需 NVIDIA GPU）
4.1 安装 NVIDIA 驱动和容器工具
安装 NVIDIA 驱动（根据显卡型号选择版本）
# 自动安装推荐驱动
sudo ubuntu-drivers autoinstall
# 或手动安装特定驱动（例如 NVIDIA 525）
sudo apt install nvidia-driver-525 -y
sudo reboot # 重启后验证驱动
nvidia-smi # 应显示 GPU 信息
安装 NVIDIA Container Toolkit
distribution=$(. /etc/os-release; echo $ID$VERSION_ID) # 获取 Ubuntu 版本（如 ubuntu22.04）
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker
4.2 运行 GPU 容器
docker run -d
--name xinference-gpu
--gpus all # 启用所有 GPU
-p 8080:8080
-v ~/xinference/models:/app/models
-v ~/xinference/logs:/app/logs
xinference/xinference:latest
5. 验证部署
5.1 检查容器状态
docker ps -a | grep xinference
# 确保容器状态为 "Up"
5.2 测试 API 接口
curl http://localhost:8080/ping
# 应返回：{"status":"ok"}
5.3 调用模型（示例）
# 安装 requests 库
pip install requests
# Python 调用 API
import requests
response = requests.post(
"http://localhost:8080/api/v1/models",
json={"model_name": "llama-30b"}
)
print(response.json())
6. 高级配置
6.1 自定义配置文件
在 ~/xinference/config.toml 中配置：
[api]
host = "0.0.0.0"
port = 8080
log_level = "debug" # 调试时使用
[model]
storage_path = "/app/models"
运行时挂载配置文件：
docker run -d
--name xinference
-v ~/xinference/config.toml:/app/config.toml
... 其他参数 ...
7. 故障排除
7.1 常见问题及解决
| 问题描述 | 解决方案 |
|---|---|
| 端口被占用 | 检查 8080 端口：sudo lsof -i :8080，终止占用进程或更换端口（如 -p 8090:8080）。 |
| 模型加载失败 | 确保 models 目录挂载正确，且模型文件已正确下载到 ~/xinference/models。 |
| GPU 未识别 | 运行 nvidia-smi 确认驱动正常；检查容器是否添加 --gpus all 参数。 |
| 权限问题 | 确保目录权限：sudo chmod -R 755 ~/xinference。 |
8. 维护与更新
8.1 停止和删除容器
docker stop xinference
docker rm xinference
8.2 更新镜像
docker pull xinference/xinference:latest
docker run ... # 重新启动容器
9. 扩展资源
- 官方文档：https://xinference.com/
- GitHub 仓库：https://github.com/xinference/xinference
- Ubuntu Docker 官方指南：https://docs.docker.com/engine/install/ubuntu/
通过以上步骤，您可以在 Ubuntu 系统上成功部署 Xinference，并通过 Docker 实现灵活的模型推理服务。如需进一步优化性能或扩展功能，请参考官方文档或社区资源。
Xorbits Inference：模型推理， 轻而易举 🤖
Xinference 云服务 · Xinference 企业版 · 自托管 · 文档
Xorbits Inference（Xinference）是一个性能强大且功能全面的分布式推理框架。可用于大语言模型（LLM），语音识别模型，多模态模型等各种模型的推理。通过 Xorbits Inference，你可以轻松地一键部署你自己的模型或内置的前沿开源模型。无论你是研究者，开发者，或是数据科学家，都可以通过 Xorbits Inference 与最前沿的 AI 模型，发掘更多可能。
🔥 近期热点
框架增强
- Xllamacpp: 全新llama.cpp Python binding，由 Xinference 团队维护，支持持续并行且更生产可用: #2997
- 分布式推理：在多个 worker 上运行大尺寸模型：#2877
- VLLM 引擎增强: 跨副本共享KV Cache: #2732
- 支持 Transformers 引擎的持续批处理: #1724
- 支持针对苹果芯片优化的MLX后端: #1765
- 支持加载模型时指定 worker 和 GPU 索引: #1195
- 支持 SGLang 后端: #1161
- 支持LLM和图像模型的LoRA: #1080
新模型
- 内置 QwQ-32B: #3005
- 内置 DeepSeek V3 and R1: #2864
- 内置 InternVL2.5: #2776
- 内置 DeepSeek-R1-Distill-Llama: #2811
- 内置 DeepSeek-R1-Distill-Qwen: #2781
- 内置 Kokoro-82M: #2790
- 内置 qwen2.5-vl: #2788
- 内置 internlm3-instruct: #2789
- 内置 MeloTTS: #2760
集成
- FastGPT：一个基于 LLM 大模型的开源 AI 知识库构建平台。提供了开箱即用的数据处理、模型调用、RAG 检索、可视化 AI 工作流编排等能力，帮助您轻松实现复杂的问答场景。
- Dify: 一个涵盖了大型语言模型开发、部署、维护和优化的 LLMOps 平台。
- RAGFlow: 是一款基于深度文档理解构建的开源 RAG 引擎。
- MaxKB: MaxKB = Max Knowledge Base，是一款基于大语言模型和 RAG 的开源知识库问答系统，广泛应用于智能客服、企业内部知识库、学术研究与教育等场景。
- Chatbox: 一个支持前沿大语言模型的桌面客户端，支持 Windows，Mac，以及 Linux。
主要功能
🌟 模型推理，轻而易举：大语言模型，语音识别模型，多模态模型的部署流程被大大简化。一个命令即可完成模型的部署工作。
⚡️ 前沿模型，应有尽有：框架内置众多中英文的前沿大语言模型，包括 baichuan，chatglm2 等，一键即可体验！内置模型列表还在快速更新中！
🖥 异构硬件，快如闪电：通过 ggml，同时使用你的 GPU 与 CPU 进行推理，降低延迟，提高吞吐！
⚙️ 接口调用，灵活多样：提供多种使用模型的接口，包括 OpenAI 兼容的 RESTful API（包括 Function Calling），RPC，命令行，web UI 等等。方便模型的管理与交互。
🌐 集群计算，分布协同: 支持分布式部署，通过内置的资源调度器，让不同大小的模型按需调度到不同机器，充分使用集群资源。
🔌 开放生态，无缝对接: 与流行的三方库无缝对接，包括 LangChain，LlamaIndex，Dify，以及 Chatbox。
为什么选择 Xinference
| 功能特点 | Xinference | FastChat | OpenLLM | RayLLM |
|---|---|---|---|---|
| 兼容 OpenAI 的 RESTful API | ✅ | ✅ | ✅ | ✅ |
| vLLM 集成 | ✅ | ✅ | ✅ | ✅ |
| 更多推理引擎（GGML、TensorRT） | ✅ | ❌ | ✅ | ✅ |
| 更多平台支持（CPU、Metal） | ✅ | ✅ | ❌ | ❌ |
| 分布式集群部署 | ✅ | ❌ | ❌ | ✅ |
| 图像模型（文生图） | ✅ | ✅ | ❌ | ❌ |
| 文本嵌入模型 | ✅ | ❌ | ❌ | ❌ |
| 多模态模型 | ✅ | ❌ | ❌ | ❌ |
| 语音识别模型 | ✅ | ❌ | ❌ | ❌ |
| 更多 OpenAI 功能 (函数调用) | ✅ | ❌ | ❌ | ❌ |
