Esegui Tesseract come API
o servizio self-hosted.

pip install fastapi uvicorn python-multipart pytesseract pillow
# installa prima il motore + i pacchetti lingua (vedi la guida all'installazione)
uvicorn app:app --host 0.0.0.0 --port 8000

Poi chiamalo: curl -F "file=@fattura.png" "http://localhost:8000/ocr?lang=ita". Tesseract si installa secondo la guida all'installazione.

Una sola intenzione principale per endpoint. Mantieni /ocr per il testo e aggiungi endpoint separati per PDF e dati di layout invece di sovraccaricare una risposta.

import asyncio, io
from concurrent.futures import ProcessPoolExecutor
from fastapi import FastAPI, File, UploadFile, HTTPException, Query
from PIL import Image
import pytesseract

app = FastAPI(title="Tesseract OCR API")
pool = ProcessPoolExecutor(max_workers=4)
MAX_BYTES = 10 * 1024 * 1024  # 10 MB
LANGS = {"eng", "deu", "fra", "ita"}

def _ocr(data: bytes, lang: str) -> str:
    image = Image.open(io.BytesIO(data))
    return pytesseract.image_to_string(image, lang=lang)

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/ocr")
async def ocr(file: UploadFile = File(...), lang: str = Query("ita")):
    if lang not in LANGS:
        raise HTTPException(400, "Lingua non supportata")
    data = await file.read()
    if len(data) > MAX_BYTES:
        raise HTTPException(413, "File troppo grande")
    loop = asyncio.get_running_loop()
    try:
        text = await asyncio.wait_for(loop.run_in_executor(pool, _ocr, data, lang), timeout=30)
    except asyncio.TimeoutError:
        raise HTTPException(504, "Timeout OCR")
    return {"text": text, "lang": lang}

Dettagli chiave: lista bianca delle lingue, applica un limite di byte prima di decodificare, esegui l'OCR in un pool di processi e limita il tempo reale. Vedi la guida Python per l'API pytesseract completa.

FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      tesseract-ocr tesseract-ocr-eng tesseract-ocr-ita \
      libgl1 libglib2.0-0 && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 8000
HEALTHCHECK CMD python -c "import urllib.request;urllib.request.urlopen('http://localhost:8000/health')"
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

Aggiungi solo i pacchetti lingua necessari per mantenere l'immagine piccola. La guida all'installazione copre Docker e la posizione di tessdata in maggiore dettaglio.

• Pool di processi o sottoprocessi della CLI: il GIL di Python impedisce a un pool di thread di accelerare l'OCR. Usa ProcessPoolExecutor o un pool di sottoprocessi tesseract.
• Worker vs repliche: esegui alcuni worker uvicorn per container e scala le repliche orizzontalmente dietro un load balancer.
• Code: per picchi o documenti lunghi, accetta l'upload, restituisci un ID job e processa da una coda (Celery, RQ o un broker).
• Backpressure: limita la coda e rifiuta con 429 quando è satura invece di lasciare che la latenza esploda.
• Limiti di risorse: fissa CPU/memoria per worker e imposta un timeout OCR così un'immagine scadente non blocca una replica.

• Nessuna uscita di dati: le immagini restano nella tua rete — importante per documenti legali, medici e finanziari.
• Valida l'input: controlla il tipo MIME e i magic byte, non solo l'estensione; decodifica in try/except.
• Limita le risorse: dimensione massima di upload, timeout per richiesta e un tetto di memoria contro le bombe di decompressione.
• Autentica: metti una chiave API o un gateway davanti; gli endpoint OCR sono costosi da abusare.
• Rimuovi i metadati: se conservi i file, rimuovi l'EXIF ed elimina gli originali periodicamente.

• Runtime di container: Cloud Run, immagini di container AWS Lambda e Fly.io eseguono un'immagine Tesseract senza gestire server.
• Avvii a freddo: un'immagine Tesseract con pacchetti lingua è grande, quindi gli avvii a freddo sono lenti — mantieni un'istanza calda per il traffico sensibile alla latenza.
• Limiti: aumenta memoria e timeout; un piccolo timeout predefinito ucciderà i documenti grandi.
• Disco effimero: scrivi file temporanei solo in /tmp; considera il filesystem usa e getta.

Molti team self-hostano Tesseract per lavori ad alto volume e sensibili alla privacy e ricorrono a un'API gestita solo per la minoranza difficile di documenti.