네이티브 INT4 CUDA 커널(kernels)을 갖춘 초고효율 메모리 LLM 추론 엔진(inference engine).

24GB GPU에서 32B 모델을 실행하세요. 8GB GPU에서 7B 모델을 실행하세요. 빠른 콜드 스타트(cold starts), 단일 파일 배포를 지원합니다.

🆕 v1.4.1: 모델 허브(Model Hub) + 풀(Pull) 명령어

8GB GPU에서 7B 모델을 학습(Train)하세요. 48GB GPU에서 70B 모델을 학습(Train)하세요.

from zse.format import load_zse_model
from zse.training import LoRAConfig, add_lora_to_model, save_lora_adapter

...

학습 종속성 설치: pip install zllm-zse[training]

🚀 벤치마크 (검증됨, 2026년 3월)

ZSE Custom Kernel (기본값)

ZSE bnb Backend (대체)

VRAM 비교

GPU 호환성

주요 기능

• 📦 단일 .zse 파일: 모델 + 토크나이저 + 설정(config)을 하나의 파일에 포함
• 🚫 네트워크 호출 없음: 모든 것이 내장되어 오프라인에서 작동
• ⚡ ZSE Custom Kernel: 최대 VRAM 효율성을 갖춘 네이티브 INT4 추론
• 🧠 메모리 효율성: 72B 모델을 41GB, 32B 모델을 19GB, 7B 모델을 5.7GB VRAM에서 구동
• 🏃 빠른 콜드 스타트: 7B 모델 기준 5.7초, 32B 모델 기준 20초, 72B 모델 기준 52초
• 🎯 듀얼 백엔드: Custom kernel (기본값) 또는 bnb backend (대체)
• 🔥 QLoRA 학습: LoRA 어댑터를 사용하여 INT4 모델 미세 조정 가능 (v1.4.0에서 신규)
• 📄 .zpf를 이용한 내장 RAG: 일반 청킹(plain chunking) 대비 정확도 100%에 도달하면서 LLM 토큰 사용량 25% 감소

설치

pip install zllm-zse

요구 사항:

• Python 3.11 이상
• CUDA GPU (8GB 이상 VRAM 권장)
• bitsandbytes (자동 설치)

빠른 시작

1. 사전 변환된 모델 가져오기 (가장 빠름)

# 사용 준비가 된 .zse 모델 다운로드 (변환 시 GPU 불필요)
zse pull qwen-7b          # 5.18 GB 다운로드
zse pull mistral-7b       # 3.86 GB 다운로드
...

2. 또는 모델을 .zse 형식으로 변환 (일회성)

2. 또는 모델을 .zse 형식으로 변환 (일회성)

# 모든 HuggingFace 모델 변환
zse convert Qwen/Qwen2.5-7B-Instruct -o qwen7b.zse
zse convert Qwen/Qwen2.5-32B-Instruct -o qwen32b.zse
...

2. 로드 및 실행 (Load and Run)

from zse.format.reader_v2 import load_zse_model

# 모델 로드 (최적 설정 자동 감지)
...

3. 서버 시작 (OpenAI 호환)

zse serve qwen7b.zse --port 8000

import openai

client = openai.OpenAI(base_url="http://localhost:8000/v1", api_key="zse")
...

.zse 형식의 장점 (Format Benefits)

.zpf: 토큰 비용 절감을 포함한 내장 RAG

.zpf는 일반 청킹(plain chunking) 대비 25% 낮은 LLM 토큰 비용으로 100% 검색 정확도를 제공하며, 실제 노이즈가 많은 웹 콘텐츠에서 테스트되었습니다.

.zpf (Z Packed Format)는 RAG를 위한 ZSE의 내장 시맨틱 문서 형식입니다. 이 형식은 쓰기 시간에 문서를 압축하여 노이즈(쿠키 배너, 탐색 메뉴, 상투적인 내용, 채우기 글 등)를 제거하는 동시에 LLM이 필요한 내용을 보존합니다.

비용 벤치마크 (CNN 노이즈 웹 기사)

빠른 시작 (Quick Start)

# RAG 스토어에 문서 색인화(Ingest)하기
zse rag add paper.pdf --title "ML Paper"

...

from zse.core.zrag.pipeline import RAGPipeline

pipeline = RAGPipeline(store_dir="./my_store")
...

작동 방식 (How It Works)

1. 시맨틱 청킹 (Semantic chunking) — 콘텐츠 유형별로 분할 (CODE, TABLE, DEFINITION, PROCEDURE 등 11개 블록 유형)
2. 10단계 압축 (10-layer compression) — 채우기 구문(filler phrases), 장황한 패턴(verbose patterns), 중복 한정사(redundant qualifiers), 노이즈 라인 제거
3. 맥락 임베딩 (Contextual embedding) — 각 블록은 교차 섹션 검색을 위해 상위 섹션 계층 구조와 함께 임베딩됨
4. 하이브리드 검색 (Hybrid retrieval) — 크기 정규화, 블록 유형 부스팅, 식별자 인식 점수(identifier-aware scoring)를 적용하여 0.6× 임베딩 유사도 + 0.4× BM25 결합

다중 GPU: 텐서 병렬 처리 및 파이프라인 병렬 처리 (Multi-GPU: Tensor Parallelism & Pipeline Parallelism)

여러 GPU에 걸쳐 모델을 실행하여 GPU당 VRAM (Video RAM)을 줄이거나 더 큰 모델을 서빙할 수 있습니다.

# 텐서 병렬 처리 (Tensor Parallelism) — GPU 간 가중치 분할 (NCCL all-reduce)
zse serve qwen-32b -tp 2 --port 8000

...

Multi-GPU 벤치마크 (Qwen2.5-7B INT4, A10G GPU)

상황별 사용 가이드:

• TP (Tensor Parallelism): 가장 빠른 추론 속도, 모든 레이어를 분할. GPU가 NVLink를 통해 연결된 경우 최적.
• PP (Pipeline Parallelism): 최적의 VRAM 절감, 거의 완벽한 메모리 분할. PCIe 환경에서도 작동.
• TP+PP: 최대 확장성 — 4개의 소비자용 GPU에서 72B 모델 실행 가능.

고급 사용법 (Advanced Usage)

QLoRA 미세 조정 (Fine-Tuning) (v1.4.0+)

양자화된 INT4 베이스 모델에 LoRA 어댑터를 적용하는 QLoRA를 통해 어떤 모델이든 학습할 수 있습니다.

# 학습 의존성 설치
pip install zllm-zse[training]

from zse.format import load_zse_model, convert_model
from zse.training import (
    LoRAConfig, 
...

QLoRA VRAM 사용량:

캐싱 전략 제어 (Control Caching Strategy)

# 자동 (Auto, 기본값): VRAM을 감지하여 최적의 전략 선택
model, tok, info = load_zse_model("qwen7b.zse", cache_weights="auto")

...

환경 벤치마크 (Benchmark Your Setup)

# 전체 벤치마크
python3 -c "
import time, torch
...

CLI 명령어

# 모델 관리 (Model Management)
zse pull <model>                    # 사전 변환된 .zse 모델 다운로드
zse list                            # 사용 가능한 모델 탐색
...

🤗 사전 변환된 모델 (Pre-Converted Models)

huggingface.co/zse-zllm에서 즉시 다운로드 가능한 13개의 모델:

작동 원리 (How It Works)

1. 변환 (Conversion): HF 모델을 INT4로 양자화 (Quantize), 가중치 패킹 (pack weights), 토크나이저 (tokenizer) + 설정 (config) 임베딩
2. 로딩 (Loading): .zse 파일을 메모리 맵 (Memory-map) 하고, INT4 가중치를 GPU로 직접 로드
3. 추론 (Inference): ZSE 커스텀 커널 (custom kernel, 기본값) 또는 행렬 곱셈 (matmul)을 위한 bnb 백엔드 사용

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  HuggingFace    │────▶│   .zse File     │────▶│   GPU Model     │
│  Model (FP16)   │     │   (INT4 + tok)  │     │  (ZSE Kernel)   │
...

OpenClaw 통합 (OpenClaw Integration)

@steipete가 만든 24/7 AI 어시스턴트인 OpenClaw를 통해 로컬 모델을 실행하세요.

# ZSE 서버 시작
zse serve <model-name> --port 8000

...

또는 OpenClaw의 config.yaml에서 다음과 같이 설정할 수 있습니다:

llm:
  provider: openai-compatible
  api_base: http://localhost:8000/v1
...

장점: 100% 프라이버시 보장, API 비용 제로, 오프라인 작동, 모든 (ANY) 모델 실행 가능.

Docker 배포 (Docker Deployment)

# CPU
docker run -p 8000:8000 ghcr.io/zyora-dev/zse:latest

...

Runpod, Vast.ai, Railway, Render, 그리고 Kubernetes를 포함한 전체 배포 가이드는 deploy/DEPLOY.md를 참조하세요.

라이선스 (License)

Apache 2.0

후원사 (Sponsors)

연락처 (Contact)

• 웹사이트 (Website): zllm.in
• 회사 (Company): Zyora Labs
• 이메일 (Email): zse@zyoralabs.com