Choose an AngeVoice runtime mode

The deployment profile selects CPU or GPU. The runtime mode controls when models load, how they unload and how failures are recovered.

Recommended default: on demand with process isolation

• The API starts quickly and loads a model only for the first request.
• A stuck model process can be terminated without taking down the API service.
• Idle models can release RAM and VRAM, which is useful on NAS and single-GPU hosts.

KOKORO_PROCESS_ISOLATION_ENABLED=true
MOSS_PROCESS_ISOLATION_ENABLED=true
ZIPVOICE_PROCESS_ISOLATION_ENABLED=true
ANGEVOICE_STARTUP_PRELOAD_ENABLED=false
ANGEVOICE_MODEL_UNLOAD_ON_SWITCH=true

When to enable startup preload

Enable preload only when one model is used repeatedly, memory is sufficient and first-request latency matters. Keep the model in an isolated worker rather than loading it into the API process.

ANGEVOICE_STARTUP_PRELOAD_ENABLED=true
ANGEVOICE_STARTUP_PRELOAD_MODEL=kokoro

When to keep a model resident

For continuous short requests, extend the idle timeout. Do not keep several speech and media models resident on the same memory-constrained GPU.

Full cleanup after idle unload

Some CUDA or ONNX environments retain low-level resources after a normal unload. Full cleanup exits the service process and relies on the container or service manager to restart it.

Quick choice