모델 해석

모델 해석 (Model Resolution)

vLLM은 HuggingFace 호환 모델을 불러올 때, 모델 저장소의 config.json에 있는 architectures 필드를 검사해 그에 대응하는 구현을 찾습니다. 이때 vLLM에 등록된(registered) 아키텍처와 이름이 일치해야 합니다.

출처: 문서

본문

그런데 모델 해석은 다음 이유로 실패할 수 있습니다.

  • 모델 저장소의 config.json에 architectures 필드가 없습니다.
  • 비공식 저장소가 vLLM에 기록되지 않은 대체 이름으로 모델을 참조합니다.
  • 같은 아키텍처 이름이 여러 모델에 쓰여, 어느 모델을 로드해야 하는지 모호합니다.

이를 고치려면 hf_overrides 옵션에 config.json 오버라이드를 넘겨 모델 아키텍처를 명시적으로 지정하면 됩니다. 예를 들어 다음과 같습니다.

from vllm import LLM

llm = LLM(
    model="cerebras/Cerebras-GPT-1.3B",
    hf_overrides={"architectures": ["GPT2LMHeadModel"]},  # GPT-2
)

이 예시에서 Cerebras-GPT-1.3B 모델은 안의 구조가 GPT-2 아키텍처이므로, architectures를 GPT2LMHeadModel로 오버라이드해 vLLM이 올바른 구현을 로드하도록 합니다.

vLLM이 인식하는 모델 아키텍처 목록은 공식 지원 모델 목록에서 확인할 수 있습니다. 즉 모델을 못 찾을 때는 ① config.json의 아키텍처가 vLLM에 실제로 등록되어 있는지 확인하고, ② 아니라면 hf_overrides로 정확한 아키텍처 이름을 명시하는 방식으로 해결합니다.

실무 팁으로, 아키텍처 이름은 대소문자와 표기(예: LlamaForCausalLM vs llama)가 정확히 일치해야 합니다. 오타가 있으면 "architecture not supported" 류의 오류가 나므로, 모델 카드의 config.json을 직접 열어 정확한 architectures 값을 복사해서 쓰는 것이 안전합니다.

더 알아보기 (Learn more)