Files API: gestire repository di documenti con Claude

In questa lezione presentiamo il concetto di Files API nella piattaforma Claude illustrandone le caratteristiche e la logica di utilizzo.

Sviluppando applicazioni con Claude, ci troviamo spesso di fronte alla necessità di inviare documenti (come PDF, testi o immagini) ai modelli. Ripetere il caricamento di file identici più volte risulta inefficiente e può aumentare la latenza o i tempi di utilizzo di uno specifico software. Files API ci consente di caricare file una sola volta e poi riutilizzarli in molteplici richieste, semplicemente facendo riferimento a un file_id univoco. In questo modo, ottimizziamo i flussi di lavoro, riduciamo la ridondanza e miglioriamo le prestazioni complessive.

Modelli Claude supportati e compatibilità

È fondamentale sapere che le Files API sono supportate soltanto per i modelli che accettano il tipo di file inviato. Ad esempio:

• Le immagini sono supportate in tutti i modelli Claude 3+.
• I PDF sono supportati nei modelli Claude 3.5+.
• Altri tipi di file (come CSV, dati strutturati) possono essere utilizzati con il code execution tool e dunque supportati spesso nelle versioni Claude 3.5 Haiku e Claude 3.7+.

Come funzionano le Files API

L’approccio proposto dalle Files API è al tempo stesso lineare ed estremamente efficace: caricare un documento una sola volta e riutilizzarlo ogni volta che se ne presenta la necessità. Il flusso operativo si articola in alcune fasi ben definite. In primo luogo, effettuiamo il caricamento del file sulla piattaforma Anthropic, ottenendo come risultato un identificativo univoco (file_id). Successivamente, nelle richieste che inoltriamo tramite le Messages API, non dobbiamo più reinviare il contenuto del documento, ma semplicemente richiamare tale identificativo, con un notevole risparmio di tempo e di risorse.

A ciò si aggiunge la possibilità di scaricare i file prodotti dal code execution tool, ampliando le modalità di interazione con i dati. Infine, possiamo amministrare l’intero archivio grazie alle operazioni di elenco, consultazione e cancellazione dei file.

Le Files API rappresentano dunque una soluzione agile e robusta per la gestione di repository documentali, che diventano così più ordinati, performanti e pronti per essere integrati in flussi applicativi complessi.

Esempio di upload di un file

Dopo aver configurato il nostro ambiente effettuiamo il caricamento di un documento:

import anthropic
client = anthropic.Anthropic()
client.beta.files.upload(
  file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)

Il codice che presentiamo utilizza il client Python ufficiale di Anthropic per caricare un file PDF tramite le Files API. Importiamo la libreria con import anthropic e inizializziamo un client con client = anthropic.Anthropic(), il quale gestisce l’autenticazione attraverso la nostra chiave API. La chiamata client.beta.files.upload(...) consente di eseguire l’upload: l’argomento file è una tupla che comprende il nome con cui desideriamo registrare il documento sulla piattaforma ("document.pdf"), il file aperto in modalità binaria (open("/path/to/document.pdf", "rb")) e il tipo MIME che ne specifica il formato ("application/pdf"). In questo modo inviamo il documento alla piattaforma Anthropic e otteniamo in risposta un oggetto JSON contenente, tra gli altri campi, un identificativo univoco (file_id).

Questo identificativo rappresenta il riferimento al file caricato di cui abbiamo già parlato in precedenza e ci consente di richiamarlo successivamente nelle nostre richieste tramite le Messages API senza dover reinviare il contenuto.

Inoltre, possiamo servirci di tale file_id per gestire il documento attraverso le operazioni messe a disposizione dalle Files API, come la consultazione dei metadati, l’elenco dei file disponibili o la loro cancellazione.

Repository documentale con le Files API

Immaginiamo di voler realizzare un piccolo sistema di gestione documentale in Python. Il nostro obiettivo è costruire un “repository” che ci permetta di centralizzare i file caricati nella piattaforma Anthropic, ottenendo per ciascuno un identificativo univoco (file_id) che possiamo usare per successive interazioni con Claude.

Ecco un esempio di implementazione:

import anthropic
import os
# Inizializziamo il client con la chiave API (deve essere impostata nelle variabili d'ambiente)
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
class DocumentRepository:
    def __init__(self, client):
        self.client = client
    def upload_document(self, path, mime_type="application/pdf"):
        """
        Carica un documento nel repository e restituisce il file_id.
        """
        file_name = os.path.basename(path)
        with open(path, "rb") as f:
            uploaded_file = self.client.beta.files.upload(
                file=(file_name, f, mime_type),
            )
        print(f"Documento '{file_name}' caricato con file_id: {uploaded_file.id}")
        return uploaded_file.id
    def list_documents(self):
        """
        Elenca i documenti presenti nel repository.
        """
        files = self.client.beta.files.list()
        for f in files.data:
            print(f"ID: {f.id}, Nome: {f.name}, Tipo: {f.type}, Creato: {f.created_at}")
        return files.data
    def retrieve_document(self, file_id):
        """
        Recupera i metadati di un documento specifico.
        """
        file_info = self.client.beta.files.retrieve(file_id)
        print(f"Documento recuperato: {file_info.name} ({file_info.type})")
        return file_info
    def delete_document(self, file_id):
        """
        Cancella un documento dal repository.
        """
        self.client.beta.files.delete(file_id)
        print(f"Documento con file_id {file_id} eliminato con successo.")
# ESEMPIO DI UTILIZZO
if __name__ == "__main__":
    repo = DocumentRepository(client)
    # 1. Carichiamo un documento PDF
    file_id = repo.upload_document("/path/to/document.pdf")
    # 2. Elenchiamo tutti i documenti disponibili
    repo.list_documents()
    # 3. Recuperiamo le informazioni sul file appena caricato
    repo.retrieve_document(file_id)
    # 4. Eliminiamo il documento
    repo.delete_document(file_id)

Commento al codice

In questo esempio abbiamo definito una classe DocumentRepository che incapsula le operazioni principali sulle Files API: caricamento (upload_document), elenco (list_documents), recupero dei metadati (retrieve_document) e cancellazione (delete_document). Ogni metodo utilizza il client Anthropic per interagire con la piattaforma, e restituisce informazioni utili per la gestione del nostro archivio documentale.

Nella sezione finale (if __name__ == "__main__":) simuliamo l’utilizzo del repository: carichiamo un file PDF, elenchiamo i documenti presenti, recuperiamo le informazioni relative a quello appena caricato e infine lo cancelliamo. In questo modo possiamo osservare l’intero ciclo di vita di un documento all’interno delle Files API.

Conclusione: cosa possiamo fare con le Files API di Claude

Le Files API si rivelano uno strumento essenziale per la costruzione di applicazioni che richiedono una gestione efficiente di documenti e contenuti multimediali all’interno della piattaforma Claude. Grazie alla possibilità di caricare un file una sola volta e di richiamarlo successivamente tramite il suo identificativo univoco, possiamo ridurre ridondanze, ottimizzare i flussi di lavoro e mantenere repository documentali più ordinati e scalabili. La loro integrazione con le Messages API amplia ulteriormente le potenzialità di analisi e manipolazione dei dati, permettendoci di progettare sistemi solidi e performanti.