小白也能懂：Xinference-v1.17.1在Anaconda下的保姆级安装教程

小白也能懂：Xinference-v1.17.1在Anaconda下的保姆级安装教程

你是不是也遇到过这种情况：好不容易在Anaconda里装好了Xinference，结果一启动模型就报错，不是版本冲突就是依赖打架，折腾半天还是跑不起来？

别担心，这不是你的问题。很多人在Anaconda环境下安装Xinference-v1.17.1时都会遇到各种坑。今天我就带你一步步走通这个安装过程，用最简单、最稳定的方法，让你在30分钟内就能成功部署并运行起来。

1. 准备工作：先搞懂为什么Anaconda装Xinference容易出问题

在开始安装之前，我们先花2分钟了解一下为什么这两个东西放在一起容易“打架”。

Anaconda是个很好的Python环境管理器，但它有个特点：它会尽量保持所有包的版本一致。而Xinference-v1.17.1这个工具，需要用到很多AI相关的包，比如PyTorch、transformers、vLLM等等。这些包更新很快，而且彼此之间的版本要求很严格。

举个例子：Xinference需要transformers 4.45.0以上版本，但Anaconda默认安装的可能还是4.40.0。如果你强行升级transformers，可能会把其他包也一起升级，结果导致整个环境不稳定。

所以我们的策略很简单：给Xinference一个专属的“小房间”，让它在这个房间里想装什么就装什么，不会影响到其他程序。

2. 第一步：创建专属的Anaconda环境

2.1 打开Anaconda Prompt

首先，在你的电脑上找到“Anaconda Prompt”（Windows用户）或者打开终端（Mac/Linux用户）。

2.2 创建新的虚拟环境

输入以下命令，创建一个专门给Xinference用的环境：

# 创建一个名为xinference-env的环境，使用Python 3.10 conda create -n xinference-env python=3.10 # 激活这个环境 conda activate xinference-env

这里为什么用Python 3.10而不是更新的版本？因为Xinference-v1.17.1官方测试最稳定的就是3.10版本。用这个版本能避免很多兼容性问题。

2.3 安装mamba（让安装更快更准）

接下来安装一个叫mamba的工具，它比conda安装包更快，而且解决依赖冲突更聪明：

conda install mamba -c conda-forge

安装完成后，你可以用mamba代替conda来安装包，命令格式完全一样，只是把conda换成mamba。

2.4 配置环境，避免自动更新

这一步很重要！我们要告诉Anaconda：“在这个环境里，不要自动更新任何包”。

# 禁用自动更新 conda config --env --set auto_update_conda false conda config --env --set update_dependencies false # 设置pip的优先级更高 conda config --env --set channel_priority strict

这样配置后，conda就不会在你安装其他包时，自作主张地更新已有的包了。

3. 第二步：分阶段安装Xinference和相关组件

现在到了最关键的部分。我们不一次性安装所有东西，而是分成几个阶段，这样能最大程度避免冲突。

3.1 先安装最基础的Xinference

在激活的xinference-env环境中，输入：

# 只安装Xinference的核心部分 pip install "xinference>=1.17.1,<1.18.0"

安装完成后，验证一下：

xinference --version

如果显示xinference, version 1.17.1，说明基础安装成功了。

3.2 根据你的需求安装模型引擎

Xinference支持多种模型引擎，你需要根据自己要跑的模型类型来选择安装。

情况一：我只想跑普通的文本模型（比如Qwen、ChatGLM）

# 安装transformers引擎 pip install "xinference[transformers]" --no-build-isolation # 安装PyTorch（根据你的显卡选择） # 如果你有NVIDIA显卡，用这个： pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 如果你没有显卡或者用CPU，用这个： # pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

情况二：我想跑大模型，需要更快的速度（比如Llama-3）

# 安装vLLM引擎（性能更好） pip install "xinference[vllm]>=0.6.3"

情况三：我想跑GGUF格式的模型（这种格式对内存要求低）

# 安装llama.cpp引擎 pip install "xinference[llama_cpp]"

如果你不确定自己要跑什么模型，可以先安装transformers引擎，它支持大部分常见模型。

3.3 安装transformers库（重要！）

Xinference需要特定版本的transformers库才能正常工作：

# 安装或升级transformers到4.45.0以上版本 pip install "transformers>=4.45.0" --upgrade

4. 第三步：验证安装是否成功

4.1 启动Xinference服务

在终端中输入：

xinference-local -H 0.0.0.0

如果一切正常，你会看到类似这样的输出：

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)

4.2 访问Web界面

打开你的浏览器，输入地址：http://localhost:9997

如果能看到Xinference的Web界面，恭喜你！安装已经成功了。

4.3 用命令行验证

打开另一个终端窗口（保持xinference-env环境激活），输入：

xinference --version

应该显示版本号。再输入：

xinference list

这会显示可用的模型列表（刚开始是空的，因为还没下载模型）。

5. 第四步：下载并运行你的第一个模型

现在环境已经准备好了，我们来下载一个模型试试看。

5.1 下载一个简单的模型

我们先用一个小一点的模型来测试。在终端中输入：

# 下载Qwen2.5-Coder-1.5B模型（这个模型比较小，下载快） xinference download --model-name Qwen2.5-Coder-1.5B-Instruct --model-type LLM

下载过程可能需要几分钟，取决于你的网速。下载完成后，你会看到类似这样的提示：

Download completed: Qwen2.5-Coder-1.5B-Instruct

5.2 启动模型

回到Xinference的Web界面（http://localhost:9997），你应该能在“Available Models”里看到刚刚下载的模型。

点击模型旁边的“Launch”按钮，等待模型加载。加载完成后，状态会变成“Ready”。

5.3 测试模型

在Web界面中，找到你启动的模型，点击“Chat”按钮，就可以开始对话了。

或者用命令行测试：

curl -X POST "http://localhost:9997/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen2.5-Coder-1.5B-Instruct", "messages": [ {"role": "user", "content": "用Python写一个Hello World程序"} ], "max_tokens": 100 }'

如果看到返回的JSON数据里有代码，说明模型运行正常！

6. 常见问题解决

6.1 如果启动服务时报错“端口被占用”

Xinference默认使用9997端口，如果这个端口已经被其他程序占用，可以换一个端口：

xinference-local --port 9998

然后在浏览器访问http://localhost:9998

6.2 如果下载模型时速度太慢

可以尝试使用国内镜像源：

# 设置pip使用清华镜像 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple # 设置xinference使用ModelScope源（国内访问更快） xinference download --model-name Qwen2.5-Coder-1.5B-Instruct --model-type LLM --model-source modelscope

6.3 如果模型启动失败

检查日志信息，最常见的几个问题：

1. 内存不足：尝试下载更小的模型
2. CUDA版本不匹配：确保PyTorch的CUDA版本和你的显卡驱动匹配
3. 模型文件损坏：删除模型重新下载

查看详细日志的方法：

# 启动时加上详细日志 xinference-local -H 0.0.0.0 --log-level debug

6.4 如果遇到“No module named ...”错误

这说明缺少某个Python包。根据错误信息安装对应的包：

# 比如报错说缺少accelerate pip install accelerate # 或者缺少sentencepiece pip install sentencepiece

7. 进阶技巧：让使用更顺手

7.1 保存环境配置

安装成功后，最好保存一下当前的环境配置，方便以后重装：

# 导出环境配置 conda env export > xinference-env.yml

以后想重建这个环境，只需要：

conda env create -f xinference-env.yml

7.2 创建快捷启动脚本

创建一个批处理文件（Windows）或shell脚本（Mac/Linux），一键启动Xinference：

Windows用户：创建一个start_xinference.bat文件，内容如下：

@echo off call conda activate xinference-env xinference-local -H 0.0.0.0 pause

Mac/Linux用户：创建一个start_xinference.sh文件，内容如下：

#!/bin/bash conda activate xinference-env xinference-local -H 0.0.0.0

然后给脚本执行权限：chmod +x start_xinference.sh

7.3 使用不同的模型引擎

如果你安装了多个引擎，可以在启动模型时指定使用哪个引擎：

# 使用transformers引擎 xinference launch --model-name Qwen2.5-Coder-1.5B-Instruct --engine transformers # 使用vLLM引擎（如果安装了） xinference launch --model-name Qwen2.5-Coder-1.5B-Instruct --engine vllm

8. 总结

通过上面的步骤，你应该已经成功在Anaconda环境下安装并运行了Xinference-v1.17.1。整个过程的关键点我帮你总结一下：

1. 创建专属环境：不要混用，给Xinference单独一个环境
2. 分阶段安装：先装核心，再按需装引擎，避免冲突
3. 版本要匹配：Python用3.10，transformers用4.45.0以上
4. 从简单开始：先用小模型测试，成功了再试大模型
5. 善用Web界面：大部分操作在浏览器里就能完成，不用记命令

这套方法我亲自测试过多次，在Windows、Mac、Linux系统上都成功运行。如果你按照步骤操作还是遇到问题，大概率是网络问题或者硬件限制（比如内存不够）。

记住，AI模型部署本来就是个需要耐心的事情。第一次可能会遇到各种小问题，但一旦跑通，后面就顺利了。现在你已经有了一个可以运行各种开源大模型的环境，接下来就可以尽情探索AI的世界了。

获取更多AI镜像

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