Claude Platform Docs
MessaggiCapacità del modello

Citazioni

Fonda le risposte di Claude sui tuoi documenti sorgente. Le citazioni restituiscono i passaggi esatti che supportano ogni affermazione, così puoi verificare le risposte e mostrare le fonti ai tuoi utenti.

Claude può fornire citazioni dettagliate quando risponde a domande sui documenti, aiutandoti a tracciare e verificare le fonti dietro ogni risposta.

Tutti i modelli attivi supportano le citazioni.

L’esempio seguente mostra come abilitare le citazioni su un documento di testo semplice con la Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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?"},
            ],
        }
    ],
)
print(response)

Come funzionano le citazioni

Le citazioni funzionano in tre fasi:

  1. Fornisci i documenti e abiliti le citazioni

    • Includi i documenti in uno qualsiasi dei formati supportati: documenti PDF, testo semplice o contenuto personalizzato.
    • Imposta citations.enabled=true su ciascuno dei tuoi documenti. Una richiesta non può mescolare documenti con le citazioni abilitate e documenti senza.
    • Claude può citare il testo ma non le immagini.
  2. L’API elabora i documenti

    • I contenuti dei documenti vengono suddivisi in “chunk” per definire la granularità minima delle possibili citazioni. Ad esempio, la suddivisione in frasi consente a Claude di citare una singola frase o di concatenare più frasi consecutive per citare un paragrafo o un passaggio più lungo.
      • Per i PDF: L’API estrae il testo come descritto in Supporto PDF e lo suddivide in frasi. Claude non può citare le immagini nei PDF.
      • Per i documenti di testo semplice: L’API suddivide il contenuto in frasi.
      • Per i documenti a contenuto personalizzato: L’API utilizza i tuoi blocchi di contenuto così come sono e non effettua alcuna ulteriore suddivisione.
  3. Claude risponde con citazioni

    • Una risposta può includere più blocchi di testo. Ciascun blocco di testo può contenere un’affermazione fatta da Claude e un elenco di citazioni che la supportano.
    • Le citazioni fanno riferimento a posizioni specifiche nei documenti sorgente. Il formato di una citazione dipende dal tipo di documento che Claude cita.
      • Per i PDF: Le citazioni includono l’intervallo di numeri di pagina (indicizzato a partire da 1).
      • Per i documenti di testo semplice: Le citazioni includono l’intervallo di indici dei caratteri (indicizzato a partire da 0).
      • Per i documenti a contenuto personalizzato: Le citazioni includono l’intervallo di indici dei blocchi di contenuto (indicizzato a partire da 0) corrispondente all’elenco di contenuti originale fornito.
    • Gli indici dei documenti vengono forniti per indicare la fonte di riferimento e sono indicizzati a partire da 0 secondo l’elenco di tutti i documenti nella tua richiesta originale.

Contenuto citabile rispetto a non citabile

  • Il testo trovato all’interno del contenuto source di un documento può essere citato.
  • title e context sono campi opzionali che vengono passati al modello ma non utilizzati ai fini del contenuto citato.
  • title è limitato in lunghezza, quindi il campo context è utile per memorizzare i metadati del documento come testo o JSON in formato stringa.

Indici delle citazioni

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

Costi dei token

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

Compatibilità delle funzionalità

Le citazioni funzionano con altre funzionalità dell’API, tra cui la cache dei prompt, il conteggio dei token e l’elaborazione in batch.

Ottenere dati strutturati con citazioni

Per ottenere una citazione per ciascun valore estratto, chiedi a Claude di rispondere con una riga per campo. Quindi analizza le righe nel tuo codice per trasformarle in dati strutturati.

Evita prompt utente o prompt di sistema che richiedono solo JSON, come “Restituisci solo un oggetto JSON, nessun altro testo.” Una richiesta con un prompt di questo tipo ha esito positivo, ma la risposta potrebbe contenere poche citazioni o nessuna.

Il seguente prompt richiede due campi dal documento di testo semplice dell’esempio all’inizio di questa pagina. Invialo al posto della domanda di quell’esempio:

Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.

Nella seguente risposta, ogni valore ha le proprie citazioni:

{
  "content": [
    { "type": "text", "text": "grass_color: " },
    {
      "type": "text",
      "text": "green",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The grass is green. ",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 0,
          "end_char_index": 20
        }
      ]
    },
    { "type": "text", "text": "\nsky_color: " },
    {
      "type": "text",
      "text": "blue",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The sky is blue.",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 20,
          "end_char_index": 36
        }
      ]
    }
  ]
}

Per analizzare la risposta, segui questi passaggi:

  1. Leggi i blocchi text in ordine e aggiungi il testo di ciascun blocco alla riga corrente. Inizia una nuova riga a ogni carattere di nuova riga.
  2. Associa le citations di ciascun blocco a ogni riga che contiene parte del suo testo. Un blocco citato può contenere solo il valore, come in questo esempio, oppure un’intera riga.
  3. Salta le righe che non contengono i due punti. Dividi ciascuna riga rimanente al primo segno di due punti in un nome di campo e un valore, e rimuovi gli spazi iniziali e finali da entrambi. Salta le righe il cui nome non corrisponde a nessuno dei tuoi campi, come una nota conclusiva.
  4. Verifica che ogni campo abbia un valore e almeno una citazione. L’API non garantisce né l’uno né l’altra.

Utilizzo della cache dei prompt con le citazioni

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

client = anthropic.Anthropic()

# Contenuto di un documento lungo (ad esempio, documentazione tecnica)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-5-5",
    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"
                    },  # Cache the document content
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?",
                },
            ],
        }
    ],
)
print(response)

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 al contempo del contenuto del documento memorizzato nella cache.
  • Le richieste successive che utilizzano lo stesso documento beneficiano del contenuto memorizzato nella cache.

Tipi di documento

Scelta di un tipo di documento

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

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

Documenti di testo semplice

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

Per una richiesta completa di testo semplice, consulta il primo esempio in questa pagina. Il blocco del documento utilizza una sorgente text:

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

Documenti PDF

Puoi fornire i documenti PDF come dati codificati in base64, come URL oppure tramite file_id. L’API ne estrae il testo e lo suddivide in frasi.

Claude non può citare le immagini, quindi non può citare un PDF che è la scansione di un documento e non contiene testo estraibile.

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

Documenti a contenuto personalizzato

I documenti a contenuto personalizzato ti danno il controllo sulla granularità delle citazioni. Nella source del documento, type è content e il campo content contiene un elenco di blocchi di contenuto. L’API non effettua alcuna ulteriore suddivisione: ogni blocco di testo che fornisci costituisce un chunk, la più piccola unità che Claude può citare.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "content",
                        "content": [
                            {"type": "text", "text": "First chunk"},
                            {"type": "text", "text": "Second chunk"},
                        ],
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)


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
        }
      ]
    },
    {
      "type": "text",
      "text": ". Information from page 5 states that "
    },
    {
      "type": "text",
      "text": "water is essential",
      "citations": [
        {
          "type": "page_location",
          "cited_text": "Water is essential for life.",
          "document_index": 1,
          "document_title": "PDF Document",
          "start_page_number": 5,
          "end_page_number": 6
        }
      ]
    },
    {
      "type": "text",
      "text": ". The custom document mentions "
    },
    {
      "type": "text",
      "text": "important findings",
      "citations": [
        {
          "type": "content_block_location",
          "cited_text": "These are important findings.",
          "document_index": 2,
          "document_title": "Custom Content Document",
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Supporto dello streaming

Per le risposte in streaming, le citazioni arrivano come tipo di delta citations_delta all’interno degli eventi content_block_delta. Ogni delta contiene una singola citazione da aggiungere all’elenco citations sul blocco di contenuto text corrente.

Prossimi passi

Scopri il flusso degli eventi e gli altri tipi di delta dei blocchi di contenuto che arrivano insieme a citations_delta.

Passa i risultati di ricerca dalla tua pipeline RAG come blocchi di contenuto di prima classe con supporto integrato per le citazioni.

Scopri come Claude estrae il testo dai PDF e come le citazioni basate sulle pagine si ricollegano ai tuoi file sorgente.

Carica i documenti una sola volta e referenziali tramite file_id in più richieste di citazione.

Disponibilità

Citazioni
API
  • Messages API
  • Managed Agents Non supportato
Modelli
  • Tutti i modelli

Endpoint applicabili

  • /v1/messages
Conservazione zero dei datiIdoneo

Esclude Modelli coperti

HIPAAIdoneo

Questa pagina ti è stata utile?