Citazioni

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

Tutti i modelli attivi supportano le citazioni, ad eccezione di Haiku 3.

Ecco un esempio di come usare 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-sonnet-4-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?"
          }
        ]
      }
    ]
  }'

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-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)

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;

public class DocumentExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        PlainTextSource source = PlainTextSource.builder()
                .data("The grass is green. The sky is blue.")
                .build();

        DocumentBlockParam documentParam = DocumentBlockParam.builder()
                .source(source)
                .title("My Document")
                .context("This is a trustworthy document.")
                .citations(CitationsConfigParam.builder().enabled(true).build())
                .build();
        
        TextBlockParam textBlockParam = TextBlockParam.builder()
                .text("What color is the grass and sky?")
                .build();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_SONNET_4_20250514)
                .maxTokens(1024)
                .addUserMessageOfBlockParams(List.of(ContentBlockParam.ofDocument(documentParam), ContentBlockParam.ofText(textBlockParam)))
                .build();

        Message message = client.messages().create(params);
        System.out.println(message);
    }
}

Come funzionano le citazioni

Integra le citazioni con Claude in questi passaggi:

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 usati verso il contenuto citato.
• title è limitato in lunghezza quindi potresti trovare utile il campo context per memorizzare qualsiasi metadato del documento come testo o json stringificato.

Indici delle citazioni

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

Costi dei token

• Abilitare le citazioni comporta un leggero aumento nei token di input dovuto alle aggiunte del prompt di sistema e alla suddivisione dei documenti.
• Tuttavia, la funzione 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 verso i token di output.
• Quando passato indietro nei turni di conversazione successivi, cited_text non viene contato nemmeno verso i token di input.

Compatibilità delle funzioni

Le citazioni funzionano insieme ad altre funzioni API inclusi prompt caching, conteggio token e elaborazione batch.

Usare Prompt Caching con le Citazioni

Le citazioni e il prompt caching possono essere usati insieme efficacemente.

I blocchi di citazione generati nelle risposte non possono essere memorizzati nella cache direttamente, ma i documenti sorgente che referenziano 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 documento lungo (ad es., documentazione tecnica)
long_document = "Questo è un documento molto lungo con migliaia di parole..." + " ... " * 1000  # Lunghezza minima memorizzabile nella cache

response = client.messages.create(
    model="claude-sonnet-4-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"}  # Memorizza nella cache il contenuto del documento
                },
                {
                    "type": "text",
                    "text": "Cosa dice questo documento sulle funzioni API?"
                }
            ]
        }
    ]
)

In questo esempio:

• Il contenuto del documento viene memorizzato nella cache usando cache_control sul blocco 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 usano 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 per 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:

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 controllo sulla granularità delle citazioni. Non viene fatta suddivisione aggiuntiva e i blocchi vengono forniti al modello secondo i blocchi di contenuto forniti.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "Primo blocco"},
            {"type": "text", "text": "Secondo blocco"}
        ]
    },
    "title": "Titolo Documento", # opzionale
    "context": "Contesto sul documento che non verrà citato", # 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": "Secondo il documento, "
        },
        {
            "type": "text",
            "text": "l'erba è verde",
            "citations": [{
                "type": "char_location",
                "cited_text": "L'erba è verde.",
                "document_index": 0,
                "document_title": "Documento di Esempio",
                "start_char_index": 0,
                "end_char_index": 20
            }]
        },
        {
            "type": "text",
            "text": " e "
        },
        {
            "type": "text",
            "text": "il cielo è blu",
            "citations": [{
                "type": "char_location",
                "cited_text": "Il cielo è blu.",
                "document_index": 0,
                "document_title": "Documento di Esempio",
                "start_char_index": 20,
                "end_char_index": 36
            }]
        },
        {
            "type": "text",
            "text": ". Le informazioni dalla pagina 5 affermano che ",
        },
        {
            "type": "text",
            "text": "l'acqua è essenziale",
            "citations": [{
                "type": "page_location",
                "cited_text": "L'acqua è essenziale per la vita.",
                "document_index": 1,
                "document_title": "Documento PDF",
                "start_page_number": 5,
                "end_page_number": 6
            }]
        },
        {
            "type": "text",
            "text": ". Il documento personalizzato menziona ",
        },
        {
            "type": "text",
            "text": "scoperte importanti",
            "citations": [{
                "type": "content_block_location",
                "cited_text": "Queste sono scoperte importanti.",
                "document_index": 2,
                "document_title": "Documento di Contenuto Personalizzato",
                "start_block_index": 0,
                "end_block_index": 1
            }]
        }
    ]
}

Supporto 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.