Citazioni

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

Tutti i modelli attivi supportano le citazioni, con l'eccezione di Haiku 3.

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 in questi passaggi:

Contenuto citabile e non citabile

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

Indici di citazione

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

Costi dei token

• L'abilitazione delle citazioni comporta un leggero aumento dei token di input dovuto alle aggiunte del prompt di sistema e alla suddivisione dei documenti.
• Tuttavia, la funzione di citazioni è molto efficiente con i token di output. Dietro le quinte, il modello sta generando citazioni in un formato standardizzato che vengono quindi analizzate in testo citato e indici di posizione del documento. Il campo cited_text viene fornito per comodità e non conta verso i token di output.
• Quando passato di nuovo nei turni di conversazione successivi, cited_text non viene conteggiato nemmeno verso i token di input.

Compatibilità delle funzioni

Le citazioni funzionano insieme ad altre funzioni dell'API incluse prompt caching, token counting e batch processing.

Utilizzo del Prompt Caching con le citazioni

Le citazioni e il prompt caching 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.

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 mentre beneficia del contenuto del documento memorizzato nella cache
• Le richieste successive che utilizzano lo stesso documento beneficeranno del contenuto memorizzato nella cache

Tipi di documento

Scelta di un tipo di documento

Tre tipi di documento sono supportati per le citazioni. I documenti possono essere forniti direttamente nel messaggio (base64, testo o URL) o caricati tramite l'API Files e referenziati da file_id:

Documenti di testo semplice

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

Documenti PDF

I documenti PDF possono essere forniti come dati codificati in base64 o per 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.

Documenti di contenuto personalizzato

I documenti di contenuto personalizzato ti danno il controllo sulla granularità delle citazioni. Non viene eseguita 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",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "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,
                }
            ],
        },
        {
            "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, è incluso un tipo citations_delta che contiene una singola citazione da aggiungere all'elenco citations sul blocco di contenuto text corrente.