零基础实战！Xinference-v1.17.1安装教程：包含Python代码调用示例

你是不是也遇到过这样的困惑：看到别人用开源大模型做各种有趣的项目，自己也想试试，结果第一步安装就卡住了？网上教程要么太复杂，要么版本过时，要么就是一堆看不懂的命令行，让人望而却步。

别担心，这篇教程就是为你准备的。我们不谈复杂的原理，不讲晦涩的术语，只做一件事：让你在30分钟内，从零开始，稳稳当当地把Xinference-v1.17.1安装好、启动起来，并且能用Python代码调用它。

无论你是刚接触AI的新手，还是有一定经验但被环境配置困扰的开发者，只要跟着步骤一步步来，你就能在自己的电脑上拥有一个功能强大的本地大模型推理平台。

1. 准备工作：安装前的三件小事

在开始安装之前，花几分钟做好这三件事，能避免90%的常见问题。

1.1 检查Python版本

Xinference-v1.17.1需要Python 3.9或更高版本。版本太低会报错，版本太高（比如3.13）可能有些依赖还没适配好。

打开你的终端（Windows用户可以用PowerShell或者WSL2），输入：

python --version
# 或者
python3 --version

如果显示的是Python 3.9.x、Python 3.10.x、Python 3.11.x，那么恭喜你，可以直接进入下一步。

如果显示的是Python 3.8.x或更低，你需要先升级Python。推荐使用pyenv来管理多个Python版本，或者直接从Python官网下载安装包。

如果显示的是Python 3.13.x，建议暂时切换到3.11版本，因为这是Xinference官方测试最稳定的版本。

小提示：如果你不确定自己用的是哪个Python，可以运行which python（Linux/macOS）或where python（Windows）查看具体路径。尽量使用python3而不是系统自带的旧版本。

1.2 清理旧版本（非常重要！）

如果你之前安装过Xinference的任何版本，哪怕是尝试性的安装，都建议先彻底清理干净。旧版本的缓存和配置文件可能会和新版本冲突，导致各种奇怪的问题。

执行下面的命令来卸载旧版本并清理缓存：

pip uninstall xinference -y
pip cache purge

如果你之前运行过Xinference服务，还需要检查是否有残留的后台进程：

# Linux/macOS
ps aux | grep xinference
# 如果看到相关进程，记下PID，然后：
kill -9 <PID>

# Windows PowerShell（管理员权限）
Get-Process | Where-Object {$_.ProcessName -like "*xinference*"} | Stop-Process -Force

1.3 确认你的硬件配置

Xinference支持多种硬件配置，你需要根据自己的设备选择合适的安装方式：

设备类型	推荐安装命令	说明
有NVIDIA显卡（RTX 30/40系列，显存≥6GB）	pip install "xinference[all]"	自动安装GPU加速版本，性能最好
只有CPU（老电脑、无显卡笔记本）	pip install "xinference[cpu]"	纯CPU推理，速度稍慢但兼容性好
Mac M1/M2/M3芯片	pip install "xinference[metal]"	使用Apple Metal加速，性能接近中端GPU

本教程默认按照有NVIDIA显卡的情况来写，因为这是最常见的配置。如果你是CPU或Mac用户，只需要把后续命令中的xinference[all]换成对应的选项即可，其他步骤完全一样。

2. 创建虚拟环境并安装Xinference

强烈建议使用虚拟环境来安装Xinference，这样可以避免污染你的系统Python环境，也方便后续管理。

2.1 创建并激活虚拟环境

# Linux/macOS
python3 -m venv xinference_env
source xinference_env/bin/activate

# Windows
python -m venv xinference_env
.\xinference_env\Scripts\Activate.ps1

激活成功后，你的命令行提示符前面会显示(xinference_env)，表示你现在在这个虚拟环境中。

2.2 安装Xinference-v1.17.1

现在执行安装命令。为了加快下载速度，我们使用国内的镜像源：

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

这个命令会安装Xinference-v1.17.1及其所有依赖，包括：

• WebUI界面
• 命令行工具
• OpenAI兼容的API
• 各种模型后端（llama.cpp、vLLM、transformers等）

安装过程可能需要3-10分钟，具体时间取决于你的网络速度和电脑性能。耐心等待，直到看到类似下面的输出：

Successfully installed xinference-1.17.1 ...

3. 验证安装是否成功

安装完成后，不要急着启动服务。我们先做几个简单的检查，确保一切正常。

3.1 检查版本号

在虚拟环境中运行：

xinference --version

你应该能看到：

xinference 1.17.1

如果显示command not found，说明虚拟环境没有激活成功，或者安装失败了。请回到上一步重新激活虚拟环境。

3.2 启动最小化服务测试

运行下面的命令启动一个最简单的服务，不加载任何模型，只验证服务能否正常启动：

xinference start --host 127.0.0.1 --port 9997 --log-level warning

参数说明：

• --host 127.0.0.1：只允许本机访问，更安全
• --port 9997：指定端口号，避免和常用端口冲突
• --log-level warning：只显示警告和错误信息，减少日志输出

几秒钟后，你应该能看到类似这样的输出：

INFO     Starting Xinference server...
INFO     Server is running at http://127.0.0.1:9997
INFO     OpenAI compatible API endpoint: http://127.0.0.1:9997/v1

这说明服务已经成功启动了。保持这个终端窗口打开，或者按Ctrl+Z挂起它。

3.3 测试API连通性

新开一个终端窗口（或者按Ctrl+C停止上一步的服务，然后重新运行测试命令），执行：

curl http://127.0.0.1:9997/health

如果一切正常，你会看到：

{"status":"ok"}

这个/health接口是Xinference的健康检查接口，以后排查问题时经常会用到它。

4. 启动WebUI并加载第一个模型

现在我们已经确认Xinference可以正常运行了，接下来启动带图形界面的完整服务。

4.1 启动带WebUI的服务

先停止之前启动的服务（如果还在运行的话），然后执行：

xinference start --host 0.0.0.0 --port 9997 --ui

参数说明：

• --ui：启用WebUI界面
• --host 0.0.0.0：允许局域网内的其他设备访问（比如用手机或平板访问），如果只在本地使用，可以继续用127.0.0.1

启动成功后，日志的最后会多出一行：

INFO     Web UI is running at http://127.0.0.1:9997

4.2 访问WebUI

打开你的浏览器（Chrome、Firefox、Safari都可以），访问： http://127.0.0.1:9997

你会看到Xinference的蓝色主界面，左侧是导航栏，顶部是模型管理区域。第一次打开时，页面会显示"No models are registered yet."（还没有注册任何模型），这是正常的，因为我们还没有下载任何模型。

4.3 下载并启动第一个模型

我们从一个轻量级的模型开始，这样下载快，启动也快，适合新手体验。

在WebUI页面，点击左侧的"Models"，然后点击"Launch Model"。

在弹出的表单中，按照下面的配置填写：

字段	填写内容	说明
Model Name	qwen2	选择Qwen2系列，这是阿里开源的模型，中文支持好，体积小
Model Size	0.5B	选择0.5B版本，这是最小的版本，CPU和GPU都能快速启动
Quantization	q4_k_m	4位量化，在速度和精度之间取得平衡，显存占用小于1.2GB
GPU Devices	0	如果你有GPU，填0表示使用第一块显卡；CPU用户留空或填-1

填写完成后，点击右下角的"Launch"按钮。

后台会自动完成以下操作：

1. 从Hugging Face下载模型文件（约300MB，第一次下载可能需要几分钟）
2. 将模型加载到内存或显存中
3. 注册为可用的模型

等待进度条走完，然后刷新页面，点击"Models" -> "List Models"，你应该能看到：

qwen2-chat-q4_k_m | RUNNING | 0.5B | llama.cpp

恭喜！你的第一个本地大模型已经准备就绪了。

5. 两种方式调用模型：Web聊天和Python代码

现在模型已经运行起来了，你可以选择自己喜欢的方式来和它对话。

5.1 方式一：使用Web聊天界面（最简单直观）

在WebUI页面，点击顶部导航栏的"Chat"。

1. 在左上角的下拉框中，选择我们刚刚启动的模型：qwen2-chat-q4_k_m
2. 在输入框中输入："你好，请介绍一下你自己"
3. 点击发送按钮（或者按Ctrl+Enter）

几秒钟后，右侧就会显示模型的回复，比如：

"我是通义千问Qwen2，由通义实验室研发的超大规模语言模型……"

你刚刚完成了一个完整的本地大模型部署和调用流程，所有的数据都在你自己的设备上，不需要连接任何外部API。

5.2 方式二：使用Python代码调用（为开发做准备）

如果你想把Xinference集成到自己的项目中，或者想要更灵活地控制模型的调用，那么Python代码调用是更好的选择。

创建一个新的Python文件，比如叫做test_xinference.py，然后写入以下代码：

from xinference.client import Client

# 第一步：连接到本地Xinference服务
client = Client("http://127.0.0.1:9997")

# 第二步：获取当前可用的模型列表
models = client.list_models()
print("当前可用的模型：")
for model_id, model_info in models.items():
    print(f"- {model_id}: {model_info['model_name']}")

# 第三步：获取第一个模型的实例（通常就是我们刚刚启动的qwen2）
model_uid = list(models.keys())[0]
chat_model = client.get_model(model_uid)

# 第四步：发送消息并获取回复
response = chat_model.chat(
    messages=[
        {
            "role": "user",
            "content": "用Python写一个简单的Hello World程序"
        }
    ],
    generate_config={
        "max_tokens": 200,  # 最大生成token数
        "temperature": 0.7,  # 温度参数，控制随机性
        "stream": False  # 是否流式输出
    }
)

# 第五步：打印模型的回复
print("\n模型回复：")
print(response["choices"][0]["message"]["content"])

保存文件后，在终端中运行：

python test_xinference.py

你会看到控制台输出模型的回复，比如一个完整的Python Hello World程序。

代码说明：

• Client("http://127.0.0.1:9997")：这是连接Xinference服务的核心，所有操作都通过这个客户端进行
• chat_model.chat(...)：这个接口和OpenAI的ChatCompletion接口完全兼容，这意味着你现有的基于OpenAI的代码几乎不需要修改就能运行

6. 更实用的Python调用示例

上面的例子展示了最基本的调用方式，但在实际开发中，我们可能需要更复杂的交互。下面看几个更实用的例子。

6.1 多轮对话示例

大模型的一个重要特性就是能记住上下文，进行多轮对话。下面是一个多轮对话的示例：

from xinference.client import Client

client = Client("http://127.0.0.1:9997")

# 获取模型
models = client.list_models()
model_uid = list(models.keys())[0]
chat_model = client.get_model(model_uid)

# 第一轮对话
print("=== 第一轮对话 ===")
response1 = chat_model.chat(
    messages=[
        {"role": "user", "content": "Python中的列表和元组有什么区别？"}
    ],
    generate_config={"max_tokens": 150}
)
answer1 = response1["choices"][0]["message"]["content"]
print(f"用户：Python中的列表和元组有什么区别？")
print(f"AI：{answer1}")

# 第二轮对话（基于第一轮的上下文）
print("\n=== 第二轮对话 ===")
response2 = chat_model.chat(
    messages=[
        {"role": "user", "content": "Python中的列表和元组有什么区别？"},
        {"role": "assistant", "content": answer1},
        {"role": "user", "content": "那在什么情况下应该使用元组而不是列表呢？"}
    ],
    generate_config={"max_tokens": 150}
)
answer2 = response2["choices"][0]["message"]["content"]
print(f"用户：那在什么情况下应该使用元组而不是列表呢？")
print(f"AI：{answer2}")

6.2 流式输出示例

对于生成长文本的场景，流式输出可以提供更好的用户体验，让用户看到生成过程而不是等待全部生成完成：

from xinference.client import Client

client = Client("http://127.0.0.1:9997")

models = client.list_models()
model_uid = list(models.keys())[0]
chat_model = client.get_model(model_uid)

print("正在生成故事...（流式输出）")
print("-" * 50)

# 使用流式输出
response_stream = chat_model.chat(
    messages=[
        {"role": "user", "content": "写一个关于人工智能的短篇科幻故事，大约200字"}
    ],
    generate_config={
        "max_tokens": 300,
        "temperature": 0.8,
        "stream": True  # 启用流式输出
    }
)

# 逐块打印输出
full_response = ""
for chunk in response_stream:
    if "choices" in chunk:
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            content = delta["content"]
            print(content, end="", flush=True)
            full_response += content

print("\n" + "-" * 50)
print("故事生成完成！")

6.3 批量处理示例

如果你需要处理多个问题，可以使用批量处理来提高效率：

from xinference.client import Client
import time

client = Client("http://127.0.0.1:9997")

models = client.list_models()
model_uid = list(models.keys())[0]
chat_model = client.get_model(model_uid)

# 定义要处理的多个问题
questions = [
    "解释一下什么是机器学习",
    "Python中的装饰器是什么？",
    "如何学习编程？给一些建议",
    "人工智能的未来发展方向是什么？"
]

print("开始批量处理问题...")
start_time = time.time()

results = []
for i, question in enumerate(questions, 1):
    print(f"\n处理第{i}个问题：{question}")
    
    response = chat_model.chat(
        messages=[{"role": "user", "content": question}],
        generate_config={"max_tokens": 100}
    )
    
    answer = response["choices"][0]["message"]["content"]
    results.append({"question": question, "answer": answer[:50] + "..."})  # 只显示前50字符
    
    print(f"回答：{answer[:50]}...")

end_time = time.time()
print(f"\n批量处理完成！总共处理了{len(questions)}个问题，耗时{end_time - start_time:.2f}秒")

# 显示处理结果摘要
print("\n=== 处理结果摘要 ===")
for result in results:
    print(f"问题：{result['question']}")
    print(f"回答：{result['answer']}")
    print("-" * 50)

7. 常见问题与解决方案

在安装和使用过程中，你可能会遇到一些问题。这里列出了一些常见问题及其解决方法。

7.1 CUDA相关错误

如果你看到类似这样的错误：

OSError: CUDA error: no kernel image is available for execution on the device

这通常是因为CUDA版本和你的显卡驱动不匹配，常见于RTX 4090/4080等新显卡。解决方法：

# 先卸载现有的llama-cpp-python
pip uninstall llama-cpp-python -y

# 安装CUDA 12.1版本的llama-cpp-python
pip install llama-cpp-python --no-deps --force-reinstall --upgrade --index-url https://jllllll.github.io/llama-cpp-python-cu121

7.2 WebUI打不开或显示空白

如果访问http://127.0.0.1:9997时显示空白页面或404错误，可以尝试重建前端：

xinference start --host 127.0.0.1 --port 9997 --ui --rebuild-ui

7.3 导入错误

如果启动时遇到类似下面的错误：

ImportError: cannot import name 'xxx' from 'pydantic'

这是因为pydantic版本冲突。Xinference需要pydantic 2.x版本，但你的环境中可能有1.x版本。解决方法：

pip install "pydantic>=2.0" --force-reinstall

7.4 模型下载失败

如果你在国内，下载Hugging Face上的模型可能会很慢甚至失败。可以设置镜像源：

# Linux/macOS
export HF_ENDPOINT=https://hf-mirror.com

# Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"

# 然后重新启动模型
xinference launch --model-name qwen2 --size 0.5B --quantization q4_k_m

8. 进阶使用建议

现在你已经掌握了Xinference的基本用法，下面是一些进阶建议，帮助你更好地利用这个工具。

8.1 尝试更大的模型

0.5B的模型虽然轻量，但能力有限。你可以尝试更大的模型来获得更好的效果：

在WebUI的"Launch Model"页面，尝试以下配置：

• Model Name: qwen2
• Model Size: 7B
• Quantization: q5_k_m
• GPU Devices: 0（如果有GPU）

7B模型需要约2.1GB的存储空间，下载和加载时间会更长，但生成的质量会明显提升。

8.2 设置开机自启动

如果你经常使用Xinference，可以设置开机自启动，这样就不用每次手动启动了。

对于Linux/macOS，创建一个启动脚本：

#!/bin/bash
# 保存为 start_xinference.sh
nohup xinference start --host 0.0.0.0 --port 9997 --ui --log-level warning > /tmp/xinference.log 2>&1 &

然后添加到crontab中开机启动：

@reboot /path/to/start_xinference.sh

对于Windows，创建一个批处理文件：

@echo off
start /min cmd /c "xinference start --host 0.0.0.0 --port 9997 --ui --log-level warning"

然后将这个批处理文件的快捷方式放到启动文件夹中。

8.3 集成到其他工具中

Xinference提供了OpenAI兼容的API，这意味着你可以把它当作本地版的OpenAI来使用。只需要把API地址改成http://127.0.0.1:9997/v1即可。

例如，在LangChain中：

from langchain_openai import ChatOpenAI

# 使用本地Xinference服务
llm = ChatOpenAI(
    openai_api_base="http://127.0.0.1:9997/v1",
    model_name="qwen2-chat-q4_k_m",
    temperature=0.7
)

response = llm.invoke("你好，请介绍一下你自己")
print(response.content)

9. 总结

通过这篇教程，你应该已经成功完成了Xinference-v1.17.1的安装和基本使用。让我们回顾一下关键步骤：

1. 环境准备：检查Python版本，清理旧版本，确认硬件配置
2. 安装部署：创建虚拟环境，使用一行命令安装Xinference
3. 验证测试：检查版本，启动服务，测试API连通性
4. 启动WebUI：启动带图形界面的服务，访问Web管理界面
5. 加载模型：下载并启动第一个轻量级模型（Qwen2-0.5B）
6. 调用模型：通过Web界面聊天，或使用Python代码调用
7. 进阶使用：尝试更大的模型，设置开机启动，集成到其他工具中

Xinference的强大之处在于它的灵活性和易用性。你可以在自己的电脑上运行各种开源大模型，完全掌控数据隐私，而且不需要支付API费用。无论是学习AI、开发原型，还是部署生产应用，它都是一个很好的选择。

现在你已经有了一个本地的AI助手，可以开始探索更多可能性了。试着用它来写代码、回答问题、创作内容，或者集成到你自己的项目中。实践是最好的学习方式，多尝试、多探索，你会发现AI的世界比你想象的更加精彩。

---

获取更多AI镜像

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