I playground web sono ottimi per le demo. Incolli un blocco di testo, guardi il modello generare un riassunto ordinato e chiudi la scheda. Ma questo non è ingegneria. Il lavoro in produzione significa API, gestione degli errori e codice che gira mentre dormi. Se hai bisogno di elaborare trascrizioni di riunioni, ticket di supporto o documenti di ricerca seguendo un programma prestabilito, hai bisogno di una pipeline.

Questa guida ti accompagnerà nella creazione di proprio ciò: uno script leggero e automatizzato per la sintesi di documenti utilizzando Python, l'AWS SDK per Python (boto3) e Amazon Bedrock. Useremo Claude 3 Haiku di Anthropic, un modello che rappresenta il perfetto equilibrio tra velocità e costi per i compiti di sintesi del testo.

Perché Bedrock e Claude 3 Haiku?

Amazon Bedrock è un servizio gestito che espone modelli di base attraverso un unico set di API AWS. Invece di dover assemblare endpoint esterni e lottare con modelli di fatturazione e sicurezza separati, chiami un endpoint AWS con i normali controlli IAM. I tuoi dati rimangono all'interno del tuo ambiente AWS.

Claude 3 Haiku è il modello più snello della famiglia Claude 3 di Anthropic. È progettato per la reattività e i bassi costi, il che lo rende ideale per sintesi ad alto volume in cui si desidera un output prevedibile senza pagare per la potenza di calcolo di modelli più grandi per compiti di lettura semplici.

Cosa ti serve

Prima di scrivere qualsiasi codice, assicurati di avere pronto quanto segue:

  • Un account AWS attivo.
  • Python 3.9 o versioni successive installato localmente.
  • L'AWS CLI configurata con credenziali che abbiano il permesso di invocare i modelli Bedrock. Se non hai ancora eseguito aws configure, fallo ora. Se riscontri errori di autorizzazione in seguito, probabilmente dovrai associare i permessi di invocazione Bedrock appropriati al tuo utente o ruolo IAM.
  • Accesso ai modelli abilitato specificamente per Anthropic Claude 3 Haiku all'interno della console AWS Bedrock. AWS richiede che tu accetti esplicitamente ogni fornitore di modelli prima di poterlo chiamare.

Passaggio 1: Abilitare l'accesso ai modelli

Bedrock non ti permette di chiamare i modelli immediatamente. Devi prima attivare l'opzione nella console.

  1. Accedi alla console di gestione AWS.
  2. Usa la barra di ricerca per trovare Amazon Bedrock.
  3. Nel pannello di navigazione a sinistra, seleziona Model access.
  4. Clicca su Modify model access.
  5. Seleziona la casella per Anthropic (Claude 3 Haiku) e invia la richiesta.

Una volta che lo stato passa a "Access granted", puoi chiamare il modello tramite codice.

Passaggio 2: Configurare l'ambiente

Un ambiente Python pulito mantiene le dipendenze isolate e riproducibili. Apri il terminale ed esegui questi comandi:

mkdir bedrock-summarizer && cd bedrock-summarizer
python3 -m venv venv
source venv/bin/activate
pip install boto3

Gli utenti Windows dovrebbero sostituire il comando di attivazione con venv\Scripts\activate. Dopo il completamento di pip install boto3, avrai tutto ciò di cui hai bisogno per comunicare con le API AWS.

Passaggio 3: Scrivere lo script

Crea un file chiamato summarize.py. L'obiettivo è leggere un documento dal disco, passarlo alle API Converse di Bedrock e stampare una sintesi concisa.

Di seguito trovi un'implementazione completa e funzionante. Utilizziamo l'API Converse perché astrae la formattazione JSON grezza che i diversi fornitori di modelli si aspettano. Devi solo passare una lista di messaggi e le impostazioni di inferenza.

import boto3

def summarize_document(text: str) -> str:
    client = boto3.client("bedrock-runtime")
    
    model_id = "anthropic.claude-3-haiku-20240307-v1:0"
    
    messages = [
        {
            "role": "user",
            "content": [
                {
                    "text": (
                        "Provide a concise summary of the following document. "
                        "Focus on the main points and avoid unnecessary detail:\n\n"
                        f"{text}"
                    )
                }
            ]
        }
    ]
    
    response = client.converse(
        modelId=model_id,
        messages=messages,
        inferenceConfig={
            "temperature": 0.3,
            "maxTokens": 512
        }
    )
    
    summary = response["output"]["message"]["content"][0]["text"]
    return summary.strip()


if __name__ == "__main__":
    with open("document.txt", "r", encoding="utf-8") as f:
        document_text = f.read()
    
    result = summarize_document(document_text)
    print("\n--- Summary ---\n")
    print(result)

Alcuni dettagli pratici che vale la pena sottolineare:

  • boto3.client("bedrock-runtime") punta all'endpoint di runtime che gestisce l'inferenza. Assicurati che la tua regione AWS in ~/.aws/config supporti Bedrock e che tu abbia abilitato Haiku in quella stessa regione.
  • Model ID anthropic.claude-3-haiku-20240307-v1:0 è l'identificatore esatto che Bedrock si aspetta. Copialo esattamente.
  • Temperatura impostata a 0.3 mantiene l'output concreto. Per la sintesi, desideri coerenza e fedeltà al testo sorgente, non abbellimenti creativi. Se aumenti la temperatura verso 1.0, il modello inizia a prendere libertà con la formulazione e occasionalmente inventa dettagli.
  • Il prompt stesso è specifico. Invece di lanciare del testo grezzo al modello con un vago "riassumi questo", chiediamo esplicitamente i punti principali e gli istruiamo a saltare i fronzoli. Questo tipo di chiarezza separa un output inutilizzabile da qualcosa che puoi effettivamente distribuire.

Inserisci qualsiasi file di testo che desideri riassumere nella stessa directory e nominalo document.txt.

Passaggio 4: Eseguirlo

Con l'ambiente virtuale attivo, esegui:

python summarize.py

Se le tue credenziali e l'accesso al modello sono corretti, dovresti vedere una sintesi ordinata stampata nel terminale entro pochi secondi. Se ricevi un errore di accesso, ricontrolla i tuoi permessi IAM e conferma di aver abilitato Claude 3 Haiku nella console.

Andare oltre lo script

Questa pipeline è intenzionalmente semplice, ma rappresenta la base per una vera automazione. Ecco come puoi estenderla senza aggiungere complessità inutile.

Elaborazione batch. Sostituisci la lettura di un singolo file con un ciclo su una directory. Inserisci cinquanta PDF o file di testo in una cartella di input, iteraci attraverso e scrivi i riassunti in una cartella di output. Se desideri elaborare direttamente i PDF, avrai bisogno di una fase di pre-elaborazione con una libreria come PyPDF2 o pdfplumber per estrarre il testo grezzo prima che venga inviato a Bedrock.

Strategia di chunking. Documenti molto lunghi potrebbero superare il limite di contesto del modello. Quando ciò accade, dividi il testo in chunk logici per paragrafo o sezione, riassumi ogni chunk individualmente e poi passa i riassunti intermedi nuovamente al modello per una sintesi finale. Questo approccio in due fasi ti permette di rimanere entro i limiti dei token preservando al contempo la copertura dell'intero documento.

Gestione degli errori. Il codice di produzione dovrebbe gestire specificamente boto3.exceptions.ClientError. AWS potrebbe limitare le tue richieste (throttling) se chiami l'API in modo troppo aggressivo. Avvolgi la tua chiamata converse in un ciclo di retry con exponential backoff, oppure usa una libreria come tenacity per gestire i limiti di frequenza (rate limits) in modo fluido.

Prompt engineering. La differenza tra un riassunto mediocre e uno utile spesso dipende dal prompt. Richiedi un elenco puntato se hai bisogno di una rapida consultabilità. Richiedi un riassunto esecutivo di un paragrafo se il pubblico è composto da dirigenti senior. Puoi persino passare vincoli di formattazione, come "Limita il riassunto a tre frasi" o "Restituisci l'output come JSON con chiavi per topic, key_points e action_items."

Il vero valore aggiunto

Passare da un playground di chat a uno script funzionante è il punto di svolta in cui l'IA diventa infrastruttura. Una volta che questa pipeline viene eseguita localmente, puoi spostarla in una funzione AWS Lambda attivata da caricamenti su S3, pianificarla su ECS Fargate o integrarla in un workflow di dati esistente. La chiamata API è la parte facile. Il valore ingegneristico deriva dall'avvolgere quella chiamata in una logica che gestisce file, errori e formattazione, così non dovrai mai più copiare e incollare testo in un browser.

Per ulteriori contesti e varianti di questa configurazione, consulta la guida originale su Dev.to. Se desideri discutere di architetture AWS, pipeline LLM o prompt engineering con una community di sviluppatori, unisciti alla conversazione su [GyaanSetu AI on Telegram](https://t.me/GyaanSet