Xinference模型下载慢

简介

Xinference 是 Xorbits 推出的开源推理平台，用于在云端或本地运行并集成各类 AI 模型，覆盖大语言模型、Embedding、ReRank、多模态与语音识别模型。它在首次启动某个模型时会自动下载权重，网络受限或带宽不足时，这一步就会表现为下载慢、加载慢。本页围绕「模型下载慢」给出成因判断、排查顺序与绕行做法，适合在内网 GPU 服务器、Windows 桌面或 Docker 容器里跑模型的开发者。核心思路只有一条：机器上已经有的权重就直接复用，不再重复下载。

核心功能

• 一键部署大语言模型、多模态模型、语音识别模型等，把部署流程收敛为一次启动操作。
• 首次启动模型时自动下载权重，无需手动取文件；代价是这一步的耗时直接取决于网络状况。
• 提供与 OpenAI 兼容的 API，可以把正在运行的模型当作 OpenAI 的本地替代来调用。
• 支持在页面上点 register model 注册本地已有模型：选择模型类型，输入模型的本地地址即可。
• 提供 Docker 镜像与本地源码两种获取方式，另有 Docker Compose 与 Kubernetes 集群的部署路径。
• 运行容器时可用 docker run 指定本地卷，把宿主机目录挂载到容器内，并为 Xinference 配置环境变量指向该目录。
• 除 LLM 外还支持 Embedding 与 ReRank 模型，可在同一套服务里组合使用。

使用场景

• 内网或纯内网的 GPU 服务器：镜像可能需要手动压缩后再解压才能正常部署，模型权重同样需要离线拷贝。
• 已有本地权重复用：把宿主机目录挂载到容器内并配置环境变量，直接加载已下载好的模型，跳过自动下载。
• Windows 桌面环境：issue #3364 中，Xinference v1.2.2 加载 glm4-chat 时速度约 104.94s/it，属于典型的加载慢反馈。
• 企业级 RAG 构建：需要同时用到 LLM、Embedding 与 ReRank 三类模型，权重体积叠加后下载耗时更明显。
• 想把模型当作 OpenAI 本地替代的业务：希望权重位置可控、启动路径可预期，避免每次启动都依赖外网。

安装与获取步骤

1. 先选定获取方式：Docker 镜像，或直接在本地用源码方式准备，两条路径都写在官方文档 https://inference.readthedocs.io/zh-cn/latest/getting_started/ 中。
2. 用 Docker 跑服务时，在 docker run 命令中指定本地卷，把宿主机存放权重的目录挂载进容器，同时为 Xinference 配置环境变量指向该路径。
3. 启动服务后首次启动目标模型，Xinference 会自动下载权重；这一步可能需要一定时间，先预留出等待窗口再判断是否异常。
4. 如果下载确实过慢，改用机器上已经下载好的模型：在页面点 register model，选择模型的类型，输入模型的本地地址。
5. 注册时给模型起一个自定义名称，因为模型名称不能与内置模型同名，否则会注册失败。
6. 需要集群化或编排部署时，可改用 Docker Compose 或在 Kubernetes 集群中部署，具体步骤以官方文档页面为准。

下载慢的排查顺序

• 先区分是「下载慢」还是「加载慢」：首次启动才触发下载，已存在权重的启动只走加载路径。
• 确认权重是否真的缺失：若宿主机目录里已有该模型，直接走 register model 填本地地址，不必再等自动下载。
• 确认容器内外路径是否一致：容器里看不到宿主机文件，通常意味着没有挂载本地卷或环境变量没指向该目录。
• 确认网络出口：纯内网机器无法访问外部源时，自动下载会长时间无进展，应改为离线拷贝权重。
• 确认现象可复现并记录版本与环境，例如 issue #3364 中记录的 v1.2.2、Windows10、glm4-chat 与 104.94s/it，便于对照官方 issue 页面。

注意事项

• 首次启动模型时自动下载是预期行为，耗时较长不等于故障，先确认网络与权重路径再下结论。
• 通过页面注册本地模型时，模型名称不能与内置模型同名，需要另起一个名称。
• 纯内网环境下镜像可能要手动压缩、解压后才能在目标机器上使用，权重文件也需离线搬运。
• 宿主机目录未挂载到容器内、或环境变量未指向该目录时，容器内会找不到已有权重，表现为反复触发下载。
• 版本号、参数与命令细节以官方页面 https://inference.readthedocs.io/zh-cn/latest/ 与项目仓库 https://github.com/xorbitsai/inference 的最新说明为准。