문제 해결#

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 토큰이 구성되지 않은 경우에 발생합니다. 다음 방법으로 이 문제를 해결할 수 있습니다.

허깅페이스 저장소 권한 신청#

액세스 권한을 얻으려면 해당 Hugging Face 저장소를 열고 이용 약관 및 주의 사항에 동의하십시오. ``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.

NVIDIA 드라이버와 PyTorch 버전이 일치하지 않습니다.#

If you are using an NVIDIA graphics card, you may encounter the following 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.)

이 문제는 일반적으로 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``을 전달해야 합니다. 자세한 사항은 :ref:`여기 <about_model_engine>`를 참조하세요.

MKL 스레드 레이어 충돌 해결#

Xinference 서버를 시작할 때 다음 오류가 발생하는 경우: ValueError: Model architectures ['Qwen2ForCausalLM'] failed to be inspected. . Please check the logs for more details.

로그에 표시된 근본 원인은 다음과 같습니다:

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.

이는 일반적으로 사용자의 NumPy가 conda를 통해 설치되었고, conda의 NumPy가 Intel MKL 최적화로 빌드되어 환경에 로드된 GNU OpenMP 라이브러리(libgomp)와 충돌을 일으키기 때문입니다.

해결책 1: 스레드 계층 재작성#

MKL_THREADING_LAYER=GNU를 설정하면 Intel Math Kernel Library(MKL)가 GNU의 OpenMP 구현을 강제로 사용하도록 할 수 있습니다:

MKL_THREADING_LAYER=GNU xinference-local

해결 방법 2: pip을 사용하여 NumPy 재설치#

conda로 설치한 numpy를 제거한 후, pip를 사용하여 다시 설치하십시오.

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

PyPI 미러를 구성하여 패키지 설치 속도 향상#

중국 본토에서 PyPI 미러를 사용하면 소프트웨어 패키지 설치 속도를 크게 높일 수 있습니다. 다음은 자주 사용되는 미러 소스입니다:

  • 칭화대학교 미러: https://pypi.tuna.tsinghua.edu.cn/simple

  • 阿里云 미러: https://mirrors.aliyun.com/pypi/simple/

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

단, 일부 미러 소스에는 특정 패키지가 없을 수 있습니다. 예를 들어, Alibaba Cloud 미러만 사용하여 ``xinference[audio]``를 설치하면 설치가 실패할 수 있습니다.

이는 MeloTTS``가 의존하는 ``num2words 패키지가 Alibaba Cloud 미러에서 사용할 수 없기 때문입니다. 따라서 pip install xinference[audio]``를 실행할 때, 이전 버전인 ``xinference==1.2.0 및 xoscar==0.8.0 (2025년 10월 27일 기준)으로 대체 설치될 수 있습니다.

이 구버전들은 호환되지 않으며, 다음과 같은 오류가 발생합니다: 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

xinference 오디오 패키지를 설치할 때 이 문제를 방지하려면 여러 미러 소스를 동시에 사용하는 것이 좋습니다:

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

uv를 사용한 Xinference 1.12.0 설치 실패 (2025년 11월 기준)#

참고: 이는 현재 소프트웨어 패키지 생태계와 uv의 종속성 분석 전략으로 인한 임시적인 문제입니다. uv는 **간접 종속성 버전**보다 **직접 종속성의 상위 버전**을 우선 선택합니다.

증상#

2025년 11월에 uv pip install xinference 를 사용하여 xinference 1.12.0을 설치할 때, 특히 다음과 같은 매우 오래된 버전의 종속성 패키지가 설치되는 문제가 발생할 수 있습니다.

  • transformers==4.12.2 (from 2021)

  • tokenizers==0.10.3 (2021년 버전)

  • huggingface-hub==1.0.1

그 다음 uv 오류: “Failed to build tokenizers==0.10.3” (tokenizers==0.10.3 빌드 실패)

근본 원인#

이 문제가 발생하는 이유는 uv가 **간접 종속성**의 버전 요구사항을 무시하고 **직접 종속성의 높은 버전**을 우선 선택하기 때문입니다:

  1. xinference 1.12.0은 ``huggingface-hub>=0.19.4``를 **직접 종속성**으로 지정합니다 (상한 제약 없음).

  2. 2025년 11월 6일 기준으로 uv는 최신 버전을 선택합니다: huggingface-hub==1.0.1

  3. 그러나 ``transformers<=4.57.3``（``peft``를 통해 도입된 간접 종속성）은 ``huggingface-hub<1.0``을 요구합니다.

  4. 의존성 충돌을 해결하기 위해 uv는 직접 의존성 ``huggingface-hub==1.0.1``을 유지하고, 간접 의존성 ``transformers``를 매우 오래된 버전인 4.12.2로 다운그레이드했습니다.

이는 uv의 설계 특성입니다. 사용자가 명시적으로 지정한 의존성(직접 의존성)을 전이 의존성보다 우선 처리합니다. 참고 링크: astral-sh/uv#16601

업데이트: 2026.01.05 기준, transformers 최신 버전 4.57.3은 여전히 ``huggingface-hub<1.0``에 의존합니다.

해결 방안#

해결 방법 1: huggingface-hub 버전 사전 제한 (권장)

``huggingface-hub``을 호환 가능한 버전 범위로 명시적으로 제한합니다:

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

이렇게 하면 uv가 최신 버전의 transformers``와 호환되는 ``huggingface-hub 버전을 강제로 선택하도록 할 수 있습니다.

해결 방법 2: transformers를 직접 종속성으로 설정

``transformers``를 명시적으로 지정하면, 이것이 직접 의존성이 되어 uv는 더 높은 버전을 우선 선택합니다:

uv pip install transformers xinference

해결 방법 3: pip 사용

또는 직접 ``pip install xinference``를 사용하면, 자동으로 다음 버전 조합으로 해석됩니다:

  • transformers==4.57.1

  • huggingface-hub==0.36.0

  • tokenizers==0.22.1

vLLM + Torch + Xinference 호환성 문제 (세그멘테이션 오류)#

증상#

**vLLM < 0.12.0**을 설치한 상태에서 xinference를 업그레이드하면(특히 ``uv pip install -U xinference``를 사용할 때), xinference가 시작 시 세그멘테이션 오류로 인해 실패할 수 있습니다.

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)

근본 원인#

이 문제는 세 가지 요인이 함께 작용하여 발생합니다.

  1. 바이너리 비호환성: vLLM 0.12.0 이전 버전은 PyTorch 2.8.0을 기반으로 컴파일되었으며, 해당 버전은 PyTorch 2.9와 호환되지 않습니다. 참고: vLLM v0.12.0 릴리스 노트

  2. Xinference가 Torch 의존성에 상한을 설정하지 않음: Xinference의 ``setup.cfg``에서 PyTorch에 대해 버전 상한을 지정하지 않음:

    [options]
install_requires =
    torch                    # No version constraint!

    This allows package managers to upgrade PyTorch to incompatible versions.

  3. 다른 패키지 관리자의 동작 차이:

    • pip: 비교적 보수적 — 의존성이 호환되지 않을 때만 관련 의존성을 업그레이드하며, 그 외에는 지정된 패키지만 업그레이드합니다.

    • -U 매개변수를 사용하는 uv: 전략이 다소 공격적입니다 — 모든 의존성을 다시 분석하고 최신 버전을 선택합니다.

따라서, 전체 기술 스택을 업그레이드할 준비가 되지 않았고 xinference만 업그레이드하려는 경우 다음을 사용할 수 있습니다:

  • `pip install -U xinference` (PyTorch 버전은 유지하고, xinference만 업그레이드)

  • uv pip install "xinference==1.16.0" （-U 플래그를 사용하지 않아도 xinference만 업그레이드됨）