GSV.CPP / docs /build.md
KakaruHayate's picture
docs: api/benchmark/usage
c9aef91 verified
|
Raw History Blame Contribute Delete
7.66 kB

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-tools provides glslc, 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.bat first).

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_1d and 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)