VindexLLM이란 무엇인가?

Follow on Bluesky

VindexLLM이란 무엇인가?

VindexLLM은 Delphi로 완전히 작성되었으며, 모든 무거운 계산에 Vulkan compute shaders를 사용하는 GPU 가속 LLM 추론 엔진입니다. 표준 GGUF 모델 파일을 로드하고, 전체 트랜스포머 순전파(forward pass)를 GPU에서 실행하며 텍스트를 생성합니다. Python도 없고, CUDA toolkit도 없고, 외부 런타임도 필요 없습니다. 유일한 종속성은 모든 최신 GPU 드라이버에 이미 포함된 vulkan-1.dll입니다.

프롬프트를 입력하면 토큰을 받습니다. 임베딩 조회(embedding lookup), 어텐션 및 FFN의 34개 레이어, 정규화(normalization), 샘플링 등 모든 과정이 GLSL 450 compute shaders를 통해 GPU에서 처리되며 SPIR-V로 컴파일되어 바이너리에 Windows 리소스로 내장됩니다.

단발성 추론 (Single-shot inference)

var
  LInference: TVdxInference;
  LConfig: TVdxSamplerConfig;
...

영구 메모리를 사용한 대화형 채팅 (Interactive chat with persistent memory)

var
  LChat: TVdxConsoleChat;
  LConfig: TVdxSamplerConfig;
...

모델을 로드하고 텍스트를 생성하면 끝입니다. 이 채팅 예제는 SQLite 기반의 영구 메모리와 세션 간 RAG 검색(RAG retrieval)을 포함하는 다중 턴 대화 기능을 추가합니다. 상태 콜백, 취소 지원, 이벤트 후크, 오류 처리 및 성능 통계 등 전체 구현은 testbed\UTest.Demo.pas를 참조하십시오.

VindexLLM을 사용하는 이유?

대부분의 LLM 추론 스택은 CUDA(NVIDIA 전용, 약 3GB 툴킷 설치), Python 환경 또는 대규모 런타임 라이브러리에 의존합니다. VindexLLM은 다른 접근 방식을 취합니다:

• 설치 불필요 (Zero install) — Vulkan은 모든 NVIDIA, AMD, Intel GPU 드라이버에 포함되어 있습니다. 별도의 툴킷 다운로드, PATH 설정, DLL 지옥이 없습니다. 앱은 LoadLibrary('vulkan-1.dll')을 호출하고 GPU와 직접 통신합니다.
• 벤더 종속성 없음 (No vendor lock-in) — Vulkan은 모든 최신 GPU에서 실행됩니다. NVIDIA 하드웨어에 묶여 있지 않습니다.
• 자체 포함 바이너리 (Self-contained binary) — 37개의 모든 컴퓨트 셰이더는 빌드 시점에 SPIR-V로 컴파일되어 실행 파일 내의 Windows 리소스로 임베딩됩니다. 느슨한 셰이더 파일도, 런타임 컴파일도 없습니다.
• Python 없음, 런타임 없음 — 순수 컴파일된 Delphi 언어입니다. 즉시 시작하며, 인터프리터 워밍업이나 의존성 해결 과정이 없습니다.
• 메모리 매핑 모델 로딩 (Memory-mapped model loading) — GGUF 파일은 CreateFileMapping / MapViewOfFile을 통해 직접 매핑됩니다. 가중치는 파일 오프셋에서 접근되어 스테이징 버퍼를 통해 VRAM으로 업로드됩니다. 중간 복사 과정이나 사용자 정의 형식 파싱 과정이 없습니다.
• 모든 것을 GPU에서 실행 — 잔여 스트림(residual stream)은 레이어 간에 VRAM을 벗어나지 않습니다. 유일한 PCIe 전송은 초기 토큰 임베딩(~10KB)과 샘플링을 위한 최종 로짓 다운로드입니다. 나머지 모든 것—어텐션, FFN, 정규화(norms), 활성화 함수, 잔여 덧셈—은 GPU 컴퓨트 디스패치로 실행됩니다.

작동 방식 (How It Works)

VindexLLM은 표준 밀집 변환기 순전파(dense transformer forward pass)를 구현합니다. 각 토큰마다 엔진은 GPU에서 어텐션 및 FFN 계산을 34개 레이어 동안 실행한 다음, 출력 로짓으로부터 다음 토큰을 샘플링합니다.

                         ┌──────────────┐
                         │  GGUF 파일   │
                         │  (mmap'd)    │
... 

프리필(Prefill)은 배치된 matmul 셰이더를 사용하여 모든 프롬프트 토큰을 병렬로 처리합니다. 자기회귀 생성(Autoregressive generation)은 matvec 셰이더를 사용하여 한 번에 하나의 토큰을 실행합니다. 두 경로는 동일한 KV 캐시를 공유하며, 이는 TQ3 압축을 사용하여 F32 대비 VRAM 사용량을 약 9배 줄입니다.

현재 상태 (Current Status)

밀집 추론(Dense inference)이 엔드투엔드로 작동합니다. 엔진은 Gemma 3 4B GGUF를 로드하고, 채팅 템플릿 포맷팅으로 프롬프트를 토큰화한 다음, GPU에서 전체 순전파(forward pass)를 실행하여 설정 가능한 샘플링을 통해 일관된 텍스트를 생성합니다. 영구 메모리와 RAG가 결합된 완전한 대화형 채팅 시스템이 이 추론 엔진 위에 구축됩니다.

현재 구현된 기능:

• Gemma 3 4B 전체 순전파 (34 레이어, 모두 GPU에서 처리하며 CPU 폴백 없음)

• 배치 사전 채우기(Batched prefill) (모든 프롬프트 토큰을 matmul 셰이더를 통해 병렬로 처리)

• 스트리밍 토큰 콜백을 사용한 자기회귀 생성(Autoregressive generation)

• F16, Q8_0, 및 Q4_0 가중치 포맷 지원 (GGUF 메타데이터에서 자동 감지)

• 융합 어텐션 스코어링을 사용하는 TurboQuant TQ3 KV 캐시 압축 (별도의 디퀀타이즈 단계 없음)

• GGUF 어휘집에서 직접 로드되는 순수 Delphi BPE 토크나이저 (외부 SentencePiece 라이브러리 불필요)

• 토큰 샘플링: 온도(temperature), top-K, top-P, min-P, 반복 페널티(repetition penalty), 결정론적 시딩(deterministic seeding) (xoshiro256** PRNG)

• Gemma 3 채팅 템플릿 포맷팅

• 스트리밍 출력, ESC 취소, 슬래시 명령이 가능한 대화형 다중 턴 콘솔 채팅(TVdxConsoleChat)

• SHA-256 중복 제거 및 의미론적 중복 제거(코사인 유사도 임계값)를 갖춘 SQLite 기반 영구 대화 메모리(TVdxMemory)

• RAG 검색: EmbeddingGemma 300M을 사용하여 저장된 턴에 대한 코사인 유사도 벡터 검색 후, 매 턴마다 참조 컨텍스트로 병합 및 주입

• 임베딩 모델 지원(TVdxEmbeddings) — 추론 모델과 독립적으로 벡터 검색을 위해 두 번째 GGUF를 로드

• 세션 관리(TVdxSession) — 추론 + 메모리 + 임베딩을 단일 생명주기(lifecycle)로 묶음

• 아키텍처 레지스트리가 있는 모델 추상화 계층 — 지원되지 않는 모델에 대한 우아한 오류 처리

• 모델 최대값 클램핑을 통한 아키텍처 검증 및 설정 가능한 컨텍스트 길이

• VRAM 사용량 보고 (가중치, 캐시, 버퍼 분해)

• 컨텍스트 오버플로우 감지 (srContextFull 중지 이유)

• 추론 이벤트 콜백 (로드/언로드/사전 채우기/생성 시작/종료)

• Cancel callback (레이어별 폴링, 테스트베드에서 ESC로 중단)

• 제로 카피(zero-copy) GGUF 가중치 읽기를 위한 메모리 매핑 파일 접근(TVdxVirtualFile)

• CPU 작업 공간을 위한 페이지 파일 백업 가상 버퍼(TVdxVirtualBuffer<T>) — 터치될 때까지 물리적 RAM을 커밋하지 않고 주소 공간 할당

• SPIR-V로 컴파일되어 Windows 리소스로 임베딩된 37개의 GLSL 450 컴퓨트 셰이더

TurboQuant (TQ3)

TurboQuant는 VindexLLM의 커스텀 3비트 양자화 포맷으로, KV 캐시 압축을 위해 특별히 설계되었습니다. 이는 Walsh-Hadamard Transform (WHT)를 사용하여 각 32개 요소 블록 내의 값들을 디코릴레이션(decorrelate)한 후, 표준 정규 분포에 적합하게 피팅된 Lloyd-Max 최적 중심점(optimal centroids)을 이용해 3비트로 양자화합니다.

그 결과는 F32 대비 약 9배 압축률을 달성하며, WHT가 양자화 전에 모든 요소에 정보를 확산시키기 때문에 단순한 3비트 반올림보다 월등히 높은 품질을 보여줍니다.

TQ3 파이프라인 (32개 값 블록당):

1. 고정 부호 플립 패턴 적용 (WHT 에너지 분포 개선)
2. 5단계 버터플라이 WHT (제자리(in-place), 임시 버퍼 없음)
3. $1/ ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{} ext{}$로 정규화
4. 절대 최대값 찾기, FP16 스케일 팩터(gamma) 계산
5. 각 값을 가장 가까운 Lloyd-Max 중심점(8 레벨, 3비트)으로 양자화
6. 패킹: 낮은 2비트를 qs 워드에, 높은 1비트를 qr 워드에, gamma를 FP16에 저장

네 가지 TQ3 단계 모두 GPU 컴퓨트 셰이더로 실행됩니다: 일반 양자화/역양자화(tq3_quantize.comp, tq3_dequantize.comp), KV 캐시 전용 양자화/역양자화(tq3_kv_quantize.comp, tq3_kv_dequantize.comp), 결합 배치 KV 저장 + 양자화(kv_cache_store_batch_tq3.comp), 그리고 TQ3 압축된 키에 대한 어텐션 스코어 직접 계산 (attn_scores_mh_tq3.comp) — 이로써 별도의 K 역양자화 단계가 완전히 제거됩니다.

CPU 참조 구현은 검증을 위해 VindexLLM.TurboQuant.pas에 존재합니다.

지원 모델

VindexLLM은 현재 Gemma 3 4B 아키텍처를 구현합니다. 다음 GGUF 파일들은 검증되었으며 정확한 출력을 생성하는 것으로 확인되었습니다. 모든 검증된 모델은 tinyBigGAMES Hugging Face 컬렉션에서 모아볼 수 있습니다.

두 검증된 모델 모두 후처리 양자화(post-training quantized) Q4_0 대신 양자화 인식 학습 (Quantization-Aware Training, QAT) Q4_0을 사용합니다. QAT를 사용하면 양자화 오류가 훈련 과정에서 고려되므로 — 모델이 낮은 정밀도에 대한 보상을 학습하여 — 동일한 4비트 크기에서도 훨씬 더 좋은 출력 품질을 생성합니다. 이는 가장 작은 실용적 VRAM(VRAM) 점유율을 제공하면서 품질을 유지할 수 있게 하여, 대부분의 소비자 GPU에서 4~6 GB의 VRAM으로 전체 스택(추론 + 임베딩 + 메모리/RAG)을 편안하게 실행하는 것이 가능합니다.

다른 Gemma 3 4B GGUF 파일도 작동할 수 있지만 테스트되지 않았습니다. 비-Gemma 아키텍처는 현재 지원하지 않습니다 — 지원되지 않는 모델을 로드하려고 시도하면 엔진이 명확한 오류 메시지를 보고할 것입니다.

성능 (Performance)

NVIDIA RTX 3060 12GB에서 Gemma 3 4B Q8_0으로 측정:

시작하기 (Getting Started)

1. 위 링크에서 검증된 GGUF 모델을 다운로드합니다 (추론 모델 필수, 메모리/RAG용 임베딩 모델 선택 사항)
2. 저장소를 클론합니다:

git clone https://github.com/tinyBigGAMES/VindexLLM.git

3. Delphi 12 이상에서 src\VindexLLM - Liberating LLM inference.groupproj 열기
4. VdxTestbed 프로젝트 빌드하기
5. 다운로드한 GGUF 파일을 가리키도록 testbed\UTest.Common.pas의 모델 경로(CModelPath 및 CEmbedderPath) 수정하기
6. 테스트베드를 실행합니다. 이 과정에서 모델을 로드하고, 가중치 업로드 중 상태 메시지를 출력한 다음, 스트리밍 출력을 통해 텍스트를 생성합니다.

테스트베드에는 testbed\UTest.Demo.pas에 두 가지 데모가 포함되어 있습니다: 콜백(callbacks), 샘플러 설정(sampler config), 통계 보고서(stats reporting)를 보여주는 싱글샷 추론(Demo_Inference); 그리고 영구 메모리 및 RAG를 사용한 다중 턴 대화(Demo_Chat)를 보여주는 인터랙티브 채팅입니다.

시스템 요구 사항 (System Requirements)

소스 코드에서 빌드하기 (Building from Source)

1. 저장소 클론(Clone the repository)
2. Delphi 12 이상에서 src\VindexLLM - Liberating LLM inference.groupproj 열기
3. 프로젝트 그룹 빌드하기 (Win64 타겟)

셰이더 SPIR-V 바이너리 및 컴파일된 리소스 파일(VindexLLM.Shaders.res)은 저장소에 포함되어 있으므로, 빌드를 위해 GLSL 컴파일러가 필요하지 않습니다. 만약 .comp 셰이더 파일을 수정했다면, shaders\compile.cmd를 실행하여 다시 컴파일해야 합니다. 이 작업에는 Vulkan SDK 또는 glslang 릴리스의 glslangValidator.exe가 필요합니다.

아키텍처 (Architecture)

Gemma 3 4B 모델 사양 (Model Specs)

소스 유닛 (Source Units)

컴퓨트 셰이더 (Compute Shaders) (37개 셰이더)

[!중요]
이 저장소는 활발하게 개발 중입니다. 현재 엔진은 Gemma 3 4B 아키텍처만 지원합니다. 다른 모델 아키텍처를 사용하려면 해당 구조의 레이어 구현이 필요할 것입니다. 진행 상황을 추적하려면 저장소를 팔로우하거나 Discord에 참여하세요.

기여 (Contributing)

VindexLLM은 오픈 프로젝트입니다. 버그 수정, 문서 개선, 새로운 모델 아키텍처 지원 추가, 또는 기능 제안 등 모든 기여를 환영합니다.

• 버그 보고: 최소한의 재현 과정을 포함하여 이슈를 열어주세요. 예시가 작을수록 수정이 빠릅니다.
• 기능 제안: 먼저 사용 사례를 설명해주세요. 실제 문제에서 파생된 기능들이 가장 빠르게 주목받습니다.
• 풀 리퀘스트 제출: 버그 수정, 문서 개선, 새로운 셰이더 최적화, 그리고 범위가 잘 정의된 모든 기능은 환영합니다. 변경 사항에 집중해 주세요.

Discord에 참여하여 개발 논의를 하거나 질문하고 자신이 만들고 있는 것을 공유하세요.

프로젝트 지원 (Support the Project)

VindexLLM은 오픈 소스로 구축되었습니다. 만약 이 프로젝트가 시간을 절약해 주거나 유용한 영감을 준다면: