모델 해석
모델 해석 (Model Resolution)
vLLM에 모델을 불러오다 보면, 가끔 "이 모델은 도대체 어떤 구현으로 로드되는 거지?" 하는 순간이 있어요. vLLM이 모델을 어떻게 식별하는지 이해하면, 특이한 저장소의 모델을 쓸 때도 헤매지 않을 수 있답니다.
vLLM은 어떻게 모델을 찾을까?
vLLM은 HuggingFace와 호환되는 모델을 로드할 때, 모델 저장소(repository)의 config.json 안에 있는 architectures 필드를 검사해요. 그리고 그 이름에 해당하는, vLLM에 등록된 구현체를 찾아 연결하죠. 이게 기본적인 모델 해석(model resolution) 과정이에요.
모델 해석이 실패하는 경우
하지만 이 과정이 항상 순조롭게 흘러가지는 않아요. vLLM의 모델 해석이 실패하는 흔한 이유들을 정리하면 이렇습니다.
- 동일한 아키텍처 이름이 여러 모델에 쓰이는 경우 — 어떤 모델을 로드해야 할지 모호해져요.
- 비공식 저장소(ufficial repositories)에서 대체 이름을 쓰는 경우 — vLLM에 기록되지 않은 다른 이름으로 모델을 지칭해요.
- 모델 저장소의
config.json에architectures필드가 없는 경우 — vLLM이 어디로 연결해야 할지 단서가 없어져요.
구조를 명시적으로 지정하기: hf_overrides
이런 경우를 해결하는 방법은 간단해요. hf_overrides 옵션에 config.json 오버라이드를 넘겨서 모델 아키텍처를 명시적으로 지정하면 됩니다. 예를 들어 다음 코드는 Cerebras-GPT 모델을 GPT-2 아키텍처로 강제로 해석하도록 지정해요.
from vllm import LLM
llm = LLM(
model="cerebras/Cerebras-GPT-1.3B",
hf_overrides={"architectures": ["GPT2LMHeadModel"]}, # GPT-2
)
vLLM이 실제로 인식하는 모델 아키텍처 목록은 지원 모델 목록에서 확인할 수 있어요. 로드에 실패하거나 이상하게 동작한다면, 이 목록과 대조해 보는 게 첫 번째 해결 단계가 됩니다.