Citazioni
Fonda le risposte di Claude sui tuoi documenti sorgente. Le citazioni restituiscono i passaggi esatti che supportano ogni affermazione, così puoi verificare le risposte e mostrare le fonti ai tuoi utenti.
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
Le citazioni funzionano in tre fasi:
Fornisci i documenti e abiliti le citazioni
- Includi i documenti in uno qualsiasi dei formati supportati: documenti PDF, testo semplice o contenuto personalizzato.
- Imposta
citations.enabled=truesu ciascuno dei tuoi documenti. Una richiesta non può mescolare documenti con le citazioni abilitate e documenti senza. - Claude può citare il testo ma non le immagini.
L’API elabora i documenti
- 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: L’API estrae il testo come descritto in Supporto PDF e lo suddivide in frasi. Claude non può citare le immagini nei PDF.
- Per i documenti di testo semplice: L’API suddivide il contenuto in frasi.
- Per i documenti a contenuto personalizzato: L’API utilizza i tuoi blocchi di contenuto così come sono e non effettua alcuna ulteriore suddivisione.
- 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.
Claude risponde con citazioni
- Una risposta può includere più blocchi di testo. Ciascun blocco di testo può contenere un’affermazione fatta da Claude e un elenco di citazioni che la supportano.
- Le citazioni fanno riferimento a posizioni specifiche nei documenti sorgente. Il formato di una citazione dipende dal tipo di documento che Claude 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
sourcedi un documento può essere citato. titleecontextsono campi opzionali che vengono passati al modello ma non utilizzati ai fini del contenuto citato.titleè limitato in lunghezza, quindi il campocontextè 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
contentfornito 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 in termini di token di output. Internamente, il modello produce le citazioni in un formato standardizzato, che vengono poi analizzate in testo citato e indici di posizione nel documento. Il campo
cited_textè fornito per comodità e non viene conteggiato nei token di output. - Quando viene restituito nei turni di conversazione successivi,
cited_textnon viene nemmeno conteggiato ai fini degli input token.
Compatibilità delle funzionalità
Le citazioni funzionano con altre funzionalità dell’API, tra cui la cache dei prompt, il conteggio dei token e l’elaborazione in batch.
Ottenere dati strutturati con citazioni
Per ottenere una citazione per ciascun valore estratto, chiedi a Claude di rispondere con una riga per campo. Quindi analizza le righe nel tuo codice per trasformarle in dati strutturati.
Evita prompt utente o prompt di sistema che richiedono solo JSON, come “Restituisci solo un oggetto JSON, nessun altro testo.” Una richiesta con un prompt di questo tipo ha esito positivo, ma la risposta potrebbe contenere poche citazioni o nessuna.
Il seguente prompt richiede due campi dal documento di testo semplice dell’esempio all’inizio di questa pagina. Invialo al posto della domanda di quell’esempio:
Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.Nella seguente risposta, ogni valore ha le proprie citazioni:
{
"content": [
{ "type": "text", "text": "grass_color: " },
{
"type": "text",
"text": "green",
"citations": [
{
"type": "char_location",
"cited_text": "The grass is green. ",
"document_index": 0,
"document_title": "My Document",
"start_char_index": 0,
"end_char_index": 20
}
]
},
{ "type": "text", "text": "\nsky_color: " },
{
"type": "text",
"text": "blue",
"citations": [
{
"type": "char_location",
"cited_text": "The sky is blue.",
"document_index": 0,
"document_title": "My Document",
"start_char_index": 20,
"end_char_index": 36
}
]
}
]
}Per analizzare la risposta, segui questi passaggi:
- Leggi i blocchi
textin ordine e aggiungi il testo di ciascun blocco alla riga corrente. Inizia una nuova riga a ogni carattere di nuova riga. - Associa le
citationsdi ciascun blocco a ogni riga che contiene parte del suo testo. Un blocco citato può contenere solo il valore, come in questo esempio, oppure un’intera riga. - Salta le righe che non contengono i due punti. Dividi ciascuna riga rimanente al primo segno di due punti in un nome di campo e un valore, e rimuovi gli spazi iniziali e finali da entrambi. Salta le righe il cui nome non corrisponde a nessuno dei tuoi campi, come una nota conclusiva.
- Verifica che ogni campo abbia un valore e almeno una citazione. L’API non garantisce né l’uno né l’altra.
Utilizzo della cache dei prompt con le citazioni
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_controlsul 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:
| Tipo | Ideale per | Suddivisione | Formato della citazione |
|---|---|---|---|
| Testo semplice | Documenti di testo semplice, prosa | Frase | Indici dei caratteri (indicizzati a partire da 0) |
| File PDF con contenuto testuale | Frase | Numeri di pagina (indicizzati a partire da 1) | |
| Contenuto personalizzato | Elenchi, trascrizioni, formattazione speciale, citazioni più granulari | Nessuna suddivisione aggiuntiva | Indici dei blocchi (indicizzati a partire da 0) |
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:
Per una richiesta completa di testo semplice, consulta il primo esempio in questa pagina. Il blocco del documento utilizza una sorgente text:
{
"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 }
}In questi esempi, la source di un blocco document fa riferimento a un file caricato tramite la Files API. L’ID del file in ogni esempio è l’id restituito dal caricamento (consulta Caricare un file).
cited_response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": file_id},
"title": "Document Title",
"context": "Context about the document that will not be cited from",
"citations": {"enabled": True},
},
{"type": "text", "text": "Summarize this document."},
],
}
],
)
print(cited_response){
"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
Puoi fornire i documenti PDF come dati codificati in base64, come URL oppure tramite file_id. L’API ne estrae il testo e lo suddivide in frasi.
Claude non può citare le immagini, quindi non può citare un PDF che è la scansione di un documento e non contiene testo estraibile.
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)client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "url",
"url": "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf",
},
"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)In questi esempi, la source di un blocco document fa riferimento a un file caricato tramite la Files API. L’ID del file in ogni esempio è l’id restituito dal caricamento (consulta Caricare un file).
cited_response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": file_id},
"title": "Document Title",
"context": "Context about the document that will not be cited from",
"citations": {"enabled": True},
},
{"type": "text", "text": "Summarize this document."},
],
}
],
)
print(cited_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. Nella source del documento, type è content e il campo content contiene un elenco di blocchi di contenuto. L’API non effettua alcuna ulteriore suddivisione: ogni blocco di testo che fornisci costituisce un chunk, la più piccola unità che Claude può citare.
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
Scopri il flusso degli eventi e gli altri tipi di delta dei blocchi di contenuto che arrivano insieme a citations_delta.
Passa i risultati di ricerca dalla tua pipeline RAG come blocchi di contenuto di prima classe con supporto integrato per le citazioni.
Scopri come Claude estrae il testo dai PDF e come le citazioni basate sulle pagine si ricollegano ai tuoi file sorgente.
Carica i documenti una sola volta e referenziali tramite file_id in più richieste di citazione.
Disponibilità
Claude API
- API
- Messages API
- Managed Agents Non supportato
- Modelli
- Tutti i modelli
Amazon Bedrock
- API
- Messages API
- Modelli
- Tutti i modelli
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelli
- Tutti i modelli
Claude Platform on AWS
- API
- Messages API
- Managed Agents Non supportato
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents Non supportato
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelli
- Tutti i modelli
Microsoft Foundry
- API
- Messages API
- Modelli
- Tutti i modelli
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/messages
Esclude Modelli coperti
Questa pagina ti è stata utile?