故障排除#

没有 huggingface 仓库权限#

获取模型时，有时候会遇到权限问题。比如在获取 llama2 模型时可能会有以下提示：

Cannot access gated repo for url https://huggingface.co/api/models/meta-llama/Llama-2-7b-hf.
Repo model meta-llama/Llama-2-7b-hf is gated. You must be authenticated to access it.

这种情况一般是缺少 huggingface 仓库的权限，或者是没有配置 huggingface token。可以按照接下来的方式解决这个问题。

申请 huggingface 仓库权限#

想要获取访问权限，打开对应的 huggingface 仓库，同意其条款和注意事项。以 llama2 为例，可以打开这个链接去申请：https://huggingface.co/meta-llama/Llama-2-7b-hf.

设置访问 huggingface 凭证#

可以在 huggingface 页面找到凭证，https://huggingface.co/settings/tokens.

可以通过设置环境变量设置访问凭证，export HUGGING_FACE_HUB_TOKEN=your_token_here。

英伟达驱动和 PyTorch 版本不匹配#

如果你在使用英伟达显卡，你可能会遇到以下错误：

UserWarning: CUDA initialization: The NVIDIA driver on your system is too old
(found version 10010). Please update your GPU driver by downloading and installi
ng a new version from the URL: http://www.nvidia.com/Download/index.aspx Alterna
tively, go to: https://pytorch.org to install a PyTorch version that has been co
mpiled with your version of the CUDA driver. (Triggered internally at  ..\c10\cu
da\CUDAFunctions.cpp:112.)

这种情况一般是 CUDA 的版本和 Pytorch 版本不兼容导致的。

可以到 https://pytorch.org 官网安装和 CUDA 对应的预编译版本的 PyTorch。同时，请检查安装的 CUDA 版本不要小于 11.8，最好版本在 11.8 到 12.1之间。

比如你的 CUDA 版本是 11.8，可以使用以下命令安装对应的 PyTorch：

pip install torch==2.0.1+cu118

外部系统无法通过 `<IP>:9997` 访问 Xinference 服务#

在启动 Xinference 时记得要加上 -H 0.0.0.0 参数:

xinference-local -H 0.0.0.0

那么 Xinference 服务将监听所有网络接口（而不仅限于 127.0.0.1 或 localhost）。

如果使用的是 Docker 镜像，请在 Docker 运行命令中加上 -p <PORT>:9997 ，，你就可以通过本地机器的 <IP>:<PORT> 进行访问。

启动内置模型需要很长时间，模型有时下载失败#

Xinference 默认使用 HuggingFace作为模型源。如果你的机器在中国大陆，使用内置模型可能会有访问问题。

要解决这个问题，可以在启动 Xinference 时添加环境变量 XINFERENCE_MODEL_SRC=modelscope，将模型源更改为 ModelScope，在中国大陆速度下载更快。

如果你用 Docker 启动 Xinference，可以在 Docker 命令中包含 -e XINFERENCE_MODEL_SRC=modelscope 选项。

使用官方 Docker 映像时，RayWorkerVllm 因 OOM 而死亡，导致模型无法加载#

Docker 的 --shm-size 参数可以用来设置共享内存的大小。共享内存(/dev/shm)的默认大小是 64MB，对于 vLLM 后端来说可能不够。

你可以通过设置参数 --shm-size 来增加它的大小：

docker run --shm-size=128g ...

加载 LLM 模型时提示缺失 `model_engine` 参数#

自 v0.11.0 版本开始，加载 LLM 模型时需要传入额外参数 model_engine 。具体信息请参考这里。