Solução de problemas#

Sem permissão do repositório huggingface#

Ao obter o modelo, às vezes você pode encontrar problemas de permissão. Por exemplo, ao obter o modelo llama2, pode surgir o seguinte aviso:

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.

Geralmente isso ocorre por falta de permissão ao repositório do Hugging Face, ou por não ter configurado o token do Hugging Face. Você pode resolver esse problema seguindo os passos a seguir.

Solicitar permissão para o repositório do Hugging Face#

Para obter acesso, abra o repositório correspondente no Hugging Face e aceite seus termos e condições. Usando llama2 como exemplo, você pode acessar este link para solicitar: https://huggingface.co/meta-llama/Llama-2-7b-hf.

Defina as credenciais de acesso ao Hugging Face.#

Você pode encontrar as credenciais na página do Hugging Face, https://huggingface.co/settings/tokens.

Você pode configurar a credencial de acesso definindo uma variável de ambiente: export HUGGING_FACE_HUB_TOKEN=your_token_here.

O driver NVIDIA e a versão do PyTorch não são compatíveis.#

Se você estiver usando uma placa de vídeo NVIDIA, pode encontrar o seguinte erro:

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.)

Geralmente, isso é causado pela incompatibilidade entre a versão do CUDA e a versão do PyTorch.

Você pode instalar o PyTorch pré-compilado correspondente à versão CUDA no site oficial https://pytorch.org. Além disso, certifique-se de que a versão do CUDA instalada não seja inferior a 11.8, sendo ideal que esteja entre 11.8 e 12.1.

Por exemplo, se sua versão do CUDA for 11.8, você pode usar o seguinte comando para instalar o PyTorch correspondente:

pip install torch==2.0.1+cu118

O sistema externo não pode acessar o serviço Xinference através de <IP>:9997.#

Ao iniciar o Xinference, lembre-se de adicionar o parâmetro -H 0.0.0.0:

xinference-local -H 0.0.0.0

Então o serviço Xinference escutará em todas as interfaces de rede (não apenas em 127.0.0.1 ou localhost).

Se estiver usando o Imagem Docker, adicione -p <PORT>:9997 ao comando de execução do Docker, e você poderá acessar através de <IP>:<PORT> na máquina local.

O início do modelo embutido leva muito tempo, e às vezes o download do modelo falha.#

Xinference usa HuggingFace como fonte de modelo padrão. Se sua máquina estiver na China continental, o uso de modelos integrados pode ter problemas de acesso.

Para resolver esse problema, ao iniciar o Xinference, adicione a variável de ambiente XINFERENCE_MODEL_SRC=modelscope para alterar a fonte do modelo para ModelScope, o que resulta em downloads mais rápidos na China continental.

Se você iniciar o Xinference com Docker, pode incluir a opção -e XINFERENCE_MODEL_SRC=modelscope no comando Docker.

Ao usar a imagem oficial do Docker, o RayWorkerVllm morre devido a OOM, impedindo o carregamento do modelo.#

O parâmetro --shm-size do Docker pode ser usado para definir o tamanho da memória compartilhada. O tamanho padrão da memória compartilhada (/dev/shm) é de 64MB, que pode ser insuficiente para o backend vLLM.

Você pode aumentar seu tamanho definindo o parâmetro --shm-size:

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

Erro ao carregar modelo LLM: parâmetro model_engine ausente.#

A partir da versão v0.11.0, é necessário passar o parâmetro adicional model_engine ao carregar o modelo LLM. Para mais informações, consulte aqui.

Resolvendo conflitos na camada de threads MKL#

Ao iniciar o servidor Xinference, se encontrar o erro: ValueError: Model architectures ['Qwen2ForCausalLM'] failed to be inspected. . Please check the logs for more details.

A causa raiz mostrada no log é:

Error: mkl-service + Intel(R) MKL: MKL_THREADING_LAYER=INTEL is incompatible with libgomp-a34b3233.so.1 library.
Try to import numpy first or set the threading layer accordingly. Set MKL_SERVICE_FORCE_INTEL to force it.

Isso geralmente acontece porque seu NumPy foi instalado via conda, e o NumPy do conda é construído com a otimização Intel MKL, o que causa conflito com a biblioteca GNU OpenMP (libgomp) já carregada no ambiente.

Solução 1: Reescrever a camada de thread#

Definir MKL_THREADING_LAYER=GNU força a Intel Math Kernel Library (MKL) a usar a implementação OpenMP do GNU:

MKL_THREADING_LAYER=GNU xinference-local

Solução 2: Reinstalar o NumPy usando pip#

Desinstale o numpy instalado pelo conda e reinstale usando pip.

pip uninstall -y numpy && pip install numpy
#Or just --force-reinstall
pip install --force-reinstall numpy

Configurar o espelho PyPI para acelerar a instalação de pacotes de software#

Se você estiver na China continental, usar um mirror do PyPI pode acelerar significativamente a instalação de pacotes. Abaixo estão algumas fontes de mirror comuns:

  • Espelho da Universidade de Tsinghua: https://pypi.tuna.tsinghua.edu.cn/simple

  • Alibaba Cloud Mirror: https://mirrors.aliyun.com/pypi/simple/

  • Nuvem Tencent: https://mirrors.cloud.tencent.com/pypi/simple

No entanto, esteja ciente de que alguns pacotes podem estar faltando em determinados espelhos de origem. Por exemplo, se você usar apenas o espelho Alibaba Cloud para instalar xinference[audio], a instalação pode falhar.

Isso ocorre porque o pacote num2words, do qual o MeloTTS depende, não está disponível no espelho da Alibaba Cloud. Portanto, ao executar pip install xinference[audio], pode haver um fallback para a instalação de versões mais antigas, como xinference==1.2.0 e xoscar==0.8.0 (até 27 de outubro de 2025).

Essas versões antigas são incompatíveis e causam o seguinte erro: MainActorPool.append_sub_pool() got an unexpected keyword argument 'start_method'

curl -s https://mirrors.aliyun.com/pypi/simple/num2words/ | grep -i "num2words"
# Returns NOTHING! But it works on Tsinghua or Tencent mirrors.
# uv pip install "xinference[audio]" will then install the following packages (as of Oct 27, 2025):
+ x-transformers==2.10.2
+ xinference==1.2.0
+ xoscar==0.8.0

Para evitar esse problema ao instalar o pacote de áudio do xinference, é recomendável usar múltiplos mirrors simultaneamente:

uv pip install xinference[audio] --index-url https://mirrors.aliyun.com/pypi/simple --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Optional: Set this globally in your uv config
mkdir -p ~/.config/uv
cat >> ~/.config/uv/uv.toml << EOF
index-url = "https://mirrors.aliyun.com/pypi/simple"
extra-index-url = ["https://pypi.tuna.tsinghua.edu.cn/simple"]
EOF

Falha ao instalar o Xinference 1.12.0 usando uv (até novembro de 2025)#

Nota: Esta é uma questão temporária, decorrente do ecossistema de pacotes atual e da estratégia de resolução de dependências do uv — ele prioriza versões mais altas de dependências diretas em vez de versões de dependências indiretas.

Sintomas#

Em novembro de 2025, ao instalar o xinference 1.12.0 com uv pip install xinference, você pode encontrar problemas com a instalação de pacotes de dependência em versões muito antigas, especialmente:

  • transformers==4.12.2 (versão de 2021)

  • tokenizers==0.10.3 (versão de 2021)

  • huggingface-hub==1.0.1

Em seguida, o uv apresentou o erro: “Falha ao construir tokenizers==0.10.3” (Falha ao construir tokenizers==0.10.3).

Causa raiz#

A causa do problema é que o uv prioriza a versão mais alta da dependência direta, ignorando os requisitos de versão das dependências indiretas:

  1. xinference 1.12.0 especifica huggingface-hub>=0.19.4 como uma dependência direta (sem limite superior).

  2. Até 6 de novembro de 2025, o uv selecionará a versão mais recente: huggingface-hub==1.0.1

  3. No entanto, transformers<=4.57.3 (uma dependência indireta introduzida via peft) requer huggingface-hub<1.0.

  4. Para resolver o conflito de dependências, o uv manteve a dependência direta huggingface-hub==1.0.1 e fez o downgrade da dependência indireta transformers para a versão muito antiga 4.12.2.

Isso é uma característica de design do uv: ele prioriza as dependências explicitamente especificadas (dependências diretas) em vez de dependências transitivas. Link de referência: astral-sh/uv#16601

Atualização: Em 05/01/2026, a versão mais recente do transformers, 4.57.3, ainda depende de huggingface-hub<1.0.

Solução#

Solução 1: Pré-limitar a versão do huggingface-hub (recomendado)

Explicitly restringir o huggingface-hub a uma faixa de versões compatível:

uv pip install "huggingface-hub>=0.34.0,<1.0" xinference

Isso força o uv a selecionar uma versão do huggingface-hub compatível com a versão moderna do transformers.

Solução 2: Definir transformers como dependência direta

Ao especificar explicitamente transformers, ele se torna uma dependência direta, e o uv priorizará a versão mais recente:

uv pip install transformers xinference

Solução 3: Usando pip

Ou use diretamente pip install xinference, que resolverá automaticamente para a seguinte combinação de versões:

  • transformers==4.57.1

  • huggingface-hub==0.36.0

  • tokenizers==0.22.1

vLLM + Torch + Xinference Problema de Compatibilidade (Erro de Segmentação)#

Sintomas#

Se você instalou o vLLM < 0.12.0 e atualizou o xinference (especialmente ao usar uv pip install -U xinference), o xinference pode falhar na inicialização devido a um erro de segmentação:

root@server:/home# xinference-local --host 0.0.0.0 --port 9997
INFO 12-30 17:35:37 [__init__.py:216] Automatically detected platform cuda.
Aborted (core dumped)

Causa raiz#

Esse problema é causado por três fatores em conjunto:

  1. Incompatibilidade binária: o vLLM foi compilado com base no PyTorch 2.8.0 em versões anteriores à 0.12.0, e essas versões são incompatíveis com o PyTorch 2.9. Referência: Notas de lançamento do vLLM v0.12.0

  2. Dependência do Torch sem limite superior no Xinference: O setup.cfg do Xinference não especifica um limite superior de versão para o PyTorch:

    [options]
install_requires =
    torch                    # No version constraint!

    This allows package managers to upgrade PyTorch to incompatible versions.

  3. Diferenças de comportamento entre diferentes gerenciadores de pacotes:

    • pip: mais conservador — só atualiza as dependências relacionadas quando há incompatibilidade; caso contrário, atualiza apenas o pacote especificado.

    • Usando o parâmetro -U no uv: A estratégia é mais agressiva — irá resolver todas as dependências novamente e selecionar as versões mais recentes.

Portanto, quando você ainda não estiver pronto para atualizar toda a pilha tecnológica, mas apenas quiser atualizar o xinference, pode optar por usar:

  • pip install -U xinference (mantendo a versão do PyTorch inalterada, apenas atualizando o xinference)

  • uv pip install "xinference==1.16.0" (sem usar o parâmetro -U, também atualizará apenas o xinference)