개발 가이드¶

이 섹션은 mlxcel 내부를 확장하고 기여하는 방법을 다룹니다.

목차¶

문서	설명
새 모델 추가하기	새 모델 아키텍처(텍스트 및 VLM) 추가를 위한 완전한 체크리스트
mlxcel-core FFI 브리지	모든 모델 구현이 사용하는 MLX C++ FFI 레이어 가이드
테스트	단위 테스트, 통합 테스트, 분산 E2E 테스트, 벤치마킹
MLXCEL 환경 변수	런타임, 서버, 빌드, 진단, CI용 `MLXCEL_*` shell 변수
OpenXLA 백엔드	StableHLO/IREE 소스 상태, 거기에 닿는 기본값 off Cargo feature, 기본 build가 MLX만 노출하는 이유

저장소 구조¶

src/
  bin/             # Binary entry points (mlxcel CLI, mlxcel-server)
  commands/        # CLI command implementations
  distributed/     # Distributed inference (TP, PP, disaggregated)
  execution/       # Runtime environment, device selection, sampling
  lib/
    mlxcel-core/   # MLX C++ FFI bridge (cxx-based bindings)
      src/engine/  # Batch-native decode engine (Engine, DirectEngine)
    mlxcel-mlx-pin/ # Unit tests for the MLX pin derivation
    mlxcel-surgery/ # Weight-load surgery framework (model surgery)
    mlxcel-xla/    # OpenXLA/StableHLO emitter and IREE runtime (opt-in)
    mlxcelverse/   # MLX-side C++ layer
      CMakeLists.txt # Fetches the pinned MLX commit, applies overlays, builds libmlx
      overlays/    # Per-backend MLX source overlays: cpu/, metal/, cuda/, rocm/
      kernels/     # mlxcel's own fused kernels and launchers (paged attention, sampling, ...)
  loading/         # Model loading pipeline (config-backed, VLM, special)
  lora/            # LoRA adapter loading
  models/          # Model implementations (one file per architecture)
  multimodal/      # VLM prompt building utilities
  server/          # HTTP server (routes, types, streaming, batch)
  tokenizer/       # Tokenizer wrapper
  vision/          # Vision encoders, connectors, processors
  loaded_model.rs  # LoadedModel enum + dispatch macros
  model_metadata.rs # Centralized model kind/adapter/route policy
tests/             # Integration and E2E tests
docs/              # Documentation

빌드 및 개발 명령¶

# Debug build
make build

# Release build (native CPU optimization)
make release

# Run tests (single-threaded; required for model tests)
make test

# Run tests with verbose output
make test-verbose

# Lint (clippy)
make lint

# Format code
make fmt

# Full development workflow (format + check + test)
make dev

# CI workflow (format check + check + lint + test)
make ci