Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Xyntetik Runner는 AI 모델의 추측 기반 실행 결과를 실제 측정 가능한 데이터로 대체하는 라이프사이클 엔진입니다. 이 도구는 모델을 기기에 적합한지, 메모리 사용량은 어떠한지 등을 정확하게 검증할 수 있게 합니다. 특히, 모델 크기 최적화, 컨텍스트 캐시 효율성 확인, 그리고 실제 실행 상태 유지 등 개발 과정에서 발생하는 불확실성을 해소하는 데 도움을 줍니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기모델을 직접 실행하는 것은 대부분 추측에 의존합니다. 적합할까요? 축소했더니 작동하지 않게 된 걸까요? 아무것도 실행하고 있지 않은데 왜 노트북 메모리가 부족할까요? Runner는 이러한 추측들을 확인할 수 있는 답변으로 대체하기 위해 존재합니다.
<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="site/assets/readme-fit-dark.svg"> <img src="https://raw.githubusercontent.com/Joakimpalm-Zen/xyntetik-runner/HEAD/site/assets/readme-fit-light.svg" alt="runner --fit reading the first 16 MB of Granite 4.2 8B on an RTX 3070: FITS, 35 of 40 layers on the GPU" width="560"> </picture> </p> <p align="center"><sub class="Real output:">실제 출력: Runner가 RTX 3070에서 Granite 4.2 8B에 대해 문의했으며, 적합하게 축소되었습니다. <a href="docs/compat-reports/fit-capture-1.0.2-2026-10-06-rtx3070.md">전체 캡처</a></sub></p>사용해 보는 것은 약 1분이면 충분합니다: quick start.
버전
1.4.2. 명령줄, HTTP API, 기록 형식 및 로드되는 모델 파일은 1.x 전반에 걸쳐 호환됩니다 (versioning policy). 이 페이지는 간략한 버전이며, 모든 플래그, 엔드포인트, 제한 사항 및 측정 항목은 매뉴얼에 있습니다.
이 페이지에서: 빠른 시작 · The Xyntetik-Lab ·
적합성 확인 · 자신만의 파일 만들기 ·
더 많은 컨텍스트, 적은 메모리 · 유휴 메모리 ·
도구 호출 · 학습시키기 ·
상자 안의 내용물도 확인하기 · 모든 명령어 ·
모델이 무엇을 했는지 증명하기
<a id="quick-start"></a>
<a id="sixty-seconds-to-a-served-model"></a>
1. Runner 다운로드하기 (Apple Silicon용 macOS 표시; Linux, Windows 및 체크섬 단계):
curl -LO https://github.com/Joakimpalm-Zen/xyntetik-runner/releases/latest/download/runner-macos-arm64
chmod +x runner-macos-arm64 && mv runner-macos-arm64 runner
2. 모델 시작하기. Runner가 모델을 다운로드하고, Hub의 SHA-256 기록과 비교한 후 http://127.0.0.1:8080에서 서비스합니다:**
./runner -hf Joakimpalm-Zen/Qwen3-30B-A3B-selective-attnQ8_0-expQ4_0-GGUF --serve
# 8GB 장비에서는 더 작은 모델로 시작하세요:
./runner -hf ibm-granite/granite-4.1-3b-GGUF:Q8_0 --serve
3. 요청 보내기:
curl http://127.0.0.1:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"messages":[{"role":"user","content":"Say hello in one sentence."}]}'
터미널에서 채팅하는 것을 선호하시나요? ./runner -m model.gguf -i.
<a id="files"></a>
<a id="published-artifacts"></a>
이 연구소는 제작하는 모든 것을 측정값과 실패 사례와 함께 공개합니다.
**연구소 내부로 이동**하여 Xyntetik-Runner 릴리즈를 확인하거나, 다음 중 하나를 따라가세요.
<a id=
RTX 3070에서 --fit을 사용하면 GPU와 CPU를 동일하게 지정하여 로더가 총 72개 중 70개의 케이스에서 작동했으며 나머지 두 케이스에서는 한 레이어에 주의를 기울였고, 결코 낙관적이지 않았습니다 (총 6개 모델, 2개 컨텍스트 크기, 4개 캐시 포맷).
이유. 모델이 로드되지 않는다는 것을 알게 되면 보통 20GB 파일을 다운로드하고 충돌하는 것을 지켜봐야 합니다. 해결책은 파일의 처음 몇 메가바이트에 이미 적혀 있습니다. Runner는 그 부분만 읽어서 산술적인 계산으로 알려줍니다.
방법.
# 모델의 첫 16MB만 가져온 후 요청하기
curl -r 0-16777215 -L -o head.gguf \
https://huggingface.co/ORG/REPO/resolve/main/MODEL.gguf
...
gpu NVIDIA GeForce RTX 3070, offload budget 6.95 GiB 현재
split f16: GPU에 40개 중 35개 레이어, RAM에 1.22 GiB | --kv q8: GPU에 40개 중 39개 레이어, RAM에 0.47 GiB | ...
verdict FITS — GPU에 40개 중 35개 레이어, 컨텍스트 크기 16384에서 남은 RAM 6.53 GiB
./runner --caps는 이 시스템과 빌드가 무엇을 실행할 수 있는지 알려주며, ./runner -m model.gguf --doctor는 모델을 로드하고 프로브(probe)하여 보고합니다.
판단 결과가 계산되는 방식
<a id="models-and-conversion"></a>
17.99 GB의 Qwen3-30B 파일은 하나의 명령어와 한 줄짜리 계획에서 나왔습니다. 이는 공식 4비트 파일보다 작고 원본에 더 가깝습니다: 해당 파일이 94.75%의 일치도를 보이는 곳에서 99.50%의 일치도를 보입니다.
이유. 모델 파일은 거대한 숫자표이며, 일반적으로 크기를 줄이는 방식은 가장 중요한 부분까지 포함하여 모든 부분을 같은 양만큼 압축합니다. Runner는 어떤 부분을 압축할지, 어떤 부분을 선명하게 유지할지 선택할 수 있게 해주며, 그 후 결과가 원본에서 얼마나 벗어났는지 알려줍니다.
방법. 해당 파일을 구축한 계획과 명령어들:
{"default": "keep", "rules": [{"match": "_exps.weight", "type": "q4_0"}]}
# 계획 파일에서 일부 텐서를 선명하게 유지하고 다른 텐서는 압축합니다.
./runner -m model-Q8_0.gguf --quantize out.gguf --type-plan plan.json
# 희소 전문가 모델(mixture-of-experts)이 거의 사용하지 않는 전문가를 제거합니다.
...
<a id="long-contexts"></a>
--kv k8v4는 컨텍스트 캐시를 일반적인 바이트의 약 41%에 저장합니다. 4B부터 30B까지의 세 모델에서 각각 500개 위치에 대해 전체 크기 캐시와 100% 일치하는 결과를 보였습니다.
이유. 모델이 긴 문서를 읽을 때 지금까지의 모든 단어에 대한 메모를 유지하며, 컨텍스트가 길수록 이 메모가 사용 가능한 메모리보다 더 많이 차지할 수 있습니다. Runner는 이 메모를 더 작게 작성할 수 있습니다. 어느 부분을 볼지 결정하는 절반에는 8비트를 유지하고, 어떤 측정값이 중요한지를 보여주는 부분은 그대로 두고 나머지 절반을 4비트로 줄입니다.
방법.
./runner -m model.gguf --serve -c 32768 --kv k8v4
./runner -m model.gguf --serve -c 32768 --kv q8 # 더 온건한 설정, 약 절반 크기
--fit은 아무것도 로드하기 전에 각 설정이 사용자의 장치에서 무엇을 제공하는지 보여줍니다.
캐시 형식 및 측정 비용
<a id="designed-to-stay-on"></a>
128 GB Apple Silicon Mac에서 로드되어 유휴 상태인 63 GB 모델은 Runner 사용 시 35 MB의 전용 메모리를, llama-server 사용 시 60.8 GB를 차지합니다. 8 GB M1에서는 각각 8 MB와 3,819 MB입니다.
<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="site/assets/readme-idle-dark.svg"> <img src="https://raw.githubusercontent.com/Joakimpalm-Zen/xyntetik-runner/HEAD/site/assets/readme-idle-light.svg" alt="63 GB 모델 로드 및 유휴 상태의 연결된 메모리: Runner 0~40 MB 스케일에서 35 MB, llama-server는 스케일을 벗어난 60.8 GB" width="440"> </picture> </p>