AI 튜토리얼

Splash로 Apple Silicon에서 빠른 로컬 AI 모델 실행

지원되는 Mac에 Splash를 설치하고, 모델 서버를 실행하며, OpenAI 호환 API를 호출하고, 코딩 에이전트를 연결하고, 메모리와 컨텍스트 제한을 관리하고, 인증을 활성화하고, 고급 로컬 추론 워크플로를 최적화하는 방법을 알아보세요.

2026년 9월 19일약 12분 소요

Splash란 무엇인가요?

Splash는 Apple 실리콘을 위해 특별히 설계된 로컬 추론 엔진입니다. OpenAI 또는 Anthropic API를 지원하는 코딩 에이전트와 애플리케이션에 최적화된 언어 모델을 제공합니다. 서버는 하나의 Mac에서 로컬로 실행되며 127.0.0.1:8000에서 API를 노출합니다.

범용 추론 엔진과 달리 Splash는 지원되는 각 모델에 맞춰 커널, 추측 디코딩 초안 모델, 가중치 레이아웃 및 메모리 계획을 특화합니다. 모델 패키지는 바로 실행할 수 있는 상태로 제공되므로 Xcode, 컴파일러 도구 모음 또는 모델별 튜닝이 필요하지 않습니다.

주요 기능

로컬 Apple 실리콘 추론: Splash는 지원되는 Mac에서 모델을 직접 실행합니다.
OpenAI 호환성: /v1/chat/completions에서 Chat Completions를, /v1/responses에서 Responses를 제공합니다.
Anthropic 호환성: Anthropic Messages 요청을 /v1/messages에서 사용할 수 있습니다.
고급 요청 지원: API는 스트리밍, 도구 호출, JSON Schema 출력, 이미지 및 인라인 PDF를 지원합니다.
코딩 에이전트 통합: Splash에는 OpenCode, Claude, Codex 및 Hermes용 명령이 포함되어 있습니다.
모델별 가속: 모든 모델 패키지에는 추측 디코딩을 위한 DFlash 2 초안 모델과 해당 모델의 정확한 차원에 맞게 튜닝된 사전 컴파일 Metal 커널이 포함됩니다.
자동 메모리 계획: Splash는 시작 시 Metal에서 사용할 수 있는 메모리를 기준으로 컨텍스트, KV 캐시 용량 및 배치 제한을 계산합니다.
프롬프트 검사: /tokenize 및 /apply-template 엔드포인트는 추론을 실행하지 않고 토큰 ID 또는 렌더링된 프롬프트를 반환합니다.

시스템 요구 사항

Splash를 설치하기 전에 시스템이 다음 요구 사항을 모두 충족하는지 확인하세요:

Apple M3 이상 프로세서
macOS 26.4 이상
Homebrew
통합 메모리 36GB 이상
통합 메모리 48GB 이상 권장

사용 가능한 컨텍스트 용량은 메모리 상태에 따라 달라집니다. 지원되는 모델의 네이티브 컨텍스트 윈도우는 최대 256K이지만, 모든 Mac에서 전체 윈도우를 사용할 수 있는 것은 아닙니다.

Splash 설치

Inco Homebrew tap을 통해 패키지 릴리스를 설치합니다:

brew install incoai/tap/splash

생성해야 할 구성 파일은 없습니다. Splash는 선택적 설정에 명령줄 플래그와 환경 변수를 사용합니다.

모델 서버 시작

다음 명령으로 최적화된 Qwen3.8-27B 패키지를 제공합니다:

splash serve --model incoai/Qwen3.8-27B-Splash

처음 실행하면 Splash가 모델 패키지를 다운로드하고 확인한 다음, 사용 가능한 메모리를 점검하고 메모리 계획을 생성한 뒤 127.0.0.1:8000에서 서버를 시작합니다. Qwen3.8-27B 패키지는 17.4GB를 다운로드하며 4비트 대상 모델과 DFlash 2 초안 모델을 포함합니다.

터미널에 Ready가 표시될 때까지 기다리세요. 모델을 사용하는 동안 해당 터미널을 열어 두세요. 그런 다음 브라우저에서 http://127.0.0.1:8000을 열어 채팅 페이지에 접속할 수 있습니다.

Splash를 중지하려면 서버 터미널에서 Ctrl+C를 누르세요.

대체 모델 사용

Splash는 4비트 Qwen3.6-35B-A3B 모델과 DFlash 2 초안 모델이 포함된 20.9GB 패키지도 제공합니다:

splash serve --model incoai/Qwen3.6-35B-A3B-Splash

--model 옵션에는 유효한 Splash 패키지가 포함된 다른 owner/repo 저장소를 지정할 수 있습니다. 일반 MLX 및 Transformers 체크포인트는 호환되지 않습니다. 비공개 Hugging Face 저장소를 사용하려면 적절한 HF_TOKEN을 제공하세요.

코딩 에이전트 연결

서버가 준비되었다고 보고하면 다른 터미널을 열고 지원되는 설치된 코딩 에이전트 중 하나를 실행하세요:

splash opencode
splash claude
splash codex
splash hermes

사용하려는 에이전트에 해당하는 명령만 실행하세요. 에이전트가 요청을 보내는 동안 원래 서버 프로세스가 계속 실행 중이어야 합니다.

OpenAI Chat Completions API 호출

애플리케이션은 Splash를 OpenAI 호환 로컬 서버로 호출할 수 있습니다. 다음 요청은 실행 중인 모델에 한 문장으로 설명해 달라고 요청합니다:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "incoai/Qwen3.8-27B-Splash",
    "messages": [
      {
        "role": "user",
        "content": "Explain speculative decoding in one sentence."
      }
    ]
  }'

model 속성은 선택 사항입니다. 포함하는 경우 값이 현재 제공 중인 패키지와 일치해야 합니다.

적절한 API 엔드포인트 선택

OpenAI Chat Completions 클라이언트에는 /v1/chat/completions를 사용하세요.
OpenAI Responses 클라이언트에는 /v1/responses를 사용하세요.
Anthropic Messages 클라이언트에는 /v1/messages를 사용하세요.
모델을 실행하지 않고 토큰 ID를 가져오려면 /tokenize를 사용하세요.
추론을 실행하지 않고 렌더링된 프롬프트를 확인하려면 /apply-template을 사용하세요.

추론 제어

추론은 기본적으로 활성화되어 있습니다. 비활성화하려면 요청 본문에 "reasoning_effort": "none"을 추가하세요. Qwen3.8-27B는 low, medium 및 xhigh도 허용합니다.

{
  "model": "incoai/Qwen3.8-27B-Splash",
  "reasoning_effort": "none",
  "messages": [
    {
      "role": "user",
      "content": "Summarize speculative decoding."
    }
  ]
}

추론을 비활성화하면 긴 추론 과정이 필요하지 않은 작업에서 유용할 수 있습니다. 추론의 이점을 얻을 수 있는 Qwen3.8-27B 작업에서는 워크로드에 맞춰 지원되는 추론 수준을 선택하세요.

메모리 및 컨텍스트 제한 구성

Splash는 적절한 기본값을 자동으로 결정하지만, splash serve는 더욱 세밀하게 제어할 수 있는 선택적 플래그를 제공합니다.

--max-memory 28G는 Metal 할당량의 상한을 설정합니다.
--max-context 100K는 컨텍스트 창을 제한합니다. 모델의 기본 최대 한도는 256K입니다.
--max-image-pixels는 각 이미지의 최대 조정 픽셀 수를 제어합니다. 기본값은 4,194,304입니다.
--allowed-host는 프록시에서 사용하는 호스트와 같은 추가 HTTP Host 이름을 허용합니다. 이 옵션은 여러 번 사용할 수 있습니다.
--no-webui는 브라우저 채팅 페이지를 비활성화합니다.

예를 들어 다음 명령은 Metal 할당량을 28 GB로 제한하고 컨텍스트를 100K로 제한합니다.

splash serve \
  --model incoai/Qwen3.8-27B-Splash \
  --max-memory 28G \
  --max-context 100K

모델이 사용 가능한 메모리에 들어가지 않으면 Splash는 메모리 예산 내역을 출력하고, 사용할 수 없는 서버를 시작하는 대신 종료합니다. 컨텍스트 또는 메모리 요구량을 줄이면 도움이 될 수 있지만, 모델 가중치와 필요한 런타임 상태는 여전히 메모리에 들어가야 합니다.

로컬 API 보호

인증은 기본적으로 비활성화되어 있습니다. 서버를 시작하는 셸에서 SPLASH_API_KEY를 설정하면 키를 요구할 수 있습니다.

export SPLASH_API_KEY='replace-with-your-key'
splash serve --model incoai/Qwen3.8-27B-Splash

Splash가 관리하는 코딩 에이전트를 실행할 때 사용하는 셸에도 동일한 환경 변수를 설정하세요.

export SPLASH_API_KEY='replace-with-your-key'
splash opencode

API 클라이언트는 bearer 토큰 또는 x-api-key 헤더를 통해 키를 전송할 수 있습니다. 서버의 --api-key 옵션으로 키를 직접 제공할 수도 있습니다. 상태 및 준비 상태 프로브는 계속 공개된 상태로 유지됩니다.

고급 팁

모델 캐시를 고려한 계획

다운로드한 패키지는 Hugging Face 캐시에 저장됩니다. brew upgrade splash를 실행해도 이러한 패키지, 모델 링크 및 에이전트 세션은 유지되므로 엔진을 업그레이드할 때 이를 삭제할 필요가 없습니다.

프록시에서 호스트 허용 목록 사용

서버는 로컬에서 127.0.0.1:8000에 바인딩됩니다. 로컬 프록시가 다른 HTTP Host 값을 보내는 경우 --allowed-host로 해당 호스트 이름을 추가하세요. 여러 호스트 이름을 허용해야 한다면 이 플래그를 반복해서 사용하세요.

API 전용 사용을 위해 웹 인터페이스 비활성화

Splash가 애플리케이션 또는 에이전트만 제공할 경우 --no-webui와 함께 시작하세요. 이렇게 하면 지원되는 API 엔드포인트는 유지하면서 채팅 페이지를 끌 수 있습니다.

추론 전에 프롬프트 검사

토큰 ID가 필요하면 /tokenize를 사용하고, 최종 렌더링된 프롬프트를 확인하려면 /apply-template을 사용하세요. 이러한 엔드포인트는 모델을 실행하지 않으므로 컨텍스트 크기와 프롬프트 형식을 디버깅할 때 유용합니다.

SSD 캐시 오프로딩 실험

풀 리퀘스트 3의 실험적 구현은 KV 캐시와 GDN 상태를 SSD로 오프로드할 수 있습니다. 해당 브랜치를 빌드한 후 --max-cache-disk 8G와 함께 서버를 시작하면 이 기능이 활성화됩니다. RAM이 제한된 경우 재사용 가능한 프리픽스를 보존하고 반복적인 프리필 작업을 줄이는 데 도움이 될 수 있습니다.

SSD 오프로딩 기능은 실험 단계이며 빠른 시작에서 설명한 표준 패키지 워크플로에는 포함되지 않습니다.

Splash 성능 이해

Splash는 각 모델에 맞게 대부분의 추론 스택을 특화하여 속도를 높입니다. 추측 디코딩은 선택적 모드가 아니라 표준 디코딩 경로입니다. 모델별 DFlash 2 초안 모델이 토큰 블록을 제안하면 대상 모델이 이를 병렬로 검증합니다.

퓨즈드 Metal 커널은 모델의 정확한 형태에 맞춰 컴파일되며, 추가 복사 없이 디스크에서 매핑된 특수 패킹 가중치를 읽습니다. Splash는 시작 시 현재 시스템에 맞는 컨텍스트, 캐시 및 배치 제한도 계산합니다.

프로젝트가 16코어 GPU와 48 GB 메모리를 탑재한 M5 Pro에서 측정한 결과에 따르면 Qwen3.8-27B는 짧은 프롬프트 디코딩에서 초당 74토큰에 도달했으며, 캐시된 32K 컨텍스트를 재생할 때 첫 토큰을 282 ms 만에 반환했습니다. 결과는 모델, 프롬프트, 동시성, 하드웨어 및 메모리 상태에 따라 달라집니다. Splash 출시 게시물에서 벤치마크 방법과 비교 결과를 확인할 수 있습니다.

결론

Splash는 최신 Apple silicon에서 엄선된 고도로 최적화된 모델을 실행하는 간소화된 방법을 제공합니다. Homebrew로 설치하고 호환되는 Splash 모델 패키지를 시작한 다음 브라우저, 지원되는 코딩 에이전트 또는 OpenAI 및 Anthropic 호환 API를 통해 연결하세요. 자동 기본값으로 초기 설정은 간단하게 진행할 수 있으며, 메모리, 컨텍스트, 보안, 호스트 및 인터페이스 옵션을 사용하면 더욱 세밀하게 배포를 제어할 수 있습니다.