timtoole02/Camelid

Rust 네이티브 로컬 LLM 추론 엔진 — GGUF 입력, OpenAI 스타일 API 출력, 모든 주장은 재현 가능한 증거로 뒷받침됩니다.

Camelid는 GGUF 모델을 직접 로드하고, 이를 로컬 OpenAI 스타일 API를 통해 제공하며, 모든 최적화된 경로는 참조 구현(reference implementation)과의 토큰 단위 일치성(token-for-token parity)을 통해 검증됩니다. 이는 Ollama나 llama.cpp의 래퍼(wrapper)가 아닙니다. 토크나이저(tokenizer), GGUF 로더(loader), CPU 커널(kernels), 그리고 Metal GPU 경로는 모두 이 저장소에서 구현되었으며, Python 없이 단일 정적 Rust 바이너리로 제공됩니다.

로컬 웹 프런트엔드 — 호환성 계약(compatibility contract)이 인식하는 모델 행에 대해서만 채팅을 활성화하는 어두운 색상의 축소된 레일(collapsed-rail) 채팅 인터페이스입니다.

🦀 Rust 네이티브 |
토크나이저(tokenizer), GGUF 로더(loader), CPU 커널(kernels), Metal GPU 경로는 이 저장소에 존재합니다. 단일 정적 바이너리이며, Python은 필요하지 않습니다. |
📦 직접 GGUF 지원 |
.gguf 파일을 지정하기만 하면 됩니다 — 변환이나 가져오기 단계가 필요 없습니다. |
🔌 OpenAI 스타일 API |
SSE 스트리밍을 지원하는 /v1/chat/completions 및 /v1/completions를 로컬에서 제공합니다. |
✅ 정확성 우선 |
최적화된 경로는 참조 구현과 토큰 단위 일치성이 확인된 후에만 배포됩니다. 지원되지 않는 설정은 타입화된 오류(typed errors)와 함께 안전하게 실패(fail closed)합니다. |
🧾 증거 포함 |
모든 요청은 봉인된 일치 영수증(parity receipt)을 발행할 수 있습니다 — 정확한 GGUF (SHA-256), 정확한 입력, 정확한 토큰을 포함하며, 16GB Mac에서의 7B 영수증을 포함하여 사용자의 기기에서 llama.cpp와 독립적으로 재검증이 가능합니다. |
📊 증거 기반 검증 |
모든 게시된 수치는 원시 로그(raw logs), 명령어, 버전이 포함된 커밋된 번들에서 나옵니다. 원시 로그가 없으면 주장도 없습니다. |
⚡ Apple Silicon 경로 |
Metal 기반 파이프라인(GPU 프리필(prefill), GPU 디코드(decode) 및 GPU 내 그리디 샘플링(greedy sampling))을 통해 llama.cpp 및 MLX-LM과 직접 비교 측정하였으며 — 승리, 무승부, 패배를 모두 명시합니다. |
🚀 빠른 모델 로딩 |
Apple Silicon에서 서버는 GPU가 제자리(in place)에서 읽을 수 있도록 Q8_0 가중치를 매핑하므로, 읽고 복사하는 대신 빠르게 다시 로드할 수 있으며 피크 메모리(peak memory)를 낮게 유지합니다. |

지원은 정확한 모델 행별(특정 양자화가 적용된 특정 GGUF)로 이루어지며, 각 행은 커밋된 증거로 뒷받침됩니다. 목록에 없는 모든 것은 안전하게 실패(fail closed)합니다.

모델 행	양자화(Quant)	서비스 레인(Serve lane)	증거(Evidence)
TinyLlama 1.1B Chat	Q8_0	single-node	Current verified gate
...	Gemma 4 E2B-It	Q8_0	single-node (CPU + Metal)
Gemma 4 E4B-It	Q8_0	single-node (CPU + Metal)	Greedy parity + bounded context 512→8192
Gemma 4 12B-It	Q8_0	two-Mac distributed	Distributed parity + serve/WebUI smoke
Gemma 4 26B-A4B-It QAT	Q4_0 (128-expert MoE)	two-Mac distributed	Distributed parity + serve/WebUI smoke

안전하게 실패(fail closed)하는 항목: Mixtral-8x7B v0.1 (검증 진행 중, 토큰당 런타임만 가능); Gemma 4 26B-A4BQ8_0(26.9 GB) 및 31B (2×16 GB 범위를 초과); Gemma 4 MTP/drafter 행; DiffusionGemma 26B-A4B (인식되었으나, 이산 블록 확산 인코더-디코더이며 자동회귀 엔진에서 실행 불가 — recon 참조); 멀티모달 입력; 그리고 v0.1의 모든 다른 양자화.

행별 상세 정보 및 정확한 증거 아티팩트는 SUPPORT_MATRIX_v0.1.md와 COMPATIBILITY.md에 있습니다.

기능(Capability)	상태(Status)	참고 사항(Notes)
GGUF 로딩	✅ 작동 중 (Working)	메타데이터/텐서 검사(camelid inspect)를 통한 직접 로드.
...
Camelid는 gemma4 엔진에서 Gemma 4를 처음부터 구현했습니다: 레이어 유형별 슬라이딩/글로벌 어텐션(GGUF의 sliding_window_pattern이 권위적임; E2B는 4:1), 레이어별 FFN 너비 및 KV-헤드 개수, QK-norm, 이중-$ heta$ RoPE, GeGLU, 레이어별 임베딩(Per-Layer-Embeddings), 교차 레이어 KV 공유, 그리고 생각 채널 억제(thinking-channel suppression)를 포함하는 / /chat 마커. 멀티모달 입력은 유형 오류와 함께 안전하게 실패합니다.

E2B-It & E4B-It (Q8_0, 단일 노드). CPU와 Metal GPU 상주 런타임(GPU-resident runtime) 모두에서 고정된 llama.cpp 오라클(oracle)을 대상으로 한 5-프롬프트 탐욕적 패리티(greedy parity) 테스트를 수행하였으며, **512 / 1024 / 2048 / 4096 / 8192의 체크된 제한적 컨텍스트 팩(bounded context packs)**을 확인했습니다 (recall 방식, 캡처 시 오라클 recall 확인 — 모든 버킷에서 전체 예산 CPU+GPU 패스 수행, 기록된 프런티어 없음). 채팅 템플릿은 바이트 및 토큰 단위로 정확하게 고정되어 있습니다 (qa/gemma4/template_shapes_v1.json, 두 가지 사고 모드 모두 포함). Metal GPU 상주 디코드 경로 (camelid gemma4-generate-gpu)는 메모리 대역폭 한계(memory-bandwidth wall)에서 GPU를 통해 전체 E4B 순전파(forward)를 실행합니다. QAT 행 (gemma-4-E4B_q4_0-it, Q4_0 레이어 + Q6_K 결합 헤드) 또한 동일한 GPU 상주 경로에서 실행됩니다 — Q4_0 프로젝션(projections)은 GPU에서 디코드되며(패리티 게이트 방식의 wire GEMVs), Q6_K 결합 헤드는 CPU에서 실행됩니다. M4에서는 CPU 런타임과 토큰 단위로 동일하며, 워밍업 후 약 25% 더 빠릅니다 (15.2 vs 12.2 tok/s). 블록별 GPU↔CPU 패리티는 CI에서 게이트(gated) 처리되며, 엔드 투 엔드(end-to-end) GPU==CPU 체크는 로컬에서 실행됩니다 (CI에는 GPU 모델이 없음). docs/performance/gemma4-qat-gpu-2026-06-11.md를 참조하십시오. 커밋된 CPU QAT 패리티 (E4B QAT basic_v1: 3/5 전체 예산 + 2개 프로브 검증 프런티어)는 변경되지 않았습니다.

12B-It (Q8_0) & 26B-A4B-It QAT (Q4_0, MoE) — 두 대의 Mac 분산 처리. 이 행들은 단일 16 GB 호스트에 담기에는 너무 크기 때문에, 지원되는 경로는 TCP를 통한 분산 레이어 샤딩(distributed layer sharding)입니다: gemma4-master / gemma4-worker가 버전 관리된 핸드셰이크(handshake)와 패킷당 체크섬(checksum)을 사용하여 하나의 행을 두 대의 머신으로 분할하며, 분산 탐욕적 출력(distributed greedy output)은 단일 노드와 토큰 단위로 동일함이 확인되었습니다 (tests/gemma4_distributed_parity.rs). 26B 행은 128-전문가 MoE (Q4_0 전문가 + Q6_K 결합 헤드)로, 밀집 공유 전문가(dense shared-expert)와 희소 top-8 브랜치(sparse top-8 branch)가 엔드 투 엔드로 구현되었습니다.

두 대의 16 GB M4 Mac mini에서 고정된 참조 모델 대비 전체 basic_v1 팩으로 검증되었습니다:

두 행 모두 동일한 레인(lane)을 통해 HTTP로 서비스를 제공합니다 — CAMELID_GEMMA4_SERVE=1 및 CAMELID_GEMMA4_WORKER/CAMELID_GEMMA4_SPLIT, 그리고 /v1/chat/completions(SSE 포함)와 /v1/completions이 영구 마스터 샤드(persistent master shard)를 통해 요청별 워커 세션(per-request worker sessions)으로 라우팅됩니다 (와이어 프로토콜 v1). 분산 서비스/WebUI 배포 테스트는 두 경우 모두 녹색입니다. 증거 번들(Evidence bundles)은 qa/evidence-bundles/에 있습니다; 설정은 docs/gemma4-two-mac-cluster.md를 참조하세요.

범위 제한(Scope guardrails): 이는 정확한 행(exact-row) 주장일 뿐입니다 — Gemma 계열 전체 지원이나 검사된 팩을 넘어서는 모델 네이티브/더 큰 컨텍스트는 없습니다.

빌드:

cargo build --release

로컬 GGUF 모델(Q8_0) 서비스:

./target/release/camelid serve \
--model /path/to/Llama-3.2-3B-Instruct-Q8_0.gguf \
--threads 4

서버는 기본적으로 127.0.0.1:8181에서 수신합니다. 로드된 모델 목록(그 id는 GGUF 메타데이터에서 가져옴):
curl -s http://127.0.0.1:8181/v1/models

채팅 (모델 id를 위에서 반환된 것으로 대체하고, SSE의 경우 `

경계값 읽기: 하나의 정확한 모델 행(row)과 하나의 머신에서 얻은 동일 세션 결과이며, 차이가 미미합니다 — 이는 지속 가능하거나 일반적인 주장이 아닙니다. 일부 레인(lane)은 비교 대상보다 낮은 성능을 보였으며 (긴 컨텍스트 꼬리 부분의 디코딩 시 MLX-LM), 더 깊은 프롬프트 깊이(prompt depths)에서는 프로토콜 등급의 라운드 대신 단일 웜 프로브(warm probes)를 사용했습니다. 전체 방법론, 원시 로그(raw logs), 라운드별 상세 정보, 그리고 Camelid가 뒤처지는 레인에 대한 정보는 BENCHMARKS.md 및 qa/evidence-bundles/ 아래의 번들(bundles)에 있습니다.

정확성 증거 (토큰 일치 게이트(token-parity gates), 행별 검증 아티팩트(per-row validation artifacts))는 COMPATIBILITY.md 및 CORRECTNESS_v0.1.md에 인덱싱되어 있습니다.

패리티 영수증(parity receipt)은 하나의 요청에 대한 검증 가능한 기록입니다: 정확한 GGUF (SHA-256 기준), 정확한 입력, 그리고 생성된 정확한 토큰들입니다. /v1/chat/completions 또는 /v1/completions에서 "camelid_receipt": true를 선택(opt in)한 다음, 어떤 머신에서든 다음 명령어로 확인하십시오:

camelid verify-receipt receipt.json --gguf path/to/exact-model.Q8_0.gguf

검증기(verifier)는 영수증의 다이제스트(digest)를 재계산하고, 사용자의 GGUF가 지정된 파일인지 확인하며, Camelid를 통해 요청을 재현(replay)한 뒤, llama.cpp를 통해 다시 실행합니다 — 이 과정은 두 번의 격리된 패스(isolated passes)로 이루어져 각 모델이 하나의 모델 메모리 점유 공간(memory footprint) 내에서 로드되므로, 7B 영수증을 16 GB Mac에서 검증할 수 있습니다. 영수증은 결정론적 (greedy) 실행에 대해서만 존재하며, 샘플링된(sampled) 실행은 reproducible: false로 표시됩니다. 영수증은 단일 요청을 검증할 뿐이며, 릴리스 원장(release ledger)을 변경하거나 특정 레인을 승격시키지 않습니다. 자세한 내용은 RECEIPTS.md를 참조하십시오.

Camelid뿐만 아니라 모든 로컬 런타임(runtime)을 결정론, 런타임 간 일치성, 토크나이저 패리티(tokenizer parity), 그리고 동일한 모델 바이트에 대한 증명 가능성 측면에서 측정하려면 적합성 스위트(conformance suite)를 참조하십시오.

문서	포함 내용
SUPPORT_MATRIX_v0.1.md	어떤 정확한 모델 행이 지원되는지, 그리고 그 증거는 무엇인지
COMPATIBILITY.md	지속 가능한 지원 계약 (durable support contract)
BENCHMARKS.md	벤치마크 (Benchmark) 스냅샷 및 주장 규칙
RECEIPTS.md	검증 가능한 단일 요청 패리티 (single-request parity) 영수증
docs/CONFORMANCE.md	하나의 척도로 모든 런타임 (runtime) 측정
STATUS.md	현재 증거 스냅샷 및 차단 요소 (blockers)
ARCHITECTURE.md	구현 아키텍처 (Implementation architecture)
docs/gemma4-two-mac-cluster.md	두 대의 Mac을 이용한 분산 서빙 (distributed serve) 설정
RELEASE_NOTES_v0.1.md	v0.1 릴리스 노트
ROADMAP.md	계획된 엔지니어링 시퀀스 (engineering sequence)

코드 변경 사항에 대한 검증:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

Camelid는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다.

Camelid의 토크나이저 (tokenizer), 참조 호환성 레이아웃 (reference compatibility layouts), 그리고 검증 벤치마크 (validation benchmarks)는 llama.cpp에서 영감을 얻었으며 이를 기준으로 확인됩니다.

(Copyright © 2023–2026 The ggml authors, MIT License). Camelid는 ggml 생태계의 참조 작업을 명시하면서 자체적인 Rust 네이티브 코드베이스를 유지합니다.