sampaiodev.
PTEN
API de transcrição CPUOpen-source

transcricao

Uma API FastAPI para upload de áudio/vídeo, transcrição com faster-whisper e deploy em Docker Compose com rótulos Traefik.

FastAPIfaster-whisperCTranslate2DockerTraefik

Leitura técnica

Leitura rápida do case

Problema

Nem todo pipeline precisa de stack grande. Para VPS simples, o desafio é carregar modelo uma vez, limitar arquivo, expor healthcheck e manter deploy previsível.

Solução

A API inicializa o modelo no startup, recebe arquivo via `/transcribe`, usa `int8` em CPU por padrão e expõe `/health` com modelo, device e compute type.

Stack

FastAPI · faster-whisper · CTranslate2 · Docker

Status

Open-source

Arquitetura

Menos serviços, caminho direto para transcrição

Projeto deliberadamente enxuto: request entra, engine local processa e a API responde. O foco é CPU-only e deploy simples.

Fluxo técnico

  • Entrada
  • Processamento
  • Persistência
  • Saída
Fluxograma
Renderizando fluxograma…

Fluxo em etapas

01Entrada
Audio/videoArquivo enviado para transcricao
02API
FastAPIEndpoint /transcribe, upload e validacao
03Runtime
Modelo carregadoModelo inicializado no startup
04Processamento
faster-whisper/CTranslate2Transcricao CPU-only/int8
05Saida
JSON/transcricaoTexto e segmentos retornados pela API
06Operacao
Docker/Traefik/PortainerEmpacotamento e roteamento de deploy
Código do diagrama (Mermaid)
Cole em qualquer renderizador Mermaid
flowchart LR
  file["Audio/video"]
  api["FastAPI"]
  model["Modelo carregado"]
  engine["faster-whisper/CTranslate2"]
  json["JSON/transcricao"]
  deploy["Docker/Traefik/Portainer"]
  file --> api
  api --> model
  model --> engine
  engine --> json
  json --> deploy
1. Audio/video (Entrada) → FastAPI. 2. FastAPI (API) → Modelo carregado. 3. Modelo carregado (Runtime) → faster-whisper/CTranslate2. 4. faster-whisper/CTranslate2 (Processamento) → JSON/transcricao. 5. JSON/transcricao (Saida) → Docker/Traefik/Portainer. 6. Docker/Traefik/Portainer (Operacao).

Stack e responsabilidades

  • FastAPI

    Recebe upload, valida parâmetros e responde a transcrição.

  • faster-whisper

    Engine de transcrição local.

  • CTranslate2

    Execução otimizada em CPU.

  • Docker Compose

    Deploy local/Portainer com variáveis de ambiente.

  • Traefik

    Rótulos de roteamento em ambiente Swarm/Portainer.

Decisões técnicas

  • CPU-first

    Configuração padrão usa device CPU e compute type int8 para VPS simples.

  • Modelo carregado uma vez

    Evita custo de inicialização em cada request.

Operação

  • documentadoHealthcheck

    `/health` retorna status, modelo, device e compute type.

  • documentadoVariáveis de ambiente

    PORT, WHISPER_MODEL, idioma, limite de arquivo, CPU threads.

  • não públicoPersistência

    README não documenta banco; a resposta é direta via API.

Status e próximos passos

  • Adicionar fila se o uso exigir concorrência controlada.
  • Documentar limites por tamanho/duração de arquivo em produção.

Contato

Quer algo parecido para seu processo?

Se existe uma entrada repetida, uma etapa manual e uma saída esperada, provavelmente dá para desenhar um sistema.

Falar sobre um projeto