Citazioni

Claude può fornire citazioni dettagliate quando risponde a domande sui documenti, aiutandoti a tracciare e verificare le fonti alla base di 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",
    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:



Contenuto citabile e non citabile

• Il testo presente 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 per il contenuto citato.
• title ha una lunghezza limitata, quindi il campo context è utile per memorizzare i metadati del documento come testo o JSON serializzato in stringa.



Indici delle citazioni

• Gli indici dei documenti hanno indice a partire da 0 rispetto all'elenco di tutti i blocchi di contenuto di tipo documento nella richiesta (attraverso tutti i messaggi).
• Gli indici dei caratteri hanno indice a partire da 0 con indici finali esclusivi.
• I numeri di pagina hanno indice a partire da 1 con numeri di pagina finali esclusivi.
• Gli indici dei blocchi di contenuto hanno indice a partire da 0 con indici finali esclusivi rispetto all'elenco content fornito nel documento con 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à delle citazioni è molto efficiente con i token di output. Internamente, il modello produce le citazioni in un formato standardizzato che viene poi analizzato in testo citato e indici di posizione nel documento. Il campo cited_text viene fornito per comodità e non viene conteggiato nei token di output.
• Quando viene ripassato nei turni di conversazione successivi, cited_text non viene conteggiato nemmeno nei token di input.



Compatibilità con altre funzionalità

Le citazioni funzionano in combinazione con altre funzionalità dell'API, tra cui la cache dei prompt, il conteggio dei token e l'elaborazione 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 direttamente nella cache, ma i documenti sorgente a cui fanno riferimento possono esserlo. Per ottimizzare le prestazioni, applica cache_control ai tuoi blocchi di contenuto di tipo documento di primo livello.

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",
    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



Scegliere 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) oppure 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 tramite 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 }
}



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",
    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 con contenuto personalizzato

I documenti con contenuto personalizzato ti danno il controllo sulla granularità delle citazioni. Non viene eseguita alcuna suddivisione aggiuntiva e i chunk vengono forniti al modello in base ai blocchi di contenuto forniti.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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 per lo 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.



Passaggi successivi