Xinference-v1.17.1新手必看：Ubuntu系统部署与API调用实战

Xinference-v1.17.1新手必看：Ubuntu系统部署与API调用实战

1. 引言：为什么选择Xinference？

如果你正在寻找一个简单又强大的工具，想在Ubuntu服务器上快速运行各种开源AI模型，那么Xinference-v1.17.1可能就是你要找的答案。它就像一个“万能插座”，让你能用一套统一的接口，轻松调用从文本生成到图像理解的各种模型，而不用为每个模型单独搭建一套复杂的环境。

想象一下，你只需要改一行代码，就能把原本调用GPT的接口，无缝切换到另一个开源大模型上。这种灵活性对于开发者来说太重要了，无论是做产品原型、内部工具，还是学术研究，都能大大节省时间和精力。今天，我就带你从零开始，在Ubuntu系统上把Xinference跑起来，并学会如何通过API来调用它。

2. 部署前准备：检查你的Ubuntu环境

在动手安装之前，我们先花几分钟确认一下你的系统环境是否就绪。这能避免很多后续的麻烦。

2.1 系统与硬件要求

Xinference-v1.17.1对Ubuntu的兼容性很好，从18.04到最新的22.04 LTS版本都能支持。我个人推荐使用Ubuntu 20.04或22.04 LTS，这两个版本社区支持最完善，遇到问题也最容易找到解决方案。

硬件方面主要看你的需求：

• 纯CPU运行：任何现代CPU都可以，只是运行大模型时会比较慢，适合小模型测试或学习。
• GPU加速（推荐）：如果你有NVIDIA显卡，体验会好很多。显存大小决定了你能运行多大的模型：
  • 8GB显存：可以流畅运行7B参数左右的模型（如Llama-2-7B, Qwen2-7B）。
  • 16GB以上显存：可以尝试13B或34B级别的更大模型。
  • 24GB+显存：能驾驭更多70B级别的顶尖开源模型。

2.2 基础环境配置

打开你的终端，我们先更新系统并安装一些必备的软件包。这就像盖房子前先打好地基。

# 1. 更新软件包列表和升级现有软件 sudo apt update sudo apt upgrade -y # 2. 安装Python环境、Git和常用工具 sudo apt install -y python3-pip python3-venv git curl wget

检查一下Python版本，确保是3.8或以上：

python3 --version

如果版本低于3.8，你需要单独安装新版本的Python。对于Ubuntu 20.04/22.04，系统自带的Python3通常已经满足要求。

3. 关键一步：为GPU安装驱动和CUDA（可选但推荐）

如果你打算使用GPU来加速模型推理，那么这一步至关重要。如果只用CPU，可以跳过这一节。

3.1 安装NVIDIA显卡驱动

首先，检查你的系统是否已经安装了正确的驱动：

nvidia-smi

如果这个命令能显示出你的显卡型号、驱动版本和显存使用情况，那恭喜你，驱动已经装好了。如果报错或没有输出，我们就需要安装它。

最简单的安装方法是使用Ubuntu自带的驱动管理工具：

# 自动检测并安装合适的驱动 sudo ubuntu-drivers autoinstall # 安装完成后，重启系统使驱动生效 sudo reboot

重启后，再次运行nvidia-smi确认驱动安装成功。你应该能看到类似下面的信息，其中Driver Version就是驱动版本号。

3.2 安装CUDA工具包

CUDA是NVIDIA提供的并行计算平台，很多AI框架（包括PyTorch）都需要它来调用GPU。Xinference配合的PyTorch通常需要CUDA 11.8或12.x。

这里以安装CUDA 12.2为例：

# 下载CUDA 12.2的安装包（文件较大，请耐心等待） wget https://developer.download.nvidia.com/compute/cuda/12.2.2/local_installers/cuda_12.2.2_535.104.05_linux.run # 运行安装程序 sudo sh cuda_12.2.2_535.104.05_linux.run

在安装界面中，你可能会看到很多选项。对于新手，我建议取消勾选驱动安装（Driver），因为我们已经用ubuntu-drivers装好了。只保留CUDA Toolkit的勾选，然后继续安装。

安装完成后，需要把CUDA的路径添加到系统环境变量，这样系统才能找到它：

# 将以下两行添加到 ~/.bashrc 文件的末尾 echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc # 让配置立即生效 source ~/.bashrc

最后，验证CUDA是否安装成功：

nvcc --version

如果命令输出了CUDA的版本信息（如release 12.2），那么一切就准备就绪了。

4. 安装与启动Xinference服务

基础环境搞定后，我们就可以开始安装Xinference本体了。

4.1 使用虚拟环境安装

强烈建议使用Python虚拟环境。这就像给你的Xinference项目一个独立的“房间”，里面的软件包不会和系统其他项目冲突，管理起来也干净。

# 1. 创建一个名为 xinference-env 的虚拟环境 python3 -m venv xinference-env # 2. 激活这个虚拟环境 source xinference-env/bin/activate

激活后，你的命令行提示符前面通常会显示(xinference-env)，表示你已经在这个虚拟环境里了。接下来所有pip安装的包，都会装在这个独立的环境里。

# 3. 安装Xinference pip install xinference

如果你打算使用GPU，还需要安装对应版本的PyTorch。Xinference通常基于PyTorch构建：

# 安装支持CUDA 11.8的PyTorch pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

安装完成后，验证一下：

xinference --version

如果看到输出版本号是1.17.1，说明安装成功。

4.2 启动推理服务

Xinference的核心是一个本地的推理服务。启动它非常简单：

xinference-local --host 0.0.0.0 --port 9997

• --host 0.0.0.0表示服务监听所有网络接口，这样同一局域网内的其他机器也能访问。如果只想本机访问，可以改成127.0.0.1。
• --port 9997指定服务端口，你可以改成任何未被占用的端口。

启动后，终端会输出日志信息。此时，打开你的浏览器，访问http://你的服务器IP地址:9997。如果一切正常，你会看到Xinference的Web管理界面。这个界面很直观，你可以在这里查看、启动、停止模型。

为了让服务在后台持续运行（关闭终端也不退出），可以这样启动：

nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1 &

这会把日志输出到xinference.log文件。查看日志可以用tail -f xinference.log。

对于生产环境，我建议配置成系统服务，这样服务器重启后也能自动启动。以systemd为例：

sudo nano /etc/systemd/system/xinference.service

将以下内容粘贴进去，注意替换你的用户名和你的家目录路径：

[Unit] Description=Xinference AI Inference Service After=network.target [Service] Type=simple User=你的用户名 WorkingDirectory=/home/你的用户名 Environment=PATH=/home/你的用户名/xinference-env/bin ExecStart=/home/你的用户名/xinference-env/bin/xinference-local --host 0.0.0.0 --port 9997 Restart=always RestartSec=5 [Install] WantedBy=multi-user.target

保存退出后，启用并启动服务：

sudo systemctl daemon-reload sudo systemctl enable xinference.service sudo systemctl start xinference.service

你可以用sudo systemctl status xinference.service来检查服务状态。

5. 实战：部署模型与API调用

服务跑起来了，现在我们来玩点真的：部署一个模型，然后用代码调用它。

5.1 部署你的第一个模型

在Web界面点击“Launch Model”，或者在终端使用命令，都可以部署模型。我们以部署一个流行的中文模型Qwen2-7B-Instruct为例。

在终端（确保虚拟环境已激活）执行：

xinference launch --model-name Qwen2-7B-Instruct --model-type LLM

第一次运行会从网络下载模型文件，需要一些时间，请保持网络通畅。下载完成后，模型会自动加载到内存（或显存）中。在Web界面的“Running Models”标签页，你应该能看到这个模型的状态变为“Ready”。

5.2 通过Python客户端调用API

这是最常用的方式，和调用OpenAI的API非常相似。创建一个Python脚本，比如test_xinference.py：

# test_xinference.py from xinference.client import Client # 1. 连接到本地的Xinference服务 client = Client("http://localhost:9997") # 2. 获取我们刚刚启动的模型 # 注意：这里的模型ID（uid）可以在Web界面或启动命令的输出中找到 # 一个简单的方法是列出所有运行中的模型 model_uid = client.list_models()[0] # 获取第一个运行模型的UID model = client.get_model(model_uid) # 3. 开始对话！ response = model.chat( messages=[ {"role": "system", "content": "你是一个乐于助人的助手。"}, {"role": "user", "content": "用简单的语言解释一下什么是人工智能？"} ], generate_config={ "max_tokens": 512, # 生成的最大token数 "stream": False # 是否流式输出，False表示一次性返回 } ) # 4. 打印模型的回复 print("模型回复：") print(response["choices"][0]["message"]["content"])

运行这个脚本，你就能看到模型的回答了。xinference.client的接口设计得很友好，如果你之前用过OpenAI的Python库，会感觉非常熟悉。

5.3 通过HTTP API调用（通用方法）

任何能发送HTTP请求的语言或工具都可以调用Xinference，因为它提供了OpenAI兼容的API。这意味着，你之前为ChatGPT写的代码，几乎可以不加修改地用来调用Xinference托管的开源模型。

用最经典的curl命令来试试：

curl -X POST http://localhost:9997/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2-7b-instruct", # 模型名称，注意这里是小写 "messages": [ {"role": "user", "content": "你好，请介绍一下你自己。"} ], "max_tokens": 100, "temperature": 0.7 }'

你会收到一个JSON格式的响应，结构化和OpenAI API返回的一模一样。这意味着你可以轻松地将现有的、基于OpenAI API的应用，迁移到使用开源模型的Xinference服务上，只需要改一下API的地址和模型名。

5.4 更多玩法：函数调用与集成

Xinference-v1.17.1还支持更高级的**函数调用（Function Calling）**功能。这允许模型在对话中决定调用你预先定义好的工具函数，非常适合构建智能助手或自动化流程。

此外，它还能和LangChain、LlamaIndex等流行的AI应用框架无缝集成。例如，在LangChain中，你可以这样使用：

from langchain.llms import Xinference llm = Xinference( server_url="http://localhost:9997", model_uid="你的模型UID" ) response = llm.invoke("LangChain你好！") print(response)

6. 常见问题与解决思路

新手在部署时可能会遇到几个典型问题，这里给你一些排查思路：

1. 模型下载慢或失败：

   • 原因：默认从Hugging Face下载，国内网络可能不稳定。
   • 解决：设置环境变量，使用国内镜像源（如ModelScope）。

   export XINFERENCE_MODEL_SRC=modelscope

   • 然后重新执行xinference launch命令。

2. GPU显存不足（CUDA out of memory）：

   • 原因：模型太大，显存放不下。
   • 解决：
     • 换一个更小的模型（如从7B换到3B）。
     • 在启动模型时，通过--gpu-memory-utilization 0.8参数限制显存使用比例。
     • 如果显卡支持，可以开启--enable-cpu-offload，将部分层卸载到CPU内存。

3. 端口被占用：

   • 解决：换一个端口启动服务，例如--port 9999。

4. 服务启动后无法访问Web界面：

   • 检查：确认防火墙是否放行了对应端口（如9997）。在Ubuntu上可以运行：

   sudo ufw allow 9997

5. Python依赖冲突：

   • 解决：这是使用虚拟环境的主要原因。如果还有冲突，尝试重新创建一个干净的虚拟环境，并严格按照顺序安装（先PyTorch，后Xinference）。

7. 总结

走完这一趟，你会发现，在Ubuntu上部署和调用Xinference并没有想象中那么复杂。它把繁琐的模型服务化工作打包成了一个简单的命令和一套统一的API。你不再需要为每一个想尝试的模型去折腾不同的环境、不同的部署脚本。

核心收获：

• 环境隔离是关键：使用Python虚拟环境，能让你的项目干干净净。
• GPU加速是体验保障：如果有条件，务必配置好CUDA，推理速度的提升是数量级的。
• 服务化思维：xinference-local启动的是一个常驻服务，你的应用通过HTTP API与之通信，这是现代AI应用的标准做法。
• OpenAI兼容性是王牌：这套API标准几乎成了业界的通用语言，让你的代码具备极强的可移植性。

从今天起，你可以把Xinference当作你本地或内网的“私有化AI模型底座”。无论是想快速验证一个想法，还是为你的应用集成AI能力，它都是一个高效、灵活且成本可控的起点。动手试试吧，从部署第一个7B模型开始，感受开源AI模型的魅力。

获取更多AI镜像

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