Risultati di ricerca
Abilita citazioni naturali per applicazioni RAG fornendo risultati di ricerca con attribuzione della fonte
I blocchi di contenuto dei risultati di ricerca sono attualmente in beta. Usa l’header beta search-results-2025-06-09
beta header per abilitare questa funzionalità.
I blocchi di contenuto dei risultati di ricerca abilitano citazioni naturali con attribuzione appropriata della fonte, portando citazioni di qualità da ricerca web alle tue applicazioni personalizzate. Questa funzionalità è particolarmente potente per applicazioni RAG (Retrieval-Augmented Generation) dove hai bisogno che Claude citi le fonti accuratamente.
Benefici chiave
- Citazioni naturali - Ottieni la stessa qualità di citazione della ricerca web per qualsiasi contenuto
- Integrazione flessibile - Usa nei ritorni degli strumenti per RAG dinamico o come contenuto di primo livello per dati pre-recuperati
- Attribuzione appropriata della fonte - Ogni risultato include informazioni sulla fonte e sul titolo per un’attribuzione chiara
- Nessun workaround di documento necessario - Elimina la necessità di workaround basati su documenti
- Formato di citazione coerente - Corrisponde alla qualità e al formato delle citazioni della funzionalità di ricerca web di Claude
Come funziona
I risultati di ricerca possono essere forniti in due modi:
- Da chiamate di strumenti - I tuoi strumenti personalizzati restituiscono risultati di ricerca, abilitando applicazioni RAG dinamiche
- Come contenuto di primo livello - Fornisci risultati di ricerca direttamente nei messaggi utente per contenuto pre-recuperato o memorizzato in cache
In entrambi i casi, Claude può automaticamente citare informazioni dai risultati di ricerca con attribuzione appropriata della fonte.
Schema dei risultati di ricerca
I risultati di ricerca usano la seguente struttura:
Campi richiesti
Campo | Tipo | Descrizione |
---|---|---|
type | string | Deve essere "search_result" |
source | string | L’URL della fonte o identificatore per il contenuto |
title | string | Un titolo descrittivo per il risultato di ricerca |
content | array | Un array di blocchi di testo contenenti il contenuto effettivo |
Campi opzionali
Campo | Tipo | Descrizione |
---|---|---|
citations | object | Configurazione delle citazioni con campo booleano enabled |
cache_control | object | Impostazioni di controllo della cache (es. {"type": "ephemeral"} ) |
Ogni elemento nell’array content
deve essere un blocco di testo con:
type
: Deve essere"text"
text
: Il contenuto di testo effettivo (stringa non vuota)
Metodo 1: Risultati di ricerca da chiamate di strumenti
Il caso d’uso più potente è restituire risultati di ricerca dai tuoi strumenti personalizzati. Questo abilita applicazioni RAG dinamiche dove gli strumenti recuperano e restituiscono contenuto rilevante con citazioni automatiche.
Esempio: Strumento di base di conoscenza
Metodo 2: Risultati di ricerca come contenuto di primo livello
Puoi anche fornire risultati di ricerca direttamente nei messaggi utente. Questo è utile per:
- Contenuto pre-recuperato dalla tua infrastruttura di ricerca
- Risultati di ricerca memorizzati in cache da query precedenti
- Contenuto da servizi di ricerca esterni
- Test e sviluppo
Esempio: Risultati di ricerca diretti
Risposta di Claude con citazioni
Indipendentemente da come vengono forniti i risultati di ricerca, Claude include automaticamente citazioni quando usa informazioni da essi:
Campi delle citazioni
Ogni citazione include:
Campo | Tipo | Descrizione |
---|---|---|
type | string | Sempre "search_result_location" per citazioni di risultati di ricerca |
source | string | La fonte dal risultato di ricerca originale |
title | string o null | Il titolo dal risultato di ricerca originale |
cited_text | string | Il testo esatto che viene citato |
search_result_index | integer | Indice del risultato di ricerca (basato su 0) |
start_block_index | integer | Posizione iniziale nell’array content |
end_block_index | integer | Posizione finale nell’array content |
Nota: Il search_result_index
si riferisce all’indice del blocco di contenuto del risultato di ricerca (basato su 0), indipendentemente da come sono stati forniti i risultati di ricerca (chiamata di strumento o contenuto di primo livello).
Blocchi di contenuto multipli
I risultati di ricerca possono contenere blocchi di testo multipli nell’array content
:
Claude può citare blocchi specifici usando i campi start_block_index
e end_block_index
.
Uso avanzato
Combinare entrambi i metodi
Puoi usare sia risultati di ricerca basati su strumenti che di primo livello nella stessa conversazione:
Combinare con altri tipi di contenuto
Entrambi i metodi supportano la combinazione di risultati di ricerca con altro contenuto:
Controllo della cache
Aggiungi controllo della cache per migliori prestazioni:
Controllo delle citazioni
Per impostazione predefinita, le citazioni sono disabilitate per i risultati di ricerca. Puoi abilitare le citazioni impostando esplicitamente la configurazione citations
:
Quando citations.enabled
è impostato su true
, Claude includerà riferimenti di citazione quando usa informazioni dal risultato di ricerca. Questo abilita:
- Citazioni naturali per le tue applicazioni RAG personalizzate
- Attribuzione della fonte quando si interfaccia con basi di conoscenza proprietarie
- Citazioni di qualità da ricerca web per qualsiasi strumento personalizzato che restituisce risultati di ricerca
Se il campo citations
è omesso, le citazioni sono disabilitate per impostazione predefinita.
Le citazioni sono tutto-o-niente: o tutti i risultati di ricerca in una richiesta devono avere le citazioni abilitate, o tutti devono averle disabilitate. Mescolare risultati di ricerca con impostazioni di citazione diverse risulterà in un errore. Se hai bisogno di disabilitare le citazioni per alcune fonti, devi disabilitarle per tutti i risultati di ricerca in quella richiesta.
Migliori pratiche
Per ricerca basata su strumenti (Metodo 1)
- Contenuto dinamico: Usa per ricerche in tempo reale e applicazioni RAG dinamiche
- Gestione degli errori: Restituisci messaggi appropriati quando le ricerche falliscono
- Limiti dei risultati: Restituisci solo i risultati più rilevanti per evitare overflow del contesto
Per ricerca di primo livello (Metodo 2)
- Contenuto pre-recuperato: Usa quando hai già risultati di ricerca
- Elaborazione batch: Ideale per elaborare risultati di ricerca multipli in una volta
- Test: Ottimo per testare il comportamento delle citazioni con contenuto noto
Migliori pratiche generali
-
Struttura i risultati efficacemente
- Usa URL di fonte chiari e permanenti
- Fornisci titoli descrittivi
- Dividi contenuto lungo in blocchi di testo logici
-
Mantieni coerenza
- Usa formati di fonte coerenti attraverso la tua applicazione
- Assicurati che i titoli riflettano accuratamente il contenuto
- Mantieni formattazione coerente
-
Gestisci gli errori con grazia
Limitazioni
- I blocchi di contenuto dei risultati di ricerca sono disponibili solo con l’header beta
- Solo contenuto di testo è supportato all’interno dei risultati di ricerca (nessuna immagine o altri media)
- L’array
content
deve contenere almeno un blocco di testo