Solución de problemas#

No tienes permisos para el repositorio de Hugging Face.#

Al obtener el modelo, a veces pueden surgir problemas de permisos. Por ejemplo, al obtener el modelo llama2 puede aparecer el siguiente mensaje:

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.

Generalmente, esto se debe a la falta de permisos en el repositorio de Hugging Face o a la ausencia de configuración del token de Hugging Face. Puedes resolver este problema siguiendo los pasos a continuación.

Solicitar permisos del repositorio de Hugging Face#

Para obtener acceso, abre el repositorio correspondiente de Hugging Face y acepta sus términos y condiciones. Tomando como ejemplo llama2, puedes abrir este enlace para solicitarlo: https://huggingface.co/meta-llama/Llama-2-7b-hf.

Configurar credenciales de acceso a Hugging Face#

Las credenciales se pueden encontrar en la página de Hugging Face, https://huggingface.co/settings/tokens.

Puede configurar las credenciales de acceso estableciendo una variable de entorno, export HUGGING_FACE_HUB_TOKEN=your_token_here.

Controlador de NVIDIA y versión de PyTorch no coinciden#

Si estás utilizando una tarjeta gráfica NVIDIA, es posible que te encuentres con el siguiente error:

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

Generalmente, esto se debe a que la versión de CUDA es incompatible con la versión de PyTorch.

Puede instalar la versión precompilada de PyTorch correspondiente a CUDA desde el sitio web oficial https://pytorch.org. Al mismo tiempo, verifique que la versión de CUDA instalada no sea inferior a 11.8, y preferiblemente esté entre 11.8 y 12.1.

Por ejemplo, si tu versión de CUDA es la 11.8, puedes usar el siguiente comando para instalar PyTorch correspondiente:

pip install torch==2.0.1+cu118

El sistema externo no puede acceder al servicio Xinference a través de <IP>:9997.#

Al iniciar Xinference, recuerda agregar el parámetro -H 0.0.0.0:

xinference-local -H 0.0.0.0

Entonces el servicio Xinference escuchará en todas las interfaces de red (no solo en 127.0.0.1 o localhost).

Si estás usando Imagen de Docker, agrega -p <PORT>:9997 al comando de ejecución de Docker, y podrás acceder a través de <IP>:<PORT> desde tu máquina local.

Iniciar el modelo integrado requiere mucho tiempo, y a veces la descarga del modelo falla.#

Xinference usa HuggingFace como fuente de modelos por defecto. Si tu máquina está en China continental, el uso de modelos integrados puede tener problemas de acceso.

Para resolver este problema, puede agregar la variable de entorno XINFERENCE_MODEL_SRC=modelscope al iniciar Xinference, cambiando la fuente del modelo a ModelScope, lo que permite una descarga más rápida en China continental.

Si estás iniciando Xinference con Docker, puedes incluir la opción -e XINFERENCE_MODEL_SRC=modelscope en el comando de Docker.

Cuando se utiliza la imagen oficial de Docker, RayWorkerVllm muere por OOM, lo que impide cargar el modelo.#

El parámetro --shm-size de Docker se puede utilizar para establecer el tamaño de la memoria compartida. El tamaño predeterminado de la memoria compartida (/dev/shm) es de 64 MB, lo que puede no ser suficiente para el backend de vLLM.

Puede aumentar su tamaño configurando el parámetro --shm-size:

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

Al cargar el modelo LLM se solicita el parámetro faltante model_engine.#

A partir de la versión v0.11.0, al cargar el modelo LLM es necesario pasar el parámetro adicional model_engine. Para más información, consulte aquí.

Resolución de conflictos en la capa de hilos de MKL#

Al iniciar el servidor Xinference, si se encuentra el error: ValueError: Model architectures ['Qwen2ForCausalLM'] failed to be inspected. . Please check the logs for more details.

La causa raíz mostrada en los registros es:

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.

Esto suele deberse a que tu NumPy fue instalado mediante conda, y la versión de NumPy de conda está construida con la optimización Intel MKL, lo que provoca un conflicto con la biblioteca GNU OpenMP (libgomp) ya cargada en el entorno.

Solución 1: Reescribir la capa de hilos#

Establecer MKL_THREADING_LAYER=GNU fuerza a la biblioteca central matemática de Intel (MKL) a usar la implementación de OpenMP de GNU:

MKL_THREADING_LAYER=GNU xinference-local

Solución 2: Reinstalar NumPy con pip#

Desinstala numpy instalado por conda y luego vuelve a instalarlo usando pip.

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

Configurar el espejo de PyPI para acelerar la instalación de paquetes#

Si te encuentras en China continental, usar un espejo de PyPI puede acelerar significativamente la velocidad de instalación de paquetes. A continuación se presentan algunas fuentes de espejo comúnmente utilizadas:

  • Espejo de la Universidad de Tsinghua: https://pypi.tuna.tsinghua.edu.cn/simple

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

  • Espejo de Tencent Cloud: https://mirrors.cloud.tencent.com/pypi/simple

Pero ten en cuenta que algunos espejos pueden carecer de ciertos paquetes. Por ejemplo, si solo usas el espejo de Alibaba Cloud para instalar xinference[audio], la instalación podría fallar.

Esto ocurre porque el paquete num2words del que depende MeloTTS no está disponible en el mirror de Alibaba Cloud. Por lo tanto, al ejecutar pip install xinference[audio], podría retroceder e instalar una versión anterior, como xinference==1.2.0 y xoscar==0.8.0 (a fecha del 27 de octubre de 2025).

Estas versiones antiguas son incompatibles y causarán el siguiente error: 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 este problema al instalar el paquete de audio de xinference, se recomienda utilizar múltiples fuentes de espejo al mismo tiempo.

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

Fallo al instalar Xinference 1.12.0 usando uv (hasta noviembre de 2025)#

Nota: Este es un problema temporal debido al ecosistema de paquetes actual y la estrategia de resolución de dependencias de uv, que prioriza versiones altas de dependencias directas en lugar de versiones de dependencias indirectas.

Síntomas#

En noviembre de 2025, al instalar xinference 1.12.0 con uv pip install xinference, es posible que encuentres problemas con la instalación de versiones muy antiguas de paquetes dependientes, especialmente:

  • transformers==4.12.2 (procedente de la versión de 2021)

  • tokenizers==0.10.3 (de la versión de 2021)

  • huggingface-hub==1.0.1

Luego, uv reportó un error: «Failed to build tokenizers==0.10.3» (fallo al construir tokenizers==0.10.3).

Causa raíz#

El motivo de este problema es que uv prioriza las versiones más recientes de dependencias directas, ignorando los requisitos de versión en las dependencias indirectas:

  1. xinference 1.12.0 especifica huggingface-hub>=0.19.4 como dependencia directa (sin restricción superior).

  2. Al 6 de noviembre de 2025, uv seleccionará la versión más reciente: huggingface-hub==1.0.1

  3. Sin embargo, transformers<=4.57.3 (una dependencia indirecta introducida por peft) requiere huggingface-hub<1.0.

  4. Para resolver el conflicto de dependencias, uv mantuvo la dependencia directa huggingface-hub==1.0.1 y degradó la dependencia indirecta transformers a la versión muy antigua 4.12.2.

Es una característica de diseño de uv: prioriza las dependencias que especificas explícitamente (dependencias directas) sobre las dependencias transitivas. Enlace de referencia: astral-sh/uv#16601

Actualización: Hasta el 2026.01.05, la versión más reciente de transformers, la 4.57.3, aún depende de huggingface-hub<1.0.

Solución#

Solución 1: Limitar la versión de huggingface-hub de antemano (recomendado)

Limita explícitamente huggingface-hub a un rango de versiones compatible:

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

Esto fuerza a uv a seleccionar una versión de huggingface-hub compatible con la versión moderna de transformers.

Solución 2: Establecer transformers como dependencia directa

Al especificar explícitamente transformers, se convierte en una dependencia directa, y uv priorizará la versión más reciente:

uv pip install transformers xinference

Solución 3: Usar pip

O directamente usa pip install xinference, que resolverá automáticamente la siguiente combinación de versiones:

  • transformers==4.57.1

  • huggingface-hub==0.36.0

  • tokenizers==0.22.1

vLLM + Torch + Xinference problema de compatibilidad (fallo de segmentación)#

Síntomas#

Si tienes instalado vLLM < 0.12.0 y actualizas xinference (especialmente al usar uv pip install -U xinference), es posible que xinference falle al iniciar debido a un error de segmentación:

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 raíz#

El problema es causado por la combinación de tres factores:

  1. Incompatibilidad binaria: vLLM en versiones anteriores a la 0.12.0 fue compilado con PyTorch 2.8.0, y estas versiones son incompatibles con PyTorch 2.9. Referencia: Notas de lanzamiento de vLLM v0.12.0

  2. Dependencia de Torch sin límite superior en Xinference: En el archivo setup.cfg de Xinference no se especifica un límite de versión para PyTorch.

    [options]
install_requires =
    torch                    # No version constraint!

    This allows package managers to upgrade PyTorch to incompatible versions.

  3. Diferencias de comportamiento entre diferentes gestores de paquetes:

    • pip: es más conservador — solo actualiza las dependencias relacionadas cuando son incompatibles; de lo contrario, solo actualiza el paquete especificado.

    • Usando uv con el parámetro -U: la estrategia es más agresiva: vuelve a resolver todas las dependencias y selecciona la versión más reciente.

Por lo tanto, cuando no estés listo para actualizar toda la pila tecnológica y solo quieras actualizar xinference, puedes optar por usar:

  • pip install -U xinference (manteniendo la versión de PyTorch sin cambios, solo actualiza xinference)

  • uv pip install "xinference==1.16.0" (without -U flag, only upgrades xinference too)