Xinference-v1.17.1环境部署：Ubuntu/CentOS/Docker三平台安装与验证全流程

想试试最新的开源大模型，但被复杂的部署步骤劝退？每次换模型都要重新折腾一遍环境，是不是很头疼？

今天，我来带你搞定一个“万能”的AI模型部署工具——Xinference。它最大的魅力在于，你只需要改一行代码，就能把GPT换成任何你喜欢的开源大模型，无论是Llama、Qwen还是ChatGLM。而且，它能在你的云服务器、本地电脑，甚至笔记本上，通过一个统一的、像OpenAI一样好用的API来运行这些模型。

这篇文章，我会手把手带你完成Xinference-v1.17.1在Ubuntu、CentOS和Docker这三种最常见平台上的安装与验证。无论你是AI新手还是老手，都能跟着步骤，轻松搭建起属于自己的AI模型服务。

1. 认识Xinference：你的开源模型“万能插座”

在开始动手之前，我们先花几分钟了解一下Xinference到底是什么，以及它能帮你解决什么问题。

简单来说，Xinference就像一个为开源AI模型设计的“万能插座”和“统一遥控器”。以前，每个模型都有自己的部署方式、启动命令和调用接口，管理起来非常混乱。Xinference的出现，就是为了终结这种混乱。

1.1 它主要能帮你做什么？

• 一键部署模型：不管是什么模型，通常只需要一行命令就能启动服务，大大降低了使用门槛。
• 提供统一API：所有通过Xinference启动的模型，都对外提供和OpenAI兼容的RESTful API。这意味着，你为ChatGPT写的代码，几乎不用修改就能用来调用你自己的Llama或通义千问模型。
• 智能调度硬件：它能自动利用你机器上的GPU和CPU资源，用最高效的方式运行模型，特别是通过集成ggml库来优化性能。
• 集中化管理：提供了一个Web界面，让你可以方便地查看所有已启动的模型、它们的状态，并进行管理。

1.2 为什么选择Xinference-v1.17.1？

每个版本都会带来修复和改进。v1.17.1作为一个稳定的次版本更新，通常包含了重要的错误修复和性能优化，能确保我们安装的环境更加可靠。选择这个特定版本，是为了保证教程的准确性和可复现性。

好了，理论部分到此为止。接下来，我们进入正题，开始准备安装环境。

2. 安装前准备：打好基础

无论选择哪个平台，一些基础的准备工作是共通的。做好这些，能让后续的安装过程更加顺利。

2.1 系统更新与基础工具

首先，确保你的系统软件包列表是最新的，并安装一些必要的工具，比如用于下载文件的wget或curl，以及pip（Python的包管理工具）。

对于Ubuntu/Debian系统：

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3-pip python3-venv wget curl

对于CentOS/RHEL系统：

sudo yum update -y
sudo yum install -y python3-pip wget curl
# 如果系统默认Python3版本较低，可能需要先安装EPEL仓库或使用Software Collections
# sudo yum install -y centos-release-scl
# sudo yum install -y rh-python38-python-pip

2.2 创建独立的Python环境（强烈推荐）

这是一个好习惯，可以避免不同项目间的Python包版本冲突。我们使用venv来创建一个干净的虚拟环境。

# 创建一个名为‘xinference-env’的虚拟环境
python3 -m venv xinference-env

# 激活这个虚拟环境
# 在Linux/Mac上：
source xinference-env/bin/activate

激活后，你的命令行提示符前通常会显示(xinference-env)，表示你正在这个虚拟环境中操作。后续的所有pip install命令都应该在这个激活的环境中进行。

记住这个命令：以后每次打开新的终端窗口想使用Xinference，都需要先运行source xinference-env/bin/activate来激活环境。

准备工作完成，我们可以根据不同的平台，开始安装Xinference了。

3. 平台一：在Ubuntu上安装Xinference

Ubuntu是AI开发中最流行的Linux发行版之一，社区支持完善。我们通过pip直接安装。

3.1 使用pip安装

在已经激活的虚拟环境中，执行安装命令。我们指定安装1.17.1版本。

pip install "xinference[all]==1.17.1" -i https://pypi.tuna.tsinghua.edu.cn/simple

命令解释：

• xinference[all]：安装Xinference及其所有额外功能依赖（如WebUI等）。如果只想装核心功能，可以只装xinference。
• ==1.17.1：明确指定安装这个版本。
• -i https://pypi.tuna.tsinghua.edu.cn/simple：使用清华镜像源加速下载，国内网络环境必备。

安装过程会下载一堆依赖包，请耐心等待。

3.2 验证安装

安装完成后，最简单的验证方法是查看版本号。

xinference --version

如果安装成功，终端会输出类似 Xinference, version 1.17.1 的信息。

恭喜你，在Ubuntu上的安装已经成功！你可以直接跳到第5章查看如何启动和使用。

4. 平台二：在CentOS上安装Xinference

CentOS常见于服务器环境，其安装过程与Ubuntu类似，但可能需要额外注意Python版本和开发工具链。

4.1 解决可能的依赖问题

CentOS自带的Python3和pip版本可能较旧。如果安装过程中遇到编译错误（比如提示缺少Python.h），你可能需要安装Python开发工具包。

# 安装Python3开发包和编译器工具
sudo yum install -y python3-devel gcc gcc-c++ make

4.2 使用pip安装

同样在激活的虚拟环境中，执行安装命令。

pip install "xinference[all]==1.17.1" -i https://pypi.tuna.tsinghua.edu.cn/simple

4.3 验证安装

使用同样的命令验证：

xinference --version

看到版本号输出，即表示CentOS平台安装成功。

5. 平台三：使用Docker安装Xinference（最推荐）

如果你不想污染主机环境，或者希望部署过程能完全一致、可重复，那么Docker是最佳选择。Xinference官方提供了镜像，让部署变得异常简单。

5.1 安装Docker

如果你的系统还没有Docker，需要先安装它。

Ubuntu安装Docker：

sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker
# 将当前用户加入docker组，避免每次都用sudo（需要重新登录生效）
sudo usermod -aG docker $USER

CentOS安装Docker：

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

安装后，可以运行docker --version检查，并可能需要退出终端重新登录以使用户组生效。

5.2 拉取并运行Xinference镜像

使用Docker，我们无需关心Python环境或系统依赖，一切都在容器内。

# 拉取官方Xinference镜像
docker pull xprobe/xinference:latest

# 运行Xinference容器
docker run -d --name xinference -p 9997:9997 xprobe/xinference:latest

命令解释：

• -d：后台运行容器。
• --name xinference：给容器起个名字，方便管理。
• -p 9997:9997：将容器内部的9997端口映射到主机的9997端口。Xinference的Web界面和API默认就在这个端口。
• xprobe/xinference:latest：使用的镜像名。

5.3 验证Docker容器运行状态

容器运行后，我们可以通过几条命令来确认它工作正常。

# 查看容器是否在运行
docker ps | grep xinference

# 查看容器的日志，确认启动过程无报错
docker logs xinference

如果docker ps命令能看到名为xinference的容器，并且状态是Up，同时日志中没有明显的错误信息，那么Docker部署就成功了。

Docker方式的巨大优势：无论你的主机是Ubuntu、CentOS、Mac还是Windows，只要装了Docker，运行上面两条命令就能得到一个完全相同的Xinference环境。迁移和备份也变得极其简单。

6. 启动Xinference并验证服务

安装完成，是时候启动它，看看这个“万能插座”到底长什么样了。

6.1 启动Xinference服务

对于Ubuntu/CentOS的本地安装： 在激活的虚拟环境中，运行：

xinference-local

这个命令会启动一个本地服务。默认情况下，它会启动一个Web UI服务和一个后端推理服务。

对于Docker安装： 容器在docker run命令执行后就已经启动了服务，我们不需要额外操作。

6.2 访问Web管理界面

无论哪种安装方式，服务启动后，你都可以通过浏览器访问Xinference的Web管理界面。

打开你的浏览器，输入地址：

http://你的服务器IP地址:9997

如果是本地安装，可以直接访问 http://localhost:9997 或 http://127.0.0.1:9997。

你会看到一个清晰的管理界面。在这里，你可以：

• 查看内置模型：浏览Xinference官方预置支持的模型列表。
• 启动模型：点击模型，选择参数（如型号、大小），然后启动它。首次启动某个模型时会自动从网上下载。
• 管理已启动模型：查看所有正在运行的模型，它们的状态、地址，并可以停止它们。

6.3 核心验证：通过命令行与API交互

Web界面很直观，但作为开发者，我们更关心API是否可用。让我们用最直接的方式测试一下。

首先，我们需要在Web界面上启动一个模型。比如，找一个较小的文本模型（如Qwen2.5-Coder-1.5B-Instruct）启动。启动成功后，在“Running Models”列表里，你会看到这个模型的UID和一个Endpoint地址，例如 http://127.0.0.1:9997/v1/chat/completions。

打开你的终端，我们可以使用curl命令来模拟一个API调用：

curl http://127.0.0.1:9997/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder-1.5b-instruct", # 替换为你的模型UID
    "messages": [
      {"role": "user", "content": "用Python写一个快速排序函数"}
    ],
    "max_tokens": 200
  }'

如果一切正常，你会收到一个JSON格式的响应，其中choices[0].message.content字段里就包含了模型生成的代码。

这就是Xinference的核心价值：你调用它的方式，和调用OpenAI的GPT API几乎一模一样。这意味着，你现有的、基于OpenAI API的应用程序，只需要把API的base_url从 https://api.openai.com/v1 改成 http://你的Xinference地址:9997/v1，就能无缝切换到你自己部署的开源模型上。

7. 总结与下一步

跟着上面的步骤走一遍，你应该已经成功在至少一个平台上部署了Xinference-v1.17.1，并且验证了它的服务是正常的。

我们来回顾一下今天的重点：

1. 为什么用Xinference：它统一了开源模型的部署和调用接口，让你能像使用GPT一样使用Llama、Qwen等模型，实现了“一行代码切换模型”的梦想。
2. 三种部署方式：
   • Ubuntu/CentOS原生安装：适合深度定制和开发。
   • Docker安装：最推荐，简单、干净、一致，适合生产和快速体验。
3. 验证成功的关键：能通过Web界面(:9997)管理模型，并能通过兼容OpenAI的API（/v1/chat/completions）成功调用模型获得响应。

你的AI模型“万能插座”已经通电了，接下来可以：

• 探索更多模型：在Web界面里尝试启动不同种类、不同大小的文本、嵌入或多模态模型。
• 集成到应用：修改你现有AI应用的后端地址，指向你的Xinference服务，立即体验私有化部署的魅力。
• 学习进阶功能：研究如何配置模型缓存路径、如何启用GPU加速、如何搭建分布式集群等。

部署只是第一步，拥有一个随时待命、完全受控的AI模型服务，接下来的创意和实践空间，才是真正精彩的部分。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。