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, ad eccezione di Haiku 3.

Ecco un esempio di come utilizzare 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-opus-4-6",
    "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?"
          }
        ]
      }
    ]
  }'

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 metadati 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 (che si estendono 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 finale 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 producendo 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 in combinazione con altre funzioni dell'API incluse prompt caching, token counting e batch processing.

Utilizzo di Prompt Caching con 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.

import anthropic

client = anthropic.Anthropic()

# Long document content (e.g., technical documentation)
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # Minimum cacheable length

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

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

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 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 ulteriore suddivisione 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, abbiamo aggiunto un tipo citations_delta che contiene una singola citazione da aggiungere all'elenco citations sul blocco di contenuto text corrente.