Claude è in grado di fornire citazioni dettagliate quando risponde a domande sui documenti, aiutandoti a tracciare e verificare le fonti di informazione nelle risposte.

La funzionalità di citazioni è attualmente disponibile su Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (nuovo) e Haiku 3.5.

Citazioni con Claude Sonnet 3.7

Claude Sonnet 3.7 potrebbe essere meno propenso a fare citazioni rispetto ad altri modelli Claude senza istruzioni più esplicite da parte dell’utente. Quando si utilizzano le citazioni con Claude Sonnet 3.7, consigliamo di includere istruzioni aggiuntive nel turno user, come ad esempio "Usa citazioni per supportare la tua risposta.".

Abbiamo anche osservato che quando al modello viene chiesto di strutturare la sua risposta, è improbabile che utilizzi citazioni a meno che non gli venga esplicitamente detto di utilizzarle all’interno di quel formato. Ad esempio, se al modello viene chiesto di utilizzare i tag nella sua risposta, dovresti aggiungere qualcosa come “Utilizza sempre citazioni nella tua risposta, anche all’interno di .”

Ti preghiamo di condividere il tuo feedback e suggerimenti sulla funzionalità delle citazioni utilizzando questo modulo.

Ecco un esempio di come utilizzare le citazioni con l’API Messages:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "document",
            "source": {
              "type": "text",
              "media_type": "text/plain",
              "data": "The grass is green. The sky is blue."
            },
            "title": "My Document",
            "context": "This is a trustworthy document.",
            "citations": {"enabled": true}
          },
          {
            "type": "text",
            "text": "What color is the grass and sky?"
          }
        ]
      }
    ]
  }'

Confronto con approcci basati su prompt

Rispetto alle soluzioni di citazioni basate su prompt, la funzionalità di citazioni ha i seguenti vantaggi:

  • Risparmio sui costi: Se il tuo approccio basato su prompt chiede a Claude di produrre citazioni dirette, potresti vedere un risparmio sui costi grazie al fatto che cited_text non conta ai fini dei token di output.
  • Maggiore affidabilità delle citazioni: Poiché analizziamo le citazioni nei rispettivi formati di risposta menzionati sopra ed estraiamo cited_text, le citazioni sono garantite per contenere puntatori validi ai documenti forniti.
  • Migliore qualità delle citazioni: Nelle nostre valutazioni, abbiamo riscontrato che la funzionalità di citazioni è significativamente più propensa a citare le citazioni più rilevanti dai documenti rispetto agli approcci puramente basati su prompt.

Come funzionano le citazioni

Integra le citazioni con Claude in questi passaggi:

1

Fornisci documenti e abilita le citazioni

  • Includi documenti in uno qualsiasi dei formati supportati: PDF, testo semplice, o documenti a contenuto personalizzato
  • Imposta citations.enabled=true su ciascuno dei tuoi documenti. Attualmente, le citazioni devono essere abilitate su tutti o nessuno dei documenti all’interno di una richiesta.
  • Nota che attualmente sono supportate solo le citazioni di testo e le citazioni di immagini non sono ancora possibili.
2

I documenti vengono elaborati

  • I contenuti dei documenti vengono “suddivisi in blocchi” per definire la granularità minima delle possibili citazioni. Ad esempio, la suddivisione in frasi consentirebbe a Claude di citare una singola frase o concatenare più frasi consecutive per citare un paragrafo (o più lungo)!
    • Per i PDF: Il testo viene estratto come descritto in Supporto PDF e il contenuto viene suddiviso in frasi. La citazione di immagini dai PDF non è attualmente supportata.
    • Per i documenti di testo semplice: Il contenuto viene suddiviso in frasi che possono essere citate.
    • Per i documenti a contenuto personalizzato: I blocchi di contenuto forniti vengono utilizzati così come sono e non viene effettuata ulteriore suddivisione.
3

Claude fornisce una risposta con citazioni

  • Le risposte possono ora includere più blocchi di testo dove ogni blocco di testo può contenere un’affermazione che Claude sta facendo e un elenco di citazioni che supportano l’affermazione.
  • Le citazioni fanno riferimento a posizioni specifiche nei documenti di origine. Il formato di queste citazioni dipende dal tipo di documento da cui si sta citando.
    • Per i PDF: le citazioni includeranno l’intervallo di numeri di pagina (con indice 1).
    • Per i documenti di testo semplice: Le citazioni includeranno l’intervallo di indici di caratteri (con indice 0).
    • Per i documenti a contenuto personalizzato: Le citazioni includeranno l’intervallo di indici dei blocchi di contenuto (con indice 0) corrispondenti all’elenco di contenuti originale fornito.
  • Gli indici dei documenti vengono forniti per indicare la fonte di riferimento e sono indicizzati a 0 secondo l’elenco di tutti i documenti nella richiesta originale.

Suddivisione automatica vs contenuto personalizzato

Per impostazione predefinita, i documenti di testo semplice e PDF vengono automaticamente suddivisi in frasi. Se hai bisogno di un maggiore controllo sulla granularità delle citazioni (ad esempio, per punti elenco o trascrizioni), utilizza invece documenti a contenuto personalizzato. Vedi Tipi di documento per maggiori dettagli.

Ad esempio, se vuoi che Claude sia in grado di citare frasi specifiche dai tuoi blocchi RAG, dovresti inserire ogni blocco RAG in un documento di testo semplice. Altrimenti, se non vuoi che venga effettuata alcuna ulteriore suddivisione, o se vuoi personalizzare qualsiasi suddivisione aggiuntiva, puoi inserire i blocchi RAG in documenti a contenuto personalizzato.

Contenuto citabile vs non citabile

  • Il testo trovato all’interno del contenuto source di un documento può essere citato.
  • title e context sono campi opzionali che verranno passati al modello ma non utilizzati per il contenuto citato.
  • title è limitato in lunghezza, quindi potresti trovare utile il campo context per memorizzare qualsiasi metadato del documento come testo o json convertito in stringa.

Indici di citazione

  • Gli indici dei documenti sono indicizzati a 0 dall’elenco di tutti i blocchi di contenuto del documento nella richiesta (estendendosi su tutti i messaggi).
  • Gli indici dei caratteri sono indicizzati a 0 con indici finali esclusivi.
  • I numeri di pagina sono indicizzati a 1 con numeri di pagina finali esclusivi.
  • Gli indici dei blocchi di contenuto sono indicizzati a 0 con indici finali esclusivi dall’elenco content fornito nel documento a contenuto personalizzato.

Costi in token

  • L’abilitazione delle citazioni comporta un leggero aumento dei token di input a causa delle aggiunte al prompt di sistema e della suddivisione dei documenti.
  • Tuttavia, la funzionalità di citazioni è molto efficiente con i token di output. Sotto il cofano, il modello sta producendo citazioni in un formato standardizzato che vengono poi analizzate in testo citato e indici di posizione del documento. Il campo cited_text è fornito per comodità e non conta ai fini dei token di output.
  • Quando viene passato nei turni di conversazione successivi, cited_text non viene conteggiato nemmeno nei token di input.

Compatibilità delle funzionalità

Le citazioni funzionano in combinazione con altre funzionalità dell’API, tra cui caching dei prompt, conteggio dei token ed elaborazione in batch.

Utilizzo del caching dei prompt con le citazioni

Le citazioni e il caching dei prompt possono essere utilizzati insieme in modo efficace.

I blocchi di citazione generati nelle risposte non possono essere memorizzati nella cache direttamente, ma i documenti di origine a cui fanno riferimento possono essere memorizzati nella cache. Per ottimizzare le prestazioni, applica cache_control ai tuoi blocchi di contenuto del documento di livello superiore.

import anthropic

client = anthropic.Anthropic()

# Contenuto di documento lungo (ad esempio, documentazione tecnica)
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # Lunghezza minima memorizzabile nella cache

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": long_document
                    },
                    "citations": {"enabled": True},
                    "cache_control": {"type": "ephemeral"}  # Memorizza nella cache il contenuto del documento
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

In questo esempio:

  • Il contenuto del documento viene memorizzato nella cache utilizzando cache_control sul blocco del documento
  • Le citazioni sono abilitate sul documento
  • Claude può generare risposte con citazioni beneficiando del contenuto del documento memorizzato nella cache
  • Le richieste successive che utilizzano lo stesso documento beneficeranno del contenuto memorizzato nella cache

Tipi di documento

Scegliere un tipo di documento

Supportiamo tre tipi di documento per le citazioni. I documenti possono essere forniti direttamente nel messaggio (base64, testo o URL) o caricati tramite l’API Files e referenziati tramite file_id:

TipoIdeale perSuddivisioneFormato di citazione
Testo sempliceDocumenti di testo semplice, prosaFraseIndici di caratteri (indicizzati a 0)
PDFFile PDF con contenuto testualeFraseNumeri di pagina (indicizzati a 1)
Contenuto personalizzatoListe, trascrizioni, formattazione speciale, citazioni più granulariNessuna suddivisione aggiuntivaIndici di blocco (indicizzati a 0)

Documenti di testo semplice

I documenti di testo semplice vengono automaticamente suddivisi in frasi. Puoi fornirli in linea o per riferimento con il loro file_id:

{
    "type": "document",
    "source": {
        "type": "text",
        "media_type": "text/plain",
        "data": "Plain text content..."
    },
    "title": "Document Title", # opzionale
    "context": "Context about the document that will not be cited from", # opzionale
    "citations": {"enabled": True}
}

Documenti PDF

I documenti PDF possono essere forniti come dati codificati in base64 o tramite file_id. Il testo PDF viene estratto e suddiviso in frasi. Poiché le citazioni di immagini non sono ancora supportate, i PDF che sono scansioni di documenti e non contengono testo estraibile non saranno citabili.

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": base64_encoded_pdf_data
    },
    "title": "Document Title", # opzionale
    "context": "Context about the document that will not be cited from", # opzionale
    "citations": {"enabled": True}
}

Documenti a contenuto personalizzato

I documenti a contenuto personalizzato ti danno il controllo sulla granularità delle citazioni. Non viene effettuata alcuna suddivisione aggiuntiva e i blocchi vengono forniti al modello secondo i blocchi di contenuto forniti.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"}
        ]
    },
    "title": "Document Title", # opzionale
    "context": "Context about the document that will not be cited from", # opzionale
    "citations": {"enabled": True}
}

Struttura della risposta

Quando le citazioni sono abilitate, le risposte includono più blocchi di testo con citazioni:

{
    "content": [
        {
            "type": "text",
            "text": "According to the document, "
        },
        {
            "type": "text",
            "text": "the grass is green",
            "citations": [{
                "type": "char_location",
                "cited_text": "The grass is green.",
                "document_index": 0,
                "document_title": "Example Document",
                "start_char_index": 0,
                "end_char_index": 20
            }]
        },
        {
            "type": "text",
            "text": " and "
        },
        {
            "type": "text",
            "text": "the sky is blue",
            "citations": [{
                "type": "char_location",
                "cited_text": "The sky is blue.",
                "document_index": 0,
                "document_title": "Example Document",
                "start_char_index": 20,
                "end_char_index": 36
            }]
        }
    ]
}

Supporto allo streaming

Per le risposte in streaming, abbiamo aggiunto un tipo citations_delta che contiene una singola citazione da aggiungere all’elenco citations sul blocco di contenuto text corrente.