lucasjinreal/Crane

A Pure Rust based LLM, VLM, VLA, TTS, OCR Inference Engine, powering by Candle & Rust. Alternate to your llama.cpp but much more simpler and cleaner..

🚀 Crane이란?

Crane(Candle‑based Rust Accelerated Neural Engine)은 Rust로 작성된 오픈소스 추론 프레임워크로, Candle 머신러닝 라이브러리 위에 구축되었습니다. 그 목표는 대규모 언어 모델(LLM) 및 멀티모달 모델 추론을 CPU, NVIDIA CUDA, Apple Metal, 심지어 AMD ROCm과 같은 다양한 하드웨어에서 빠르고 휴대 가능하며 사용하기 쉽게 만드는 것입니다.

핵심 아이디어

아이디어	의미
Rust + Candle	Rust는 안전성과 단일 바이너리 배포 모델을 제공하고, Candle은 PyTorch와 유사한 API와 Rust/CUDA/Metal로 작성된 최적화된 커널을 제공합니다.
GGUF 우선	모델은 GGUF 형식(llama.cpp에서 사용하는 것과 동일)에서 직접 로드됩니다. 추가 변환 단계가 필요 없습니다.
하드웨어 독립적 백엔드	런타임 시 동일한 모델을 코드 변경 없이 CPU, CUDA, Metal(macOS) 또는 ROCm(AMD)에서 실행할 수 있습니다.
OpenAI 호환 서버	`crane‑serve`는 OpenAI의 chat/completions API(및 SGLang)를 구현하므로 기존 클라이언트 코드가 그대로 작동합니다.
즉시 사용 가능한 AI 기능	일반 텍스트 생성 외에도 OCR, 음성 인식(ASR), 음성 합성(TTS), 음악 전사, 비전-언어 작업을 위한 즉시 사용 가능한 파이프라인을 제공합니다.

이것으로 할 수 있는 일

일반 하드웨어에서 거대한 모델 실행 – 예를 들어, 27 B Bonsai 삼진 모델은 16 GB RAM에 맞으며 CPU 또는 단일 GPU에서 실행할 수 있습니다.
API를 통해 모델 서비스 제공 – crane‑serve를 시작하고 /v1/chat/completions, /v1/audio/speech 등을 호출합니다.
자체 Rust 앱 작성 – crane-core 크레이트는 깔끔한 Rust API(ModelForCausalLM, GenerationConfig, 토크나이저 등)를 제공하므로 추론을 모든 Rust 바이너리에 임베드할 수 있습니다.
양자화 실험 – --quant q4_0 및 유사한 플래그는 로드 중에 in‑situ 양자화를 수행하여 VRAM/RAM 사용량을 줄입니다.

📦 지원되는 모델(README 기준)

Bonsai 2 Ternary 27B – 네이티브 Prism PTQ1_0 / PQ2_0 GGUF, CPU 및 CUDA 지원.
Qwen 3.8‑Flash‑Next(177 B MoE) – SYCL을 통해 Intel Arc GPU에서 실행.
Qwen 3.5 / 3.6 / 3.8(다양한 크기, 밀집 및 비전-언어 변형).
Ornith‑1.0‑9B – 도구 호출 에이전트.
Gemma 4, Hunyuan Dense, Moonshine ASR, Silero VAD, Qwen3‑TTS, Voxtral‑4B‑TTS, KugelAudio, MuScriptor(음악 전사), PaddleOCR‑VL 등.
더 많은 모델이 "곧 출시"로 나열되어 있습니다.

🛠️ 시작하기(빠른 시작)

# 클론 및 설치
git clone https://github.com/lucasjinreal/Crane
./install.sh

# 서버 실행(Bonsai 삼진 모델 예시)
./target/release/crane-serve \
    --model-path checkpoints/Ternary-Bonsai-2-27B-gguf/Ternary-Bonsai-2-27B-PTQ1_0.gguf \
    --ui

UI가 브라우저에서 열리며 코드를 작성하지 않고도 채팅, OCR, ASR 등을 실행할 수 있습니다.

간단한 Rust 프로그램 실행

README에는 Qwen2.5‑0.5B‑Instruct를 로드하고 순수 Rust로 응답을 생성하는 최소한의 예제가 포함되어 있습니다. 단 몇 십 줄의 코드입니다.

⚡ 성능 하이라이트(변경 로그에서)

하드웨어	모델	PyTorch / llama.cpp 대비 속도
Apple M1/M2/M3(CPU)	Qwen3‑VL 2B	네이티브 PyTorch보다 약 50배 빠름
NVIDIA RTX 3090(CUDA)	Qwen 3.5‑2B‑Q8_0	llama.cpp보다 3배 빠름(커널 융합 후)
AMD RX 7800 XT(ROCm)	Qwen 3.5‑2B‑Q8_0	CPU보다 5–7배 빠르며 CUDA와의 격차를 좁힘
Intel Arc Pro B70(SYCL)	Qwen 3.8‑Flash‑Next	단일 32 GB GPU에서 실행

주요 최적화에는 다음이 포함됩니다:

커널 융합(정규화, GDN 재귀, top‑k 샘플링).
In‑situ 양자화 – 전체 정밀도 가중치를 GPU 메모리에 로드하는 것을 방지.
커널 시작 오버헤드 감소 – 토큰당 제출 시간이 약 22 ms에서 약 7 ms로 단축.

📚 내부 작동 방식

모델 로드 – crane-core가 GGUF 헤더를 읽고 아키텍처(예: qwen3_5)를 감지한 후 적절한 dtype/device로 Candle VarBuilder를 구축합니다.
백엔드 선택 – 런타임 시 장치(cpu, cuda, metal, rocm)가 선택되며 동일한 Rust 코드가 해당 Candle 커널로 디스패치됩니다.
생성 루프 – Candle의 ModelForCausalLM 트레이트를 사용하며 TextStreamer가 토큰을 클라이언트로 스트리밍합니다.
서버 레이어 – crane-serve는 생성 로직을 비동기 HTTP 서버로 감싸 OpenAI 호환 엔드포인트를 제공합니다.

🛣️ 로드맵 / 향후 계획

더 많은 멀티모달 모델(VLA, 고급 비전-언어 파이프라인).
ROCm에서 완전한 MoE 지원.
점수 행렬을 제거하기 위한 더 메모리 효율적인 어텐션 커널(플래시 스타일).
모델 변환 및 양자화를 위한 도구 확장.

위의 모든 정보는 저장소의 README에서 직접 가져온 것이며 외부 가정은 추가되지 않았습니다.