Download docs/build.md from KakaruHayate/GSV.CPP: direct link, hf CLI and curl.
- Browser
- Download file 7.66 kB
-
https://huggingface.co/KakaruHayate/GSV.CPP/resolve/main/docs/build.md
- Command line
-
hf download hf://KakaruHayate/GSV.CPP/docs/build.md
-
curl -L -o build.md https://huggingface.co/KakaruHayate/GSV.CPP/resolve/main/docs/build.md
Building gsv.cpp from scratch
This guide takes a clean machine to a working /tts server: engine, GGUF models, and the Python
text frontend.
Two supported paths:
- Linux (x86_64, glibc 2.35+): the reference build, also what CI produces.
- Windows (x86_64, Visual Studio 2022): same code, MSVC; a prebuilt one-click package also
exists on Hugging Face (
windows/GSV.CPP-win64-*.zip).
CPU-only builds are supported on both (skip the Vulkan parts).
text ──► Python sidecar (G2P + BERT ids) ──┐
├─► gsv_server (C++/ggml) ──► 48 kHz WAV
GGUF models (AR/cond/DiT/refcode/BERT/HuBERT/vocoder) ─┘
1. Prerequisites
Linux (Ubuntu 22.04+)
sudo apt-get update
sudo apt-get install -y build-essential cmake git python3 python3-venv \
libvulkan-dev vulkan-tools glslang-tools mesa-vulkan-drivers
- CMake 3.20+, a C++17 compiler, Python 3.10+.
glslang-toolsprovidesglslc, which ggml-vulkan needs at build time.- GPU users need a working Vulkan driver (
vulkaninfo --summary).
Windows
- Visual Studio 2022 with the "Desktop development with C++" workload (MSVC + CMake).
- Vulkan SDK 1.3+ (from https://vulkan.lunarg.com/), which ships
glslc.exe. - Git and Python 3.10+.
- Build from a x64 Native Tools Command Prompt for VS 2022 (or run
vcvars64.batfirst).
2. Get the sources
git clone https://github.com/KakaruHayate/gsv.cpp
cd gsv.cpp
The engine needs a patched llama.cpp/ggml (conv1d + audio ops are not upstream). The exact
commit is pinned in .github/workflows/ci.yml (LLAMA_CPP_COMMIT):
git clone https://github.com/ggml-org/llama.cpp
git -C llama.cpp checkout f0c41e0168dfd4b5ef72b21d1a311b24cc7a894a
git -C llama.cpp apply ../patches/0001-ggml-audio-patch-port-on-llamacpp.patch
The patch is what makes
ggml_conv_1d,ggml_conv_transpose_1d,ggml_pad_reflect_1dand the sub-pixel path available. Without it the engine does not compile.
3. Build ggml
Vulkan (GPU)
cmake -S llama.cpp -B llama.cpp/build-vk-rel \
-DGGML_VULKAN=ON -DGGML_NATIVE=OFF -DGGML_AVX2=ON -DGGML_FMA=ON -DGGML_F16C=ON \
-DGGML_BUILD_TESTS=OFF -DGGML_BUILD_EXAMPLES=OFF \
-DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF \
-DLLAMA_BUILD_TOOLS=OFF -DLLAMA_BUILD_SERVER=OFF \
-DCMAKE_BUILD_TYPE=Release
cmake --build llama.cpp/build-vk-rel --config Release \
--target ggml ggml-base ggml-cpu ggml-vulkan -j 2
Windows: add -G "Visual Studio 17 2022" -A x64 to the configure step (the libraries end up in
llama.cpp/build-vk-rel/Release/).
CPU only
cmake -S llama.cpp -B llama.cpp/build-cpu-rel \
-DGGML_NATIVE=OFF -DGGML_AVX2=ON -DGGML_FMA=ON -DGGML_F16C=ON \
-DGGML_BUILD_TESTS=OFF -DLLAMA_BUILD_TESTS=OFF \
-DCMAKE_BUILD_TYPE=Release
cmake --build llama.cpp/build-cpu-rel --config Release --target ggml ggml-base ggml-cpu -j
4. Build the server
cmake -S . -B build -DGSV_GGML_LIB_DIR=llama.cpp/build-vk-rel -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --target gsv_server -j 4
Output:
- Linux:
build/gsv_server - Windows:
build/Release/gsv_server.exe
Tests (optional but recommended): -DGSV_BUILD_TESTS=ON is the default and adds
test_add_act, test_conv_direct_act, test_svc; run them with ctest --test-dir build.
Windows: copy ggml*.dll next to the exe (they are in llama.cpp/build-vk-rel/Release/), or add
that directory to PATH. The VC++ runtime (vcruntime140*.dll, msvcp140.dll) must be present —
the prebuilt package ships them.
5. Get the models
The engine reads GGUF only. Either
a) download the prebuilt set (recommended) from https://huggingface.co/KakaruHayate/GSV.CPP:
models/
gsv-ar-q8.gguf # AR, Q8 (default recommendation)
gsv-cond-f16.gguf # v5turbo cond
gsv-dit-f16all.gguf # v5turbo DiT
gsv-refcode.gguf # v5turbo reference encoder
gsv-bert-f16.gguf # shared BERT
gsv-hubert-f16.gguf # shared CN-HuBERT
gsv-vocoder-f32.gguf # shared HiFi-GAN (sub-pixel, F32)
resampy_kaiser_best.bin # resampling filter table
v5dev additionally needs gsv-v5dev-cond-f16.gguf, gsv-v5dev-dit-f16all.gguf,
gsv-v5dev-refcode.gguf; describe it in a voice manifest (models/voices/v5dev/manifest.json).
b) convert your own fine-tune with tools/export_gguf — see
tools/export_gguf/README.md. You still need BERT/HuBERT
(prebuilt or --kind bert/hubert).
6. Text frontend (G2P sidecar)
The frontend is vendored in frontend/ and needs no torch/transformers.
python3 -m venv .venv-sidecar
.venv-sidecar/bin/pip install -r frontend/requirements-zh.txt # Windows: .venv-sidecar\Scripts\pip
.venv-sidecar/bin/pip install -r frontend/requirements-multi.txt # en/ja/ko/yue
Data (not in git):
| what | where to put it | env override |
|---|---|---|
G2PW model (g2pW.onnx + dicts, ~608 MB) |
models/frontend/g2pw/ |
GSV_G2PW_MODEL |
BERT tokenizer (vocab.txt, config.json, tokenizer_config.json) |
models/frontend/bert_tokenizer/ |
GSV_BERT_DIR |
nltk_data (cmudict + averaged_perceptron_tagger_eng) |
models/frontend/nltk_data/ |
NLTK_DATA |
fast-langdetect model (lid.176.bin, ~125 MB) |
models/frontend/fast_langdetect/ |
GSV_FAST_LANGDETECT |
All four are published on Hugging Face under frontend/. With the layout above the sidecar finds
them automatically; the env vars are only needed for custom locations.
Start it:
.venv-sidecar/bin/python tools/text_sidecar.py --host 127.0.0.1 --port 9882
GET /health answers {"ok": true, "ready": true} once the Chinese frontend is warm (a few
seconds; the other languages warm on first use).
7. Run
# GPU
./build/gsv_server --models models --device vulkan --sidecar 127.0.0.1:9882 --port 9880
# CPU
./build/gsv_server --models models --device cpu --sidecar 127.0.0.1:9882 --port 9880
--allow-path restricts which directories may be used for reference audio (defaults to the
current directory + the upload temp dir; --allow-path '*' disables the restriction).
Check it:
curl -s http://127.0.0.1:9880/health
curl -s http://127.0.0.1:9880/models
Synthesize (see api.md for all parameters):
curl -X POST http://127.0.0.1:9880/tts -H 'Content-Type: application/json' -d '{
"text": "你好,欢迎使用语音合成系统。",
"text_lang": "all_zh",
"ref_audio_path": "models/ref.wav",
"prompt_text": "参考音频对应的文本",
"prompt_lang": "all_zh",
"sample_steps": 4
}' -o out.wav
Reference audio must be 3–10 s (max 30 s) and readable by the process.
8. Troubleshooting
| symptom | cause / fix |
|---|---|
CMake: llama.cpp not found |
clone it next to the repo, or pass -DGSV_LLAMA_DIR=/path/to/llama.cpp |
ggml build: glslc not found |
install glslang-tools (Linux) / Vulkan SDK (Windows) |
[device] no Vulkan device |
driver missing; try --device cpu, or vulkaninfo to check |
text sidecar 不可达 |
sidecar not running / wrong port / it crashed (check its stderr) |
| G2PW download error at startup | GSV_G2PW_MODEL points to the wrong directory (must contain g2pW.onnx) |
reference audio too long |
trim the clip to 3–10 s |
Windows: missing ggml-*.dll |
copy them next to gsv_server.exe (or add to PATH) |
Linux binary: GLIBC_2.38 not found |
build on the oldest distro you need (CI uses Ubuntu 22.04) |