yzma - Go with your own intelligence

Linux

macOS

Windows

WASM

GitHub Release

Bluesky

Mastodon

yzma를 사용하면 하드웨어 가속을 활용하여 완전히 로컬 환경에서 추론(inference)이 가능한 Go 애플리케이션을 직접 작성할 수 있습니다. 이 과정에는 llama.cpp가 통합됩니다.

• Linux, macOS 또는 Windows에서 최신 Vision Language Models (VLM) 및 Large/Small/Tiny Language Models (LLM)을 실행할 수 있습니다.
• 최대 성능을 위해 CUDA, Metal, OpenVINO, 또는 Vulkan과 같은 사용 가능한 모든 하드웨어 가속 기능을 사용할 수 있습니다.
• 또한, TinyGo와 WebAssembly를 사용하여 브라우저에서 실행할 수 있으며, CPU 또는 WebGPU를 통해 GPU에서도 실행 가능합니다.
• yzma는 CGo가 필요하지 않도록 purego 및 ffi 패키지를 사용합니다.
• 최신 llama.cpp 릴리스와 작동하므로, 최신 기능, 성능 개선 및 버그 수정 사항을 사용할 수 있습니다.

문서는 **yzma.ai**에서 확인할 수 있습니다.

이 예제는 SmolLM2-135M-GGUF 모델을 사용합니다:

package main

import (
...

yzma 설치하기를 한 후, yzma 명령줄 도구를 사용하여 모델을 다운로드하십시오:

$ yzma model get -u https://huggingface.co/QuantFactory/SmolLM2-135M-GGUF/resolve/main/SmolLM2-135M.Q4_K_M.gguf

Go 프로그램을 실행합니다:

$ go run ./examples/hello/

"Yes, I'm ready to go." 

설치 (Installation)

go install github.com/hybridgroup/yzma@latest
yzma install --lib /path/to/lib
export YZMA_LIB=/path/to/lib

yzma 명령줄 도구는 사용자의 플랫폼에 맞는 llama.cpp 사전 빌드 라이브러리를 다운로드합니다. 또한, 애플리케이션 자체적으로 CUDA 및 ROCm에 대한 자동 감지 기능을 통해 이를 다운로드할 수 있습니다.

다운로드된 각 파일은 릴리스와 함께 공개된 SHA-256 다이제스트와 비교되며, yzma verify 명령은 기존 설치를 확인합니다.

macOS, Linux, Windows, Raspberry Pi, NVIDIA Jetson Orin, Arduino UNO Q, 그리고 브라우저에 대한 지침은 **yzma.ai/getting-started/install**를 참조하십시오.

예제 (Examples)

저희는 examples 디렉토리에서 yzma를 사용하는 여러 가지 방법을 제공합니다.

비전 언어 모델(VLM) 멀티모달 예제 (Vision Language Model (VLM) Multimodal Example)

이 예제는 Qwen2.5-VL-3B-Instruct-Q8_0 VLM 모델을 사용하여 텍스트 프롬프트와 이미지를 모두 처리한 다음, 결과를 표시합니다.

$ go run ./examples/vlm/ -model ~/models/Qwen2.5-VL-3B-Instruct-Q8_0.gguf -mmproj ~/models/mmproj-Qwen2.5-VL-3B-Instruct-Q8_0.gguf -image ./images/domestic_llama.jpg -p "What is in this picture?"

The image features a white llama standing in a fenced-in area, possibly a zoo or a farm. The llama is positioned in the center of the image, with its body facing the right side. The fenced area is surrounded by trees, creating a natural environment for the llama.

코드 보기.

Small Language Model (SLM) 대화형 채팅 예제

yzma를 사용하여 텍스트 언어 모델에 대한 추론(inference)을 수행할 수 있습니다. 이 예제는 대화형 채팅 세션을 위해 qwen2.5-0.5b-instruct-fp16.gguf 모델을 사용합니다.

$ go run ./examples/chat/ -model ./models/qwen2.5-0.5b-instruct-fp16.gguf
Enter prompt: Are you ready to go?

...

코드 보기.

WebAssembly 예제

yzma는 텍스트 또는 이미지와 함께 브라우저에서도 실행됩니다. llama.cpp는 자체 WebAssembly 모듈로 실행되며, TinyGo가 컴파일한 Go 프로그램이 pkg/llamawasm 패키지를 통해 이를 구동합니다. 모델은 사용자 기기를 벗어나지 않으며, 서버가 어떤 작업도 수행하지 않습니다.

$ make download-llama.cpp-wasm
$ make wasm-example
$ make wasm-vlm-example
...

그런 다음 http://localhost:8080에서 채팅을 하거나, http://localhost:8080/vlm.html로 이동하여 이미지에 대한 질문을 할 수 있습니다. 각 페이지는 어떤 백엔드를 로드했는지 보여줍니다:

backend: webgpu (WebGPU)

llama.cpp에는 세 가지 빌드가 있으며, JavaScript glue가 브라우저에서 실행할 수 있는 최적의 것을 선택합니다:

따라서 WebGPU가 없는 브라우저에서도 CPU로 작동합니다. GPU는 이미지 처리에서 가장 큰 도움을 줍니다. 모델의 프로젝터(projector)를 통해 하나를 실행하는 데 걸리는 시간은 GPU에서는 1~2초인 반면, CPU에서는 절반 분 이상이 걸립니다.

브라우저에서는 pkg/llamawasm의 더 작은 API를 사용하여 텍스트 생성, 임베딩 및 이미지에 필요한 호출을 수행합니다. 호출 이름과 순서는 pkg/llama와 pkg/mtmd와 일치하므로, 프로그램을 포팅하는 것은 가져오기(import) 변경만으로 충분합니다.

여기서 코드를 확인하세요 또는 이미지 예제를 확인하세요.

작동 방식, 각 빌드의 속도, 그리고 페이지가 하나를 사용하기 위해 해야 할 일에 대한 자세한 내용은 wasm/README.md를 참조하세요.

추가 예제

yzma 사용 방법에 대한 더 많은 예제는 examples 디렉터리에서 확인하세요.

yzma 활용 사례

누가 yzma를 사용할까요? 도구, 애플리케이션, 예제, 그리고 블로그 게시물 및 비디오를 확인해 보세요!

모델

yzma는 llama.cpp에서 지원하는 GGUF 형식의 모델을 사용합니다. Hugging Face에는 (최근 집계 기준 201k개 이상) 많은 GGUF 형식의 모델이 있습니다:

예를 들어, 다음 명령어를 사용하여 gemma-3-1b-it-GGUF 모델을 다운로드할 수 있습니다:

$ yzma model get -u https://huggingface.co/ggml-org/gemma-3-1b-it-GGUF/resolve/main/gemma-3-1b-it-Q4_K_M.gguf

각 모델의 다운로드 및 실행 명령어는 모델 페이지를 확인하세요.

지원

yzma는 현재 llama.cpp 기능의 96% 이상을 지원합니다. 전체 목록은 ROADMAP.md에서 확인하세요.

Linux, macOS 및 Windows에서 멀티모달 모델(이미지/오디오)과 텍스트 언어 모델을 완벽한 하드웨어 가속으로 사용할 수 있습니다.

pkg/llamawasm 패키지에서는 더 작은 API를 사용합니다. 이 API는 텍스트 생성, 임베딩 및 이미지를 다루지만, 오디오, 비디오, LoRA 어댑터, 저장된 상태 또는 양자화(quantization)는 지원하지 않습니다. 위의 WebAssembly 예제와 wasm/README.md를 참고하세요.

llama.cpp에 새로운 릴리스가 있을 때마다 yzma의 테스트가 자동으로 실행됩니다. 이는 최신 코드 및 모델을 유지하는 데 도움이 됩니다.

필요한 llama.cpp 버전

때로는 llama.cpp에 예기치 않은 변경 사항(breaking changes)이 있어 yzma 업데이트가 필요할 수 있습니다. 태그가 지정된 릴리스의 알려진 호환 버전은 다음과 같습니다:

yzma의 태그가 지정된 릴리스는 기본적으로 자체 llama.cpp 릴리스를 설치하므로, -version 플래그 없이 yzma install을 실행하면 이 표에 있는 버전이 적용됩니다. 최신 나이틀리 빌드(nightly build)를 사용하려면 -version latest를 사용하세요. main 브랜치에서 빌드된 경우 항상 가장 최근의 나이틀리 빌드를 사용합니다.

다음은 llama.cpp 나이틀리 빌드의 알려진 호환 버전입니다:

벤치마크 (Benchmarks)

yzma는 llama.cpp를 동일한 프로세스에서 호출하기 때문에 빠릅니다. 외부 서버가 필요 없습니다!

예를 들어, Apple M4 Max(RAM 128 GB)에서 이미지와 텍스트 프롬프트에 대해 다중 모드 추론을 수행하는 Qwen3-VL-2B-Instruct 시각 언어 모델(VLM)의 성능은 다음과 같습니다:

$ go test -run none -benchtime=10s -count=5 -bench BenchmarkMultimodalInference
goos: darwin
goarch: arm64
...

더 많은 벤치마크를 보고 싶으신가요? 플랫폼별로 파일이 있는 BENCHMARKS.md 문서를 확인하세요. 이 수치를 자신의 컴퓨터에서 재현하려면 ./benchmarks/run.sh을 실행하세요. 벤치마크 실행 방법를 참고하세요.

추가 정보 (More Info)

yzma를 사용하여 언어 모델을 Golang 코드에 직접 통합하는 완전한 애플리케이션을 구축할 준비가 되었습니다.

llama.cpp와 함께 yzma의 장점은 다음과 같습니다:

• 일반적인 go build 및 go run 명령어로 yzma를 사용하는 Go 프로그램을 컴파일할 수 있습니다. C 컴파일러가 필요하지 않습니다!
• 구성에 따라 사용 가능한 모든 하드웨어 가속(CUDA, Vulkan 등)을 가진 llama.cpp 라이브러리를 사용할 수 있습니다.
• 동일한 프로세스 내에서 함수 호출을 수행하므로 고성능을 제공합니다. 외부 모델 서버가 필요 없습니다!
• Github에서 llama.cpp 사전 컴파일된 라이브러리를 직접 다운로드하거나 애플리케이션에 포함할 수 있습니다.
• llama.cpp가 심각한 변경 사항을 만들지 않는 한, Go 프로그램을 다시 컴파일하지 않고도 llama.cpp 라이브러리를 업데이트할 수 있습니다.

이 아이디어는 Go 개발자가 컨테이너를 사용하거나 일반적인 GOOS 및 GOARCH 환경 변수 외에 다른 작업을 할 필요 없이 언어 모델을