Apple Silicon의 MLX LM

Libre WebUI에는 M 시리즈 Mac에서 MLX 형식 언어 모델을 직접 실행하는 MLX LM(Apple Silicon) 플러그인이 포함되어 있습니다. 플러그인은 MLX LM에 내장된 OpenAI 호환 HTTP API에 연결됩니다.

MLX 체크포인트를 Ollama 또는 GGUF 모델로 변환하지 않고 네이티브 Metal 추론을 사용하려는 경우에 유용합니다.

아키텍처

Libre WebUI in native development mode
  frontend http://localhost:5173
  backend  http://localhost:3001
                  |
                  | OpenAI-compatible chat request
                  v
mlx_lm.server http://127.0.0.1:8081
                  |
                  v
MLX model on Apple Silicon unified memory

포트 8081은 의도적으로 선택되었습니다. MLX LM은 보통 기본값으로 8080을 사용하며, 이는 패키지형 npx libre-webui 서버와 충돌합니다.

요구 사항

Apple Silicon Mac(M1 이상)
Xcode 명령줄 도구를 사용할 수 있는 macOS
Python 3.10 이상
선택한 모델, KV 캐시 및 macOS에 충분한 통합 메모리
네이티브로 실행되는 Libre WebUI. 두 백엔드가 모두 Mac 루프백 인터페이스를 사용할 수 있으므로 소스 개발 워크플로가 가장 간단합니다.

기본 Ternary Bonsai 모델은 디스크에서 약 8.5 GB를 차지하며 실행 중에는 더 많은 메모리가 필요합니다. 16 GB 통합 메모리가 있는 Mac은 짧은 컨텍스트를 처리할 수 있지만 24 GB 이상이면 실용적인 여유가 더 큽니다. 메모리가 부족하면 더 작은 MLX 체크포인트를 사용하고 복사한 플러그인 정의에 저장소 ID를 추가하세요.

MLX LM 설치

uv를 사용하면 명령이 Homebrew Python 패키지에서 격리됩니다.

brew install uv
uv tool install --upgrade mlx-lm
rehash
mlx_lm.server --help

도구가 이미 있다면 다음을 실행합니다.

uv tool upgrade mlx-lm
rehash

Qwen 3.5 모델에는 mlx-lm 0.30.7 이상이 필요합니다. 저장소 예제에는 0.31.3 이상이 필요합니다.

서버 시작

Ternary Bonsai 모델의 경우:

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 262144 \
  --allowed-origins "http://localhost:5173,http://127.0.0.1:5173"

처음 실행하면 Hugging Face에서 모델을 다운로드합니다. 이후에는 로컬 캐시를 사용합니다. Ternary Bonsai는 최대 위치 수로 262144를 선언합니다. 프롬프트와 생성 출력은 같은 컨텍스트 창을 공유하므로 서버 허용량을 모델 최대값으로 설정해도 긴 프롬프트는 생성 가능한 토큰 수를 줄입니다.

더 작은 시작 모델의 경우:

mlx_lm.server \
  --model "mlx-community/Llama-3.2-3B-Instruct-4bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 2048

저장소에는 재사용 가능한 실행기도 포함되어 있습니다.

cd examples/mlx-lm-server
uv run server.py

모델을 로드하지 않고 해석된 명령을 확인합니다.

uv run server.py --dry-run

OpenAI 호환 API 확인

상태와 모델 검색을 확인합니다.

curl http://127.0.0.1:8081/health
curl http://127.0.0.1:8081/v1/models

스트리밍하지 않는 채팅 요청을 보냅니다.

curl http://127.0.0.1:8081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "prism-ml/Ternary-Bonsai-27B-mlx-2bit",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Reply with: MLX is ready."}
    ],
    "temperature": 0.7,
    "top_p": 0.95,
    "max_tokens": 64,
    "stream": false
  }'

서버는 "stream": true일 때 스트리밍 Server-Sent Events도 지원합니다.

Libre WebUI 연결

Libre WebUI 저장소 루트에서 다음을 실행합니다.

npm install
npm run dev

http://localhost:5173을 연 다음 다음을 수행하세요.

설정 > 플러그인을 엽니다.
**MLX LM(Apple Silicon)**을 찾습니다.
엔드포인트가 http://127.0.0.1:8081/v1/chat/completions인지 확인합니다.
플러그인을 활성화합니다. 로컬 MLX에는 API 키가 필요하지 않습니다.
Chat으로 돌아가 MLX 모델을 선택합니다.

기본 제공 모델 목록에는 다음이 포함됩니다.

prism-ml/Ternary-Bonsai-27B-mlx-2bit

Libre WebUI에서 선택한 모델은 MLX 서버에서 사용할 수 있는 모델과 일치해야 합니다. 다른 체크포인트를 사용하려면 plugins/mlx-lm.json을 내보내거나 복사하고, 저장소 ID를 model_map에 추가한 뒤 설정 > 플러그인에서 편집한 정의를 가져오세요.

생성 설정

Ternary Bonsai에서 공개한 권장값은 다음과 같습니다.

설정	값
Temperature	`0.7`
Top P	`0.95`
Top K	`20`

Libre WebUI는 플러그인을 통해 temperature와 Top P를 보냅니다. 권장 Top K 값을 사용하려면 서버를 --top-k 20으로 시작하세요.

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --top-k 20 \
  --max-tokens 262144

Work 및 도구 호출

MLX 플러그인은 OpenAI 호환 채팅 형식을 사용하므로 Work에 표시될 수 있습니다. 모델과 채팅 템플릿이 OpenAI 방식 도구 호출을 안정적으로 지원할 때만 Work에서 선택하세요. Chat에서 일반 텍스트 생성이 작동한다고 해서 체크포인트가 도구를 지원한다는 뜻은 아닙니다.

도구 파서와 모델 템플릿은 빠르게 변합니다. Work 실행에서 잘못된 도구 호출이 반환되면 mlx-lm을 업데이트하고, 동일한 도구 요청을 서버에 직접 테스트하고, MLX 카드에 도구 사용이 명시된 모델을 사용해 보세요.

Docker 네트워킹

Libre WebUI의 네이티브 개발 실행을 권장합니다. 컨테이너는 Mac의 127.0.0.1에 접근할 수 없습니다.

Libre WebUI를 Docker에서 실행한다면 다음을 수행하세요.

--host 0.0.0.0으로 MLX LM을 시작합니다.
http://192.168.1.20:8081/v1/chat/completions 같은 비공개 Mac LAN 주소를 플러그인 엔드포인트로 사용합니다.
신뢰할 수 있는 로컬 네트워크에만 포트 8081을 허용합니다.

mlx_lm.server를 공개 인터넷에 직접 노출하지 마세요. 관리자들은 기본적인 보안 검사만 있는 로컬 서버라고 설명합니다. 로컬이 아닌 배포에는 인증된 HTTPS 역방향 프록시를 앞에 배치하세요.

문제 해결

Model type qwen3_5 not supported

이전 실행기가 여전히 사용되고 있습니다.

rehash
which -a mlx_lm.server
uv tool upgrade mlx-lm

Libre WebUI에 모델이 표시되지만 요청이 실패함

동일한 모델 ID가 직접 작동하는지 확인합니다.

curl http://127.0.0.1:8081/v1/models

그런 다음 플러그인 엔드포인트에 /v1/chat/completions가 포함되어 있는지 확인하세요.

주소가 이미 사용 중임

Libre WebUI는 정상 포트에 두고 MLX를 옮깁니다.

mlx_lm.server --model "owner/model" --port 8082

플러그인 엔드포인트를 http://127.0.0.1:8082/v1/chat/completions로 업데이트하세요.

첫 요청에서 모델이 느림

초기 로드와 프롬프트 프리필은 토큰 단위 생성보다 비용이 큽니다. Activity Monitor에서 메모리 압력을 확인하고 macOS가 스왑을 시작하면 더 작은 모델이나 더 짧은 대화를 선택하세요.

아키텍처​

요구 사항​

MLX LM 설치​

서버 시작​

OpenAI 호환 API 확인​

Libre WebUI 연결​

생성 설정​

Work 및 도구 호출​

Docker 네트워킹​

문제 해결​

관련 문서​