콘텐츠로 이동

메모리 추정

mlxcel은 MLX 런타임을 건드리기 전에 모델 로드에 필요한 메모리를 추정할 수 있습니다. 모델, 컨텍스트 길이, 배치 형태, KV 캐시 모드를 실제 생성이나 서버 시작 전에 점검할 때 사용합니다.

이 추정기는 로드 전 읽기 전용 경로입니다. config.json, safetensors 메타데이터, 환경 변수 한도, Linux 메모리 정보를 읽을 수 있지만 텐서를 할당하거나 MLX를 초기화하거나 모델 가중치를 로드하지 않습니다.

계산 항목

추정 결과는 다음 항목으로 구성됩니다.

항목 출처
가중치 가능한 경우 safetensors의 정확한 크기. Sharded index는 검증된 metadata.total_size를 사용하고 stale index는 shard/header 검사로 폴백합니다. 단일 safetensors 파일은 tensor 데이터를 로드하지 않고 binary header만 읽습니다.
KV 캐시 config.json의 아키텍처 필드: layer 수, KV head 수, head_dim, element 폭, 컨텍스트 길이, 배치. 아키텍처도 반영하여 sliding-window, MLA, 하이브리드, 순수 SSM 레이아웃은 단순한 layer별 공식이 아니라 각자의 캐시 형태로 계산합니다. 컨텍스트는 256토큰 allocation block 단위로 올림 처리합니다.
Allocator overhead weights + KV cache에 MLXCEL_HEADROOM_FACTOR(기본 1.20)를 적용한 값으로, MLX allocator와 그래프 working set을 반영합니다. 이 factor는 이 항에만 적용됩니다.
Activation reserve MLXCEL_ACTIVATION_MULT(기본 2.0) x batch x min(context, prefill chunk) x (hidden + intermediate) x 2 bytes에 마지막 토큰 logit 버퍼 batch x vocab x 2 bytes를 더한 값입니다. prefill chunk는 MLXCEL_PREFILL_CHUNK, 설정하지 않으면 2048입니다.
Backend in-flight ROCm 빌드 전용입니다. 커밋했지만 아직 끝나지 않은 command batch가 잡을 수 있는 MLX_ROCM_MAX_INFLIGHT_MB 예산(기본 1024 MiB)이며, 다른 빌드에서는 0입니다.
Host shadow Windows ROCm 빌드 전용입니다. CPU가 접근하는 GPU 버퍼마다 allocator가 유지하는 pinned host 사본이며, 시퀀스당 f32 logit 한 행(vocab x 4)과 컨텍스트의 int32 토큰 ID(context x 4)로 추정합니다. 호스트 RAM을 쓰므로 호스트 RAM과 따로 비교하며 합계에는 더하지 않습니다. fits는 두 비교를 모두 통과해야 참입니다. 다른 빌드에서는 0입니다.
사용 가능 메모리 Apple unified memory, Linux /proc/meminfo, Windows GlobalMemoryStatusEx, 또는 명시적인 MLXCEL_MEMORY_LIMIT cap입니다.

inspect가 보고하는 런타임 headroom은 allocator overhead, activation reserve, backend in-flight reserve의 합이고, 전체 추정치는 weights + KV cache + runtime headroom입니다. 서버는 같은 추정기로 paged KV --kv-cache-budget auto 예산과 모델 기반 프롬프트 캐시 용량 기본값을 정합니다.

KV 추정은 --kv-cache-mode int8 또는 --cache-type-k int8 --cache-type-v int8의 INT8 KV 캐시 설정을 반영합니다. TurboQuant 계열 모드도 같은 플래그 표면을 사용하지만 현재 추정기는 기본 FP16-equivalent KV 캐시와 INT8 byte-width case만 구분합니다.

모델 검사

mlxcel inspect는 preflight가 사용하는 것과 같은 byte breakdown을 출력한 뒤 모델을 로드하지 않고 종료합니다.

mlxcel inspect --model ./models/Llama-3.1-8B-Instruct-4bit

자주 쓰는 크기 조정 옵션:

# 더 긴 컨텍스트 윈도우를 추정합니다.
mlxcel inspect -m ./models/qwen3-8b --max-tokens 32768

# 동시 서버 슬롯을 추정합니다.
mlxcel inspect -m ./models/qwen3-8b --max-tokens 8192 --batch 4

# INT8 KV 캐시를 추정합니다.
mlxcel inspect -m ./models/qwen3-8b --kv-cache-mode int8

--quant fp16|int8|int4는 출력에 의도한 가중치 모드를 표시합니다. 가중치 byte 총량은 바꾸지 않습니다. mlxcel은 safetensors header를 실제 값으로 사용하고 quantized 체크포인트는 이미 실제 on-disk tensor dtype과 shape를 담고 있기 때문입니다.

JSON 리포트

recipe builder, scheduler, CI check가 machine-readable fit data를 필요로 할 때는 --json을 사용합니다.

mlxcel inspect --json -m mlx-community/Qwen3-4B-4bit

명령이 성공하면 stdout에는 JSON object 하나만 출력됩니다. resolution, download, estimator error는 기존 stderr path를 사용하고 nonzero로 종료하므로, pipeline은 명령 성공 뒤의 stdout만 parseable JSON으로 취급할 수 있습니다.

리포트 field는 별도 설명이 없으면 raw byte입니다.

Field 의미
mlxcel_version, model, model_type, family binary version, resolved model path, top-level config.json.model_type 원문, architecture metadata가 쓰는 registry family slug입니다.
inputs 추정에 사용된 effective max_tokens, batch, kv_cache_mode, quant label입니다.
weights_bytes, weights_source 가중치 footprint와 그 값이 safetensors header, analytical config estimate, fallback 중 어디서 왔는지 나타냅니다.
kv_bytes_per_token model geometry가 있으면 FP16 및 INT8 per-token KV rate를 제공합니다. turbo4는 estimator가 TurboQuant storage width를 직접 모델링할 때까지 null입니다.
kv_bytes_total, kv_detail 요청한 context와 batch의 총 KV allocation, 그리고 text banner에 표시되는 architecture detail string입니다.
per_slot_overhead_bytes 기본 paged family의 paged-decode workspace reserve입니다. dense-default 계열이거나 geometry가 없으면 null입니다.
activation_bytes, headroom_bytes, headroom_factor activation reserve, total runtime headroom(allocator overhead + activation reserve + backend in-flight reserve), allocator overhead에 사용한 multiplier입니다.
backend_inflight_bytes headroom_bytes에 포함된 backend in-flight reserve입니다. ROCm 빌드에서만 0이 아니며 MLX_ROCM_MAX_INFLIGHT_MB와 같은 값이고, 텍스트 배너에서는 Backend in-flight 줄로 나옵니다.
host_shadow_bytes, host_ram_available_bytes, host_shadow_fits Windows ROCm host-shadow reserve, 비교 대상인 호스트 RAM, 그리고 적합 여부입니다. 다른 빌드에서는 0, (0 또는 RAM 값), true입니다.
budget_bytes, total_bytes, fits available-memory budget, total estimate, preflight check와 같은 fit boolean입니다. 디바이스 예산이나 host-shadow 비교 중 하나라도 실패하면 fits는 false입니다.

생성 전 preflight

mlxcel generate --estimate-memory는 prompt rendering/tokenization 이후, 모델 로드 이전에 실행됩니다. KV 캐시는 다음 길이로 계산합니다.

렌더링된 prompt token 수 + --max-tokens

추정 총량이 사용 가능 메모리를 초과하면 모델을 로드하기 전에 생성이 중단됩니다. breakdown을 확인한 뒤에만 override를 사용하십시오.

mlxcel generate \
  --model ./models/qwen3-8b \
  --prompt "Summarize this deployment plan." \
  --max-tokens 1024 \
  --estimate-memory

mlxcel generate ... --estimate-memory --force

--no-memory-check는 --force의 별칭입니다.

서버 시작 전 preflight

mlxcel serve --estimate-memory와 mlxcel-server --estimate-memory는 worker 시작 전에 실행됩니다. 런타임과 같은 서버 컨텍스트 의미론을 사용합니다.

effective_context = floor(--ctx-size / active_slots)
active_slots      = --max-batch-size가 있으면 그 값, 없으면 --n-parallel

--no-batch에서는 active_slots가 1입니다. --ctx-size가 0이면 모델 기본 컨텍스트가 로드 전에는 확정되지 않으므로, 추정기는 기본 8192토큰 컨텍스트 길이를 사용합니다.

mlxcel serve \
  --model ./models/qwen3-8b \
  --ctx-size 32768 \
  --n-parallel 4 \
  --estimate-memory

이 예시에서 서버 preflight는 각 active slot을 8192토큰 컨텍스트와 batch 4로 계산합니다. 서버가 실행된 뒤 /health.context_size와 /slots[].context_size도 같은 슬롯별 실제 컨텍스트 윈도우를 보고합니다.

환경 변수

변수 기본값 효과
MLXCEL_MEMORY_LIMIT 미설정 soft allocator memory cap. 0이 아닌 값은 inspect, --estimate-memory, MLX runtime setup의 권위 있는 사용 가능 메모리 예산이 됩니다. 48GB, 512MB, raw bytes 같은 값을 지원합니다.
MLXCEL_HEADROOM_FACTOR 1.20 weights + KV cache에 곱하는 allocator overhead multiplier입니다. activation reserve와 backend in-flight reserve에는 적용되지 않습니다. 0 < value <= 1.0 값은 allocator overhead 항을 비활성화하고, 잘못됐거나 non-positive인 값은 경고 후 기본값으로 폴백합니다.
MLXCEL_ACTIVATION_MULT 2.0 activation reserve batch x min(context, prefill chunk) x (hidden + intermediate) x 2 bytes의 multiplier입니다. 잘못됐거나 non-positive인 값은 경고 후 기본값으로 폴백합니다.
MLX_ROCM_MAX_INFLIGHT_MB 1024 ROCm 빌드 전용. MiB 단위 backend in-flight 예산으로, 추정기는 이 값을 backend_inflight_bytes로 잡습니다. 0이면 backend 상한이 사라지고 추정기도 아무것도 잡지 않습니다.

컨테이너, CI, 공유 호스트처럼 OS가 보고하는 메모리가 실제 프로세스 예산과 다를 때는 MLXCEL_MEMORY_LIMIT를 사용하십시오.

양자화 권장과의 관계

--recommend-quant는 inspect 및 memory preflight와 같은 가중치/KV 캐시 추정기를 사용합니다. 따라서 같은 모델 디렉터리와 KV 캐시 모드에 대해 권장 사항, 출력되는 메모리 표, 서버 시작 거부 조건이 서로 어긋나지 않습니다.