# How GPT-SoVITS Handles Version Compatibility Between v1, v2, v3, v4, v2Pro, and v2ProPlus Models

> Learn how GPT-SoVITS ensures version compatibility across v1, v2, v3, v4, v2Pro, and v2ProPlus models. Discover its robust mechanisms for seamless integration and performance.

- Repository: [RVC-Boss/GPT-SoVITS](https://github.com/RVC-Boss/GPT-SoVITS)
- Tags: internals
- Published: 2026-03-07

---

**GPT-SoVITS achieves seamless version compatibility through six coordinated mechanisms including centralized weight mapping in [`config.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/config.py), conditional configuration loading in [`webui.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/webui.py), runtime backend selection in [`inference_webui.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/inference_webui.py), and strict API validation in [`TTS_infer_pack/TTS.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/TTS_infer_pack/TTS.py).**

The RVC-Boss/GPT-SoVITS repository supports six distinct model architectures—v1, v2, v3, v4, v2Pro, and v2ProPlus—each with unique hyperparameters, vocoder requirements, and sampling rates. Understanding how the framework manages **GPT-SoVITS version compatibility** ensures you select the correct training configurations and inference pipelines for your specific checkpoint files.

## Centralized Version Configuration and Weight Mapping

The foundation of compatibility lies in explicit version-to-resource mapping that prevents cross-contamination of model artifacts.

### Version Registry in config.py

In [`config.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/config.py), the framework maintains **version-specific weight maps** that bind each version identifier to its corresponding pretrained SoVITS and GPT checkpoint files. This central registry also defines the directory structures where new checkpoints are saved during training, ensuring that v1, v2, v3, v4, v2Pro, and v2ProPlus artifacts remain organized and accessible.

### Conditional Configuration Loading in webui.py

When initiating training via [`webui.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/webui.py), the `open1Ba` function selects JSON configuration files based on the supplied version string. Standard versions (v1, v2, v3, v4) load from [`s2.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2.json), while specialized Pro variants require [`s2v2Pro.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2v2Pro.json) or [`s2v2ProPlus.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2v2ProPlus.json). This conditional loading guarantees that hyperparameters such as sample rate and vocoder type match the architectural requirements of the target version.

## Runtime Backend Selection and Model Initialization

Inference pipelines adapt dynamically to version-specific synthesis requirements through runtime flag inspection.

### Backend Selection in inference_webui.py

At inference time, [`inference_webui.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/inference_webui.py) inspects the `model_version` parameter to instantiate the correct synthesis backend. The framework supports three distinct vocoder implementations: **BigVGAN** for standard versions, **Hifigan** for specific legacy configurations, and the custom **SV-CN** model exclusively for Pro families (v2Pro and v2ProPlus).

### The v2pro_set Identifier in module/models.py

To streamline Pro-version detection throughout the codebase, [`module/models.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/module/models.py) defines a helper set:

```python
v2pro_set = {"v2Pro", "v2ProPlus"}

```

This constant is reused across multiple modules to test version membership without hardcoding strings, reducing error risk when implementing version-specific logic branches.

## Data Pipeline and Sampling Rate Adaptation

Training data preprocessing adjusts automatically based on version capabilities to prevent spectral mismatches.

### Dynamic Processing in module/data_utils.py

The `DataCollator` class in [`module/data_utils.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/module/data_utils.py) sets a boolean flag during initialization:

```python
self.is_v2Pro = version in {"v2Pro","v2ProPlus"}

```

Downstream components query this flag to apply **16 kHz-only processing** required by Pro models, while standard versions may utilize different spectrogram resampling strategies. This encapsulation prevents data pipeline mismatches that could degrade model performance.

## Checkpoint Integrity and API Validation

Robust safeguards prevent accidental mixing of incompatible model artifacts across different versions.

### Binary ID Mapping in process_ckpt.py

Legacy checkpoint compatibility is maintained through binary tags in [`process_ckpt.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/process_ckpt.py). The system maps specific byte sequences—`b"05"` for v2Pro and `b"06"` for v2ProPlus—to version strings within stored `.pth` files. This metadata allows the framework to identify checkpoint origins even when files are mixed in shared `logs/` directories.

### Strict Version Validation in TTS_infer_pack/TTS.py

The public inference API exposed in [`TTS_infer_pack/TTS.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/TTS_infer_pack/TTS.py) strictly validates the `version` parameter against the allowed list:

```python
["v1","v2","v3","v4","v2Pro","v2ProPlus"]

```

The constructor raises assertions if an unsupported version is supplied, preventing runtime errors from mismatched SoVITS and GPT checkpoint pairs.

## Practical Implementation Examples

### Configuring Training for Pro Versions

To initiate training with v2Pro or v2ProPlus architectures, specify the version parameter in the UI backend call:

```python

# webui.py entry point for training (open1Ba function)

open1Ba(
    version="v2Pro",          # Selects s2v2Pro.json automatically

    batch_size=4,
    total_epoch=2000,
    exp_name="my_pro_exp",
    text_low_lr_rate=0.1,
    if_save_latest=True,
    if_save_every_weights=False,
    save_every_epoch=10,
    gpu_numbers1Ba="0-1",
    pretrained_s2G="",
    pretrained_s2D="",
    if_grad_ckpt=False,
    lora_rank=0,
)

```

The function automatically resolves the correct configuration path based on the version string.

### Initializing Inference with Version Specification

When loading checkpoints for synthesis, explicitly declare the version to ensure proper backend initialization:

```python
from GPT_SoVITS.TTS_infer_pack.TTS import TTS

tts = TTS(
    sovits_path="GPT_SoVITS/pretrained_models/v2Pro/s2Gv2Pro.pth",
    gpt_path="GPT_SoVITS/pretrained_models/s1v3.ckpt",
    version="v2Pro",          # Mandatory for correct pipeline selection

    language="zh",
)

audio = tts.infer(
    text="你好，世界！",
    speed=1.0,
    top_k=5,
    top_p=0.7,
)

```

The `TTS` class validates the version parameter and wires the appropriate model paths and vocoder settings.

### Inspecting Data Pipeline Flags

Verify Pro-version detection within the data utilities:

```python
from GPT_SoVITS.module.data_utils import DataCollator

collator = DataCollator(version="v2ProPlus")
print(collator.is_v2Pro)   # Output: True

```

This flag drives conditional logic for spectrogram generation and audio resampling throughout the training loop.

## Summary

- **Centralized mapping** in [`config.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/config.py) maintains version-specific weight directories and pretrained model paths for all six supported architectures.
- **Conditional loading** in [`webui.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/webui.py) selects appropriate JSON configurations ([`s2.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2.json) vs. [`s2v2Pro.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2v2Pro.json)) based on the version parameter passed to training functions.
- **Runtime backend selection** in [`inference_webui.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/inference_webui.py) instantiates BigVGAN, Hifigan, or SV-CN vocoders according to version requirements.
- **Pro-version detection** relies on the `v2pro_set` constant in [`module/models.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/module/models.py) and the `is_v2Pro` flag in [`module/data_utils.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/module/data_utils.py) for specialized 16 kHz processing.
- **Checkpoint integrity** is preserved through binary ID tags (`b"05"`, `b"06"`) in [`process_ckpt.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/process_ckpt.py) and strict API validation in [`TTS_infer_pack/TTS.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/TTS_infer_pack/TTS.py).

## Frequently Asked Questions

### What distinguishes v2Pro and v2ProPlus from standard versions in GPT-SoVITS?

v2Pro and v2ProPlus utilize a custom **SV-CN** synthesis backend and require **16 kHz sampling rates**, whereas standard versions (v1, v2, v3, v4) typically employ BigVGAN or Hifigan vocoders with different spectral processing parameters. The framework detects these versions through the `v2pro_set` identifier and applies specialized data preprocessing accordingly.

### Can I interchange checkpoints between different GPT-SoVITS versions?

No. The `TTS` class in [`TTS_infer_pack/TTS.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/TTS_infer_pack/TTS.py) explicitly validates version strings and prevents mixing incompatible SoVITS and GPT checkpoints. Additionally, binary ID tags in [`process_ckpt.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/process_ckpt.py) ensure that checkpoint files carry embedded version metadata, allowing the system to detect mismatches even if file paths do not indicate version information.

### How does the system select the correct configuration file during training?

The `open1Ba` function in [`webui.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/webui.py) implements conditional logic that maps version strings to specific JSON configurations. Standard versions load [`s2.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2.json), while v2Pro loads [`s2v2Pro.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2v2Pro.json) and v2ProPlus loads [`s2v2ProPlus.json`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/s2v2ProPlus.json). This mechanism ensures that training hyperparameters align with the architectural requirements of the target model version.

### Where is the version compatibility logic centralized for maintenance?

While version detection logic is distributed across multiple files for performance, the **canonical version registry** resides in [`config.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/config.py), which defines the mapping between version identifiers and resource paths. The `v2pro_set` in [`module/models.py`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/module/models.py) serves as the single source of truth for Pro-version membership testing throughout the codebase.