Citazioni

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

Integra le citazioni con Claude seguendo questi passaggi:

1. 1

   Fornisci i documenti e abilita 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. Attualmente, le citazioni devono essere abilitate su tutti o nessuno dei documenti all'interno di una richiesta.
   • Attualmente sono supportate solo le citazioni di testo. Le citazioni di immagini non sono ancora possibili.
2. 2

   I documenti vengono elaborati

   • 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: 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 da cui è possibile citare.
     • Per i documenti a contenuto personalizzato: I blocchi di contenuto forniti vengono utilizzati così come sono e non viene effettuata alcuna ulteriore suddivisione.
3. 3

   Claude fornisce una risposta con citazioni

   • Le risposte possono ora includere più blocchi di testo in cui 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 sorgente. Il formato di queste citazioni dipende dal tipo di documento da cui si 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 con gli output token. Internamente, il modello produce le citazioni in un formato standardizzato che vengono poi analizzate in testo citato e indici di posizione del documento. Il campo cited_text viene fornito per comodità e non conta ai fini degli output token.
• 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 in combinazione con altre funzionalità dell'API, tra cui la cache dei prompt, il conteggio dei token e l'elaborazione in batch.

Utilizzo della cache dei prompt con le citazioni

Le citazioni e la cache dei prompt possono essere utilizzate insieme in modo efficace.

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:

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:

{
  "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 }
}

{
  "type": "char_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_char_index": 0, // 0-indexed
  "end_char_index": 50 // exclusive
}

Documenti PDF

I documenti PDF possono essere forniti come dati codificati in base64, un URL o tramite file_id. Il testo del 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 sono citabili.

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)

{
  "type": "page_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_page_number": 1, // 1-indexed
  "end_page_number": 2 // exclusive
}

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 chunk vengono forniti al modello secondo i blocchi di contenuto forniti.

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)

{
  "type": "content_block_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_block_index": 0, // 0-indexed
  "end_block_index": 1 // exclusive
}

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.

event: message_start
data: {"type": "message_start", ...}

event: content_block_start
data: {"type": "content_block_start", "index": 0, ...}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "text_delta", "text": "According to..."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "citations_delta",
                 "citation": {
                     "type": "char_location",
                     "cited_text": "...",
                     "document_index": 0,
                     ...
                 }}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_stop
data: {"type": "message_stop"}

Prossimi passi

Compatibility