설정¶

mlxcel은 환경 변수(모든 실행에 영향을 줌)와 커맨드라인 플래그(특정 실행에 대해 환경 변수를 덮어씀)의 조합으로 설정됩니다. 이 페이지에서는 디바이스 선택과 메모리 관리를 제어하는 환경 변수, 그리고 서버 전용 설정 옵션을 설명합니다.

목차¶

• 환경 변수
• 디바이스 선택
• 메모리 관리
• 서버 설정
• 네트워킹 및 인증
• 생성 기본값
• 연속 배칭
• 투기적 디코딩
• 채팅 템플릿

환경 변수¶

아래 변수들은 시작 시 읽히며 generate 명령어와 serve 명령어 모두에 적용됩니다.

참고: LLAMA_ARG_ 접두사가 붙은 변수들은 의도적인 호환성 별칭입니다. 덕분에 이 변수들을 이미 설정해 둔 스크립트나 배포 설정에서 mlxcel을 llama-server의 드롭인 대체로 사용할 수 있습니다.

디바이스 선택¶

디바이스 선택 방식¶

mlxcel이 시작될 때 컴퓨트 디바이스를 다음 순서로 선택합니다.

1. MLXCEL_DEVICE가 cpu로 설정된 경우 무조건 CPU를 사용합니다.
2. MLXCEL_DEVICE가 gpu 또는 metal로 설정된 경우 GPU를 사용합니다(GPU가 없으면 오류가 발생합니다).
3. 그 외의 경우 GPU가 있으면 자동으로 GPU를 사용하고 없으면 CPU를 폴백으로 사용합니다.

Apple Silicon에서 GPU는 Metal 가속 통합 메모리 디바이스입니다. Linux에서는 첫 번째 CUDA 지원 GPU(cuda:0)입니다. 현재 단일 프로세스 내 멀티 GPU 라운드 로빈은 지원되지 않으며 멀티 GPU 지원은 분산 추론 기능을 통해 처리됩니다.

CPU 모드 강제 사용¶

CPU 모드는 모델 정확성 디버깅이나 호환 GPU 하드웨어가 없는 머신에서 실행할 때 유용합니다.

MLXCEL_DEVICE=cpu mlxcel generate -m ./models/my-model -p "Hello"

대부분의 모델에서 CPU 추론은 GPU 추론보다 현저히 느립니다. 프로덕션 환경에서는 권장하지 않습니다.

메모리 관리¶

와이어드 메모리 개념¶

Apple Silicon에서 MLX는 "와이어드 메모리(wired memory)"를 사용합니다. 이는 디스크로 스왑되지 않도록 고정된 메모리입니다. GPU 연산에는 메모리가 상주 상태여야 하므로 와이어드 메모리가 성능을 좌우합니다. 그러나 과도하게 와이어링하면 다른 애플리케이션도 메모리를 필요로 할 때 시스템 불안정이나 OOM(메모리 부족) 오류가 발생할 수 있습니다.

MLXCEL_WIRED_LIMIT 변수는 mlxcel이 와이어링할 수 있는 GPU 메모리 양을 제어합니다.

허용 값¶

와이어드 한도 선택¶

전용 머신에서 mlxcel을 주요 GPU 작업으로 실행하는 대부분의 사용자는 MLXCEL_WIRED_LIMIT을 설정하지 않은 상태(기본값)로 두는 것이 적절합니다. 이 경우 mlxcel은 모델 가중치가 상주 상태를 유지하도록 mlx-lm 패턴과 동일하게 wired limit을 GPU 최대값으로 설정합니다.

다른 프로세스로 인한 메모리 압박이 있다면 명시적인 한도를 설정하십시오.

# 128 GB 시스템에서 96 GB를 mlxcel에 할당하고 32 GB는 OS와 다른 앱을 위해 남겨둡니다
MLXCEL_WIRED_LIMIT=96GB mlxcel serve -m ./models/my-large-model --port 8080

중요: Linux(CUDA)에서는 MLXCEL_WIRED_LIMIT이 적용되지 않습니다. CUDA 메모리 관리는 CUDA 런타임이 처리합니다. Linux에서 GPU 할당을 제어하려면 표준 CUDA 환경 변수(CUDA_VISIBLE_DEVICES 등)를 사용하십시오.

서버 설정¶

서버 설정은 mlxcel serve 또는 mlxcel-server를 시작할 때 커맨드라인 플래그로 적용됩니다. 많은 플래그들이 위 표에서 설명한 환경 변수에서도 값을 읽어옵니다.

네트워킹 및 인증¶

예시: 로컬 네트워크에서 접근 가능하도록 인증과 함께 서버를 시작합니다.

mlxcel serve \
    --model ./models/llama-3.1-8b-4bit \
    --host 0.0.0.0 \
    --port 8080 \
    --api-key my-secret-key

생성 기본값¶

아래 플래그들은 자체 값을 지정하지 않은 요청에 적용될 기본 샘플링 파라미터를 설정합니다. 요청별 파라미터는 항상 이 기본값보다 우선 적용됩니다.

연속 배칭¶

연속 배칭은 여러 동시 요청의 디코드 스텝을 단일 포워드 패스로 묶어 한꺼번에 처리합니다. 개별 요청의 지연 시간을 늘리지 않으면서 부하 상태의 처리량을 크게 높입니다.

llama.cpp 호환성을 위해 --ctx-size C에서 C > 0이면 서버 전체 컨텍스트 예산으로 해석합니다. 슬롯별 실제 컨텍스트 윈도우는 floor(C / active_slots)이고 active_slots는 명시된 --max-batch-size, 없으면 --n-parallel입니다. --no-batch는 슬롯 1개를 사용합니다. /health.context_size, /slots[].context_size, --estimate-memory는 이 슬롯별 값을 사용합니다. 명시 예산을 나누었을 때 슬롯당 512토큰 미만이면 시작 시 오류로 거부합니다.

예시: 고동시성 환경을 위한 서버 설정.

mlxcel serve \
    --model ./models/llama-3.1-8b-4bit \
    --port 8080 \
    --n-parallel 8 \
    --max-batch-size 8 \
    --max-queue-depth 64 \
    --prefill-chunk-size 512

이 예제처럼 --prefill-chunk-size 512를 명시하면 유휴 tick과 경합 tick 모두 512로 고정됩니다. 2048/512 적응형 기본값을 쓰려면 이 플래그를 빼십시오. 청크 분할과 KV admission watermark가 스케줄러와 어떻게 맞물리는지는 연속 배칭을 참조하십시오.

투기적 디코딩¶

투기적 디코딩은 drafter가 후보 토큰을 제안하고 target 모델이 이를 검증하는 방식으로 생성을 가속합니다. 서버 모드는 DFlash/MTP drafter kind, 일반 소형 체크포인트를 쓰는 full-model drafter, drafter가 필요 없는 prompt lookup(--draft-kind prompt-lookup)을 지원합니다.

DFlash 예시:

mlxcel serve \
    --model ./models/qwen3.5-27b-4bit \
    --draft-model ./models/Qwen3.5-27B-DFlash \
    --draft-kind dflash \
    --draft-block-size 16 \
    --port 8080

채팅 템플릿¶

mlxcel은 모델의 tokenizer_config.json에서 채팅 템플릿을 자동으로 읽습니다. 사용자 지정 템플릿으로 덮어쓸 수도 있습니다.

템플릿 적용 우선순위:

1. --chat-template (인라인 문자열)
2. --chat-template-file (파일 경로)
3. tokenizer_config.json의 chat_template 필드 (자동)
4. 내장 폴백 템플릿

선택적 엔드포인트¶

웜업¶

기본적으로 서버는 시작 시 토큰 하나를 생성하고(그 후 버립니다) Metal 또는 CUDA 컴퓨트 파이프라인을 사전 컴파일합니다. 첫 번째 실제 요청의 지연 시간이 사라집니다.

# 웜업 비활성화 (더 빠른 시작, 단 첫 번째 요청이 느려집니다)
mlxcel serve --model ./models/my-model --no-warmup