Xinference-v1.17.1保姆级教程：云/本地一键部署多模态大模型（含Jupyter+SSH双路径）

你是不是也想在自己的电脑或者云服务器上，轻松运行各种开源大模型，比如能对话的LLaMA、能画图的Stable Diffusion，或者能听会说的语音模型？但一想到复杂的安装步骤、环境配置、模型下载就头疼？

今天，我来带你彻底解决这个问题。我们将一起动手，通过一个名为 Xinference（Xorbits Inference） 的神奇工具，实现从零开始的一键部署。无论你是想在本地笔记本上快速体验，还是在云端服务器上搭建一个稳定的AI服务，甚至是需要通过SSH远程管理，这篇教程都会给你讲得明明白白。

Xinference就像一个“AI模型万能管家”，它把那些繁琐的部署工作都打包好了，你只需要几条简单的命令，就能让各种顶尖的开源模型跑起来，并且提供一个统一的、类似OpenAI的API接口供你调用。这意味着，你之前为GPT写的代码，几乎不用改，就能换成其他任何你喜欢的模型。

下面，我们就开始这场轻松的部署之旅。

1. 认识你的新工具：Xinference是什么？

在开始动手之前，我们先花几分钟了解一下Xinference到底是什么，它能帮你做什么，这样后面的操作你会更有方向感。

简单来说，Xinference是一个开源的一站式大模型推理服务平台。它的核心目标是让开发者和个人用户能够像使用云服务一样，轻松地在自己的环境（本地、私有云、公有云）中部署和运行各种AI模型。

1.1 为什么选择Xinference？

你可能听说过很多类似的工具，但Xinference有几个特别吸引人的地方：

• 开箱即用：无需从零开始配置CUDA、下载巨大的模型文件、处理复杂的依赖关系。一条命令，环境、模型、服务全搞定。
• 模型超市：内置了一个丰富的模型库，涵盖了文本生成（如Llama、Qwen）、文本嵌入、图像生成、语音识别等多个类别。你只需要指定一个模型名字，它就能自动帮你下载和加载。
• 统一API：所有模型，不管它是干什么的，都通过一套与OpenAI兼容的RESTful API提供服务。这意味着你学会一种调用方式，就能玩转所有模型，迁移成本极低。
• 部署灵活：支持从单机本地部署到多机分布式部署，能充分利用你手头的硬件资源（无论是GPU还是CPU）。

1.2 它能运行哪些模型？

Xinference的“多模态”能力非常强大，主要支持以下几类模型：

• 大语言模型：对话、写作、代码生成等。例如：llama-3.2-3b-instruct, qwen2.5-7b-instruct, deepseek-coder等。
• 嵌入模型：将文本转换为向量，用于检索、聚类等。例如：bge-m3, nomic-embed-text-v1。
• 图像生成模型：文生图、图生图。例如：stable-diffusion-xl。
• 语音识别模型：将音频转换为文字。

了解了这些，你是不是已经跃跃欲试了？接下来，我们就进入实战环节。我将为你提供两种最常用的部署路径：通过Jupyter Notebook可视化操作 和 通过SSH命令行高效部署，你可以根据自己的情况任选其一。

2. 部署准备：选择你的战场

在开始安装前，我们需要确保环境基本就绪。Xinference支持多种系统，但为了获得最佳体验，我推荐使用Linux系统（如Ubuntu）或macOS。Windows用户可以通过WSL2获得类似体验。

基础要求：

• Python 3.8 或更高版本。
• pip（Python包管理器）已安装。
• （可选但推荐）如果你打算使用GPU加速，请确保已安装对应版本的NVIDIA驱动和CUDA工具包。CPU也能运行，只是速度会慢一些。

好了，准备工作完成。现在，请选择你的部署方式：

• 如果你是初学者，喜欢图形化界面，或者想在网页里点点鼠标就完成一切，请跳转到 第3章：Jupyter Notebook可视化部署。
• 如果你习惯命令行操作，需要在远程服务器（通过SSH连接）上部署，或者追求极致的效率和可控性，请跳转到 第4章：SSH命令行高效部署。

3. Jupyter Notebook可视化部署（适合新手）

这种方式非常直观，就像在网页上使用一个软件一样。我们会在Jupyter Lab环境中安装和启动Xinference。

3.1 启动Jupyter Lab环境

首先，你需要一个正在运行的Jupyter Lab。如果你还没有，可以通过以下命令快速安装和启动：

# 安装jupyterlab
pip install jupyterlab

# 启动jupyterlab，它会自动在浏览器中打开
jupyter lab

启动后，你的浏览器会显示Jupyter Lab的界面。

3.2 在Jupyter中安装Xinference

在Jupyter Lab中，新建一个Notebook（或者直接使用终端），执行以下安装命令：

# 使用pip安装xinference
!pip install "xinference[all]"

这里的 [all] 表示安装所有功能依赖，包括GPU支持。如果只需要基础功能，可以只安装 xinference。

安装过程可能需要几分钟，取决于你的网络速度。

3.3 启动Xinference服务

安装完成后，在Notebook的一个新的代码单元格中，输入并运行以下命令来启动Xinference服务：

# 导入xinference并启动服务
from xinference.client import Client

# 创建一个本地客户端，这会在后台启动Xinference服务
client = Client()

运行这行代码后，Xinference服务就在后台启动了。它会自动初始化并准备好接收你的指令。

3.4 验证安装与启动Web UI

如何确认服务启动成功了呢？Xinference提供了一个非常友好的Web用户界面。

1. 在启动 client = Client() 的代码输出中，或者在你启动Jupyter Lab的终端里，寻找类似这样的日志信息：

   INFO:     Started server process [12345]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:9997 (Press CTRL+C to quit)
   

   这告诉你服务正在运行，并且Web UI的地址是 http://<你的服务器IP>:9997。如果是本地，就是 http://localhost:9997。

2. 打开你的浏览器，访问 http://localhost:9997。你会看到Xinference的管理界面。

恭喜你！至此，通过Jupyter Notebook的部署已经完成。你可以在这个Web UI里查看可用的模型、启动模型、监控资源使用情况，甚至有一个简单的聊天界面供你直接测试模型。

4. SSH命令行高效部署（适合远程服务器）

如果你管理的是远程的Linux服务器，SSH命令行是最直接、最标准的方式。这种方式同样适用于本地终端。

4.1 通过SSH连接服务器

打开你的终端（Windows用户可使用PowerShell、CMD或WSL终端），使用SSH命令连接到你的目标服务器。

ssh username@your_server_ip

输入密码后，你就进入了服务器的命令行环境。

4.2 安装Xinference

在服务器的命令行中，执行安装命令。强烈建议使用Python虚拟环境来避免依赖冲突。

# 1. 创建并激活一个虚拟环境（可选但推荐）
python -m venv xinference_env
source xinference_env/bin/activate  # Linux/macOS
# 如果是Windows，使用 `xinference_env\Scripts\activate`

# 2. 升级pip
pip install --upgrade pip

# 3. 安装xinference（全功能版）
pip install "xinference[all]"

4.3 启动Xinference服务

安装完成后，使用一个简单的命令即可启动服务：

# 启动xinference服务，并指定Web UI的端口（例如9997）
xinference launch --host 0.0.0.0 --port 9997

参数解释：

• --host 0.0.0.0：允许任何IP地址访问此服务（对于远程服务器很重要）。
• --port 9997：指定服务运行的端口，你可以改成其他未被占用的端口。

执行后，终端会显示启动日志，最后一行会告诉你服务已运行在 http://0.0.0.0:9997。

4.4 验证安装是否成功

保持服务运行的同时，你可以打开另一个SSH终端窗口，或者使用 Ctrl+Z 然后 bg 让服务在后台运行，然后执行：

# 检查xinference的版本，确认安装成功
xinference --version

如果成功安装，你会看到类似 xinference, version 1.17.1 的输出信息。

4.5 访问与管理

现在，你可以在你的本地电脑的浏览器中，访问 http://<你的服务器公网IP>:9997，就能看到和Jupyter方式一样的Xinference Web管理界面了。

重要安全提示： 将服务暴露在公网（0.0.0.0）存在风险。在生产环境中，务必配置防火墙（如只允许特定IP访问9997端口），或结合Nginx设置反向代理和HTTPS。

5. 核心玩法：启动你的第一个模型并调用API

服务跑起来了，界面也看到了，接下来就是最激动人心的部分：启动一个模型并用起来。我们以启动一个流行的中文大语言模型 qwen2.5-7b-instruct 为例。

5.1 通过Web UI启动模型（最简单）

1. 在Xinference的Web UI（localhost:9997）中，点击侧边栏或主界的 “Models”。
2. 在模型列表里找到 qwen2.5-7b-instruct，点击它旁边的 “Launch” 按钮。
3. 在弹出的配置窗口中，你可以选择运行设备（如GPU）、量化精度等。对于初次尝试，保持默认即可，点击 “Launch”。
4. 稍等片刻，模型状态会变为 “Ready”。现在这个模型就在你的服务器上运行起来了！

5.2 通过命令行启动模型（更灵活）

如果你更喜欢命令行，或者在脚本中自动化部署，可以这样做：

# 在启动xinference服务的终端或另一个终端中执行
# 假设服务地址是 http://localhost:9997
xinference launch-model --model-name qwen2.5-7b-instruct --model-format pytorch --size-in-billions 7 --replica 1

5.3 像调用OpenAI一样调用它

模型启动后，你会获得一个唯一的 model_uid（如 qwen2.5-7b-instruct-xxxx）。现在，你可以用和ChatGPT API几乎一模一样的方式来调用它。

使用Python客户端：

from xinference.client import Client

# 连接到本地运行的Xinference服务
client = Client("http://localhost:9997")

# 列出所有已运行的模型，找到你的model_uid
models = client.list_models()
print(models)

# 获取模型对象
model = client.get_model("qwen2.5-7b-instruct-xxxx") # 替换为你的model_uid

# 开始对话！
response = model.chat(
    prompt="请用Python写一个快速排序函数",
    generate_config={"max_tokens": 512}
)
print(response["choices"][0]["message"]["content"])

使用OpenAI兼容的API（最强大的功能）：

Xinference提供了与OpenAI完全兼容的API端点。这意味着，你之前为GPT-4写的代码，只需要改一下 base_url 和 api_key（Xinference默认无需key，或可任意设置），就能无缝切换！

from openai import OpenAI

# 注意：这里导入的是官方的openai库
client = OpenAI(
    api_key="任意字符串或留空", # Xinference不强制验证key
    base_url="http://localhost:9997/v1" # 指向你的Xinference服务
)

# 创建聊天补全，和调用OpenAI API一模一样！
completion = client.chat.completions.create(
    model="qwen2.5-7b-instruct-xxxx", # 替换为你的model_uid
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己。"}
    ],
    max_tokens=256
)

print(completion.choices[0].message.content)

看到没？除了 base_url 和 model 名字，其他代码和调用官方的OpenAI API没有任何区别。这就是“通过更改一行代码将GPT替换为任何LLM”的真正含义。

6. 总结

跟着这篇教程走下来，你应该已经成功在本地或云端部署了Xinference，并且已经让第一个大模型跑了起来，还学会了如何用熟悉的OpenAI API方式去调用它。我们来回顾一下今天的收获：

1. 理解了Xinference的价值：它是一个强大的开源模型服务化工具，让你能免去繁琐的部署细节，一键运行各种多模态大模型。
2. 掌握了两种部署方式：
   • Jupyter Notebook路径：适合新手和快速原型验证，在可视化环境中轻松完成安装和启动。
   • SSH命令行路径：适合专业开发和生产环境，通过几条命令即可在远程服务器上搭建稳定的AI服务。
3. 学会了核心操作：通过Web UI或命令行启动模型，并掌握了两种调用方式——使用Xinference原生客户端或更通用的OpenAI兼容API。

Xinference的魅力在于它的 “统一” 和 “简化”。它把复杂的模型部署变成了一个简单的服务管理问题，极大地降低了个人开发者和中小企业使用前沿AI模型的门槛。

你的AI模型私有化部署之旅，就从这里正式开始了。接下来，你可以去探索模型库里的其他宝藏，比如图像生成模型 stable-diffusion-xl，或者尝试部署多个模型并利用它的分布式特性。最重要的是，开始用这个本地的“GPT”去构建你的应用吧！

---

获取更多AI镜像

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