모델 가상 환경#

Added in version v1.5.0.

배경#

일부 모델은 출시 후 더 이상 유지보수되지 않으며, 이들이 의존하는 라이브러리 버전도 오래된 상태로 유지됩니다. 예를 들어, GOT-OCR2 모델은 여전히 transformers 4.37.2에 의존합니다. 이 라이브러리를 새 버전으로 업그레이드하면 모델이 정상적으로 실행되지 않으며, 많은 새로운 모델은 최신 버전의 ``transformers``를 필요로 합니다. 이러한 버전 차이는 의존성 충돌을 초래할 수 있습니다.

해결 방안#

이 문제를 해결하기 위해 모델 가상 환경 기능을 도입했습니다.

다음 명령어를 통해 해당 기능에 필요한 의존성을 설치하세요:

# all
pip install 'xinference[all]'
# or virtualenv
pip install 'xinference[virtualenv]'

환경 변수 ``XINFERENCE_ENABLE_VIRTUAL_ENV=1``를 설정하여 해당 기능을 활성화합니다.

사용 예시:

# For command line
XINFERENCE_ENABLE_VIRTUAL_ENV=1 xinference-local ...

# For Docker
docker run -e XINFERENCE_ENABLE_VIRTUAL_ENV=1 ...

경고

이 기능은 인터넷 연결이 필요하거나, 자체 구축한 PyPI 미러 서비스를 사용해야 합니다.

Xinference는 기본적으로 현재 pip의 구성을 상속합니다.

참고

참고: 가상 환경에서 vLLM/SgLang 엔진 모델을 시작할 때 cuDNN 오류가 발생하면 다음을 설정할 수 있습니다:

export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/cudnn/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/cusparselt/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nccl/lib:$LD_LIBRARY_PATH

버전 v2.0.0에서 변경: Xinference v2.0 부터 모델 가상 환경 기능이 기본적으로 활성화됩니다(즉, ``XINFERENCE_ENABLE_VIRTUAL_ENV``의 기본값은 ``1``입니다).

기능을 전역적으로 비활성화하려면 Xinference를 시작할 때 ``XINFERENCE_ENABLE_VIRTUAL_ENV=0``을 설정하십시오.

이 기능을 활성화하면, Xinference는 모델 로드 시 자동으로 전용 가상 환경을 생성하고 해당 환경에 필요한 종속성을 설치합니다. 이를 통해 모델 간의 종속성 충돌을 방지하고 각 모델이 서로 격리된 환경에서 독립적으로 실행되도록 보장합니다.

가상 환경 관리(v2.0)#

전역 전환#

v2.0 버전부터 가상 환경이 기본적으로 활성화되어 있습니다. 전역 설정을 통해 이 옵션을 재정의할 수 있습니다:

# Enable globally (default)
XINFERENCE_ENABLE_VIRTUAL_ENV=1 xinference-local -H 0.0.0.0 -p 9997

# Disable globally
XINFERENCE_ENABLE_VIRTUAL_ENV=0 xinference-local -H 0.0.0.0 -p 9997

시작 시 모델별로 덮어씀#

모델을 시작할 때 전역 설정을 재정의할 수 있습니다:

# Force enable for this model
xinference launch -n qwen2.5-instruct --model-engine transformers --enable-virtual-env

# Force disable for this model
xinference launch -n qwen2.5-instruct --model-engine transformers --disable-virtual-env

패키지를 시작 시에 추가 또는 덮어쓰기#

명령줄에서 --virtual-env-package 또는 ``-vp``를 사용하여 단일 패키지 버전을 지정합니다.

xinference launch -n qwen2.5-instruct --model-engine transformers \
  --virtual-env-package transformers==4.46.3 \
  --virtual-env-package accelerate==0.33.0

지정한 소프트웨어 패키지가 모델의 기본 가상 환경 패키지 목록에 이미 존재하는 경우, 지정한 버전이 기본 버전을 대체하며 목록에 추가되지 않습니다.

저장 위치#

기본적으로 모델의 가상 환경은 다음 경로에 저장됩니다:

  • v1.6.0 이전: XINFERENCE_HOME / virtualenv / {model_name}

  • v1.6.0에서 v1.13.0으로: XINFERENCE_HOME / virtualenv / v2 / {model_name}

  • v1.14.0부터: XINFERENCE_HOME / virtualenv / v3 / {model_name} / {python_version}

  • v2.0부터: XINFERENCE_HOME / virtualenv / v4 / {model_name} / {model_engine} / {python_version}

이미 설치된 라이브러리 건너뛰기#

Added in version v1.8.1: 이 기능은 ``xoscar >= 0.7.12``를 요구하며, 이는 Xinference v1.8.1에서 필요로 하는 최소 Xoscar 버전입니다.

xinference``는 ``uv 도구를 사용하여 가상 환경을 생성하고, 현재 Python의 시스템 site-packages**를 기본 환경으로 설정합니다. 기본적으로 ``uv``는 **시스템 환경에 이미 패키지가 설치되어 있는지 확인하지 않으며, 가상 환경에 모든 의존성을 다시 설치합니다. 이 방식은 시스템 패키지와 더 잘 격리될 수 있지만, 중복 설치, 초기화 시간 증가 및 디스크 사용량 증가를 초래할 수 있습니다.

``v1.8.1``부터 실험 기능**이 제공됩니다: 환경 변수 ``XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1``을 설정하면, ``uv``가 **시스템 site-packages에 이미 존재하는 패키지를 건너뜁니다.

버전 v2.0에서 변경: 이 기능은 v2.0 버전에서 기본적으로 활성화되어 있습니다. 비활성화하려면 ``XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=0``을 설정하세요.

장점#

  • 반복적으로 큰 의존성을 설치하는 것을 피하십시오 (예: torch + CUDA).

  • 가상 환경 생성 속도 향상.

  • 디스크 공간 사용량 줄이기.

사용#

# Enable experimental feature

# For command line
XINFERENCE_ENABLE_VIRTUAL_ENV=1 XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1 xinference-local ...
# For docker
docker run -e XINFERENCE_ENABLE_VIRTUAL_ENV=1 -e XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1 ...

성능 비교#

CosyVoice 0.5B 모델을 예로 들면:

해당 기능이 켜져 있지 않은 경우:

Installed 98 packages in 187ms
 + aiohappyeyeballs==2.6.1
 + aiohttp==3.12.13
 ...
 + torch==2.7.1
 ...
 + yarl==1.20.1
 + zipp==3.23.0

해당 기능을 켠 후:

Installed 7 packages in 12ms
 + diffusers==0.29.0
 + hf-xet==1.1.5
 + huggingface-hub==0.33.2
 + importlib-metadata==8.7.0
 + pillow==11.3.0
 + typing-extensions==4.14.0
 + urllib3==2.5.0

모델 로드: 가상 환경 전환 및 종속성 사용자 지정#

Added in version v1.8.1.

v1.8.1부터 단일 모델에 대한 가상 환경 로드 스위치를 지원하며, 사용자 정의 패키지 종속성으로 모델의 기본 설정을 재정의할 수 있습니다.

스위치 모델 가상 공간#

모델을 로드할 때, 가상 환경을 활성화할지 여부를 지정할 수 있습니다. 지정하지 않으면 기본적으로 환경 변수의 설정을 따릅니다.

Web UI에서 선택적 설정 스위치를 통해 이 기능을 켜거나 끌 수 있습니다.

actor

명령줄 로딩 시 --enable-virtual-env 옵션을 사용하여 가상 환경을 활성화하고, --disable-virtual-env 옵션을 사용하여 가상 환경을 비활성화합니다.

사용 예시:

xinference launch xxx --enable-virtual-env

가상 환경 패키지 의존성 설정#

지원되는 모델의 경우, Xinference는 가상 환경에서 패키지 종속성 및 버전 요구 사항을 이미 정의했습니다. 하지만 특정 버전을 지정하거나 추가 종속성을 설치해야 하는 경우, 모델을 로드할 때 수동으로 제공할 수 있습니다.

Web UI에서 가상 환경 스위치와 동일한 위치에 있는 더하기 아이콘을 클릭하여 사용자 정의 종속성을 추가할 수 있습니다.

명령줄에서 --virtual-env-package 또는 ``-vp``를 사용하여 단일 패키지 버전을 지정합니다.

사용 예시:

xinference launch xxx --virtual-env-package transformers==4.54.0

일반적인 패키지 의존성 지정 방식(예: transformers==xxx) 외에도, Xinference는 몇 가지 확장 문법을 지원합니다.

  • #system_xxx#: 시스템 site packages와 동일한 버전을 사용합니다. 예를 들어 ``#system_numpy#``는 설치된 패키지 버전이 시스템 site packages의 numpy 버전과 일치하도록 하여 의존성 충돌을 방지합니다.

가상 환경 관리#

Added in version v1.14.0.

Xinference는 각 모델에 대해 독립적인 Python 환경을 생성하여 특정 패키지 의존성 요구 사항을 충족할 수 있는 포괄적인 가상 환경 관리 기능을 제공합니다.

actoractor

핵심 기능#

다중 Python 버전 지원 : 각 모델은 다양한 Python 버전의 가상 환경(예: Python 3.10.18, 3.11.5)을 가질 수 있어 다양한 모델 요구 사항과의 호환성을 실현합니다.

의존성 격리: 각 가상 환경은 자신만의 독립적인 패키지 집합을 포함하여, 서로 다른 모델 간의 의존성 충돌을 방지합니다.

관리 작업#

가상 환경 나열: 클러스터의 모든 가상 환경을 조회하며, 모델 이름 또는 작업 노드 IP 주소로 필터링할 수 있습니다.

환경 생성 : enable_virtual_env=true로 모델을 시작할 때 자동으로 생성됩니다. 시스템은 현재 Python 버전을 감지하고 필요한 패키지가 포함된 독립 환경을 생성합니다.

환경 삭제: 모델 이름과 선택적 Python 버전을 기준으로 특정 가상 환경을 삭제하거나, 모델의 모든 환경을 삭제할 수 있습니다.

ModelHub JSON 형식 (Xinference 모델용)#

Xinference의 Model Hub에 모델을 추가하려는 경우, 모델 JSON에 virtualenv 블록을 정의하십시오. v2.0(v4 workflow)부터는 **엔진 인식 태그 사용을 권장**하며, 이에 따라 단일 JSON 파일이 여러 엔진을 포괄할 수 있습니다.

중요 규칙: 새 모델이 특정 엔진을 지원하는 경우, 반드시 virtualenv.packages``에 해당 엔진의 최소 하나 이상의 패키지 항목을 포함하고, 태그(예: ``#engine# == "vllm")를 추가해야 합니다. 가상 환경이 활성화된 경우, 엔진 사용 가능 여부 확인은 이러한 태그를 통해 검증됩니다.

{
  "virtualenv": {
    "packages": [
      "#transformers_dependencies# ; #engine# == \"transformers\"",
      "#vllm_dependencies# ; #engine# == \"vllm\"",
      "#sglang_dependencies# ; #engine# == \"sglang\"",
      "#llama_cpp_dependencies# ; #engine# == \"llama.cpp\"",
      "#mlx_dependencies# ; #engine# == \"mlx\"",
      "#system_numpy# ; #engine# == \"vllm\""
    ]
  }
}

  • packages (필수): pip 요구 문자열 또는 태그의 목록.

  • inherit_pip_config (기본값: true): 시스템 pip 설정 파일이 존재할 경우 해당 설정을 상속합니다.

  • index_url / extra_index_url / find_links / trusted_host : pip 인덱스 및 미러 제어.

  • index_strategy : 가상 환경 설치 프로그램에 전달됩니다 (일부 엔진에서 사용됨).

  • no_build_isolation ：복잡한 빌드를 처리하기 위한 pip 빌드 격리 스위치입니다.

패키지된 플레이스홀더를 사용하여 엔진 기본값 주입:

  • #vllm_dependencies#

  • #sglang_dependencies#

  • #mlx_dependencies#

  • #transformers_dependencies#

  • #llama_cpp_dependencies#

  • #diffusers_dependencies#

  • #sentence_transformers_dependencies#

#engine# 또는 #model_engine#``를 사용하여 비교합니다(대소문자 구분). 엔진 값은 내부적으로 소문자로 전달되므로, ``#engine# == "vllm" 또는 ``#engine# == “transformers”``와 같이 소문자 값을 사용하는 것을 권장합니다.