vLLM이란 무엇인가? vLLM 설치 및 사용 방법 설명

vLLM에 대한 종합 가이드에 오신 것을 환영합니다! 대형 언어 모델(LLM) 세계에 관련된 분이라면 추론 속도와 처리량의 문제에 직면했을 것입니다. 이러한 대규모 모델을 효율적으로 제공하는 것은 병목 현상이 될 수 있습니다. 여기에서 vLLM이 혁신적인 솔루션으로 등장합니다. 이 튜토리얼에서는 초보자로서 알아야 할 모든 것, 즉 vLLM이 무엇인지, 왜 중요한지, 어떻게 설치하는지, 오프라인 배치 처리 및 온라인 제공에 어떻게 사용하는지를 안내합니다.

vLLM은 정확히 무엇인가요?

본질적으로, vLLM은 대형 언어 모델(LLM) 추론 및 제공을 위해 특별히 설계된 고처리량 및 메모리 효율적인 라이브러리입니다. 기존 제공 시스템의 성능 한계를 극복하고자 하는 연구자와 엔지니어들에 의해 개발된 vLLM은 LLM에서 예측(추론)을 얻는 과정을 상당히 가속화합니다.

전통적인 LLM 추론 방법은 모델의 주의 메커니즘(특히 KV 캐시)의 대규모 메모리 요구 사항을 관리하고 들어오는 요청을 효율적으로 배치하는 데 어려움을 겪습니다. vLLM은 이러한 문제를 정면으로 해결하기 위해 PagedAttention와 같은 새로운 기술을 도입합니다. 이는 훨씬 더 높은 처리량(초당 처리되는 요청 수)을 허용하고, 동시 요청을 처리할 때 많은 표준 Hugging Face Transformers 구현이나 다른 제공 프레임워크에 비해 모델을 더 빠르고 비용 효율적으로 제공할 수 있습니다.

vLLM을 미리 훈련된 LLM을 실행하는 매우 최적화된 엔진으로 생각해 보세요. 모델과 프롬프트를 제공하면 vLLM이 단일 대규모 프롬프트 배치 또는 배포된 모델과 상호 작용하는 많은 동시 사용자에 대해 신속하고 효율적으로 텍스트를 생성하는 복잡한 작업을 처리합니다.

LLM 추론에 vLLM을 선택해야 하는 이유는 무엇인가요?

여러 가지 설득력 있는 이유로 인해 vLLM은 LLM과 함께 작업하는 개발자와 조직에서 선호하는 선택입니다:

최첨단 성능: vLLM은 많은 기준 구현에 비해 상당히 높은 처리량을 제공합니다. 이는 동시에 더 많은 사용자 요청을 처리하거나 동일한 하드웨어로 대규모 데이터 세트를 더 빠르게 처리할 수 있음을 의미합니다.
효율적인 메모리 관리: 핵심 혁신인 PagedAttention은 KV 캐시를 보다 효과적으로 관리하여 메모리 낭비를 극적으로 줄입니다. 이로 인해 더 큰 모델을 GPU에 적재하거나 기존 모델을 더 적은 메모리 오버헤드로 제공할 수 있어 하드웨어 비용을 줄일 수 있습니다.
지속적인 배치 처리: vLLM은 정적 배치(서버가 처리하기 위해 전체 배치를 기다리는 경우)와는 달리 지속적인 배치 처리를 사용합니다. 요청이 도착하는 대로 동적으로 처리하여 GPU 활용도를 크게 높이고 개별 요청의 대기 시간을 줄입니다.
OpenAI 호환 서버: vLLM에는 OpenAI API를 모방하는 내장 서버가 포함되어 있습니다. 이를 통해 OpenAI Python 클라이언트 또는 호환 도구를 사용하여 이미 구축된 애플리케이션에 vLLM을 쉽게 드롭인 대체품으로 사용할 수 있습니다. 종종 엔드포인트 URL과 API 키를 변경하면 기존 코드가 자가 호스팅된 vLLM 인스턴스와 함께 작동합니다.
사용 용이성: 복잡한 내부 구조에도 불구하고, vLLM은 오프라인 추론(LLM 클래스) 및 온라인 제공(vllm serve 명령) 모두에 대해 상대적으로 간단한 API를 제공합니다.
광범위한 모델 호환성: vLLM은 Hugging Face Hub(및 가능성 있는 ModelScope)에 있는 다양한 인기 오픈 소스 LLM을 지원합니다.
활발한 개발 및 커뮤니티: vLLM은 지속적으로 개선되고 버그 수정이 이루어지는 활성 유지 관리 오픈 소스 프로젝트로, 새로운 모델과 기능에 대한 지원을 보장합니다.
최적화된 커널: vLLM은 다양한 작업을 위해 고도로 최적화된 CUDA 커널을 사용하여 NVIDIA GPU에서 성능을 더욱 향상시킵니다.

속도, 효율성 및 확장성이 LLM 애플리케이션에서 중요하다면 vLLM은 진지하게 고려해야 할 기술입니다.

vLLM은 어떤 모델을 지원하나요?

vLLM은 Hugging Face Hub에서 호스팅되는 다양한 인기 있는 변환기 기반 모델을 지원합니다. 여기에는 다음과 같은 많은 변형이 포함됩니다:

Llama (Llama, Llama 2, Llama 3)
Mistral & Mixtral
Qwen & Qwen2
GPT-2, GPT-J, GPT-NeoX
OPT
블룸
팔콘
MPT
그리고 다수의 멀티모달 모델을 포함한 많은 다른 모델들.

리스트는 지속적으로 증가하고 있습니다. 공식적으로 지원되는 모델의 가장 최신 목록은 항상 공식 vLLM 문서를 참조하세요:

vLLM 지원 모델 목록

모델이 명시적으로 나열되지 않은 경우, 아키텍처가 지원되는 모델과 유사하다면 작동할 수도 있습니다 하지만 공식 지원이나 테스트 없이 호환성은 보장되지 않습니다. 새로운 모델 아키텍처를 추가하려면 일반적으로 vLLM 프로젝트에 대한 코드 기여가 필요합니다.

몇 가지 주요 vLLM 용어:

vLLM은 겉으로 보기에는 사용하기 쉽지만, 몇 가지 핵심 개념을 이해하면 그 이유를 감상하는 데 도움이 됩니다:

PagedAttention: 이것은 vLLM의 주력 기능입니다. 전통적인 주의 메커니즘에서는 키-값(KV) 캐시(생성을 위한 중간 결과를 저장하는)가 연속적인 메모리 블록을 요구합니다. 이로 인해 단편화와 메모리 낭비(내부 및 외부)가 발생합니다. PagedAttention은 운영 체제의 가상 메모리처럼 작동합니다. KV 캐시를 비연속 블록(페이지)으로 나누어 훨씬 더 유연하고 효율적인 메모리 관리를 가능하게 합니다. 이는 메모리 오버헤드를 크게 줄이며(개발자가 보고한 경우 최대 90%까지) 메모리 중복 없이 공유 접두사와 같은 기능을 가능하게 합니다.
지속적인 배치 처리: 고정된 수의 요청이 도착할 때까지 계산을 기다리는 대신(정적 배치), 지속적인 배치 처리는 vLLM 엔진이 배치 내에서 이전의 시퀀스 생성이 완료되는 즉시 새 시퀀스를 처리하기 시작할 수 있도록 합니다. 이를 통해 GPU가 지속적으로 바쁘게 유지되어 처리량을 극대화하고 요청의 평균 대기 시간을 줄입니다.

이 두 기술은 함께 시너지 효과를 발휘하여 vLLM의 인상적인 성능 특성을 제공합니다.

vLLM을 시작하기 전에 확인해야 할 사항:

vLLM을 설치하고 실행하기 전에 시스템이 다음 요구 사항을 충족하는지 확인하세요:

운영 체제: 리눅스는 주요 지원 OS입니다. 다른 OS(예: Windows의 WSL2 또는 macOS)에 대한 커뮤니티 노력도 있을 수 있지만 리눅스는 가장 간단하고 공식적으로 지원되는 경험을 제공합니다.
Python 버전: vLLM은 Python 3.9, 3.10, 3.11 또는 3.12가 필요합니다. Python 종속성을 관리하기 위해 가상 환경을 사용하는 것이 강력히 권장됩니다.
NVIDIA GPU 및 CUDA: 최적의 성능과 핵심 기능에 접근하기 위해서는 PyTorch가 지원하는 계산 능력을 가진 NVIDIA GPU가 필요하며 필요한 CUDA 툴킷이 설치되어 있어야 합니다. vLLM은 최적화된 커널을 위해 CUDA에 대한 의존성이 큽니다. CPU 전용 추론과 다른 가속기(예: AMD GPU 또는 AWS Inferentia/Trainium)에 대한 지원은 제공되거나 개발 중에 있지만, 기본 경로는 NVIDIA 하드웨어입니다. 특정 GPU 드라이버 버전과의 CUDA 호환성은 공식 PyTorch 웹사이트를 확인하세요.
PyTorch: vLLM은 PyTorch 기반으로 구축되었습니다. 설치 과정에서 일반적으로 호환되는 버전을 자동으로 설치하지만 문제가 발생하면 CUDA 버전과 호환되는 작업 중인 PyTorch 설치가 필요합니다.

vLLM 설치 단계별 가이드

vLLM을 설치하는 권장 방법은 가상 환경 내에서 패키지 관리자를 사용하는 것입니다. 이렇게 하면 다른 Python 프로젝트와의 충돌을 방지할 수 있습니다. 다음은 인기 있는 도구를 사용한 단계입니다:

vLLM과 함께 pip 사용하기

pip는 표준 Python 패키지 설치 프로그램입니다.

가상 환경 만들기 및 활성화(권장):

python -m venv vllm-env
source vllm-env/bin/activate
# Windows에서는 다음을 사용: vllm-env\\\\Scripts\\\\activate

vLLM 설치:

pip install vllm

이 명령은 최신 안정 버전의 vLLM과 해당 핵심 종속성, 발견된 CUDA 설정에 맞는 PyTorch의 호환 버전을 다운로드하고 설치합니다(가능한 경우).

vLLM과 함께 Conda 사용하기

Conda는 특히 데이터 과학 커뮤니티에서 인기 있는 또 다른 환경 및 패키지 관리 도구입니다.

Conda 환경 만들기 및 활성화:

conda create -n vllm-env python=3.11 -y # 또는 3.9, 3.10, 3.12 사용
conda activate vllm-env

Conda 내에서 pip를 사용하여 vLLM 설치: Conda 환경 내에서 vLLM을 설치할 때는 최신 호환 빌드를 쉽게 얻기 위해 pip를 사용하는 것이 일반적으로 권장됩니다.

pip install vllm

더 나은 관리를 원한다면 먼저 Conda를 통해 PyTorch를 별도로 설치해야 할 수도 있습니다: conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia(필요에 따라 CUDA 버전 조정). 그 후 pip install vllm를 실행합니다.

vLLM과 함께 uv 사용하기

uv는 최신의 매우 빠른 Python 패키지 설치기 및 해결자입니다.

uv 설치(아직 설치하지 않았다면): 공식 uv 문서의 지침을 따르세요.

uv를 사용하여 환경 만들기 및 활성화:

uv venv vllm-env --python 3.12 --seed # 또는 3.9, 3.10, 3.11 사용
source vllm-env/bin/activate
# Windows에서는 다음을 사용: vllm-env\\\\Scripts\\\\activate

uv를 사용하여 vLLM 설치:

uv pip install vllm

vLLM 설치 확인

설치 후 Python 인터프리터에서 vLLM을 임포트하거나 기본 명령을 실행하여 빠르게 확인할 수 있습니다:

# 먼저 가상 환경을 활성화하세요(예: source vllm-env/bin/activate)
python -c "import vllm; print(vllm.__version__)"

이 명령은 오류 없이 설치된 vLLM 버전을 출력해야 합니다.

또는 서버의 도움 명령을 시도하세요(성공적인 설치가 필요합니다):

vllm --help

vLLM로 오프라인 배치 추론 수행하기

오프라인 배치 추론은 미리 정의된 입력 프롬프트 목록에 대해 텍스트를 한 번에 생성하는 것을 의미합니다. 이것은 모델 평가, 데이터 세트에 대한 응답 생성 또는 결과를 미리 계산하는 작업에 유용합니다. vLLM은 LLM 클래스를 사용하여 이를 효율적으로 수행합니다.

vLLM의 `LLM` 클래스 이해하기

vllm.LLM 클래스는 오프라인 추론의 주요 진입점입니다. 사용할 모델을 지정하여 초기화합니다.

from vllm import LLM

# Hugging Face Hub의 모델로 LLM 엔진 초기화
# 선택한 모델에 충분한 GPU 메모리가 있는지 확인하세요!
# 예: 보다 작은 모델인 OPT-125m 사용
llm = LLM(model="facebook/opt-125m")

# 예: 상당한 GPU 메모리가 필요한 Llama-3-8B-Instruct와 같은 더 큰 모델 사용
# llm = LLM(model="meta-llama/Meta-Llama-3-8B-Instruct")

print("vLLM 엔진 초기화 완료.")

기본적으로 vLLM은 Hugging Face Hub에서 모델을 다운로드합니다. 모델이 ModelScope에 호스팅되어 있는 경우, Python 스크립트를 실행하기 VLLM_USE_MODELSCOPE=1 환경 변수를 설정해야 합니다.

vLLM 샘플링 매개변수 구성하기

텍스트 생성 방식을 제어하려면 vllm.SamplingParams 클래스를 사용합니다. 이를 통해 다음과 같은 매개변수를 설정할 수 있습니다:

temperature: 무작위성을 제어합니다. 낮은 값(예: 0.2)은 출력이 보다 결정적이고 집중되게 하고, 높은 값(예: 0.8)은 무작위성을 증가시킵니다.
top_p (누클리어스 샘플링): 누적 확률이 top_p를 초과하는 가장 확률이 높은 토큰만 고려합니다. 일반적인 값은 0.95입니다.
top_k: 각 단계에서 가장 확률이 높은 top_k 개의 토큰만 고려합니다.
max_tokens: 각 프롬프트에 대해 생성할 최대 토큰 수입니다.
stop: 생성되는 경우 해당 프롬프트의 생성 프로세스를 중지할 문자열 목록입니다.

from vllm import SamplingParams

# 샘플링 매개변수 정의
# 지정하지 않으면 vLLM은 모델의 generation_config.json에서 기본값을 사용할 수 있습니다.
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=100, # 생성된 텍스트의 길이를 제한합니다.
    stop=["\\\\n", " Human:", " Assistant:"] # 이러한 토큰이 나타나면 생성을 중지합니다.
)

print("샘플링 매개변수 구성 완료.")

중요 참고 사항: 기본적으로 vLLM은 Hugging Face Hub에 있는 모델과 관련된 generation_config.json 파일에서 설정을 불러오고 사용하려고 시도합니다. 이를 무시하고 기본 샘플링 매개변수를 사용하고 싶다면, llm = LLM(model="...", generation_config="vllm")와 같이 LLM 클래스를 초기화하세요. 샘플링 매개변수 객체를 generate 메서드에 전달할 경우, 해당 매개변수가 모델의 구성 및 vLLM의 기본값보다 항상 우선합니다.

자신의 첫 vLLM 배치 작업 실행하기

이제 LLM 객체, SamplingParams 및 프롬프트 목록을 결합하여 텍스트를 생성해 보겠습니다.

from vllm import LLM, SamplingParams

# 1. 입력 프롬프트 정의
prompts = [
    "프랑스의 수도는",
    "상대성 이론을 간단한 용어로 설명하세요:",
    "비 오는 날에 대한 짧은 시를 작성하세요:",
    "Hello, world!를 독일어로 번역하세요:",
]

# 2. 샘플링 매개변수 구성
sampling_params = SamplingParams(temperature=0.7, top_p=0.95, max_tokens=150)

# 3. vLLM 엔진 초기화(하드웨어에 적합한 모델 사용)
try:
    # 상대적으로 작고 유능한 모델 사용
    llm = LLM(model="mistralai/Mistral-7B-Instruct-v0.1")
    # 또는 더 작은 GPU의 경우:
    # llm = LLM(model="facebook/opt-1.3b")
    # llm = LLM(model="facebook/opt-125m")
except Exception as e:
    print(f"LLM 초기화 오류: {e}")
    print("GPU 메모리가 충분한지 확인하고 CUDA가 올바르게 설정되었는지 확인하세요.")
    exit()

# 4. 프롬프트에 대한 텍스트 생성
# generate 메서드는 프롬프트 목록과 샘플링 매개변수를 받습니다.
print("응답 생성 중...")
outputs = llm.generate(prompts, sampling_params)
print("생성 완료.")

# 5. 결과 출력
# 출력은 RequestOutput 객체 목록입니다.
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text # 생성된 시퀀스에서 텍스트 가져오기
    print("-" * 20)
    print(f"프롬프트: {prompt!r}")
    print(f"생성된 텍스트: {generated_text!r}")
    print("-" * 20)

이 스크립트는 vLLM을 초기화하고, 프롬프트와 매개변수를 정의하며, 배치에서 효율적으로 생성 프로세스를 실행한 후 각 프롬프트에 대한 출력을 인쇄합니다. llm.generate() 호출은 내부적으로 배치 처리 및 GPU 실행의 복잡성을 처리합니다.

vLLM OpenAI 호환 서버 설정하기

vLLM의 가장 강력한 기능 중 하나는 OpenAI API와 동일한 언어로 작동하는 고성능 백엔드 서버로 작용할 수 있는 것입니다. 이를 통해 자신의 오픈 소스 모델을 쉽게 호스팅하고 OpenAI를 위해 설계된 애플리케이션에 통합할 수 있습니다.

vLLM 서버 시작하기

서버를 시작하는 것은 터미널에서 vllm serve 명령을 사용하여 간단합니다.

vLLM이 설치된 가상 환경을 활성화하세요.

source vllm-env/bin/activate

vllm serve 명령 실행: 제공할 모델을 지정해야 합니다.

# Mistral-7B-Instruct 사용 예제
vllm serve mistralai/Mistral-7B-Instruct-v0.1

# Qwen2-1.5B-Instruct와 같은 더 작은 모델 사용 예제
# vllm serve Qwen/Qwen2-1.5B-Instruct

이 명령은:

지정된 모델을 다운로드합니다(이미 캐시되지 않은 경우).
모델을 GPU에 로드합니다.
웹 서버를 시작합니다(기본적으로 Uvicorn 사용).
들어오는 API 요청을 수신 대기를 합니다. 일반적으로 http://localhost:8000에서 수신 대기합니다.

일반 옵션:

-model <model_name_or_path>: (필수) 제공할 모델입니다.
-host <ip_address>: 서버를 바인딩할 IP 주소입니다(예: 0.0.0.0는 네트워크에서 접근 가능하도록 합니다). 기본값은 localhost입니다.
-port <port_number>: 수신 대기할 포트입니다. 기본값은 8000입니다.
-tensor-parallel-size <N>: 다중 GPU 제공을 위해 N개의 GPU에 걸쳐 모델을 분할합니다.
-api-key <your_key>: 설정되면 서버는 들어오는 요청의 Authorization: Bearer <your_key> 헤더에서 이 API 키를 기대합니다. 또한 VLLM_API_KEY 환경 변수를 설정할 수 있습니다.
-generation-config vllm: 모델의 generation_config.json 대신 vLLM의 기본 샘플링 매개변수를 사용합니다.
-chat-template <path_to_template_file>: 토크나이저 구성에 정의된 대신 사용자 지정 Jinja 채팅 템플릿 파일을 사용합니다.

서버는 실행 중임을 나타내는 로그를 출력하여 요청을 수용할 준비가 된 상태입니다.

vLLM 서버와 상호작용하기: 완료 API

서버가 실행 중이면 OpenAI의 이전 완료 API처럼 /v1/completions 엔드포인트에 요청을 보낼 수 있습니다.

curl 사용하기:

curl <http://localhost:8000/v1/completions> \\\\
    -H "Content-Type: application/json" \\\\
    -d '{
        "model": "mistralai/Mistral-7B-Instruct-v0.1",
        "prompt": "샌프란시스코는 도시입니다",
        "max_tokens": 50,
        "temperature": 0.7
    }'

(제공 중인 실제 모델로 "mistralai/Mistral-7B-Instruct-v0.1"를 교체하세요)

openai Python 라이브러리 사용하기:

from openai import OpenAI

# 클라이언트를 vLLM 서버 엔드포인트로 지정합니다.
client = OpenAI(
    api_key="EMPTY", # --api-key로 설정한 경우 "EMPTY" 또는 실제 키를 사용하세요.
    base_url="<http://localhost:8000/v1>"
)

print("vLLM 서버에 요청 전송 중(완료)...")

try:
    completion = client.completions.create(
        model="mistralai/Mistral-7B-Instruct-v0.1", # 모델 이름은 제공된 것과 일치해야 합니다.
        prompt="vLLM 사용의 장점을 설명하세요:",
        max_tokens=150,
        temperature=0.5
    )

    print("응답:")
    print(completion.choices[0].text)

except Exception as e:
    print(f"오류 발생: {e}")

(제공 중인 다른 모델이 있다면 모델 이름을 바꾸는 것을 잊지 마세요)

vLLM 서버와 상호작용하기: 채팅 완료 API

vLLM은 대화형 모델 및 구조화된 메시지 형식(시스템, 사용자, 도우미 역할)에 적합한 /v1/chat/completions 엔드포인트를 지원합니다.

curl 사용하기:

curl <http://localhost:8000/v1/chat/completions> \\\\
    -H "Content-Type: application/json" \\\\
    -d '{
        "model": "mistralai/Mistral-7B-Instruct-v0.1",
        "messages": [
            {"role": "system", "content": "당신은 유용한 도우미입니다."},
            {"role": "user", "content": "vLLM에서 PagedAttention의 주요 장점은 무엇인가요?"}
        ],
        "max_tokens": 100,
        "temperature": 0.7
    }'

(필요에 따라 모델 이름을 교체하세요)

openai Python 라이브러리 사용하기:

from openai import OpenAI

# 클라이언트를 vLLM 서버 엔드포인트로 지정합니다.
client = OpenAI(
    api_key="EMPTY", # 실제 키나 "EMPTY"를 사용합니다.
    base_url="<http://localhost:8000/v1>"
)

print("vLLM 서버에 요청 전송 중(채팅 완료)...")

try:
    chat_response = client.chat.completions.create(
        model="mistralai/Mistral-7B-Instruct-v0.1", # 모델 이름은 제공된 것과 일치해야 합니다.
        messages=[
            {"role": "system", "content": "당신은 유용한 프로그래밍 도우미입니다."},
            {"role": "user", "content": "팩토리얼을 계산하는 간단한 Python 함수를 작성하세요."}
        ],
        max_tokens=200,
        temperature=0.5
    )

    print("응답:")
    print(chat_response.choices[0].message.content)

except Exception as e:
    print(f"오류 발생: {e}")

(필요한 경우 모델 이름을 변경하는 것을 잊지 마세요)

OpenAI 호환 서버를 사용하는 것은 기존 애플리케이션 논리를 거의 변경하지 않고 고성능 LLM 추론 엔드포인트를 배포할 수 있는 강력한 방법입니다.

vLLM 주의 백엔드에 대해 이야기해 봅시다

vLLM은 주의 메커니즘을 효율적으로 계산하기 위해 전문화된 "백엔드"를 활용합니다. 이러한 백엔드는 주로 NVIDIA GPU를 목표로 다양한 라이브러리 또는 기술을 활용하여 최적화된 구현입니다. 백엔드의 선택은 성능과 메모리 사용에 영향을 미칠 수 있습니다. 주요 백엔드는 다음과 같습니다:

FlashAttention: FlashAttention 라이브러리(버전 1 및 2)를 사용합니다. FlashAttention은 계산 속도를 크게 높이고 GPU 고대역폭 메모리(HBM)에서 대규모 중간 주의 행렬을 실제로 필요로 하지 않아 메모리 사용을 줄이는 매우 최적화된 주의 알고리즘입니다. 최신 GPU(예: Ampere, Hopper 아키텍처) 및 시퀀스 길이에 대해 종종 가장 빠른 옵션입니다. vLLM은 일반적으로 FlashAttention 지원을 포함한 미리 빌드된 휠을 포함하고 있습니다.
Xformers: Meta AI에서 개발한 xFormers 라이브러리를 활용합니다. xFormers 또한 MemoryEfficientAttention와 같은 메모리 효율적인 최적화된 주의 구현을 제공합니다. 다양한 GPU 아키텍처에 대한 광범위한 호환성을 제공하며, FlashAttention이 사용할 수 없거나 특정 시나리오에 최적이 아닌 경우 좋은 대안이나 백업이 될 수 있습니다. vLLM의 표준 설치는 종종 xFormers 지원을 포함합니다.
FlashInfer: FlashInfer 라이브러리를 이용한 보다 최근의 백엔드 옵션입니다. FlashInfer는 LLM 배포를 위해 특별히 조정된 고도로 최적화된 커널을 제공하며, 스펙ulative 디코딩 및 페이지 처리가 된 KV 캐시를 효율적으로 처리하는 기능을 포함하여 다양한 미리 채우기 및 디코딩 시나리오에 초점을 맞추고 있습니다. FlashInfer를 사용할 경우, 환경에 별도로 설치해야 합니다 및 vLLM이 이를 사용할 수 있습니다. FlashInfer를 사용하려면 공식 문서나 vLLM Dockerfiles에서 설치 지침을 참조하십시오.

자동 백엔드 선택: 기본적으로 vLLM은 하드웨어(GPU 아키텍처), 설치된 라이브러리(FlashAttention/xFormers/FlashInfer가 사용 가능한지) 및 사용되는 특정 모델을 기준으로 가장 적합하고 성능 높은 주의 백엔드를 자동으로 감지합니다. 이는 호환성을 보장하기 위한 검사를 수행하고 수동 구성 없이도 최상의 기본 성능을 제공하는 것을 목표로 합니다.

수동 백엔드 선택: 일부 고급 사용 사례나 벤치마킹 목적을 위해 vLLM이 특정 백엔드를 사용하도록 강제할 수 있습니다. 이를 위해 vLLM 프로세스를 시작하기 전에 VLLM_ATTENTION_BACKEND 환경 변수를 설정할 수 있습니다(오프라인 스크립트 또는 서버 모두 적용 가능).

# 예: FlashAttention 강제 사용(설치되고 호환되는 경우)
export VLLM_ATTENTION_BACKEND=FLASH_ATTN
python your_offline_script.py
# 또는
# export VLLM_ATTENTION_BACKEND=FLASH_ATTN
# vllm serve your_model ...

# 예: xFormers 강제 사용
export VLLM_ATTENTION_BACKEND=XFORMERS
python your_offline_script.py

# 예: FlashInfer 강제 사용(사전에 설치할 필요 있음)
export VLLM_ATTENTION_BACKEND=FLASHINFER
python your_offline_script.py

대부분의 초보자에게는 vLLM의 자동 백엔드 선택을 신뢰하는 것이 권장됩니다. 백엔드를 수동으로 설정하는 것은 일반적으로 실험이나 특정 성능 문제 해결을 위해 예약되어 있습니다.

vLLM 설치 및 사용 중 발생하는 일반적인 문제 해결

vLLM은 사용의 용이성을 목표로 하지만 설치 중 일반적인 장애물에 직면할 수 있습니다. 다음은 자주 발생하는 문제와 그 가능성 있는 솔루션입니다:

CUDA 메모리 부족(Out of Memory, OOM) 오류:

문제: torch.cuda.OutOfMemoryError: CUDA out of memory와 같은 오류가 발생합니다.
원인: 로드하려는 LLM이 하드웨어에서 사용 가능한 것보다 더 많은 GPU VRAM을 필요로 합니다. 더 큰 모델(예: 7B 파라미터 이상)은 상당한 메모리를 소비합니다.
해결책:
더 작은 모델 사용: 먼저 더 작은 변형(ex: opt-1.3b, Qwen/Qwen2-1.5B-Instruct)을 로드해 보세요.
배치 크기 줄이기(서버): vLLM은 동적으로 배치를 처리하지만, 지나치게 높은 동시 처리량은 여전히 메모리를 초과할 수 있습니다. 사용량을 모니터링하세요.
양자화 사용: 양자화된 모델 버전(예: AWQ, GPTQ, GGUF - 지원되는 양자화 유형은 vLLM 문서를 확인하세요)을 로드합니다. 양자화는 메모리 사용량을 줄이고, 정확도에 짧은 거래를 포함하는 경우도 많습니다. 예를 들면: llm = LLM(model="TheBloke/Mistral-7B-Instruct-v0.1-AWQ")로 변환할 수 있습니다. 특정 양자화 라이브러리는 설치가 필요할 수 있습니다.
텐서 병렬 처리: 다중 GPU가 있는 경우, 서버를 시작할 때 -tensor-parallel-size N 인수를 사용하거나 LLM 클래스를 초기화할 때 tensor_parallel_size=N를 사용하여 모델을 N개 GPU에 분산합니다.
다른 프로세스 확인: 다른 애플리케이션이 상당한 GPU 메모리를 소모하고 있지 않은지 확인하세요. nvidia-smi를 사용하여 메모리 사용량을 확인하세요.

설치 오류(CUDA/PyTorch 호환성):

문제: pip install vllm가 CUDA, PyTorch 또는 컴파일 확장과 관련된 오류로 실패합니다.
원인: 설치된 NVIDIA 드라이버, CUDA 툴킷 버전 및 vLLM이 설치하거나 사용하려는 PyTorch 버전 간의 불일치입니다.
해결책:
호환성 확인: NVIDIA 드라이버 버전이 사용하려는 PyTorch 빌드에 필요한 CUDA 툴킷 버전을 지원하는지 확인하세요. PyTorch 웹사이트의 설치 매트릭스를 참조하세요.
PyTorch 수동 설치: 때때로, vLLM 설치 전에 호환되는 PyTorch 버전을 명시적으로 설치하면 도움이 됩니다. PyTorch 공식 웹사이트로 가서 OS, 패키지 관리자(pip/conda), 컴퓨팅 플랫폼(CUDA 버전)을 선택하고 제공된 명령을 실행한 후 pip install vllm를 실행하세요.
공식 Docker 이미지 사용: 공식 vLLM Docker 이미지를 사용하는 것을 고려하세요. 이 이미지는 CUDA, PyTorch 및 vLLM의 호환 버전이 미리 구성되어 손쉬운 설치 과정을 제공합니다. Docker Hub에서 vllm/vllm-openai를 확인하세요.
빌드 도구 확인: 필요한 빌드 도구가 설치되어 있는지(build-essential on Debian/Ubuntu와 동등한) 확인하세요.

모델 로딩 실패:

문제: vLLM이 지정된 모델을 로드하지 못하고 "찾을 수 없음" 오류가 발생하거나 구성 문제가 발생합니다.
원인: 잘못된 모델 이름/경로, 모델이 원격 코드를 신뢰해야 함, 모델 형식 문제 또는 다운로드를 방해하는 네트워크 문제입니다.
해결책:
모델 이름 확인: Hugging Face Hub 식별자를 다시 확인하세요(예: mistralai/Mistral-7B-Instruct-v0.1).
원격 코드 신뢰: 일부 모델은 해당 리포지토리에서 정의된 사용자 지정 코드를 실행해야 합니다. LLM 클래스의 경우, trust_remote_code=True를 사용하세요. 서버의 경우, -trust-remote-code 플래그를 사용하세요: vllm serve my_model --trust-remote-code. 이 작업은 모델 소스에 대한 신뢰가 있는 경우에만 수행하세요.
로컬 경로 사용: 모델이 로컬에 다운로드되어 있는 경우, 모델 파일 및 토크나이저 구성 파일을 포함하는 디렉토리의 경로를 제공하세요: llm = LLM(model="/path/to/local/model").
디스크 공간 확인: 모델 가중치를 다운로드할 충분한 디스크 공간이 있는지 확인하세요(수십 GB가 필요할 수 있습니다).
네트워크 문제: 인터넷 연결을 확인하세요. 프록시 뒤에 있는 경우, HTTP_PROXY 및 HTTPS_PROXY 환경 변수를 구성하세요.

느린 성능:

문제: 추론 속도가 예상보다 훨씬 낮습니다.
원인: 최적의 주의 백엔드가 선택되지 않음, CPU 백엔드로 떨어짐, 비효율적인 샘플링 매개변수, 시스템 병목 현상입니다.
해결책:
GPU 활용도 확인: nvidia-smi 또는 nvtop을 사용하여 추론 동안 GPU가 완전히 활용되고 있는지 확인하세요. 그렇지 않다면 병목 현상이 다른 곳(CPU 전처리, 데이터 로딩)에 있을 수 있습니다.
vLLM 및 종속성 업데이트: vLLM, PyTorch, CUDA 드라이버 및 FlashAttention/xFormers와 같은 라이브러리를 최신 버전으로 사용하세요.
주의 백엔드 실험: 자동 선택은 일반적으로 좋지만 VLLM_ATTENTION_BACKEND를 수동으로 설정해 보세요(이전 섹션 참조). 다른 백엔드가 특정 하드웨어/모델 조합에 대해 더 잘 수행되는지 확인하세요.
샘플링 매개변수 검토: 매우 큰 max_tokens 값은 각 요청당 더 긴 생성 시간을 초래할 수 있습니다.

부정확한 출력 또는 어법:

문제: 모델이 무의미한 텍스트를 생성하거나 과도하게 반복하거나 지침을 따르지 않습니다.
원인: 잘못된 프롬프트 형식(특히 지침/채팅 모델의 경우), 부적절한 샘플링 매개변수, 모델 가중치 자체의 문제 또는 잘못된 채팅 템플릿 적용입니다.
해결책:
프롬프트 형식 확인: 프롬프트가 특정 모델이 훈련된 형식에 부합하는지 확인하세요(예: Llama/Mistral 지침 모델의 경우 [INST], <s>, </s>와 같은 특수 토큰 사용). 형식 지침은 Hugging Face의 모델 카드에서 확인하세요.
샘플링 매개변수 조정: 높은 temperature는 일관성을 잃을 수 있습니다. 매우 낮은 temperature는 반복을 발생시킬 수 있습니다. temperature, top_p, top_k 및 repetition_penalty로 실험해 보세요.
모델 확인: 다른 정상적인 모델로 시도하여 다운로드한 특정 모델 가중치와의 문제를 배제하세요.
채팅 템플릿(서버): 채팅 완료 API를 사용할 때 올바른 채팅 템플릿이 적용되고 있는지 확인하세요. vLLM은 일반적으로 이를 토크나이저 구성에서 로드합니다. 문제가 지속되면 서버 시작 시 -chat-template 인수를 사용하여 사용자 지정 템플릿을 제공해야 할 수도 있습니다.