개념 설명¶

이 섹션에서는 mlxcel의 설계와 구현 배경에 있는 핵심 개념들을 설명합니다. 각 페이지는 하나의 개념을 중심으로 구성되어 있으며 해당 개념이 무엇인지, 왜 존재하는지, 그리고 이 코드베이스에서 어떻게 구현되어 있는지를 다룹니다.

페이지는 명령 실행에서 모델 종류 감지를 거쳐 생성 또는 전용 추론 경로로 들어가는 요청 흐름을 따릅니다.

이 섹션의 페이지 목록¶

아키텍처 개요¶

전체 시스템을 개괄적으로 살펴봅니다. 두 바이너리 구조(mlxcel CLI와 mlxcel-server), 생성과 전용 임베딩·재순위화 작업자, 제어 평면과 데이터 평면의 분리, MLX 프레임워크로 이어지는 직접 Rust-C++ FFI 브릿지를 다룹니다.

코드베이스가 처음이라면 이 페이지부터 시작하십시오.

모델 로딩¶

mlxcel이 디스크에서 모델을 로드하는 방법을 설명합니다. 생성·임베딩·재순위화 모델 종류 감지, 생성 정책 라우팅과 로더 계열, SafeTensors 가중치 로딩, 로드 시점 모델 변환 훅을 다룹니다.

mlxcel이 런타임의 중앙 핸들 역할을 하는 LoadedModel 래퍼를 어떻게 식별하고 구성하는지 이해하고 싶다면 이 페이지를 읽으십시오.

추론 파이프라인¶

텍스트 생성의 전체 수명 주기를 설명합니다. 원시 사용자 입력부터 토크나이제이션, 채팅 템플릿 렌더링, 자기회귀 생성 루프, 토큰 스트리밍을 거쳐 최종 디코딩된 출력까지를 다룹니다. 또한 텍스트 생성 루프 이전에 이미지 처리, 시각적 인코딩, 크로스 모달 프로젝션을 추가하는 VLM 변형도 설명합니다.

추론 시점에 무슨 일이 일어나는지, 그리고 프리필과 디코드라는 두 단계가 연산 특성 면에서 어떻게 다른지 이해하고 싶다면 이 페이지를 읽으십시오.

오디오 입력 전처리¶

멀티모달 오디오 요청의 엄격한 WAV 입력 계약, 체크포인트 기반 정책 제한, Phi-4 Multimodal·Gemma 3n 전처리, 서버 admission 예산, 취소 동작을 설명합니다.

KV 캐시¶

자기회귀 디코딩을 효율적으로 만드는 키-값 캐시를 설명합니다. 세 가지 구조적 attention-cache 레이아웃(표준, rotating, chunked)을 storage/quantization mode 및 dense/paged server backend와 구분하고 시퀀스별 상태, 순환 hybrid, 메모리 회계를 설명합니다.

디코드 단계에서의 메모리와 성능 트레이드오프를 이해하고 싶다면 이 페이지를 읽으십시오.

샘플링¶

mlxcel이 각 디코드 단계에서 다음 토큰을 선택하는 방법을 설명합니다. 어휘 전체에 대한 완전한 확률 분포, 탐욕적 디코딩, 온도 스케일링, Top-K 및 Top-P(nucleus) 샘플링, Min-P 필터링, 그리고 반복 페널티, 빈도/존재 페널티, DRY(Don't Repeat Yourself), XTC와 같은 페널티 기반 방법들, 그리고 p-less 샘플링을 다룹니다. 투기적 디코딩에 대해서도 간략히 설명합니다.

샘플링 설정 파라미터들이 어떻게 상호 작용하며 출력 품질, 다양성, 일관성에 영향을 미치는지 이해하고 싶다면 이 페이지를 읽으십시오.