Splash 1.3.0으로 Qwen3.8-27B 프리필과 캐시 설정하기

Qwen3.8-27B의 모델 ID를 지정해 Splash 서버를 실행하면 가중치와 모델에 맞는 DFlash2 초안 파일을 준비해요. 준비가 끝나면 로컬 주소로 들어온 질문을 처리하고 답변을 반환해요.

긴 코드나 문서를 보내면 모델이 입력을 읽고 첫 토큰을 내놓기까지 기다려요. 이 입력 처리 단계를 프리필이라고 해요. 첫 토큰 뒤에 답변을 차례로 만드는 디코드⁷는 다음 단계예요. Splash 1.3.0은 지원되는 고밀도 모델의 긴 프리필에서 Neural Engine을 활용하고, Qwen3.8-27B 답변 생성은 GPU에서 처리해요.

긴 입력에서 첫 토큰이 늦게 나오면 Neural Engine 프리필을 비교하고, 답변 문장이 느리게 이어지면 디코드 속도를 따로 살펴보세요. Splash는 시작 시 Mac과 모델에 맞춰 입력 길이별 분할을 조정해요.

Apple M3 이상 Mac, macOS 26.4 이상, Homebrew가 필요해요. Qwen3.8-27B 4비트 예제에는 통합 메모리⁸ 36GB 이상이 필요하며 48GB를 권장해요. 첫 실행은 모델과 초안 가중치를 내려받으므로 저장 공간과 인터넷 연결도 준비하세요.

먼저 Homebrew로 설치한 다음 첫 번째 터미널에서 서버를 실행하세요. 서버 명령은 계속 실행되는 상태로 두고 Ready 표시가 나올 때까지 기다려요. 아래의 API 확인 명령은 새 터미널에서 실행합니다.

서버 터미널에 Ready가 표시되면 브라우저에서 http://127.0.0.1:8000을 여세요. Splash의 채팅 화면이 열리고 질문을 보내 답을 받을 수 있어요. 서버는 기본적으로 이 Mac 안의 로컬 주소에서 대기해요. 터미널을 닫거나 Ctrl+C를 누르면 서버가 멈춥니다.

다른 터미널에서 아래 API 요청을 보내 모델까지 연결됐는지 확인하세요. 반환된 JSON의 choices 배열에 답변 문장이 있으면 요청이 처리된 거예요.

oMLX 0.7.1rc1에서는 기존 모델 목록과 API를 유지한 채 계산만 Splash에 맡길 수 있어요. Splash 1.3.0 이상을 설치하고 Settings → Integrations → External engines를 여세요. 탐지된 실행 파일의 경로와 버전이 표시되면, Qwen3.8-27B 모델 폴더와 z-lab/Qwen3.8-27B-DFlash2 초안 모델을 준비해요.

1.3.0에서는 mlx-community/Qwen3.8-27B-4bit처럼 affine 4비트·group 64인 MLX⁹ 체크포인트¹⁰를 사용해요. 1.3.1은 mixed-bit 체크포인트도 받아요. oMLX 외부 엔진에는 예전 incoai/*-Splash 사전 패키지 대신 지원되는 MLX 파일을 지정하세요.

Model Settings → Advanced에서 Use external engine을 켜고 Splash를 고르세요. oMLX가 로컬 포트와 API 키를 관리해 별도 프로세스로 실행해요. 한 번 짧게 질문한 뒤 대시보드의 프리필 진행과 생성 속도를 확인하면 돼요. 시작하지 못하면 Integrations의 실행 파일 경로, 모델 형식, 초안 파일 순서로 점검하세요.

메모리 한도·KV 정밀도·SSD 캐시·Neural Engine 프리필은 Integrations의 Splash 항목에서 조정해요. Splash 실행 중에는 해당 엔진의 DFlash2와 캐시 설정을 사용해요. 다른 oMLX 모델에 지정한 Lightning MTP¹¹나 TurboQuant 설정을 바꾸지 말고, 같은 문서를 Splash와 기본 엔진에서 각각 실행해 TTFT¹²와 완료 시간을 비교하세요.

--disable-ane를 넣지 않으면 Splash 1.3.0은 지원되는 dense 대상에서 GPU와 Neural Engine의 FFN 계산을 나눠 처리할 수 있어요. 시작할 때 Mac과 모델에 맞춰 분할 비율을 보정하고, 어느 입력 길이부터 이득이 있는지 선택한 뒤 결과를 기억해요. 평가 실패, 제한 시간 초과, 유효하지 않은 계산값이 나오면 해당 구간을 GPU에서 다시 처리합니다.

Splash 1.3.0 릴리스의 Qwen3.8-27B 측정이에요. MLX 4비트 가중치, 요청 1개, 프롬프트¹³ 캐시를 재사용하지 않은 14,096토큰 입력으로 프리필과 첫 토큰까지의 시간(TTFT)을 비교했어요. M5 Max는 GPU 단독 14.09초, GPU+Neural Engine 12.36초였고 M5 Pro는 각각 28.28초, 21.57초였어요. TTFT는 입력 처리와 첫 토큰 출력까지 걸린 시간으로, 답변 생성 속도와 구분해 봐야 해요.

프리필 분할은 KV 캐시¹⁴에 쓸 메모리 일부를 사용해요. 긴 입력을 받는 문맥 한도는 GPU 단독보다 낮아질 수 있으니, 내 Mac에서 시작 요약과 /status의 maximum_context_tokens를 확인하세요. 짧은 답변이 이어지는 속도는 디코드 처리량¹⁵으로 따로 비교해요.

같은 문서나 지시문을 포함해 후속 질문을 보내면 앞부분을 다시 읽는 계산이 생길 수 있어요. Splash 1.3.0은 공유 프리픽스가 긴 대화에서 완료된 프리필 체크포인트를 재사용해, 두 번째 대화가 달라지는 지점부터 이어 처리할 수 있어요. 공개된 19K토큰 공통 프리픽스 사례에서는 두 번째 대화의 TTFT가 39.6초에서 6.3초로 줄었고 16,384토큰을 재사용했어요.

이 측정에서는 27B 모델의 복구 지점 하나가 187MiB를 추가로 사용했어요. 디스크 캐시를 켜면 메모리에서 밀려난 상태를 SSD에 쓸 수 있어요. --max-cache-disk 16G처럼 용량을 지정하면 현재 서버 실행 동안 SSD 캐시를 사용하고, 서버를 다시 켠 뒤에도 유지하려면 --persistent-cache를 함께 지정해요.

처음에는 디스크 옵션 없이 같은 긴 문서를 포함한 대화 두 개를 보내 프리픽스 재사용을 확인하세요. 반복 후에도 메모리가 모자라거나 상태가 밀려나는 경우에만 여유 SSD 용량을 확인하고 디스크 캐시를 추가해요. SSD 캐시는 문맥 한도를 높이지 않으며, 저장 공간이 작업 데이터보다 작으면 읽기와 쓰기가 반복될 수 있어요.

같은 입력을 다시 보낼 때 캐시가 재사용되는 양은 공통 접두부의 길이에 따라 달라져요. 같은 모델과 문서, 질문을 두 번 보내 첫 요청과 재요청의 TTFT를 각각 기록해 보세요.

프리픽스·SSD 캐시의 재사용 조건을 먼저 같게 맞추세요. 같은 모델과 긴 입력으로 GPU+Neural Engine 설정의 TTFT를 기록한 뒤, --disable-ane를 붙여 서버를 다시 시작하고 GPU 단독 결과를 측정해요. 각 설정의 첫 실행과 반복 실행을 구분하면 보정·컴파일 시간의 영향도 따로 확인할 수 있어요.

처음 Neural Engine 프로그램을 실행할 때는 컴파일과 분할 보정에 시간이 더 걸릴 수 있어요. /status의 ane_ffn에서 분할 상태와 비율, 최소 입력 chunk 크기, 평가 횟수, GPU 재실행 횟수를 확인할 수 있어요. 짧은 입력에서 이득이 없으면 GPU 단독 경로를 자동으로 선택해요.

서버가 준비되지 않으면 터미널에서 첫 오류와 macOS 버전을 확인하고, 브라우저가 연결되지 않으면 Ready 표시와 포트 8000 사용 여부를 살펴보세요. 문맥 길이 때문에 모델이 시작되지 않으면 자동 한도를 시작 요약과 /status에서 확인하고, 필요하면 --max-context를 낮춰요. Neural Engine 동작이 불안정하거나 비교 기준을 고정하고 싶을 때는 --disable-ane를 사용해 GPU 단독 프리필로 바꿀 수 있어요.

같은 긴 입력에서 Neural Engine을 켰을 때 TTFT가 줄고 필요한 문맥 길이도 유지되면 기본 경로를 쓰세요. 문맥이 부족하거나 측정이 불안정하면 --disable-ane로 GPU 단독을 선택하면 돼요.

첫 splash serve는 지정한 Qwen 가중치와 짝을 이루는 DFlash2 초안 가중치를 Hugging Face에서 받아요. Qwen3.8-27B 4비트 예제는 두 파일을 합쳐 최대 약 21GB까지 저장 공간을 쓸 수 있어요. 다운로드 진행이 멈춘 것처럼 보이면 서버를 종료하기 전에 터미널의 마지막 진행 줄과 인터넷 연결을 확인하세요. 다시 실행하면 이미 받은 파일을 재사용합니다.

터미널에 모델 저장소를 찾을 수 없다는 오류가 나오면 --model 값을 다시 확인해요. 이 가이드의 MLX ID는 mlx-community/Qwen3.8-27B-4bit예요. 저장소가 비공개이거나 접근 승인이 필요한 경우에는 본인 계정으로 Hugging Face 로그인하거나 HF_TOKEN을 설정해야 해요. 모델 이름과 접근 권한을 바로잡은 뒤 같은 명령을 다시 실행하세요.

가중치를 다 받았는데 메모리 예산 오류가 나면 모델 파일을 다시 받을 필요는 없어요. 현재 모델과 문맥 길이가 Mac의 메모리 예산에 맞지 않는 경우예요. --max-context를 낮춰 다시 시작하고, 메모리 24GB Mac이라면 지원 모델 목록에서 더 작은 GGUF¹⁶ 변형을 선택하세요.