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+)
```bash
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
```bash
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`):
```bash
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)
```bash
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
```bash
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
```bash
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](../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.
```bash
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:
```bash
.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
```bash
# 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:
```bash
curl -s http://127.0.0.1:9880/health
curl -s http://127.0.0.1:9880/models
```
Synthesize (see [api.md](api.md) for all parameters):
```bash
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) |