--- title: Servico de Extracao e Transcricao emoji: 📄 colorFrom: blue colorTo: indigo sdk: docker app_port: pinned: false --- ## Introdução API em FastAPI com dois endpoints: - `POST /extract-text` — recebe PDF, JPG ou PNG e devolve o texto contido (cru, sem tratamento). - `POST /transcribe` — recebe audio (ogg/opus do WhatsApp, mp3, m4a, wav...) e devolve a transcricao em PT-BR. A inferencia fica isolada atras de uma interface, entao rodar local hoje e na nuvem depois e questao de deploy e configuracao, nao de reescrita. ## Estrutura app/ main.py # monta o FastAPI, carrega os modelos no boot config.py # configuracao por env (flags das decisoes adiadas) api/ deps.py # injecao de dependencia routes_text.py # /extract-text routes_audio.py # /transcribe domain/ transcriber.py # interface Transcriber (o contrato) extractor.py # interface TextExtractor (o contrato) infra/ factory.py # escolhe a implementacao pela config local_transcriber.py # faster-whisper (hoje) local_extractor.py # Tesseract + PyMuPDF (hoje) services/ files.py # upload -> arquivo temporario, limpeza detect.py # tipo do arquivo por magic bytes audio_utils.py # ffmpeg: normaliza audio -> wav 16k mono pdf_utils.py # camada de texto vs. OCR, pagina a pagina ocr.py # Tesseract ## Rodando local Pre-requisitos de sistema: `ffmpeg` e `tesseract-ocr` com o idioma portugues (`tesseract-ocr-por`). # Ubuntu/Debian sudo apt install ffmpeg tesseract-ocr tesseract-ocr-por python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt cp .env.example .env uvicorn app.main:app --reload Testando: curl -F "file=@documento.pdf" http://localhost:8000/extract-text curl -F "file=@audio.opus" http://localhost:8000/transcribe Docs interativas em `http://localhost:8000/docs`. ## Docker docker build -t extracao-transcricao . docker run -p 8000:8000 extracao-transcricao ## As duas decisoes que ficaram para depois Nenhuma exige tocar nas rotas ou na logica de upload. **Self-managed vs. gerenciado** — campo `APP_ASR_BACKEND` / `APP_OCR_BACKEND`. Hoje e `local`. Para migrar, escreva uma classe adaptadora nova em `infra/` que implemente o mesmo metodo (`transcribe` ou `extract`), registre-a na `factory.py` e troque a env var. **GPU vs. CPU** — campo `APP_DEVICE` (`cpu` ou `cuda`). Em GPU, ajuste tambem `APP_ASR_COMPUTE_TYPE` para `float16`. O codigo e o mesmo; muda so a config e o alvo de deploy. ## Notas para producao - **Pesos do modelo:** evite baixar do HF Hub em runtime. Descomente a linha de pre-download no `Dockerfile` para embuti-los na imagem (cold start menor, sem chamada de saida). - **Perfis de compute distintos:** o OCR e leve (CPU) e a transcricao e pesada (pode querer GPU). Da para separar os dois em deployments independentes e escalar cada um sozinho. - **Carga:** para volume alto ou arquivos grandes, processe a inferencia em fila/worker em vez de inline na requisicao. - **Pinagem:** troque os `>=` do `requirements.txt` por versoes exatas quando fechar o ambiente. - **Manter o pipeline `transformers` atual:** crie um adaptador com o mesmo metodo e aponte a factory para ele.