Questa funzionalità è idonea per la Zero Data Retention (ZDR). Quando la tua organizzazione dispone di un accordo ZDR, i dati inviati tramite questa funzionalità non vengono conservati dopo che la risposta dell'API è stata restituita.
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, ad eccezione di Claude Haiku 3.
Condividi il tuo feedback e i tuoi suggerimenti sulla funzionalità delle citazioni utilizzando il modulo di feedback sulle 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-4-8",
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)Confronto con gli approcci basati su prompt
Rispetto al chiedere a Claude tramite prompt di citare le fonti, la funzionalità delle citazioni offre i seguenti vantaggi:
cited_text non viene conteggiato nei tuoi token di output.cited_text direttamente, è garantito che le citazioni contengano puntatori validi ai documenti forniti.Integra le citazioni con Claude seguendo questi passaggi:
Fornisci i documenti e abilita le citazioni
citations.enabled=true su ciascuno dei tuoi documenti. Attualmente, le citazioni devono essere abilitate su tutti o su nessuno dei documenti all'interno di una richiesta.I documenti vengono elaborati
Claude fornisce una risposta con citazioni
Suddivisione automatica vs contenuto personalizzato
Per impostazione predefinita, i documenti di testo semplice e PDF vengono automaticamente suddivisi in frasi. Se hai bisogno di maggiore controllo sulla granularità delle citazioni (ad esempio, per elenchi puntati o trascrizioni), usa invece i documenti con contenuto personalizzato. Consulta Tipi di documento per maggiori dettagli.
Ad esempio, se vuoi che Claude sia in grado di citare frasi specifiche dai tuoi chunk RAG, dovresti inserire ogni chunk RAG in un documento di testo semplice. Altrimenti, se non vuoi che venga eseguita alcuna ulteriore suddivisione, o se vuoi personalizzare qualsiasi suddivisione aggiuntiva, puoi inserire i chunk RAG in documenti con contenuto personalizzato.
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.content fornito nel documento con contenuto personalizzato.cited_text viene fornito per comodità e non viene conteggiato nei token di output.cited_text non viene conteggiato nemmeno nei token di input.Le citazioni funzionano in combinazione con altre funzionalità dell'API, tra cui la cache dei prompt, il conteggio dei token e l'elaborazione batch.
Le citazioni e gli output strutturati sono incompatibili
Le citazioni non possono essere utilizzate insieme agli output strutturati. Se abiliti le citazioni su qualsiasi documento fornito dall'utente (blocchi document o blocchi search_result) e includi anche il parametro output_config.format (o il parametro deprecato output_format), l'API restituisce un errore 400.
Questo perché le citazioni richiedono l'intercalazione di blocchi di citazione con l'output di testo, il che è incompatibile con i rigidi vincoli dello schema JSON degli output strutturati.
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 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-4-8",
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:
cache_control sul blocco del 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:
| Tipo | Ideale per | Suddivisione | Formato della citazione |
|---|---|---|---|
| Testo semplice | Documenti di testo semplici, prosa | Frase | Indici di carattere (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 di blocco (indicizzati a partire da 0) |
I file .csv, .xlsx, .docx, .md e .txt non sono supportati come blocchi di documento. Converti questi file in testo semplice e includili direttamente nel contenuto del messaggio. Consulta Lavorare con altri formati di file.
I documenti di testo semplice vengono automaticamente suddivisi in frasi. Puoi fornirli inline o tramite riferimento con il loro file_id:
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 saranno citabili.
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-4-8",
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)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,
}
],
},
]
}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.
Gestisci il tipo di delta citations_delta insieme ai delta di testo per visualizzare le risposte citate mentre vengono trasmesse in streaming.
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.
Was this page helpful?