bj.choi - notes

[LLM] Hugging Face 모델 배포 전 확인 항목

Updated:

Hugging Face 모델 저장소에서 가중치 크기, KV cache, 컨텍스트 길이와 서빙 설정을 확인하는 방법을 Qwen3.8-Flash-Next 사례로 정리합니다.

새 모델을 배포하려면 모델 페이지의 최대 컨텍스트만 봐서는 부족합니다. 가중치가 GPU에 들어가는지, 요청이 늘어날 때 KV cache가 얼마나 커지는지, 서빙 엔진이 모델 구조를 지원하는지 함께 확인해야 합니다.

이 글에서는 Hugging Face 저장소에서 확인할 파일과 계산 순서를 정리합니다. 예시는 Qwen3.8-Flash-Next를 사용합니다.

모델 배포 판단에 필요한 4가지 값

모델 페이지를 열면 우선 아래 네 가지 값을 확인합니다.

  1. 가중치 실제 바이트 수: GPU에 모델이 들어가는가?
  2. 총 컨텍스트 길이: 입력과 출력을 합쳐 몇 토큰인가?
  3. KV cache의 토큰당 바이트 수: 요청 길이와 동시성이 메모리를 얼마나 먹는가?
  4. 실제 트래픽의 ISL·OSL·동시성 분포: 최대 사양이 아니라 운영 부하가 무엇인가?

이 네 가지 값이 GPU 선정과 처리량 계산의 기준입니다.

Hugging Face 모델 저장소 확인 파일

아래 화면은 Qwen3.8-Flash-Next 저장소를 기준으로 표시했습니다.

Hugging Face 모델 저장소에서 먼저 확인할 파일

  1. 저장소 표시 용량 360 GB: 빠른 1차 추정값으로 정확한 텐서 바이트는 index의 metadata.total_size로 다시 확인합니다.
  2. LICENSE: 상업적 이용, 재배포, 파생 모델 조건을 확인합니다.
  3. chat_template.jinja: 실제 API 입력에 붙는 role·special token·generation prompt를 확인합니다.
  4. config.json: 모델 구조, dtype, 컨텍스트, KV head, RoPE 설정을 확인합니다.
  5. model-xxxxx-of-yyyyy.safetensors: 분할된 실제 가중치 파일입니다. 이 저장소는 파일명상 131개 shard로 구성됩니다.

여기에 model.safetensors.index.json, generation_config.json, tokenizer/processor 파일을 더하면 배포 전 정적 점검을 시작할 수 있습니다.

1. 모델 정보와 아티팩트 확정하기

필수 확인 항목

모델 이름만으로는 배포 대상(버전)을 고정할 수 없습니다. 아래 항목을 함께 기록해야 합니다.

확인 위치

확인 필요성

model_type을 엔진이 인식하더라도 해당 체크포인트의 모든 기능을 지원한다는 의미는 아닙니다. 멀티모달 전처리, reasoning parser, tool-call parser, custom attention, 양자화 포맷은 각각 별도 지원이 필요할 수 있습니다.

운영 배포에서는 main 대신 직접 개발 환경에서 검증한 revision을 고정해야 추후 배포 결과를 재현할 수 있습니다.

2. 파라미터 수와 실제 가중치 크기

모델 크기의 3가지 기준

모델 크기를 볼 때는 총 파라미터 수, 활성 파라미터 수, 체크포인트 바이트 수를 구분합니다.

MoE 모델의 활성 6B는 6B 모델처럼 메모리를 사용한다는 의미가 아닙니다. 활성 파라미터는 계산량을 설명하는 값에 가깝습니다. 전체 expert 가중치는 여전히 저장하고 로드해야 합니다.

모델 크기 확인 순서

정확한 값은 아래 항목에서 확인합니다.

  1. model.safetensors.index.json → metadata.total_size
  2. Hugging Face Safetensors 메타데이터의 dtype별 parameter_count
  3. Hub 파일 목록의 전체 shard 크기
  4. 모델 카드의 total/active parameter 설명
  5. 로드가 가능하면 model.get_memory_footprint()로 실측 권장

Hugging Face 문서에서 config.json은 모델 구조를, model.safetensors는 실제 가중치를 저장합니다. shard 모델의 index에는 metadata.total_size와 텐서별 파일 매핑 확인 가능합니다.

model.safetensors.index.json 구성과 해석

Safetensors index에서 실제 모델 크기를 확인하는 위치

  1. index 파일명: 여러 .safetensors shard를 하나의 체크포인트로 묶는 색인입니다.
  2. metadata.total_size: 저장된 텐서 전체의 바이트 합입니다.
    • 이 모델은 359,999,963,128 bytes입니다.
  3. weight_map: 각 텐서 이름이 어느 shard 파일에 들어 있는지 보여줍니다.
  4. 개별 매핑: lm_head.weight는 model-00131-of-00131.safetensors에 저장되어 있습니다.
decimal GB = 359,999,963,128 / 1,000,000,000
           ≈ 360.00 GB       # Hugging Face 화면 표기와 대응

binary GiB = 359,999,963,128 / 1,073,741,824
           ≈ 335.28 GiB

total_size는 checkpoint tensor의 크기입니다.

로딩 중 dtype 변환, 양자화 metadata와 padding, KV cache, activation, 커널 workspace, CUDA graph 등이 별도로 추가될 수 있습니다.

특히 배포 옵션 중 Tensor parallel을 사용하면 체크포인트 총량은 GPU별로 나뉠 수 있습니다.

Index 미제공 모델

index가 없다면 가중치 파일 형식에 맞춰 크기를 확인합니다.

가중치 이론값

가중치 메모리 ≈ 총 파라미터 수 × 파라미터당 바이트

FP32     4 bytes
FP16     2 bytes
BF16     2 bytes
FP8      약 1 byte + scale/metadata
INT8     약 1 byte + scale/metadata
INT4     약 0.5 byte + scale/metadata

양자화 모델은 scale, zero point, packing, 미양자화 레이어 때문에 단순 파라미터 × bit/8보다 커질 수 있습니다.

최종 용량은 checkpoint metadata와 실제 엔진 로드 후 측정값을 권장합니다

전체 GPU 메모리 구성

필요 GPU 메모리
≈ 가중치
+ KV cache
+ 순간 activation/prefill workspace
+ CUDA graph 및 컴파일 버퍼
+ attention/MoE 커널 workspace
+ 멀티모달 encoder와 processor cache
+ speculative decoding draft/MTP 상태
+ LoRA adapter
+ 런타임 여유 공간

NVIDIA도 LLM 추론 메모리의 가장 큰 두 축을 가중치와 KV cache로 설명합니다.

3. KV 계산을 위한 모델 구조

config.json에서 모델 구조와 dtype을 확인하는 위치

  1. architectures: 로드할 구현 클래스와 엔진 지원 여부를 확인하는 출발점입니다.
  2. model_type: Transformers와 서빙 엔진이 구성을 식별할 때 사용하는 키입니다.
  3. dtype: 체크포인트의 기본 dtype 힌트입니다. 실제 shard dtype·양자화 설정과 교차 확인합니다.
  4. head_dim, hidden_size: attention과 activation 용량 계산에 사용합니다.
  5. layer_types: full attention만 사용하는지, linear/sliding/SSM 계열이 섞인 hybrid인지 보여줍니다.

Transformer 주요 필드

일반 Transformer에서는 아래 필드가 메모리 계산의 기준이 됩니다.

의미 흔한 config.json 필드
레이어 수 num_hidden_layers, n_layer
hidden 크기 hidden_size, d_model, n_embd
query head 수 num_attention_heads, n_head
KV head 수 num_key_value_heads, n_head_kv
head dimension head_dim, 없으면 흔히 hidden_size / num_attention_heads
FFN 크기 intermediate_size
vocab 크기 vocab_size
dtype dtype, torch_dtype
weight quantization quantization_config

Attention 및 Hybrid 구조 판별

KV 공식에 값을 넣기 전에 attention 구조부터 구분합니다.

따라서 hidden_size만 사용하는 기존 KV 공식은 MHA 모델에는 맞을 수 있지만 GQA/MQA/MLA/hybrid 모델에서는 과대 계산이나 오계산이 발생할 수 있습니다.

4. KV cache 계산

표준 KV Cache 근사식

KV bytes/token/request
= 2                    # K와 V
 × KV cache를 저장하는 attention layer 수
 × num_key_value_heads
 × head_dim
 × KV dtype bytes

총 KV cache
= 위 값
 × 현재까지의 총 sequence length
 × 동시에 살아 있는 sequence 수

BF16/FP16 KV는 dtype bytes = 2, FP8은 대체로 1을 사용합니다.

GQA 계산 예시

가정:

layers = 32
num_key_value_heads = 8
head_dim = 128
KV dtype = BF16 = 2 bytes

계산:

KV bytes/token = 2 × 32 × 8 × 128 × 2
               = 131,072 bytes
               = 128 KiB/token

32K tokens, 요청 1개 ≈ 4 GiB
32K tokens, 요청 8개 ≈ 32 GiB

여기서 sequence length는 입력뿐 아니라 이미 생성된 출력까지 포함합니다.

표준 공식의 적용 예외

아래 구조에서는 표준 공식만으로 전체 메모리를 계산하기 어렵습니다.

이 경우 공식은 1차 추정에만 사용합니다.
엔진 시작 로그의 GPU block 수·KV capacity와 부하 테스트의 실제 memory_used를 최종값으로 사용합니다.

5. 컨텍스트 길이와 위치 인코딩

config.json에서 컨텍스트와 hybrid 구조를 확인하는 위치

  1. layer_types의 반복 패턴: 이 예시는 linear attention과 full attention이 섞인 모델입니다.
  2. mamba_ssm_dtype: 가중치 dtype과 별도로 recurrent state 계산 dtype이 존재할 수 있습니다.
  3. max_position_embeddings: 이 체크포인트에서는 262144입니다.
    • 필드 이름만으로 판단하지 않고 RoPE 확장 설정과 엔진 지원을 함께 확인합니다.
  4. MTP 관련 구성: speculative decoding이나 보조 예측 상태가 추가될 수 있습니다.
  5. attention·expert·layer 수: KV, 연산량, MoE 배치 방식을 계산하는 기본 구조값입니다.

컨텍스트 확인 항목

컨텍스트 길이는 확장 방식과 엔진 지원까지 함께 보고, 단일 필드로 판단하지 않습니다.

최대 입력 길이 계산

prompt tokens + generated tokens ≤ 서버의 총 context length

최대 입력
= 총 context length
- 예약 출력 토큰
- chat template/special token 오버헤드
- 이미지·영상에서 변환된 토큰

모델이 1M까지 확장 가능하다는 설명과 체크포인트가 1M을 native로 지원한다는 설명은 다릅니다.
RoPE scaling 값과 서빙 엔진의 context 설정을 함께 적용하고, 확장에 따른 품질도 검증해야 합니다.

config.json에서 KV head와 RoPE 설정을 확인하는 위치

  1. num_attention_heads: query head 수입니다.
  2. num_experts, num_experts_per_tok: 전체 expert 수와 토큰당 활성 expert 수를 구분합니다.
  3. num_hidden_layers: 전체 layer 수입니다.
    • hybrid 모델은 그 중 실제 KV를 저장하는 attention layer 수를 다시 확인해야 합니다.
  4. num_key_value_heads: 표준 GQA/MQA KV cache 공식에 직접 들어가는 값입니다.
  5. rope_parameters: RoPE 유형, theta, mRoPE/YaRN 같은 확장 구성을 확인합니다.

6. Tokenizer 및 Chat Template

관련 파일

Tokenizer 동작은 다음 파일에 나뉘어 저장됩니다.

동작 확인 항목

파일 존재 여부보다 최종 입력이 어떻게 만들어지는지가 더 중요합니다.

generation_config.json은 모델 메모리 한도가 아니라 샘플링·종료 기본값입니다.
배포 전에는 raw 문자열 길이가 아니라 최종 chat template을 적용한 token IDs 길이를 측정합니다.

vLLM의 OpenAI 호환 서버는 모델 저장소의 generation_config.json을 기본 적용할 수 있습니다.
같은 API 요청도 모델 제작자의 temperature·top-p·EOS 기본값에 따라 결과가 달라질 수 있습니다.
제작자 설정과 vLLM 기본값 중 어떤 값을 사용할지 명시적으로 결정합니다.

7. 멀티모달 추가 확인 항목

멀티모달 모델은 텍스트 외 입력이 소비하는 token과 processor memory를 추가로 계산합니다.

vLLM도 컨텍스트와 batch 제한 외에 멀티모달 입력 개수와 processor cache를 별도 메모리 조절 지점으로 안내합니다.

8. 엔진과 하드웨어 호환성

서빙 엔진 지원

모델 구조와 기능을 엔진이 실제로 지원하는지 확인합니다.

GPU 환경

메모리 용량과 함께 연산 형식, 통신 구조, host 자원을 확인합니다.

가중치가 여러 GPU에 나뉘어 들어간다는 사실만으로 성능이 보장되지는 않습니다.
TP는 매 layer에서 통신하며, 노드 경계를 넘으면 interconnect가 병목이 될 수 있습니다.

9. 병렬화 방식 결정

방식 주목적 주의점
Tensor Parallel 한 모델의 레이어 연산·가중치를 여러 GPU에 분할 빠른 GPU 간 통신 필요, head/expert divisibility 확인
Pipeline Parallel 레이어 묶음을 GPU/노드별로 분할 pipeline bubble과 batch 특성
Expert Parallel MoE expert를 분산 all-to-all 통신, load balancing
Data Parallel 모델 replica를 늘려 처리량 증가 GPU마다 가중치 복제, 요청 routing 필요
Context/Sequence Parallel 긴 sequence/KV를 여러 GPU에 분할 엔진·모델 지원과 통신 비용

vLLM은 모델이 한 GPU에 들어가지 않을 때 TP로 분할할 수 있습니다.
다만 일반 checkpoint는 각 프로세스가 전체 모델을 읽은 뒤 분할하므로 시작 시간이 길어질 수 있습니다.

10. vLLM 운영 설정

컨텍스트와 스케줄링

메모리와 KV

서빙 기능

vLLM은 --max-model-len을 지정하지 않으면 모델 설정에서 총 컨텍스트 길이를 추론합니다
--kv-cache-memory-bytes를 지정하지 않으면 gpu_memory_utilization을 이용해 KV 공간을 자동 산정합니다.

11. 워크로드와 실측 기준

용량 계획에서는 최대 컨텍스트보다 실제 입력·출력 분포를 먼저 확인합니다.

워크로드 지표

최대값 하나보다 분포와 SLA가 용량 계획에 더 유용합니다.

NVIDIA의 벤치마킹 가이드는 ISL이 길수록 prefill 메모리와 TTFT가 증가한다고 설명합니다. OSL이 길어지면 decode 단계의 메모리·대역폭과 ITL 부담이 증가합니다. 따라서 실제 ISL/OSL 분포를 확인해야 합니다.

동시 요청 수의 한계

KV 메모리는 요청 수보다 동시에 살아 있는 총 토큰 수에 가깝게 증가합니다.
2K 요청 10개와 100K 요청 10개는 같은 concurrency가 아닙니다. 부하 테스트에서는 실제 길이 분포를 재현해야 합니다.

배포 전 실측

계산값은 배포 가능성을 빠르게 판단하는 기준입니다. 최종 설정은 아래 항목을 같은 workload로 측정해 결정합니다.

12. Qwen3.8-Flash-Next 적용 예시

저장소 확인값

용량 및 KV 해석

이론 가중치 = 180B × 2 bytes ≈ 360 GB

활성 6B만 보고 12 GB 정도면 된다고 판단하면 안 됩니다.
저장소 자체가 약 360 GB이며, 여기에 KV cache와 런타임 메모리가 추가됩니다.

표준 KV 공식으로 12개 attention layer 부분만 단순 계산하면:

2 × 12 layers × 2 KV heads × 256 head_dim × 2 bytes
= 24,576 bytes/token/request
= 24 KiB/token/request

262,144 tokens에서 약 6 GiB/request

이 모델은 Qwen Sparse Attention, indexer, Gated DeltaNet이 섞인 hybrid 구조입니다. 따라서 위 계산값은 전체 엔진 상태의 확정치가 아닙니다.

linear-attention recurrent/conv state, sparse indexer, block allocation, TP 분할을 포함한 값은 지원 엔진의 시작 로그와 메모리 profile로 확인해야 합니다.
일반 KV 공식은 모델 구조를 확인한 뒤 적용합니다.

참고 자료

모델 및 서빙