Inferência

O Fish Audio disponibiliza dois modelos: S2-Pro e Drama 3. Ambos partilham a mesma linha de comandos e o mesmo servidor API, e o tipo de modelo é lido do config.json do diretório de pesos, pelo que cada secção abaixo está organizada como "tarefa → comando de cada modelo".

Conclua primeiro a Instalação e descarregue os pesos do modelo.

Limites de execução do Drama 3

O Drama 3 só funciona em GPUs NVIDIA: CPU, Apple MPS e AMD ROCm não são suportados, tal como --compile. Veja os Requisitos para a memória GPU.

Note

A V100 e outras GPUs anteriores a SM80 não têm bfloat16, pelo que o Drama 3 passa a float16 (mantendo o fluxo residual em fp32). Este caminho ainda não foi testado em hardware real; se obtiver silêncio, ruído ou um erro "non-finite logits", abra uma issue.

Inferência por Linha de Comando

S2-Pro

O S2-Pro usa um pipeline de três passos: "tokens VQ → tokens Semânticos → áudio".

Note

Se quer deixar o modelo escolher aleatoriamente o timbre, pode saltar o passo 1.

1. Obter tokens VQ do áudio de referência

python fish_speech/models/dac/inference.py \
    -i "test.wav" \
    --checkpoint-path "checkpoints/s2-pro/codec.pth"

Deverá obter um fake.npy e um fake.wav.

2. Gerar tokens Semânticos a partir do texto:

python fish_speech/models/text2semantic/inference.py \
    --text "O texto que quer converter" \
    --prompt-text "O seu texto de referência" \
    --prompt-tokens "fake.npy" \
    # --compile

Este comando cria um ficheiro codes_N no diretório de trabalho, onde N é um inteiro a partir de 0.

Note

Pode querer usar --compile para fundir kernels CUDA e acelerar a inferência. No entanto, recomendamos a nossa otimização de aceleração de inferência sglang. Se não planeia usar aceleração, comente o parâmetro --compile.

Info

Em GPUs sem suporte a bf16, pode precisar do parâmetro --half.

3. Gerar voz a partir dos tokens semânticos:

python fish_speech/models/dac/inference.py \
    -i "codes_0.npy" \

Depois disso obterá um ficheiro fake.wav.

Drama 3

O Drama 3 faz tudo num comando; --output escreve diretamente o áudio descodificado:

python fish_speech/models/text2semantic/inference.py \
    --checkpoint-path checkpoints/drama-3 \
    --text "O texto que quer converter" \
    --prompt-audio "reference.wav" \
    --prompt-text "O seu texto de referência" \
    --output "output.wav" \
    --device cuda:0

Em GPUs mais antigas, indique vários dispositivos, por exemplo --device cuda:0,cuda:1,cuda:2,cuda:3; o último fica com o descodificador de áudio e o codec. Apenas --device cuda usa até às quatro primeiras GPUs visíveis.

Servidor API

Iniciar o S2-Pro

python tools/api_server.py \
    --listen 0.0.0.0:8080 \
    --llama-checkpoint-path checkpoints/s2-pro \
    --decoder-checkpoint-path checkpoints/s2-pro/codec.pth \
    --decoder-config-name modded_dac_vq

Iniciar o Drama 3

python tools/api_server.py \
    --listen 0.0.0.0:8080 \
    --llama-checkpoint-path checkpoints/drama-3 \
    --device cuda:0

Note

O Drama 3 não suporta --compile. Em GPUs mais antigas, liste vários dispositivos com --device; o último fica com o descodificador de áudio e o codec.

Opções de arranque partilhadas por ambos os modelos:

• --compile: ativa a otimização torch.compile (apenas S2-Pro)
• --half: usa o modo fp16
• --api-key: exige autenticação por bearer token
• --workers: define o número de processos de trabalho
• --max-text-length: limita o comprimento do texto de um pedido; 0 significa sem limite

Verificação de saúde:

curl -X GET http://127.0.0.1:8080/v1/health

A resposta {"status":"ok"} indica que o serviço está operacional.

Endpoints da API

Método	Caminho	Descrição
POST	/v1/tts	Texto para voz; o corpo do pedido é msgpack
GET	/v1/tts/defaults	Valores de amostragem predefinidos do modelo carregado
GET	/v1/health	Verificação de saúde
POST	/v1/vqgan/encode	Áudio de referência → tokens VQ
POST	/v1/vqgan/decode	Tokens VQ → áudio
POST	/v1/references/add	Guarda uma voz de referência; campos id, audio (ficheiro), text
GET	/v1/references/list	Lista as vozes guardadas
POST	/v1/references/update	Renomeia; campos old_reference_id, new_reference_id
DELETE	/v1/references/delete	Remove; campo reference_id
GET	/ui	WebUI (incluída na imagem Docker; tem de ser construída em execução a partir do código)

Depois de guardar a voz, use-a com --reference_id (o campo de áudio precisa do tipo MIME, caso contrário o servidor não o reconhece):

curl -X POST http://127.0.0.1:8080/v1/references/add \
    -F id=my-speaker \
    -F "[email protected];type=audio/wav" \
    -F text="Transcrição do áudio de referência"

python tools/api_client.py --url http://127.0.0.1:8080/v1/tts \
    --text "Hello" --reference_id my-speaker --output demo

Enviar um pedido

O modelo usado depende dos pesos carregados pelo servidor no arranque; não há campo de modelo no pedido.

python tools/api_client.py \
    --url http://127.0.0.1:8080/v1/tts \
    --text "Hello from Fish Speech" \
    --output demo

Parâmetros mais usados:

Parâmetro	Descrição
--reference_audio / --reference_text	Áudio de referência e a respetiva transcrição; ambos precisam do mesmo número de valores
--reference_speaker	ID do falante (0–15) de cada áudio de referência, escrito como prefixo <|speaker:N|> (o uso principal no Drama 3)
--reference_id	Usa uma voz de referência guardada, por exemplo my-speaker
--format	Formato de saída: wav, pcm, mp3 ou opus; predefinição wav
--streaming	Devolve o áudio em fluxo
--single_chunk	Gera o texto todo de uma vez, sem dividir em blocos (apenas Drama 3)
--chunk_length	Comprimento do bloco, 200 por predefinição (apenas S2-Pro)
--max_new_tokens	Máximo de frames por bloco; se vazio usa a predefinição do servidor, 1024; 0 usa o limite do próprio modelo
--temperature / --top_p	Amostragem; se vazio usa as predefinições do modelo (0.7 / 0.7)
--seed	Fixa a semente aleatória (não serve para fixar o timbre)
--api_key	Obrigatório quando o servidor usa --api-key
--no-play	Não reproduz o áudio no final (por predefinição reproduz; necessário em máquinas sem dispositivo de áudio)

Note

repetition_penalty existe apenas por compatibilidade; o S2-Pro e o Drama 3 ignoram-no e usam amostragem com perceção de repetição incorporada.

Tip

Para iniciar o servidor com Docker, veja Configuração do Docker (a imagem do servidor já inclui a WebUI: abra http://localhost:8080/ui depois de arrancar).

Diferenças entre modelos

Item	S2-Pro	Drama 3
Hardware	GPU / CPU	apenas NVIDIA GPU, sem --compile
Texto longo	Dividido por chunk_length	Dividido automaticamente em blocos de cerca de 300 bytes (UTF-8) com no máximo três falantes, cortando nos fins de frase sempre que possível; o primeiro bloco e o mais recente são reenviados como contexto
Limite por passagem	1024 frames por lote por padrão; max_new_tokens=0 gera até o comprimento do contexto	1024 frames (cerca de 47 segundos) por bloco por padrão, o que com single_chunk vale para o texto inteiro; max_new_tokens=0 significa 600 frames por bloco, ou 2048 (cerca de 95 segundos) com single_chunk; sempre limitado a 10.240 frames menos o comprimento do prompt
Falantes	A ordem das referências define o papel	As etiquetas <|speaker:0|>–<|speaker:15|> definem o papel; a ordem das referências não importa
chunk_length	Tem efeito	Não tem efeito
Amostragem predefinida	temperature 0.7, top-p 0.7, top-k 30	Igual
repetition_penalty	Ignorado	Ignorado

O Drama 3 tem ainda duas variáveis de ambiente: FISH_DRAMA3_FP8_EXPERTS=0 ou 1 força especialistas desquantizados ou em FP8, e FISH_DRAMA3_CUDA_GRAPH=0 desativa a descodificação com CUDA graphs.

Inferência WebUI

Awesome WebUI

A Awesome WebUI é uma interface Web moderna construída com TypeScript, com funcionalidades mais ricas e melhor experiência de utilização.

As imagens Docker do servidor já incluem a WebUI construída: abra http://localhost:8080/ui depois de o contentor arrancar. Os passos abaixo aplicam-se a execução a partir do código.

Construir a WebUI:

Precisa de ter Node.js e npm instalados na sua máquina ou servidor.

1. Entre no diretório awesome_webui:

   cd awesome_webui
   

2. Instale as dependências:

   npm install
   

3. Construa a WebUI:

   npm run build
   

Iniciar o servidor backend:

Depois de construir a WebUI, volte à raiz do projeto e inicie o servidor API (--compile é apenas para o S2-Pro; remova-o ao carregar o Drama 3):

python tools/api_server.py --listen 0.0.0.0:8888 --compile

Acesso:

Com o servidor a correr, aceda pelo browser a: http://localhost:8888/ui