Hugging Face 통합

Hugging Face 통합 (Integration with Hugging Face)

이 문서는 vLLM이 Hugging Face 라이브러리와 어떻게 통합되는지 설명합니다. vllm serve를 실행할 때 내부적으로 어떤 일이 벌어지는지 단계별로 살펴봅니다.

vllm serve Qwen/Qwen2-7B를 실행해 인기 있는 Qwen 모델을 서빙한다고 가정해 보겠습니다.

출처: 문서

본문

  • model 인자는 Qwen/Qwen2-7B입니다. vLLM은 대응하는 구성 파일 config.json이 있는지 확인해 이 모델이 존재하는지 판단합니다. 구현은 이 코드 스니펫을 참고하세요. 이 과정에서:
    • model 인자가 존재하는 로컬 경로에 해당하면 vLLM은 그 경로에서 구성 파일을 직접 로드합니다.
    • model 인자가 사용자 이름과 모델 이름으로 이루어진 Hugging Face 모델 ID라면, vLLM은 먼저 Hugging Face 로컬 캐시에서 model 인자를 모델 이름으로, --revision 인자를 리비전으로 사용해 구성 파일을 가져오려 시도합니다. Hugging Face 캐시 동작에 대한 자세한 내용은 그들의 웹사이트를 참고하세요.
    • model 인자가 Hugging Face 모델 ID지만 캐시에서 찾을 수 없으면, vLLM은 Hugging Face 모델 허브에서 구성 파일을 다운로드합니다. 구현은 이 함수를 참고하세요. 입력 인자에는 model 인자를 모델 이름으로, --revision 인자를 리비전으로, 환경 변수 HF_TOKEN을 모델 허브 접근 토큰으로 사용합니다. 우리 경우 vLLM은 config.json 파일을 다운로드합니다.
  • 모델 존재를 확인한 뒤 vLLM은 구성을 로드해 딕셔너리로 변환합니다. 구현은 이 코드 스니펫을 참고하세요.
  • 다음으로 vLLM은 구성 딕셔너리의 model_type 필드를 검사해 사용할 구성 객체를 생성합니다. vLLM이 직접 지원하는 model_type 값이 있으며, 목록은 여기를 참고하세요. model_type이 목록에 없으면 vLLM은 model, --revision, --trust_remote_code를 인자로 하여 AutoConfig.from_pretrained로 구성 클래스를 로드합니다. 다음에 유의하세요:
    • Hugging Face도 구성 클래스 선택에 자체 로직이 있습니다. 역시 model_type 필드로 transformers 라이브러리에서 클래스 이름을 검색합니다. 지원되는 모델 목록은 여기를 참고하세요. model_type을 찾지 못하면 Hugging Face는 구성 JSON 파일의 auto_map 필드를 사용해 클래스 이름을 결정합니다. 구체적으로는 auto_map 아래의 AutoConfig 필드입니다. 예는 DeepSeek을 참고하세요.
    • auto_map 아래의 AutoConfig 필드는 모델 저장소의 모듈 경로를 가리킵니다. 구성 클래스를 만들기 위해 Hugging Face는 모듈을 import하고 from_pretrained 메서드로 구성 클래스를 로드합니다. 이는 일반적으로 임의 코드 실행을 유발할 수 있으므로 --trust_remote_code가 활성화된 경우에만 실행됩니다.
  • 그 후 vLLM은 구성 객체에 몇 가지 과거 패치를 적용합니다. 대부분 RoPE 구성과 관련이 있습니다. 구현은 여기를 참고하세요.
  • 마지막으로 vLLM은 초기화하려는 모델 클래스에 도달합니다. vLLM은 구성 객체의 architectures 필드를 사용해 초기화할 모델 클래스를 결정합니다. 자체 레지스트리에서 아키텍처 이름→모델 클래스 매핑을 유지하기 때문입니다. 아키텍처 이름이 레지스트리에 없으면 해당 모델 아키텍처는 vLLM이 지원하지 않는 것입니다. Qwen/Qwen2-7B의 경우 architectures 필드는 ["Qwen2ForCausalLM"]이며, 이는 vLLM 코드의 Qwen2ForCausalLM 클래스에 해당합니다. 이 클래스는 다양한 구성에 따라 스스로 초기화합니다.

그 외에 vLLM이 Hugging Face에 의존하는 두 가지가 더 있습니다.

  • Tokenizer: vLLM은 Hugging Face의 tokenizer를 사용해 입력 텍스트를 토큰화합니다. tokenizer는 AutoTokenizer.from_pretrained로 로드하며, model 인자를 모델 이름으로, --revision 인자를 리비전으로 사용합니다. vllm serve 명령에서 --tokenizer 인자를 지정해 다른 모델의 tokenizer를 사용할 수도 있습니다. 관련 인자는 --tokenizer-revision과 --tokenizer-mode입니다. VLLM_USE_FASTOKENS=1을 설정하면 vLLM이 로드하는 어떤 HF fast tokenizer도 드롭인 Rust BPE 백엔드로 교체됩니다(fastokens 백엔드 참고). 이 인자들의 의미는 Hugging Face 문서를 확인하세요. 이 로직은 get_tokenizer 함수에서 찾을 수 있습니다. tokenizer를 얻은 뒤 특히 vLLM은 tokenizer의 일부 비싼 속성을 vllm.tokenizers.hf.get_cached_tokenizer에 캐시합니다.
  • 모델 가중치: vLLM은 Hugging Face 모델 허브에서 model 인자를 모델 이름으로, --revision 인자를 리비전으로 사용해 모델 가중치를 다운로드합니다. vLLM은 --load-format 인자를 제공해 모델 허브에서 어떤 파일을 다운로드할지 제어합니다. 기본적으로 safetensors 형식으로 가중치를 로드하려 시도하고, safetensors가 없으면 PyTorch bin 형식으로 폴백합니다. 또한 --load-format dummy를 전달해 가중치 다운로드를 건너뛸 수 있습니다.
    • safetensors 형식을 권장합니다. 분산 추론에서 로딩이 효율적이고 임의 코드 실행으로부터 안전하기 때문입니다. safetensors 형식에 대한 자세한 내용은 문서를 참고하세요. 이 로직은 여기에서 찾을 수 있습니다.

이로써 vLLM과 Hugging Face의 통합이 완성됩니다.

요약하면, vLLM은 Hugging Face 모델 허브나 로컬 디렉터리에서 구성 파일 config.json, tokenizer, 모델 가중치를 읽습니다. 구성 클래스는 vLLM, Hugging Face transformers에서 사용하거나 모델 저장소에서 로드합니다.

더 알아보기 (Learn more)