Xinference下载模型卡住不动？从0%到100%的完整排坑指南
写在前面
最近在使用Xinference部署模型时，遇到了一个让人抓狂的问题：无论WebUI还是命令行，模型下载的进度始终卡在0%不动，多次重试后还是没变化。更诡异的是，服务日志显示一切正常，但是就是下载不了。
经过一顿倒腾，终于找到了问题所在并且成功解决，这篇文章记录了完整的排查过程以及解决方案，希望能帮助到你。
环境说明
- 平台：AutoDL部署的Xinference
- Xinference版本：最新版
- 目标模型：bge-reranker-large
- 网络环境：国内服务器
问题现象
- 启动Xinference服务成功，WebUI也能正常访问；
- 尝试下载模型，WebUI界面中进度条一直不动，命令行下载的时候也一直显示0%；
- 没有任何明确的错误提示。
排查过程
（1）确认服务状态
首先确认Xinference服务本身是否正常：
# 启动服务 xinference-local --host 0.0.0.0 --port 6006 # 检查服务健康状态 curl http://127.0.0.1:6006/v1/models输入：root@autodl-container-969947803a-48d90d73:~# curl http://127.0.0.1:6006/v1/models
输出：{"object":"list","data":[]}root@autodl-container-969947803a-48d90d73:~#
说明Xinference服务在正常运行，返回的空列表[]确认了此时没有任何模型
（2）检查环境变量
发现xinference list命令报错接连失败，是因为命令默认连接到9997端口，而我们的服务是在6006端口：
# 需要指定正确的 endpoint xinference list --endpoint http://127.0.0.1:6006（3）端口冲突
在输出的服务日志中发现一条警告：WARNING Failed to create socket with port 6006
说明6006端口已被别的进程占用，解决方法：
# 查看端口占用 lsof -i :6006 # 杀掉占用进程 kill -9 <PID> # 或者直接清理所有 Xinference 进程 pkill -f xinference（4）网络问题
端口问题解决后，下载仍然卡住，是因为国内的服务器访问Hugging Face官方源速度极慢，甚至超时。解决方法：使用国内镜像源
# 设置 Hugging Face 镜像 export HF_ENDPOINT=https://hf-mirror.com # 重新启动服务 xinference-local --host 0.0.0.0 --port 6006最终成功的启动方式
使用终端1：启动Xinference服务
# 确保端口干净 pkill -f xinference # 设置镜像源并启动 export HF_ENDPOINT=https://hf-mirror.com xinference-local --host 0.0.0.0 --port 6006 # 设置学术加速 source /etc/network_turbo使用终端2：下载模型
xinference launch --model-type rerank --model-name bge-reranker-large --model-uid my-reranker --endpoint http://127.0.0.1:6006就可以看到进度条变化了：
图形化界面也可以使用下载了：
最终就可以在 Running Models看到下载的模型：
同时可以重新查看服务的状态，发现两个模型的参数：
写在最后
每次重启Xinference后之前加载的模型都会被清空，这是因为Xinference的设计理念是：模型不会持久化运行，因此需要重新启动。打开WebUI点击Launch Model选择已经下载过的模型，点击启动即可（几秒钟就OK）