Tutoriais de VPS
Whisper em uma VPS: Speaches, transcrição em lote e legendas
Compare openai-whisper, faster-whisper e whisper.cpp, dimensione CPU/GPU e publique uma API privada com Speaches. O guia inclui transcrição em lote, legendas SRT, preparação com ffmpeg, integração ao Open WebUI e casos de áudio em chinês, com limites e configurações atuais.

O Whisper transforma gravações de reuniões, entrevistas e vídeos em texto usando a infraestrutura que você escolhe. Um serviço próprio permite enviar arquivos em lote e integrar a transcrição a outros sistemas. Ainda há custos de servidor, armazenamento, tráfego e manutenção; o áudio também continua sujeito ao acesso dos administradores e do provedor que hospeda a máquina.
Este guia compara os três principais projetos, explica a escolha do modelo e mostra como usar o Speaches para transcrever arquivos e gerar legendas. Os exemplos de reconhecimento em chinês continuam identificados como casos desse idioma. Para português, teste o modelo com gravações representativas do seu sotaque, vocabulário e ambiente.
| Projeto | Base | O que considerar |
|---|---|---|
| openai-whisper | Python, implementação de referência | Útil para compatibilidade com o projeto original; CPU, GPU e marcações de tempo dependem das opções |
| faster-whisper | Python e CTranslate2 | Inferência eficiente, quantização para CPU/GPU e marcações por palavra opcionais |
| whisper.cpp | C/C++ | Pode atender CPU, ARM, Apple e outros backends; aceleração e quantização dependem da compilação |
Os números de aproximadamente 4× de aceleração, RTF de 0.136 e WER de 3.12% contra 26.92% só fazem sentido junto com o áudio, hardware, modelo e parâmetros da respectiva medição. Sem uma comparação verificada nas mesmas condições, eles não estabelecem uma classificação universal. Quantizar o whisper.cpp não implica necessariamente aquela taxa de erro, e o openai-whisper continua sendo uma opção válida.
- Em um servidor NVIDIA, compare o faster-whisper com versões compatíveis de CUDA e cuDNN.
- Em CPU, ARM ou computador local, compare whisper.cpp e faster-whisper com configurações adequadas ao hardware.
- Quando a compatibilidade com a implementação de referência for importante, considere o openai-whisper.
O faster-whisper sozinho não separa automaticamente os participantes de uma reunião. O WhisperX pode acrescentar alinhamento e diarização com outros modelos, sujeitos aos requisitos e permissões desses componentes. A disponibilidade de marcações de tempo também depende das opções e do backend.
| Modelo | Download aproximado de referência | VRAM indicativa | Uso para comparação |
|---|---|---|---|
| tiny | ~75 MB | <1 GB | Testes rápidos, com precisão possivelmente limitada |
| base | ~150 MB | ~1 GB | Áudio simples quando a qualidade medida for suficiente |
| small | ~500 MB | ~2 GB | Um bom candidato para o primeiro teste |
| medium | ~1.5 GB | ~5 GB | Mais capacidade para áudio difícil |
| large-v3 | ~3 GB | ~6 GB | Candidato para maior qualidade, com mais recursos |
Esses valores são estimativas. Arquivos convertidos, quantização, tamanho do lote e duração do contexto alteram o consumo. Para português, espanhol ou chinês, escolha um modelo multilíngue apropriado; um modelo exclusivo de inglês não atende esses idiomas.
- Em áudio chinês, medium é um ponto inicial útil para comparar pontuação e termos especializados.
- Em inglês claro, small ou base podem ser suficientes depois de um teste.
- Para legendas que serão publicadas, compare large-v3 e faça revisão humana: nenhum tamanho garante uma legenda correta.
- Em lotes grandes, uma primeira passagem com small pode identificar os trechos que merecem uma segunda transcrição com um modelo maior.
Mantenha o cache persistente. Alternar entre modelos já baixados pode reutilizar os arquivos, mas versões ou artefatos ausentes ainda precisam de download. Uma coleção com cerca de 6 GB é apenas uma referência; some o tamanho dos modelos que você realmente pretende manter.
Como referência de planejamento, small em uma CPU moderna de 4 núcleos pode levar cerca de 20–60 minutos para uma hora de áudio, equivalente a 1–3× o tempo real. Uma GPU da classe GTX 1660 pode atingir 3–6 minutos, ou 10–20×, em determinadas condições. A diferença de 5–10× entre CPU e GPU também depende da carga; esses números não são resultados garantidos de uma VPS.
| Trabalho | Configuração inicial para testar |
|---|---|
| Arquivos curtos e ocasionais | Cerca de 2 núcleos, 4 GB de RAM e small em CPU |
| Gravações longas e lotes frequentes | GPU compatível, cerca de 6 GB ou mais de VRAM; valide o modelo maior |
| Transcrição em tempo real | Orçamento de aproximadamente 8 GB ou mais de VRAM e uma cadeia de streaming testada |
A decodificação também usa RAM do sistema. Considere 4 GB para um teste CPU com small e 8 GB ou mais quando houver concorrência. Veja as orientações de escolha de GPU. Como ponto de partida para cache, 5 GB para small/medium e 15 GB para uma coleção maior podem ajudar, mas o disco também precisa comportar sistema operacional, camadas Docker, áudio e resultados.
O Speaches, anteriormente conhecido como faster-whisper-server, oferece uma API compatível com parte da API de áudio da OpenAI. Verifique as funções, os formatos e os nomes de modelos da versão instalada. A compatibilidade da transcrição não garante que qualquer recurso de áudio ou tempo real de um aplicativo funcione sem ajustes.
Exemplo CPU de docker-compose.yml; substitua a configuração antiga de TTL antes de iniciar:
services:
speaches:
image: ghcr.io/speaches-ai/speaches:latest-cpu
container_name: speaches
restart: unless-stopped
ports:
- "127.0.0.1:8969:8000"
environment:
- API_KEY=换成一串长随机字符
- PRELOAD_MODELS=["Systran/faster-whisper-small"]
- WHISPER__TTL=-1
volumes:
- ./hf-cache:/home/ubuntu/.cache/huggingface/hub
Para NVIDIA, incorpore esta variante na mesma definição do serviço:
image: ghcr.io/speaches-ai/speaches:latest-cuda
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
Crie o diretório do projeto, escolha uma tag ou digest mantido e compatível e confira o usuário e o caminho efetivo do cache montado. Os passos do driver e toolkit NVIDIA também se aplicam aqui, mas teste o runtime usado pelo aplicativo: outra imagem CUDA funcionar não prova que essa combinação seja compatível.
Defina uma chave privada em API_KEY e teste uma chamada a /v1 com Authorization: Bearer 你的密钥. Na configuração atual, /health, /docs, /openapi.json e a interface Gradio são exceções à autenticação da API. Se você precisa apenas da API, configure ENABLE_UI=false e mantenha todo o serviço dentro da rede privada ou do túnel. Não exponha diretamente a porta 8969; acesso remoto precisa de uma fronteira de acesso adequada, como VPN ou proxy HTTPS autenticado.
PRELOAD_MODELS baixa os modelos configurados durante a inicialização. Isso não garante que a inferência já esteja aquecida: a primeira transcrição ainda pode carregar o modelo em memória. O nome WHISPER__TTL=-1 pertence a uma configuração antiga; a configuração oficial atual usa STT_MODEL_TTL=-1 para manter os modelos de transcrição residentes. Troque essa linha no exemplo antes de subir o serviço. Se a memória for limitada, use um TTL finito admitido pela versão instalada.
O volume de cache evita downloads desnecessários a cada recriação. Depois de ajustar a configuração:
docker compose up -d
docker compose logs -f
A mensagem Application startup complete confirma a inicialização da aplicação, não uma transcrição bem-sucedida. Aguarde os downloads, transcreva uma gravação que você esteja autorizado a processar e confira o texto antes de enviar uma fila inteira.
Execute o exemplo no próprio servidor ou através de um túnel que encaminhe a porta:
curl -s http://127.0.0.1:8969/v1/audio/transcriptions \
-H "Authorization: Bearer 你的API_KEY" \
-F "[email protected]" \
-F "model=Systran/faster-whisper-small" \
-F "language=zh"
O parâmetro language=zh seleciona chinês neste exemplo. Para outro material, use o idioma real ou a detecção admitida pelo servidor. Informar um idioma conhecido pode ajudar, mas não garante precisão. Substitua os textos de exemplo das chaves pela sua chave privada.
Para processar um diretório, o exemplo usa Python, requests e a pasta audios:
import os, requests
API = "http://127.0.0.1:8969/v1/audio/transcriptions"
KEY = "你的API_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}"}
for name in os.listdir("audios"):
if not name.endswith((".mp3", ".wav", ".m4a", ".flac")):
continue
with open(f"audios/{name}", "rb") as f:
r = requests.post(
API,
headers=HEADERS,
files={"file": f},
data={
"model": "Systran/faster-whisper-small",
"language": "zh",
"response_format": "srt",
},
timeout=3600,
)
out = os.path.splitext(name)[0] + ".srt"
with open(out, "w", encoding="utf-8") as f:
f.write(r.text)
print("完成:", out)
Antes de usar o lote em produção, acrescente r.raise_for_status() logo depois da requisição e antes de abrir o arquivo de saída. Assim, um erro JSON não vira um arquivo SRT. Proteja a chave, evite que arquivos de mesmo nome sobrescrevam resultados e registre os trabalhos concluídos para retomar uma execução interrompida. O timeout de 3600 segundos é um ponto inicial; gravações longas e proxies podem exigir outros limites e tentativas controladas.
O response_format pode selecionar json, text, srt, vtt ou verbose_json, conforme a API e o modelo instalados. Use srt para obter legendas diretamente quando esse formato for suportado, e revise o texto e as marcações de tempo.
Separar o áudio do vídeo reduz o material enviado ao serviço:
ffmpeg -i video.mp4 -vn -ac 1 -ar 16000 -c:a libmp3lame -b:a 64k audio.mp3
-vn descarta o vídeo, -ac 1 mistura os canais em mono e -ar 16000 reamostra para 16 kHz. O Whisper trabalha com áudio a 16 kHz, mas a codificação MP3 com perdas ainda pode alterar o reconhecimento, e a mistura em mono elimina a separação entre canais. Para PCM mono sem perdas, use ffmpeg -i video.mp4 -vn -ac 1 -ar 16000 -c:a pcm_s16le audio.wav. Preserve canais separados quando forem necessários para distinguir participantes.
Um vídeo de 1 GB resultar em 20 MB de áudio é uma possibilidade dependente da duração e do codec, não uma taxa fixa de redução. Guarde o original. Depois de revisar o SRT em um player, você pode incorporá-lo ao vídeo com ffmpeg:
ffmpeg -i video.mp4 -vf subtitles=audio.srt -c:a copy output.mp4
O filtro recodifica o vídeo. Confira sincronização, fontes, caracteres e tamanho do resultado; não substitua o original antes dessa revisão.
Em uma instalação existente de Open WebUI, configure o mecanismo de transcrição compatível:
AUDIO_STT_ENGINE=openai
AUDIO_STT_OPENAI_API_BASE_URL=http://speaches:8000/v1
AUDIO_STT_OPENAI_API_KEY=你的API_KEY
AUDIO_STT_MODEL=Systran/faster-whisper-small
O API_BASE_URL precisa ser acessível pelo componente que envia o áudio. Se os dois serviços compartilham a mesma rede Docker, use o nome do serviço Speaches e a porta 8000. Dentro de outro contêiner, 127.0.0.1:8969 aponta para o loopback daquele contêiner, não para o servidor anfitrião. Confira os nomes das opções na versão instalada e confirme, com uma gravação de teste, que o áudio vai ao endpoint escolhido.
O mesmo princípio atende outros aplicativos que aceitem um endpoint personalizado, desde que você verifique os recursos realmente utilizados por eles.
O Whisper pode misturar caracteres tradicionais e simplificados. O OpenCC permite normalizar a saída:
pip install opencc-python-reimplemented
# 代码里用 OpenCC('t2s').convert(text) 转简体
Escolha a conversão apropriada e mantenha também a transcrição original. Essa etapa não corrige palavras reconhecidas incorretamente nem garante a terminologia regional desejada.
Quando a API admite prompt, uma lista de termos pode orientar o contexto:
-F "prompt=本次会议讨论:Kubernetes、PostgreSQL、张伟、李娜"
O exemplo usa nomes e termos de uma reunião em chinês; forneça o vocabulário real das suas gravações. A orientação pode ajudar ou enviesar a saída e não garante nomes corretos. Revise a pontuação manualmente ou com pós-processamento controlado, sem esperar que um script recupere todo sinal omitido.
Música de fundo e falas simultâneas continuam difíceis. Separar participantes requer uma etapa de diarização compatível, por exemplo com WhisperX e seus modelos adicionais, eventualmente sujeitos a conta e licença. O Speaches usar faster-whisper não inclui essa separação automaticamente.
Se você transcreve poucos arquivos, compare a tarifa atual de uma API com o aluguel e o tempo de manutenção. Uma estimativa de centavos a pouco mais de um dólar por hora depende do serviço e modelo; consulte a cotação vigente. No computador local, aplicativos como MacWhisper e Buzz podem evitar a administração de servidor, respeitando os requisitos de hardware e os termos do software.
Um servidor faz mais sentido para acesso por vários dispositivos, lotes frequentes, integração a um fluxo automático ou processamento dentro de uma rede controlada. Para legendas ao vivo, é necessário testar o cliente e o caminho de streaming, a latência e a capacidade contínua da GPU. Um endpoint de transcrição compatível não estabelece sozinho uma solução em tempo real.
VAD pode pular silêncios e reduzir texto inventado nesses trechos, mas configurações agressivas também podem cortar fala baixa. Uma estimativa de 20–30% de silêncio é apenas ilustrativa. Teste as opções em gravações reais e preserve o áudio original.
O faster-whisper oferece opções de compute_type, sujeitas ao hardware e ao CTranslate2:
| Opção | Uso típico | Compromisso |
|---|---|---|
float16 | GPU compatível | Menor custo de memória/cálculo que precisão completa; desempenho variável |
int8_float16 | GPU admitida com pouca VRAM | Quantização reduz memória; precisão e suporte precisam de teste |
int8 | CPU compatível | Menor consumo de memória; compare a velocidade real |
int8_float16 pode ajudar um modelo maior a caber em aproximadamente 4 GB em algumas configurações, sem garantia geral. Na configuração atual do Speaches, a opção é WHISPER__COMPUTE_TYPE; WHISPER__COMPUTE_TYPE=int8 é um exemplo para CPU compatível.
Para gravações longas, ffmpeg pode dividir o material em partes. Três horas divididas em segmentos de aproximadamente 10 minutos são uma estratégia de processamento, não um requisito. Preserve contexto nas fronteiras e ajuste os tempos das legendas ao juntar os segmentos. Aumentar a concorrência pode esgotar RAM/VRAM ou apenas criar uma fila interna; meça um limite seguro em vez de usar automaticamente o número de núcleos.
Transcrever primeiro com small e repetir apenas os trechos fracos com um modelo maior pode economizar trabalho. O ganho depende da quantidade de retrabalho; não há multiplicador garantido.
Primeira requisição lenta: confira downloads, carregamento e PRELOAD_MODELS. O servidor iniciado ainda pode precisar preparar a inferência.
404 model not found: confira os identificadores com curl http://127.0.0.1:8969/v1/models -H "Authorization: Bearer 密钥". Esse endpoint lista modelos baixados; /v1/registry lista os modelos remotos admitidos na API atual. POST /v1/models/{模型名} faz o download de um modelo suportado. Como o identificador completo pode conter uma barra, siga o caminho admitido pelo esquema instalado e use autenticação; download concluído não prova que a GPU está pronta.
GPU não utilizada: verifique nvidia-smi, toolkit, runtime, dispositivo selecionado e precisão de cálculo. Enxergar a placa não demonstra que a transcrição esteja usando-a.
Palavras repetidas: investigue silêncio, música e identificação de idioma; teste VAD e o pré-processamento com ffmpeg. Compare modelos, mas não trate um modelo maior como solução para todos os casos.
Memória esgotada: substitua o antigo WHISPER__TTL=-1 pelo ajuste atual de STT_MODEL_TTL e revise modelos residentes, tamanho do lote e solicitações simultâneas.
Concorrência excessiva: use uma fila limitada, controle de taxa e timeouts testados no proxy e no cliente. Não deixe inferência paralela ilimitada disponível na internet.
Escolha implementação e modelo com uma amostra do seu áudio, suba um endpoint privado, confira o resultado e só então automatize. Preserve gravações e transcrições revisadas. O principal ganho é controlar o processamento e repetir um fluxo confiável de lotes, sem depender de promessas de custo ou precisão.