<div align="center">
mlxtop
로컬 LLM을 위한 top 도구. 메모리, 페이징 또는 GPU 중 무엇이 모델 속도를 늦추는지 확인하세요.
Release
CI
License: MIT
Platforms
mlxtop Overview on a Mac Studio running oMLX through Splash
설치 · 빠른 시작 · 지원 런타임 · 사용자 가이드 · 변경 로그
</div>
로컬 모델이 느려질 때, 원인은 보통 기기 자체에 있습니다: 메모리 압력, 스와핑(swapping), GPU 포화 또는 쓰로틀링된 카드입니다. mlxtop은 토큰/초, 프리필 진행률, 대기 중인 요청 및 캐시 재사용과 같은 런타임 자체의 수치 옆에 이러한 측정값을 보여주어 모델이 느려졌을 때 무엇이 변경되었는지 확인할 수 있게 합니다.
- 메모리 우선: RAM이 보유하는 것(와이어드, 앱, 압축, 캐시), OS 압력, 압축 및 페이징 각각을 경고율과 비교하여 측정합니다.
- 실시간 추론 (Live inference): 생성 속도 및 프리필 속도, 프롬프트 크기, 캐시된 토큰, 큐 및 런타임 자체의 프리필 진행률로, CPU나 GPU 사용량으로 절대 추정하지 않습니다.
- 간단한 진단: 단일 라인에
✓ Healthy가 표시되거나, 과도한 페이징(heavy paging), 모델 일부가 CPU에 있는 경우, 포화된 카드 또는 열 쓰로틀링과 같은 문제를 명시합니다.
- 13개 런타임: oMLX, Splash, mlx-serve, vLLM, SGLang, llama.cpp, Ollama, LM Studio, KoboldCpp 등 13개의 런타임을 자동으로 감지합니다.
- 로컬 및 읽기 전용: sudo가 필요 없고, 계정이 필요 없으며, 분석 데이터(analytics)를 보내지 않습니다. 프롬프트를 보내거나 모델 또는 런타임 설정을 건드리지 않습니다.
3.1.1 버전의 새로운 기능: 재시작 없이 설정 파일을 편집하고 적용하는 '설정(Settings)' 탭, 종료 전에 Esc 키를 누르면 확인 메시지 표시, 알람을 끄는 스위치, 차트 확대용 더블 클릭 기능, 그리고 mlx-serve 프리필 진행률입니다. 3.1 버전에서는 재설계된 개요(Overview), mlxtop update, 그리고 Splash를 통한 oMLX가 추가되었습니다.
릴리스 노트 →
설치 (Install)
Homebrew (macOS 및 Linux):
brew install maximpri/tap/mlxtop
설치 스크립트 (Apple Silicon용 macOS, Linux x86_64 및 ARM64): sudo 없이 ~/.local/bin에 설치됩니다:
curl -fsSL https://raw.githubusercontent.com/maximpri/mlxtop/main/scripts/install.sh | sh
Windows (x86_64, PowerShell, 관리자 권한 불필요):
irm https://raw.githubusercontent.com/maximpri/mlxtop/main/scripts/install.ps1 | iex
두 스크립트 모두 다운로드된 SHA-256 체크섬을 확인합니다. Linux 빌드는 런타임 종속성이 없는 정적 바이너리입니다. 또한 최신 릴리스에서 macOS 설치 프로그램(.dmg, 서명되지 않음) 또는 아카이브를 다운로드할 수 있습니다.
업데이트하려면 mlxtop update (--rc는 릴리스 후보용)을 실행하거나, Homebrew로 설치했다면 brew upgrade mlxtop을 사용합니다.
<details>
<summary>소스에서 빌드</summary>
Rust 1.88 이상이 필요합니다:
git clone https://github.com/maximpri/mlxtop.git
cd mlxtop
cargo install --path . --locked
</details>
빠른 시작
mlxtop
mlxtop --once
mlxtop doctor
모델을 로드하지 않은 경우에도 메모리 및 GPU 측정 항목이 즉시 표시됩니다. 런타임을 시작하고 프롬프트를 보내면, 답변하는 동안 Overview를 관찰할 수 있습니다.
| 보기 | 보여주는 내용 |
|---|
| 1 · 개요 (Overview) | 판정(verdict), 메모리, 압축, 페이징, 프롬프트 로드, 생성, 프리필(prefill), GPU, 캐시, 큐 및 최근 이벤트 |
| ... | |
| 키 | 동작 |
| --- | --- |
1–4 / Tab | 보기 전환 |
| ... | |
| 사용자 가이드에서는 모든 차트, 그 임계값, 그리고 각 측정 항목이 어디에서 오는지 설명합니다. | |
지원되는 런타임
| Runtime | Live speed | What you get |
|---|
| oMLX | ✓ | 모델, 프롬프트 및 생성 속도, 프리필(prefill) 진행 상황이 있는 요청, 캐시 활동; Splash를 통해 oMLX 서비스를 따릅니다 |
| ... | | |
| "After completion"은 사용량 기록기 또는 포함된 Python 헬퍼에 의해 기록되는 각 완료된 요청의 속도를 의미합니다. mlxtop은 한 번에 하나의 서버만 모니터링하므로, 포트, 사용자 지정 URL 및 인증에 대한 내용은 프로바이더 엔드포인트를 참조하십시오. | | |
| macOS (Apple Silicon) | Linux (x86_64, ARM64) | Windows (x86_64) |
|---|
| 메모리 압력 (Memory pressure) | 네이티브 (Native) | MemAvailable 및 PSI | 커밋 차지 (Commit charge) |
| ... | | | |
| macOS 11 이상이 필요합니다. Intel Mac은 지원되지 않습니다. | | | |
설정 (Configuration)
mlxtop은 별도의 설정 없이 작동합니다. 새로 고침 속도, 기록 길이, oMLX 엔드포인트, 알람 또는 경고 임계값을 변경하려면 4를 눌러 **설정(Settings)**으로 이동하십시오: 변경 사항은 즉시 적용되며 ~/.config/mlxtop/config.json에 저장됩니다. 해당 파일은 수동으로도 편집할 수 있습니다:
{
"interval": 2,
"omx": { "host": "127.0.0.1", "port": 8080 }
...
모든 필드와 기본값은 설정 참조(configuration reference)에 나열되어 있습니다.
제한 사항 (Limits)
- GPU 활동은 단일 모델이 아닌 전체 시스템을 다룹니다.
- 폴링(Polling)은 샘플링되므로, 두 샘플 사이에 시작하고 끝나는 요청은 놓칠 수 있습니다.
- mlxtop은 모델이 느려졌을 때 무엇이 변경되었는지 보여주지만, 원인을 증명할 수는 없습니다.
- 기록은 현재 세션에 대해서만 유지됩니다.
개인 정보 보호 (Privacy)
mlxtop은 시스템 카운터, 프로세스 정보 및 사용 중인 런타임의 로컬 API를 읽습니다. 분석 기능이 없으며, 아무것도 업로드하지 않고, 기본적으로 제공자 자격 증명(provider credentials)을 사용자 자신의 기기에 있는 엔드포인트로만 전송합니다. 로컬 진단 로그에는 프롬프트, 모델 출력 또는 API 키가 포함되지 않습니다. 데이터 소스 및 개인 정보 보호와 보안 정책을 참조하세요.
기여 (Contributing)
버그 보고, 문서 수정 및 새로운 런타임 어댑터가 환영받습니다. 먼저 CONTRIBUTING.md를 읽어주시고, 대규모 변경 작업을 시작하기 전에 이슈(issue)를 열어주세요. 버그를 보고할 때, mlxtop --version 및 mlxtop doctor의 출력과 사용 중인 OS 및 런타임을 포함해 주세요.
mlxtop은 Duet 코딩 에이전트(coding agent)와 함께 개발되었습니다.
라이선스 (License)
MIT. 종속성(Dependencies)은 각자의 라이선스를 유지합니다. mlxtop은 독립적인 프로젝트이며 Apple과 제휴하지 않습니다.
