welsonjs

WelsonJS용 llama.cpp 빌드

English version

이 폴더는 WelsonJS가 쓰는 Windows용 llama.cpp를 WelsonJS용 패치를 적용해 빌드합니다. 기본 소스는 Microsoft가 bitnet.cpp와 함께 3rdparty/llama.cpp 서브모듈로 배포하는 llama.cpp 포크이며, 이 포크는 bitnet.cpp의 양자화 기술을 지원하기 위해 만들어졌습니다. (저장소 자체는 기여자 계정인 isHuangXin/llama.cpp에 있습니다. 파일 참고.) 출력물에는 공식 llama-<version>-bin-win-cpu-<arch>.zip 패키지와 같은 파일, 즉 llama-server, llama-cli, llama-quantize와 ggml 백엔드가 들어 있습니다. x64 빌드에는 모든 x86-64 CPU 변형이 들어 있고 실행 시 하나가 선택됩니다. arm64 빌드에는 CPU 백엔드가 하나입니다.

포크는 BitNet의 I2_S 타입과 커널을 추가합니다. 그래서 이 빌드는 일반 GGUF 파일 외에도 microsoft/BitNet-b1.58-2B-4T-gguf 같은 1.58비트 BitNet 모델을 불러옵니다. 업스트림 llama.cpp는 이런 모델을 불러오지 못합니다.

이 빌드는 포크 위에 Tencent의 AngelSlim 양자화 기술인 STQ1_0 삼진(ternary) 타입과 커널을 추가합니다(ggml-org/llama.cpp#22836, 업스트림에 병합되지 않음. 0001-stq1_0.patch 참고). 그래서 tencent/Hy-MT2-1.8B-1.25Bit-GGUF처럼 AngelSlim으로 만든 1.25비트 모델을 불러옵니다. 포크도 업스트림 llama.cpp도 이런 모델을 불러오지 못합니다.

런처는 llama-server를 %APPDATA%\WelsonJS에 설치된 모델로 라우터 모드에서 실행하고, HTTP API로만 사용합니다. 요청은 모델 이름을 명시합니다(docs/llamacpp-launcher-api.md).

파일

파일 용도
commit.txt 빌드하는 llama.cpp 커밋(40자 SHA 전체). 브랜치는 움직일 수 있지만 커밋은 바뀌지 않으므로, 소스는 브랜치가 아니라 이 SHA로 가져옵니다.
version.txt 버전 이름표 <upstream 릴리스>.<커밋>.1(llama.cpp는 소스에 버전을 적지 않으므로 릴리스로 대신함). 포크가 upstream에서 갈라진 커밋보다 앞선 마지막 upstream llama.cpp 릴리스(bNNNN), 고정한 커밋(commit.txt)의 앞 일곱 글자, WelsonJS 빌드를 뜻하는 .1을 차례로 붙입니다. 이름표일 뿐(BUILDINFO.txt와 빌드 ID) 소스를 선택하지 않습니다.
source-archive.txt git으로 커밋을 가져오지 못할 때 쓰는 대체 소스 압축 파일(url=)과 그 SHA-256(sha256=).
patches/*.patch 이름 순서대로 git apply로 적용하는 패치. LF 줄바꿈으로 저장되어 있고, .gitattributes가 체크아웃 시 바이트 그대로 유지합니다.
build-llamacpp.ps1 소스를 가져와 패치를 적용하고, 빌드하고, 출력물을 씁니다.

현재 고정된 버전: https://github.com/isHuangXin/llama.cpp.git의 커밋 390c307752ab78fd8189f359d6954c9ba1be74af(브랜치 release-bitnet-embedding-0.6b-270m, 2026-07-15). BitNet 0b341e582afbf9e1011f24744b554c96a3477eb5의 서브모듈 커밋입니다. 이 커밋은 upstream llama.cpp(ggml-org/llama.cpp)의 665892536dfb(2026-07-04) 다음에서 갈라졌으며(포크 자체 커밋 46개), 그보다 앞선 마지막 upstream 릴리스가 b9871이므로 version.txt는 b9871.390c307.1입니다.

포크는 업스트림 llama.cpp보다 오래되었으므로, 그 이후의 업스트림 변경은 들어 있지 않습니다.

BitNet 저장소를 쓰지 않는 이유

bitnet.cpp는 포크를 BitNet 저장소의 하위 프로젝트로 빌드하며, 이때 두 가지가 추가됩니다:

I2_S 타입과 커널(ggml/src/ggml-cpu/ggml-cpu-i2s.c, AVX2, 가능하면 AVX-VNNI 또는 AVX512-VNNI)은 포크에 들어 있습니다. 이 커널은 BitNet 저장소의 헤더 하나, gemm-config.h(커널의 블록 크기)가 필요하며, 0002-bitnet-i2s.patch(파트 1)가 이 헤더를 포크에 복사해 넣습니다.

나머지 BitNet 파일은 포크 코드에서 #if defined(GGML_BITNET_ARM_TL1) || defined(GGML_BITNET_X86_TL2) 안에서만 쓰입니다. 포크의 CMake만 이 파일들을 조건 없이 참조하는데, 0002-bitnet-i2s.patch(파트 1)가 이를 바꿉니다. 따라서 TL1/TL2를 끄면 포크는 단독으로, 업스트림 llama.cpp처럼 MSVC로 빌드됩니다.

빌드

powershell -ExecutionPolicy Bypass -NoProfile -File native\llamacpp\build-llamacpp.ps1 `
    [-Arch x64|x86|arm64] [-OutDir <dir>] [-WorkDir <dir>] [-Source auto|git|archive] [-LlvmDir <dir>] [-InstallLlvm] [-Force]

요구 사항:

아키텍처

  x64 arm64
컴파일러 MSVC, Visual Studio 생성기 포크의 cmake\arm64-windows-llvm.cmake 툴체인을 쓰는 clang(LLVM), Ninja
환경 Visual Studio 기본 Visual Studio x64_arm64 개발자 환경(ARM64 라이브러리, x64에서 실행되는 ARM64 링커). ARM64 C 런타임이 있는 MSVC 버전을 vcvarsall.bat에 넘깁니다
CPU 대상 모든 x86-64 변형(GGML_CPU_ALL_VARIANTS), 실행 시 선택 -march=armv8.7-a, 백엔드 하나 ggml-cpu.dll(Windows의 ARM에서는 GGML_CPU_ALL_VARIANTS를 지원하지 않음)
OpenMP 켬(VC++ 재배포 패키지의 VCOMP140.DLL) 끔: clang에서는 libomp140.aarch64.dll이 필요한데, Visual Studio는 이를 debug_nonredist로만 제공합니다. ggml은 자체 스레드 풀을 씁니다
호스트 도구(llama-ui-embed) 빌드의 일부로 빌드 작업 폴더의 host-cxx.cmd(HOST_CXX_COMPILER)로 x64용으로 빌드, 아래 참고

x86(32비트)은 x64처럼 MSVC와 Visual Studio 생성기(-A Win32)로 빌드하되, CPU 백엔드는 하나(ggml-cpu.dll)이며 GGML_NATIVE=OFF의 AVX2 기준에서 BMI2를 뺍니다(GGML_CPU_ALL_VARIANTS=OFF, GGML_BMI2=OFF). ggml의 BMI2 코드가 32비트 MSVC에 없는 _pdep_u64를 쓰고, CPU 변형 여러 개가 BMI2를 켜기 때문입니다. 실행 파일은 /LARGEADDRESSAWARE로 링크해서 32비트 프로세스가 64비트 Windows에서 2GB 대신 4GB 주소 공간을 씁니다. 이것이 없으면 모델과 8192 토큰 문맥(런처의 LlamaCppContextSize)의 KV 캐시를 할당하지 못했습니다. x86 빌드는 8192 토큰 문맥에서 x64 빌드와 같은 그리디 답을 냅니다(Qwen3Guard 0.6B Q4_K_M, Hy-MT2 1.8B Q4_K_M, BitNet b1.58 2B I2_S). 더 큰 문맥이나 모델은 4GB에 들어가지 않을 수 있습니다.

소스

구성

출력과 빌드 건너뛰기

파일은 <OutDir>\<arch>에 기록됩니다. CI에서는 artifacts\llamacpp\x64, artifacts\llamacpp\arm64, artifacts\llamacpp\x86입니다. 압축 파일은 만들지 않습니다. 폴더에는 다음 파일도 있습니다:

빌드 ID는 다음 입력에 대한 SHA-256입니다:

BUILDINFO.txt의 빌드 ID가 같고 모든 파일이 SHA256SUMS.txt와 일치하면 스크립트는 빌드를 건너뜁니다. 그렇지 않으면(예: 입력이 바뀌었거나 파일이 수정됨) 다시 빌드합니다. -Force는 항상 빌드합니다.

다음은 빌드 ID에 들어가지 않습니다:

CI(AppVeyor)

CI에서는 빌드하지 않습니다. llama.cpp와 CrispEmbed를 x64, arm64, x86으로 빌드하면 AppVeyor 작업 제한 60분을 넘기 때문입니다. 개발자 PC에서 이 스크립트로 빌드해 WelsonJS blob 스토리지에 올리고, Release 작업이 이를 복원해 다른 산출물과 함께 패키징하고 서명합니다.

  1. 아키텍처마다 빌드합니다: -Arch x64, -Arch arm64, -Arch x86(PATH의 CMake가 다른 생성기를 기본으로 고르는 PC에서는 x64와 x86에 -Generator "Visual Studio 18 2026"을 줍니다).
  2. 빌드마다 게시합니다: native\publish-prebuilt.ps1 -Component llamacpp -Arch <arch> -BuildDir <OutDir>\<arch>.
    • 폴더가 SHA256SUMS.txt와 맞는지, BUILDINFO.txt가 현재 version.txt, commit.txt, 아키텍처를 적고 있는지 확인합니다.
    • 각 파일을 그대로, 그리고 gzip으로 압축한 <file>.gz로 AzCopy(먼저 azcopy login)를 써서 packages/native/llamacpp/<version>-<arch>/에 올립니다. 이미 있는 blob은 덮어쓰지 않으므로 게시한 빌드는 바뀌지 않습니다.
    • SHA256SUMS.txt를 native\llamacpp\prebuilt\<arch>.sha256으로 복사합니다.
  3. 세 prebuilt\<arch>.sha256 파일을 변경과 함께 커밋합니다.

Debug와 Release 작업은 아키텍처마다 native\restore-prebuilt.ps1 -Component llamacpp -Arch <arch>를 실행해 artifacts\llamacpp\<arch>에 둡니다. prebuilt\<arch>.sha256에 적힌 파일을 <version>-<arch>에서 <file>.gz로 받아 압축을 풀고(.gz를 받지 못하거나 쓸 수 없으면 원본 파일을 받음), SHA-256이 맞을 때만 쓰므로, 무엇을 배포할지는 스토리지가 아니라 저장소가 정합니다. 두 패키지 모두 서명합니다(Debug는 test-signing 정책, Release는 release-signing 정책). 각 작업은 version.txt와 세 prebuilt\<arch>.sha256 파일을 키로 artifacts\llamacpp를 캐시하므로, 이 파일들이 그대로면 복원된 폴더가 기록과 맞아 아무것도 받지 않습니다.

.artifact-configuration.xml은 세 아키텍처의 실행 파일과 DLL을 모두 이름으로 하나씩 적고(와일드카드 없음), 빌드 스크립트는 목록에 없는 바이너리가 있으면 실패하므로 새 바이너리가 서명되지 않은 채 남을 수 없습니다. Authenticode 서명은 파일을 바꾸므로, 서명된 패키지의 SHA256SUMS.txt는 서명 전 파일의 해시입니다.

현재 빌드(b9871.390c307.1)는 Visual Studio 2026으로 만들었습니다. x64와 x86은 MSVC 19.50(도구 집합 14.50), arm64는 MSVC 14.51 라이브러리와 clang 23입니다. 이를 실행하는 PC에는 이 도구보다 오래되지 않은 Visual C++ 2015-2026 재배포 패키지가 필요합니다.

설치

설치 프로그램은 이 빌드를 씁니다. 더 이상 공식 llama.cpp 패키지를 다운로드하지 않습니다(data\DownloadUrls.psd1에 llamacpp 항목이 없음).

업스트림 llama.cpp와의 호환성

포크는 일부 ggml 텐서 타입에 업스트림 llama.cpp와 다른 번호를 씁니다:

ggml 텐서 타입 이 빌드(포크) 업스트림 llama.cpp
36 I2_S(BitNet) 사용 안 함
37 I8_S(BitNet, 실행 중에만 사용) 사용 안 함
38 TL1(BitNet) 사용 안 함
42 TL2(BitNet), 또는 Tencent 파일의 STQ1_0(크기로 판별, 0001-stq1_0.patch 파트 3) Q2_0
43 STQ1_0(0001-stq1_0.patch, PR의 ID) F8_E4M3

BitNet(I2_S) 모델

microsoft/BitNet-b1.58-2B-4T-gguf는 추가 옵션 없이 llama-server의 채팅 API로 동작합니다. 이는 0002-bitnet-i2s.patch의 파트 4~7 덕분이며, 이 파트들은 테스트 중에 발견한 네 가지 문제를 고칩니다:

패치가 없을 때의 문제 원인 파트
첫 문장을 답한 뒤 토큰 한도까지 같은 말을 반복함 포크의 FFN이 2B-4T 모델에 SiLU를 쓰는데, 이 모델은 squared ReLU를 씀 5
AVX2가 없는 CPU(x64, sse42, sandybridge 변형)에서 ? 토큰만 생성함 포크의 비 AVX2 I2_S 대체 코드가 AVX2 코드와 다른 것을 계산함 4
/v1/chat/completions로 대화를 지어냄 GGUF 파일에 모델이 따르지 않는 채팅 템플릿이 들어 있음 6
“GENERATION QUALITY WILL BE DEGRADED” 경고, 일부 텍스트가 다르게 토큰화됨 GGUF 파일에 tokenizer.ggml.pre가 없음 7

I2_S 커널 자체는 정확했습니다. I2_S 가중치를 F16으로 변환한 GGUF가 I2_S 파일과 같은 토큰을 생성했습니다.

이 GGUF 파일의 general.file_type은 40이고, 포크에서는 Q1_0입니다. 파일에 I2_S 텐서가 있고 Q1_0 텐서가 없으므로 0001-stq1_0.patch(파트 3)는 이를 I2_S로 표시합니다. 파일 타입은 메타데이터일 뿐 불러오기에 영향을 주지 않습니다.

llama-quantize로 양자화하기

llama-quantize.exe는 다른 도구와 함께 %APPDATA%\WelsonJS\llamacpp에 설치되며, 이 폴더는 사용자 PATH에 들어 있습니다. llama-quantize --help가 받아들이는 타입 목록을 보여 줍니다.

타입은 번호가 아니라 이름으로 지정하세요. llama-quantize는 둘 다 받습니다. 먼저 이름을 찾고(대소문자 구분 없음), 없으면 목록에 있는 파일 타입 번호를 찾습니다. BitNet과 STQ1_0 타입의 번호는 빌드마다 다르므로, 다른 빌드나 파일에서 가져온 번호는 다른 타입을 고를 수 있습니다:

번호 이 빌드 다른 곳
41 I2_S Tencent 1.25비트 파일의 general.file_type 41은 STQ1_0
42 받지 않음(TL1, 목록에 없음) PR #22836의 STQ1_0
44 STQ1_0 STQ1_0은 PR #22836에서 42, Tencent 파일에서 41

예를 들어 Tencent 파일에서 가져온 41을 넣으면 STQ1_0이 아니라 I2_S로 양자화되고, 삼진 모델이 아니면 모델이 망가집니다. I2_S, STQ1_0 같은 이름은 그 타입이 있는 모든 빌드에서 같은 타입을 고릅니다.

예:

# BitNet b1.58: BitNet 변환기가 만든, 삼진 가중치를 담은 F32(또는 F16) GGUF를 I2_S로
# 출력 가중치와 토큰 임베딩은 F16으로 남습니다.
llama-quantize ggml-model-f32.gguf ggml-model-i2_s.gguf I2_S

# Sherry로 학습한 체크포인트(예: AngelSlim/Hy-MT1.5-1.8B-1.25bit)를 BF16으로 변환한 파일을 STQ1_0으로
llama-quantize Hy-MT1.5-1.8B-bf16.gguf Hy-MT1.5-1.8B-STQ1_0.gguf STQ1_0

# STQ1_0 파일을 다른 타입으로(재양자화에는 --allow-requantize가 필요)
llama-quantize --allow-requantize Hy-MT2-1.8B-1.25Bit.gguf Hy-MT2-1.8B-Q4_K_M.gguf Q4_K_M

테스트 결과

AppVeyor 빌드

빌드 0.2.7.build2427의 Release 작업에서 받은 artifacts.zip의 llamacpp\x64 파일(MSVC 19.29, 커밋 c68128af, 서명 전)을 12코어 x64 PC에서 테스트했습니다:

로컬 빌드

12코어 PC에서 MSVC 19.50(Visual Studio 2026)으로, 모든 패치를 적용해 빌드했습니다.

llama-server가 각 모델을 불러와 “What is the capital of France? Answer in one short sentence.”에 /v1/chat/completions로 답했습니다(temperature 0, 템플릿이나 토크나이저 옵션 없음). 그 PC에서 선택된 CPU 변형은 AVX2와 AVX-VNNI를 지원합니다.

모델 답 생성 속도
Qwen3Guard-Gen 0.6B Q4_K_M Safety: Safe Categories: None(분류기 출력) 71 토큰/초
Hy-MT2 1.8B Q4_K_M Paris is the capital of France. 32 토큰/초
FrogNano 4B 2609 Q4_K_M 182토큰의 추론(reasoning_content) 뒤 The capital of France is Paris. 10 토큰/초
BitNet b1.58 2B-4T(I2_S) The capital of France is Paris., 이어서 <|eot_id|> 24 토큰/초

Hy-MT2(번역)는 모델 README의 기본 프롬프트(“Translate the following text into {target_lang}. Note that you should only output the translated result without any additional explanation:”)와 temperature 0으로 테스트했습니다. 모든 파일이 다음 세 텍스트를 번역하고 스스로 멈췄습니다:

텍스트 대상 언어
The weather is really nice today, so let’s go for a walk in the park. 한국어
오늘 회의는 오후 세 시로 변경되었습니다. 늦지 않게 참석해 주세요. 영어
今天天气真好,我们去公园散步吧。 영어
파일 예(한국어로 번역) 생성 속도
tencent/Hy-MT2-1.8B-1.25Bit-GGUF(STQ1_0) 오늘 날씨가 정말 좋으니 공원에서 산책을 하러 가자. 28~30 토큰/초
tencent/Hy-MT2-1.8B-GGUF Q4_K_M 오늘 날씨가 정말 좋으니, 공원에서 산책하러 가요. 27 토큰/초
tencent/Hy-MT2-1.8B-GGUF Q6_K 오늘 날씨가 정말 좋으니, 공원에서 산책을 하러 가보죠. 23 토큰/초
tencent/Hy-MT2-1.8B-GGUF Q8_0 오늘 날씨가 정말 좋으니, 공원에서 산책을 하러 가보죠. 18 토큰/초

그 밖에 확인한 것:

패치

패치는 이름 순서대로 적용합니다. 각 패치는 관련 변경을 번호 붙은 파트로 묶으며, 각 패치 파일의 헤더(영어)가 모든 파트를 설명합니다.

파일 파트
0001-stq1_0.patch 1. STQ1_0(PR #22836), 2. STQ1_0용 x86 SIMD vec_dot, 3. 타입 42를 쓰는 STQ1_0 파일
0002-bitnet-i2s.patch 1. BitNet 저장소 없이 빌드, 2. ggml-base의 I2_S 기준 양자화, 3. llamafile 없는 I2_S 빠른 경로, 4. 비 AVX2 I2_S 대체 코드, 5. squared ReLU, 6. 채팅 템플릿, 7. 프리토크나이저(5~7은 BitNet b1.58 2B-4T용), 8. I2_S 타입 특성, 9. I2_S용 llama-quantize
0003-windows-build.patch 1. 모든 실행 파일과 DLL의 Windows 아이콘과 버전 정보, 2. 지원되지 않는 MSVC 옵션, 3. MSVC 변환 경고, 4. Visual Studio 2019 STL에서의 jinja
0004-embeddinggemma2.patch 1. gemma-embedding2 아키텍처, 2. EmbeddingGemma 2 텍스트 인코더(업스트림 #30054 백포트)

0001-stq1_0.patch

파트 1: STQ1_0(PR #22836)

이 파트는 ARM NEON vec_dot 커널과 함께 STQ1_0 삼진(ternary) 양자화 타입(가중치당 1.3125비트)을 추가합니다. ggml-org/llama.cpp#22836의 PR head 1e411d8f5a1e23525fa3265dfb4bd76265465397에서 가져왔습니다. 이 PR은 열려 있고 업스트림에 병합되지 않았습니다. STQ1_0은 Tencent AngelSlim의 1.25비트 양자화를 llama.cpp에서 쓰는 형식이며, Hy-MT2 1.25비트 모델 카드도 필요한 커널로 이 PR을 안내합니다.

PR은 업스트림 llama.cpp 기준으로 작성되었으므로 포크로 리베이스했습니다. PR과의 차이는 다음과 같습니다:

타입 ID

llama.cpp는 타입에 두 개의 별도 열거형으로 번호를 매깁니다:

포크의 ID는 그대로 둡니다. STQ1_0은 다음 빈 ID를 씁니다:

타입 ggml 텐서 타입 llama 파일 타입
여기의 STQ1_0 43(PR과 같음) 44(PR은 42를 쓰는데, 포크에서는 TL1)
GGML_TYPE_COUNT 44  

gguf-py/gguf/constants.py에도 같은 변경을 합니다. 코드의 모든 타입 표는 열거형 이름으로 인덱싱하므로(지정 초기화), 번호를 쓰는 것은 열거형 정의뿐입니다.

Tencent 파일은 다른 ID를 씁니다:

호환성:

기타 조정

PR의 빠른 커널은 ARM NEON 전용이며, 파트 2가 x86용을 추가합니다.

llama-quantize로 양자화하기

PR에는 llama-quantize 지원(STQ1_0, 여기서는 파일 타입 44)이 들어 있습니다. PR의 안내는 Sherry로 학습한 체크포인트(예: AngelSlim/Hy-MT1.5-1.8B-1.25bit)를 convert_hf_to_gguf.py로 BF16 GGUF로 변환한 뒤 llama-quantize <bf16.gguf> <out.gguf> STQ1_0을 실행하는 것입니다.

파트 2: STQ1_0용 x86 SIMD vec_dot

이 파트는 ggml/src/ggml-cpu/arch/x86/quants.c에 ggml_vec_dot_stq1_0_q8_K를 추가합니다.

동작 방식:

  1. 64 가중치 청크마다 그룹 g(0~15)는 가중치 g + p*16(p = 0~3)을 담습니다. 그래서 16바이트 벡터의 레인 g가 그룹 g입니다.
  2. 커널은 청크의 5비트 코드북 인덱스(4비트 코드와 부호 비트) 16개를 만듭니다. 코드북 절반마다 하나씩 _mm_shuffle_epi8 두 번으로 찾아보고, 부호 비트로 둘 중 하나를 고릅니다.
  3. _mm_maddubs_epi16으로 각 2비트 필드를 활성값 16개와 곱합니다.
  4. 코드는 -1/0/+1에 대해 0/1/2이므로, 결과는 sum(q * y) - sum(y)이며 sum(y)는 q8_K의 bsums에서 얻습니다.

연산이 정수이므로 결과는 일반 코드와 같습니다. AVX2, sandybridge, sse42, x64 변형에서 번역이 같았습니다.

파트 3: 타입 42를 쓰는 STQ1_0 파일

이 파트는 타입 ID를 바꾸지 않고, 타입 42를 쓰는 STQ1_0 파일을 빌드가 읽을 수 있게 합니다.

ggml 타입 42에는 두 가지 의미가 있습니다:

이 빌드는 포크의 TL2 = 42를 유지하고, PR처럼 STQ1_0에 43을 씁니다. 그래서 어느 번호 체계를 따르는 파일이든 의미가 유지됩니다.

텐서 타입(ggml/src/gguf.cpp). 두 형식은 크기가 다르고, GGUF 파일의 텐서 오프셋은 텐서 크기와 맞아야 합니다. gguf_init_from_file_impl은 텐서 정보를 읽은 직후 이를 검사합니다. 그 검사 전에, 패치는 타입 42 텐서가 있는 파일을 살펴봅니다:

파일 타입(src/llama-model-loader.cpp). general.file_type에도 번호 세 개에 같은 문제가 있으므로, 로더는 텐서 타입을 보고 판단합니다:

general.file_type 여기서의 의미 다른 쪽 사용처 표시
41 MOSTLY_I2_S Tencent의 STQ1_0 파일 파일에 STQ1_0 텐서가 있고 I2_S 텐서가 없으면 MOSTLY_STQ1_0
40 MOSTLY_Q1_0 microsoft/BitNet-b1.58-2B-4T-gguf 파일에 I2_S 텐서가 있고 Q1_0 텐서가 없으면 MOSTLY_I2_S
42 MOSTLY_TL1 PR #22836으로 만든 STQ1_0 파일(그쪽은 MOSTLY_STQ1_0 = 42, 여기는 44) 파일에 STQ1_0 텐서가 있고 TL1 텐서가 없으면 MOSTLY_STQ1_0

파일 타입은 메타데이터일 뿐입니다.

테스트한 것:

0002-bitnet-i2s.patch

파트 1: BitNet 저장소 없이 빌드

이 파트는 TL1/TL2가 꺼져 있을 때 포크가 BitNet 저장소에 의존하지 않게 합니다:

TL1이나 TL2를 켜고 BitNet 저장소 안에서 포크를 빌드하면, CMake 변경은 아무 효과가 없고 복사한 헤더가 ggml-cpu-i2s.c에 대해 BitNet의 헤더를 대신합니다(값은 같음).

파트 2: ggml-base의 I2_S 기준 양자화

이 파트는 dequantize_row_i2_s와 quantize_i2_s를 ggml/src/ggml-cpu/quants.c(CPU 백엔드)에서 ggml/src/ggml-quants.c(ggml-base)로 옮기고 GGML_API로 선언합니다.

두 함수 모두 단순한 스칼라 C이므로 그대로 옮깁니다. 이후 파트 9가 quantize_i2_s를 다시 씁니다. CPU 백엔드(ops.cpp가 dequantize_row_i2_s를 씀)는 다른 기준 양자화 함수처럼 이 함수들을 ggml-base에서 가져옵니다.

파트 3: llamafile 없는 I2_S 빠른 경로

이 파트는 ggml_compute_forward_mul_mat에 있는 포크의 I2_S GEMV/GEMM 빠른 경로가 src1_cont 대신 ggml_is_contiguous(src1)를 호출하게 합니다.

파트 4: 비 AVX2 I2_S 대체 코드

이 파트는 x64, sse42, sandybridge CPU 변형(그리고 AVX2가 없는 모든 CPU)이 I2_S에 쓰는 코드를 고칩니다. 이 파트가 없으면 2B-4T 모델은 이 변형들에서 ? 토큰만 생성했습니다.

패치를 적용하면 x64 변형이 AVX2 변형과 같은 토큰을 생성합니다.

파트 5: BitNet b1.58 2B-4T의 squared ReLU

이 파트는 bitnet-b1.58 아키텍처가 피드포워드 네트워크에서 LLM_FFN_RELU_SQR를 쓰게 합니다.

원인을 찾은 방법:

파트 6: BitNet b1.58 2B-4T의 채팅 템플릿

이 파트는 microsoft/BitNet-b1.58-2B-4T-gguf의 채팅 템플릿을 원본 모델의 템플릿으로 바꿉니다.

파트 7: BitNet b1.58 2B-4T의 프리토크나이저

이 파트는 파일에 tokenizer.ggml.pre가 없을 때 bitnet-b1.58에 llama-bpe 프리토크나이저를 줍니다.

파트 8: I2_S 타입 특성

이 파트는 clang이 보고하는, ggml/src/ggml.c에 있는 포크의 type_traits 표의 두 가지 문제를 고칩니다:

파트 9: I2_S용 llama-quantize

이 파트는 llama-quantize가 I2_S 파일을 만들 수 있게 합니다. bitnet.cpp의 setup_env.py는 llama-quantize <f32> <out> I2_S 1을 실행하지만, 포크에서는 실패했습니다:

변경 사항:

0003-windows-build.patch

파트 1: Windows 아이콘과 버전 정보

llama.cpp에는 Windows 리소스 파일이 없으므로, 실행 파일과 DLL에 아이콘도 버전 정보도 없습니다(파일 속성의 “설명”이 비어 있음). 이 파트는 최상위 CMakeLists.txt의 끝에서 불러오는 cmake/win-resources.cmake를 추가하며, 캐시 옵션은 다음과 같습니다:

옵션 빌드 스크립트가 설정하는 값 효과
LLAMA_WIN_ICON app\favicon.ico 실행 파일에 아이콘을 애플리케이션 아이콘으로 넣습니다.
LLAMA_WIN_DESCRIPTION llama.cpp built for WelsonJS 모든 실행 파일과 DLL에 VERSIONINFO 리소스를 추가합니다.
LLAMA_WIN_VERSION WelsonJS 버전 0.2.7.62(런처의 AssemblyFileVersion, 또는 -ProductVersion) FileVersion과 ProductVersion(기본값 0.0.<LLAMA_BUILD_NUMBER>.0).
LLAMA_WIN_COMPANY Catswords Research CompanyName.
LLAMA_WIN_COPYRIGHT 코드의 저작자들(아래) LegalCopyright.

LegalCopyright 값은 빌드에 코드가 들어간 모든 저작자를 적습니다:

Copyright (c) 2023-2026 The ggml authors (llama.cpp), Copyright (c) Microsoft Corporation (bitnet.cpp), Copyright (c) 2025 Tencent (AngelSlim, STQ1_0), Copyright (c) 2026 Catswords Research (WelsonJS)

각 바이너리의 VERSIONINFO 리소스에는 다음 값이 들어갑니다:

값 예(llama-server.exe) 예(ggml-cpu-haswell.dll)
FileDescription(“설명”으로 표시) llama-server - OpenAI-compatible LLM server (llama.cpp built for WelsonJS) ggml-cpu-haswell - ggml CPU backend, haswell variant (llama.cpp built for WelsonJS)
FileVersion, ProductVersion 0.2.7.62 0.2.7.62
CompanyName Catswords Research Catswords Research
LegalCopyright 위의 값 위의 값
ProductName llama.cpp llama.cpp
InternalName, OriginalFilename llama-server, llama-server.exe ggml-cpu-haswell, ggml-cpu-haswell.dll
Comments llama.cpp built for WelsonJS. llama.cpp 390c307, build 1. 같음

FileDescription의 역할 문구는 ggml tensor library, ggml base library, ggml CPU backend, <변형> variant, llama.cpp library, llama.cpp common library, llama.cpp multimodal library, <도구> implementation library, OpenAI-compatible LLM server, LLM command-line interface, GGUF model quantizer입니다. 역할을 모르는 대상은 <대상> (<텍스트>)가 됩니다.

패치가 하는 일:

아이콘 파일은 WelsonJS 저장소에 그대로 있고, 패치는 옵션만 추가합니다. LLAMA_WIN_ICON과 LLAMA_WIN_DESCRIPTION이 비어 있으면(기본값) 패치가 없는 빌드와 같습니다. 아이콘 파일이 없거나 버전 형식이 틀리면 구성 단계가 오류로 멈춥니다.

빌드 스크립트는 출력물을 검사합니다. 모든 실행 파일과 DLL에 위의 FileDescription, 버전, CompanyName, LegalCopyright가 있어야 하며, 하나라도 없으면 빌드가 실패합니다.

파트 2: 지원되지 않는 MSVC 옵션

이 파트는 ggml/src/ggml-cpu/CMakeLists.txt에서 MSVC 경고 D9002(“알 수 없는 옵션 무시”)의 원인 두 가지를 제거합니다:

옵션 문제 변경
/arch:SSE4.2(sse42 CPU 변형) 최신 MSVC에만 있습니다. MSVC 19.29(Visual Studio 2019, AppVeyor 이미지)는 이 변형의 모든 소스 파일에서 이를 무시합니다. MSVC 19.50은 받아들입니다. check_c_compiler_flag가 받아들일 때만 추가합니다. CMake는 D9002를 검사 실패로 셉니다.
-fno-lto(CPU 기능 감지 객체, ggml-cpu-*-feats) GCC/clang 옵션이라 모든 MSVC가 무시합니다. MSVC가 아닐 때만 넘깁니다. MSVC는 /GL을 주지 않으면 LTO를 쓰지 않습니다.

/arch:SSE4.2가 없으면 sse42 변형은 SSE2 코드 생성으로 컴파일됩니다. 이는 안전합니다. MSVC는 어떤 /arch에서도 SSE4 내장 함수를 받아들이고, 이 변형은 실행 시 SSE4.2가 있는 CPU에서만 선택됩니다. AppVeyor 이미지에서 SSE4 명령어를 쓰는 자동 벡터화만 잃습니다.

파트 3: MSVC 변환 경고(C4244)

이 파트는 MSVC가 llama, mtmd 등의 대상에서 보고하는 많은 C4244 경고(“데이터 손실 가능성”)를 처리합니다. MSVC 19.50에서는 이런 줄이 31개이고, MSVC 19.29(AppVeyor)는 더 많이 보고합니다.

파트 4: Visual Studio 2019 STL에서의 jinja

이 파트는 common/jinja/value.h의 value_func_t를 바꿉니다. 이 코드는 함수 타입 func_hptr로 std::function::target<func_hptr>()을 호출했습니다.

패치는 target<func_hptr *>()을 요청해 저장된 함수 포인터를 돌려주는(다른 호출 가능 객체면 nullptr) function_pointer()를 추가합니다. unique_hash()와 equivalent()가 이를 씁니다. 두 함수의 주석은 함수 포인터 비교를 설명합니다. 둘 다 지금은 쓰이지 않습니다.

0004-embeddinggemma2.patch

포크는 EmbeddingGemma 2(google/embeddinggemma-2, Apache-2.0)보다 오래되었습니다. 이 모델의 GGUF 파일(예: ggml-org/embeddinggemma-2-GGUF)은 아키텍처가 gemma-embedding2입니다. 이 패치는 업스트림 llama.cpp 4fbc76dec5(ggml-org/llama.cpp#30054, MIT)의 C++ 부분을 백포트해 llama-server --embedding이 이 모델의 텍스트 임베딩을 제공하게 합니다. 런처는 설치 구성 요소 llamacpp\embeddinggemma_2를 이렇게 실행합니다(docs/llamacpp-launcher-api.md 참고).

파트 1: gemma-embedding2 아키텍처

LLM_ARCH_GEMMA_EMBEDDING2를 LLM_ARCH_GEMMA_EMBEDDING 옆에 등록합니다. llama-arch의 이름, llama_model_mapping의 모델 클래스, KV 캐시가 없는 모델(create_memory), NEOX rope 모델(llama_model_rope_type)입니다.

파트 2: EmbeddingGemma 2 텍스트 인코더

src/models/gemma-embedding2.cpp와 models.h의 llama_model_gemma_embedding2입니다. 양방향 Gemma 4 계열 인코더(24층, 은닉 크기 512)로, 여섯 층 중 다섯 층에 대칭 슬라이딩 윈도 어텐션을 쓰고, 층마다 헤드 크기와 KV 헤드 수가 다르며, Q/K/V RMS 정규화, 투영만으로 만드는 층별 입력, 층마다 학습된 출력 배율, 마지막 은닉 상태를 768차원 임베딩으로 바꾸는 투영을 씁니다. 풀링(평균)은 GGUF에서 읽습니다. 모델이 쓰는 나머지(gemma4 토크나이저, 층별 입력, 층별 헤드 크기)는 포크에 이미 있습니다(Gemma 3n, Gemma 4).

파일은 업스트림 그대로이며, 포크 API에 맞춘 두 가지만 다릅니다.

models/*.cpp는 src/CMakeLists.txt의 file(GLOB)로 모이므로 새 파일에 CMake 변경이 필요 없습니다. 비전·오디오 인코더(mmproj 파일)와 Python 변환은 패치에 들어 있지 않습니다. GGUF 파일은 업스트림에서 변환합니다.

업데이트 방법

  1. 새 BitNet 커밋이 쓰는 llama.cpp 커밋을 찾습니다: git ls-tree <BitNet sha> 3rdparty/llama.cpp와 BitNet의 .gitmodules. commit.txt를 그 커밋으로 설정하고, 포크 URL이 바뀌었으면 스크립트의 RepositoryUrl도 바꿉니다. version.txt를 <릴리스>.<커밋 앞 일곱 글자>.1로 바꿉니다. <릴리스>는 포크가 갈라지기 전의 마지막 upstream 릴리스입니다. 갈라진 지점은 gh api repos/ggml-org/llama.cpp/compare/master...<포크 소유자>:llama.cpp:<sha>의 merge_base_commit이고, 릴리스는 gh api repos/ggml-org/llama.cpp/compare/bNNNN...<갈라진 지점>이 behind_by 0을 돌려주는 가장 큰 bNNNN 태그입니다.
  2. 그 커밋의 소스 압축 파일을 올리고(git archive --format=zip --prefix=llama.cpp-<sha>/ <sha>), source-archive.txt의 URL과 SHA-256을 업데이트합니다.
  3. 깨끗한 체크아웃에 각 패치가 git -c core.autocrlf=false apply --check로 적용되는지 확인합니다. 필요하면 패치를 리베이스하고, ggml.h, llama.h, gguf-py/gguf/constants.py의 타입 ID를 포크의 타입과 대조합니다.
  4. 포크가 여전히 BitNet 저장소의 모든 사용을 TL1/TL2 옵션 뒤에 두는지(0002-bitnet-i2s.patch 파트 1), 그리고 I2_S 소스가 모든 CPU 변형에 컴파일되는지 확인합니다.
  5. 스크립트로 x64, arm64, x86을 로컬에서 빌드합니다. 다음을 확인합니다:
    • llama-quantize --help가 STQ1_0을 보여 줌,
    • llama-server가 설치되는 모델 중 하나와 I2_S 모델로 채팅 요청에 답함,
    • llama-server --embedding -m embeddinggemma-2-Q8_0.gguf가 POST /v1/embeddings에 입력마다 768개 값으로 답함.
  6. 세 빌드를 게시하고(native\publish-prebuilt.ps1, CI 참고) 새 prebuilt\<arch>.sha256 파일과 함께 커밋합니다. 바뀐 파일 때문에 CI 캐시가 무효화되어 CI가 새 빌드를 받습니다.