C/C++를 이용한 LLM 추론 (LLM inference)

Hugging Face 캐시 마이그레이션: -hf로 다운로드된 모델

이제 모델이 표준 Hugging Face 캐시 디렉토리에 저장되어 다른 HF 도구들과 공유할 수 있습니다.

가이드: llama.cpp의 새로운 WebUI 사용법

• 가이드: llama.cpp로 gpt-oss 실행하기
• [FEEDBACK] 다운스트림 소비자(downstream consumers) 지원을 위한 llama.cpp의 더 나은 패키징 🤗
• 네이티브 MXFP4 형식을 사용하는 gpt-oss 모델 지원 추가 | PR | NVIDIA와의 협업 | 코멘트
• llama-server에 멀티모달 (Multimodal) 지원 도입: #12898
• FIM 완성을 위한 VS Code 확장 프로그램: https://github.com/ggml-org/llama.vscode
• FIM 완성을 위한 Vim/Neovim 플러그인: https://github.com/ggml-org/llama.vim
• Hugging Face Inference Endpoints에서 이제 GGUF를 즉시 지원합니다! #9669
• Hugging Face GGUF 에디터: 토론 | 도구

lama.cpp를 시작하는 방법은 간단합니다. 사용자의 기기에 설치하는 몇 가지 방법은 다음과 같습니다:

• brew, nix 또는 winget을 사용하여 llama.cpp 설치
• Docker로 실행 - Docker 문서를 참조하세요
• 릴리스(releases) 페이지에서 사전 빌드된 바이너리(pre-built binaries) 다운로드
• 이 저장소를 클론하여 소스에서 빌드 - 빌드 가이드를 확인하세요

설치가 완료되면 작업에 사용할 모델이 필요합니다. 자세한 내용은 모델 획득 및 양자화 (quantizing models) 섹션을 참조하세요.

예시 명령:

# 로컬 모델 파일 사용
lama-cli -m my_model.gguf
# 또는 Hugging Face에서 모델을 직접 다운로드하여 실행
...

llama.cpp의 주요 목표는 로컬 및 클라우드 환경의 광범위한 하드웨어에서 최소한의 설정으로 최첨단 성능 (state-of-the-art performance)을 갖춘 LLM 추론을 가능하게 하는 것입니다.

• 의존성(dependencies)이 없는 순수 C/C++ 구현
• Apple silicon을 최우선적으로 지원 - ARM NEON, Accelerate 및 Metal 프레임워크를 통해 최적화
• x86 아키텍처를 위한 AVX, AVX2, AVX512 및 AMX 지원
• RISC-V 아키텍처를 위한 RVV, ZVFH, ZFH, ZICBOP 및 ZIHINTPAUSE 지원
• 더 빠른 추론(inference)과 메모리 사용량 감소를 위한 1.5-bit, 2-bit, 3-bit, 4-bit, 5-bit, 6-bit 및 8-bit 정수 양자화 (integer quantization)
• NVIDIA GPU에서 LLM을 실행하기 위한 커스텀 CUDA 커널 (HIP를 통한 AMD GPU 및 MUSA를 통한 Moore Threads GPU 지원)
• Vulkan 및 SYCL 백엔드 (backend) 지원
• 전체 VRAM 용량보다 큰 모델을 부분적으로 가속하기 위한 CPU+GPU 하이브리드 추론

llama.cpp 프로젝트는 ggml 라이브러리의 새로운 기능을 개발하기 위한 주요 놀이터(playground)입니다.

모델 (Models)

일반적으로 아래 베이스 모델(base models)의 파인튜닝(finetunes) 모델들도 지원됩니다.

새로운 모델 지원 추가 지침: HOWTO-add-model.md

• LLaMA 🦙
• LLaMA 2 🦙🦙
• LLaMA 3 🦙🦙🦙
• Mistral 7B
• Mixtral MoE
• DBRX
• Jamba
• Falcon
• Chinese LLaMA / Alpaca 및 Chinese LLaMA-2 / Alpaca-2
• Vigogne (French)
• BERT
• Koala
• Baichuan 1 & 2 + 파생 모델
• Aquila 1 & 2
• Starcoder 모델
• Refact
• MPT
• Bloom
• Yi 모델
• StableLM 모델
• Deepseek 모델
• Qwen 모델
• PLaMo-13B
• Phi 모델
• PhiMoE
• GPT-2
• Orion 14B
• InternLM2
• CodeShell
• Gemma
• Mamba
• Grok-1
• Xverse
• Command-R 모델
• SEA-LION
• GritLM-7B + GritLM-8x7B
• OLMo
• OLMo 2
• OLMoE
• Granite 모델
• GPT-NeoX + Pythia
• Snowflake-Arctic MoE
• Smaug
• Poro 34B
• Bitnet b1.58 모델
• Flan T5
• Open Elm 모델
• ChatGLM3-6b + ChatGLM4-9b + GLMEdge-1.5b + GLMEdge-4b
• GLM-4-0414
• SmolLM
• EXAONE-3.0-7.8B-Instruct
• FalconMamba 모델
• Jais
• Bielik-11B-v2.3
• RWKV-7
• RWKV-6
• QRWKV-6
• GigaChat-20B-A3B
• Trillion-7B-preview
• Ling 모델
• LFM2 모델
• Hunyuan 모델
• BailingMoeV2 (Ring/Ling 2.0) 모델

바인딩 (Bindings)

• Python: ddh0/easy-llama
• Python: abetlen/llama-cpp-python
• Go: go-skynet/go-llama.cpp
• Node.js: withcatai/node-llama-cpp
• JS/TS (llama.cpp server client): lgrammel/modelfusion
• JS/TS (Programmable Prompt Engine CLI): offline-ai/cli
• JavaScript/Wasm (works in browser): tangledgroup/llama-cpp-wasm
• Typescript/Wasm (nicer API, available on npm): ngxson/wllama
• Ruby: yoshoku/llama_cpp.rb
• Ruby: docusealco/rllama
• Rust (more features): edgenai/llama_cpp-rs
• Rust (nicer API): mdrokz/rust-llama.cpp
• Rust (more direct bindings): utilityai/llama-cpp-rs
• Rust (automated build from crates.io): ShelbyJenkins/llm_client
• C#/.NET: SciSharp/LLamaSharp
• C#/VB.NET (more features - community license): LM-Kit.NET
• Scala 3: donderom/llm4s
• Clojure: phronmophobic/llama.clj
• React Native: mybigday/llama.rn
• Java: kherud/java-llama.cpp
• Java: QuasarByte/llama-cpp-jna
• Zig: deins/llama.cpp.zig
• Flutter/Dart: netdur/llama_cpp_dart
• Flutter: xuegao-tzx/Fllama
• PHP (API bindings and features built on top of llama.cpp): distantmagic/resonance (more info)
• Guile Scheme: guile_llama_cpp
• Swift srgtuszy/llama-cpp-swift
• Swift ShenghaiWang/SwiftLlama
• Delphi Embarcadero/llama-cpp-delphi
• Go (no CGo needed): hybridgroup/yzma
• Android: llama.android

UIs

(여기에 프로젝트가 나열되려면, 해당 프로젝트가 llama.cpp에 의존한다는 것을 명확히 밝혀야 합니다)

• AI Sublime Text 플러그인 (MIT)
• BonzAI App (독점)
• cztomsik/ava (MIT)
• Dot (GPL)
• eva (MIT)
• iohub/collama (Apache-2.0)
• janhq/jan (AGPL)
• johnbean393/Sidekick (MIT)
• KanTV (Apache-2.0)
• KodiBot (GPL)
• llama.vim (MIT)
• LARS (AGPL)
• Llama Assistant (GPL)
• LlamaLib (Apache-2.0)
• LLMFarm (MIT)
• LLMUnity (MIT)
• LMStudio (독점)
• LocalAI (MIT)
• LostRuins/koboldcpp (AGPL)
• MindMac (독점)
• MindWorkAI/AI-Studio (FSL-1.1-MIT)
• Mobile-Artificial-Intelligence/maid (MIT)
• Mozilla-Ocho/llamafile (Apache-2.0)
• nat/openplayground (MIT)
• nomic-ai/gpt4all (MIT)
• ollama/ollama (MIT)
• oobabooga/text-generation-webui (AGPL)
• PocketPal AI (MIT)
• psugihara/FreeChat (MIT)
• ptsochantaris/emeltal (MIT)
• pythops/tenere (AGPL)
• ramalama (MIT)
• semperai/amica (MIT)
• withcatai/catai (MIT)
• Autopen (GPL)

도구(Tools)

• akx/ggify – Hugging Face Hub에서 PyTorch 모델을 다운로드하고 GGML로 변환합니다.
• akx/ollama-dl – Ollama 라이브러리에서 모델을 다운로드하여 llama.cpp와 직접 사용합니다.
• crashr/gppm – NVIDIA Tesla P40 또는 P100 GPU를 활용하여 유휴 전력 소비가 감소된 상태로 llama.cpp 인스턴스를 실행합니다.
• gpustack/gguf-parser - GGUF 파일을 검토하고 메모리 사용량을 추정합니다.
• Styled Lines (독점 라이선스, Unity3d에서 게임 개발을 위한 추론 부분의 비동기 래퍼로, 사전 구축된 Mobile 및 Web 플랫폼 래퍼와 모델 예시를 포함합니다)
• unslothai/unsloth – 🦥 미세 조정되고 학습된 모델을 GGUF로 내보내거나 저장합니다 (Apache-2.0)

인프라(Infrastructure)

• Paddler - 자체 인프라에서 AI를 호스팅하고 확장하기 위한 오픈 소스 (Open-source) LLMOps 플랫폼
• GPUStack - LLM 실행을 위한 GPU 클러스터 관리
• llama_cpp_canister - WebAssembly를 사용하여 Internet Computer 상에서 스마트 컨트랙트(smart contract)로 동작하는 llama.cpp
• llama-swap - llama-server와 함께 자동 모델 전환 기능을 추가하는 투명 프록시 (transparent proxy)
• Kalavai - 어떤 규모에서든 엔드 투 엔드 (end to end) LLM 배포를 위한 크라우드소싱 (Crowdsource)
• llmaz - ☸️ Kubernetes 상에서 대규모 언어 모델을 위한 쉽고 고급스러운 추론 (inference) 플랫폼
• LLMKube - 멀티 GPU 및 Apple Silicon Metal을 지원하는 llama.cpp용 Kubernetes 오퍼레이터 (operator)

게임 (Games)

• Lucy's Labyrinth - AI 모델에 의해 제어되는 에이전트들이 당신을 속이려 시도하는 간단한 미로 게임

백엔드 (Backend)	대상 장치 (Target devices)
Metal	Apple Silicon
...

Hugging Face 플랫폼은 llama.cpp와 호환되는 다수의 LLM을 호스팅합니다.

:

다음 CLI 인자(argument)를 사용하여 GGUF 파일을 수동으로 다운로드하거나, Hugging Face 또는 기타 모델 호스팅 사이트에서 llama.cpp와 호환되는 모든 모델을 직접 사용할 수 있습니다: -hf <user>/<model>[:quant]

예시:

llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

기본적으로 CLI는 Hugging Face에서 다운로드하며, 환경 변수(environment variable)인 MODEL_ENDPOINT를 사용하여 다른 옵션으로 전환할 수 있습니다. MODEL_ENDPOINT는 반드시 Hugging Face와 호환되는 API 엔드포인트(endpoint)를 가리켜야 합니다.

모델을 다운로드한 후에는 아래 내용을 참조하여 CLI 도구를 사용해 로컬에서 실행하십시오.

llama.cpp는 모델이 GGUF 파일 형식으로 저장되어 있어야 합니다. 다른 데이터 형식의 모델은 이 저장소(repo)에 있는 convert_*.py Python 스크립트를 사용하여 GGUF로 변환할 수 있습니다.

Hugging Face 플랫폼은 llama.cpp를 사용하여 모델을 변환, 양자화 (quantizing) 및 호스팅할 수 있는 다양한 온라인 도구를 제공합니다:

• GGUF-my-repo 스페이스를 사용하여 GGUF 형식으로 변환하고 모델 가중치 (model weights)를 더 작은 크기로 양자화 (quantize)할 수 있습니다.
• GGUF-my-LoRA 스페이스를 사용하여 LoRA 어댑터 (adapters)를 GGUF 형식으로 변환할 수 있습니다 (자세한 정보: #10123).
• GGUF-editor 스페이스를 사용하여 브라우저에서 GGUF 메타데이터 (meta data)를 편집할 수 있습니다 (자세한 정보: #9268).
• Inference Endpoints를 사용하여 클라우드에서 llama.cpp를 직접 호스팅할 수 있습니다 (자세한 정보: #9669).

모델 양자화 (quantization)에 대해 더 자세히 알아보려면 이 문서를 읽어보세요.

대화 모드 (conversation mode)로 실행

채팅 템플릿 (chat template)이 내장된 모델은 자동으로 대화 모드가 활성화됩니다. 만약 활성화되지 않는다면, -cnv를 추가하고 --chat-template NAME으로 적절한 채팅 템플릿을 지정하여 수동으로 활성화할 수 있습니다.

llama-cli -m model.gguf # > hi, who are you? # Hi there! I'm your helpful assistant! I'm an AI-powered chatbot designed to assist and provide information to users like you. I'm here to help answer your questions, provide guidance, and offer support on a wide range of topics. I'm a friendly and knowledgeable AI, and I'm always happy to help with anything you need. What's on your mind, and how can I assist you today? # # > what is 1+1? # Easy peasy! The answer to 1+1 is... 2!

사용자 정의 채팅 템플릿으로 대화 모드 실행

"chatml" 템플릿 사용 (지원되는 템플릿 목록을 보려면 -h 사용) llama-cli -m model.gguf -cnv --chat-template chatml

사용자 정의 템플릿 사용 llama-cli -m model.gguf -cnv --in-prefix 'User: ' --reverse-prompt 'User:'

사용자 정의 문법 (custom grammar)으로 출력 제한

llama-cli -m model.gguf -n 256 --grammar-file grammars/json.gbnf -p 'Request: schedule a call at 8pm; Command:' # {"appointmentTime": "8pm", "appointmentDetails": "schedule a a call"}

grammars/ 폴더에는 몇 가지 샘플 문법이 포함되어 있습니다. 자신만의 문법을 작성하려면 GBNF 가이드를 확인하세요.

더 복잡한 JSON 문법을 작성하려면 https://grammar.intrinsiclabs.ai/ 를 확인하세요.

8080 포트에서 기본 설정으로 로컬 HTTP 서버 시작

8080 포트에서 기본 설정으로 로컬 HTTP 서버 시작

llama-server -m model.gguf --port 8080 # 기본 웹 UI는 브라우저를 통해 접속 가능합니다: http://localhost:8080 # 채팅 완성 (Chat completion) 엔드포인트: http://localhost:8080/v1/chat/completions

다중 사용자 및 병렬 디코딩 (Parallel decoding) 지원

# 최대 4개의 동시 요청 가능, 각 요청당 최대 컨텍스트(max context) 4096 llama-server -m model.gguf -c 16384 -np 4

투기적 디코딩 (Speculative decoding) 활성화

# draft.gguf 모델은 대상인 model.gguf의 작은 변형 모델이어야 합니다 llama-server -m model.gguf -md draft.gguf

임베딩 (Embedding) 모델 서빙

# /embedding 엔드포인트를 사용합니다 llama-server -m model.gguf --embedding --pooling cls -ub 8192

리랭킹 (Reranking) 모델 서빙

# /reranking 엔드포인트를 사용합니다 llama-server -m model.gguf --reranking

문법 (Grammar)을 사용하여 모든 출력 제한

# 사용자 정의 문법 llama-server -m model.gguf --grammar-file grammar.gbnf # JSON llama-server -m model.gguf --grammar-file grammars/json.gbnf

텍스트 파일에 대한 퍼플렉시티 (Perplexity) 측정

llama-perplexity -m model.gguf -f file.txt # [1]15.2701,[2]5.4007,[3]5.3073,[4]6.2965,[5]5.8940,[6]5.6096,[7]5.7942,[8]4.9297, ... # 최종 추정치: PPL = 5.4007 +/- 0.67339

KL 발산 (KL divergence) 측정

# TODO

기본 벤치마크 실행

llama-bench -m model.gguf # 출력: # | model | size | params | backend | threads | test | t/s | # | ------------------- | ---------: | ---------: | ---------- | ------: | ------------: | -------------------: | # | qwen2 1.5B Q4_0 | 885.97 MiB | 1.54 B | Metal,BLAS | 16 | pp512 | 5765.41 ± 20.55 | # | qwen2 1.5B Q4_0 | 885.97 MiB | 1.54 B | Metal,BLAS | 16 | tg128 | 197.71 ± 0.81 | # # 빌드: 3e0ba0e60 (4229)

기본적인 텍스트 완성 (Text completion)

llama-simple -m model.gguf # Hello my name is Kaitlyn and I am a 16 year old girl. I am a junior in high school and I am currently taking a class called "The Art of

• 기여자 (Contributors)는 PR을 열 수 있습니다.
• 협업자 (Collaborators)는 기여도에 따라 초대됩니다.
• 유지 관리자 (Maintainers)는 llama.cpp 저장소의 브랜치에 푸시(push)할 수 있으며 PR을 master 브랜치로 병합(merge)할 수 있습니다.

branch - 이슈(issues), PR, 프로젝트 관리를 도와주신다면 매우 감사하겠습니다!

• 첫 기여에 적합한 작업은 'good first issues'를 확인하세요.

• 더 자세한 정보는 CONTRIBUTING.md를 읽어보세요.

• 다음 내용을 반드시 읽어보시기 바랍니다: Inference at the edge (엣지에서의 추론)

• 관심 있는 분들을 위한 약간의 배경 지식: Changelog podcast

• 빌드 방법 (How to build)

• Docker에서 실행하기 (Running on Docker)

• Android에서 빌드하기 (Build on Android)

• 멀티 GPU 사용 (Multi-GPU usage)

• 성능 문제 해결 (Performance troubleshooting)

• GGML 팁 및 요령 (GGML tips & tricks)