L'endpoint di ricerca documenti
In questa pagina
Interrogare le tue basi di conoscenza
Finora hai costruito il contenitore: collezioni, documenti indicizzati, metadati. Nulla di tutto ciò ha importanza se non sai come porre una domanda. È questo il compito di POST /v1/documents/search, che accetta una query in linguaggio naturale e restituisce i passaggi dei tuoi documenti che rispondono nel modo migliore. Immagina un team di supporto che riceve la domanda “Qual è il periodo di recesso?”. Invece di far leggere all’agente i termini e le condizioni, invii la domanda all’endpoint e recuperi i tre paragrafi utili, completi del loro punteggio e della fonte.
Struttura della richiesta
La prima cosa da ricordare, e questa è una fonte comune di errori: questo endpoint risiede sull’API standard (api.x.ai), non sull’API di gestione che hai usato per creare le collezioni. Ti autentichi con la tua solita chiave API. La richiesta minima si riduce a tre campi.
curl -X POST https://api.x.ai/v1/documents/search \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "How do I configure OAuth authentication?",
"source": {
"collection_ids": ["col_xyz789"]
},
"retrieval_mode": {
"type": "hybrid"
}
}'
Parametri principali
- query: la tua domanda in linguaggio naturale. Più specifica è la domanda, più rilevanti saranno i risultati.
- source.collection_ids: un array di ID collezione da interrogare. Puoi cercare su più collezioni in una singola richiesta.
- retrieval_mode.type: la modalità di ricerca da utilizzare (
keyword,semanticohybrid).
Leggere la risposta
L’API non restituisce interi documenti ma frammenti, i chunk creati durante l’indicizzazione, classificati dal più al meno rilevante.
{
"results": [
{
"content": "To configure OAuth, start by...",
"score": 0.92,
"document_id": "file_abc123",
"metadata": {
"filename": "security-guide.pdf",
"page": 12
}
},
{
"content": "The OAuth 2.0 flow uses...",
"score": 0.87,
"document_id": "file_def456",
"metadata": {
"filename": "api-reference.pdf",
"page": 45
}
}
]
}
Ogni voce contiene quattro informazioni:
- content: l’estratto di testo dal documento.
- score: un punteggio di rilevanza tra 0 e 1.
- document_id: l’ID del file sorgente.
- metadata: i metadati del documento (nome, pagina, campi personalizzati).
Nell’esempio sopra, il primo estratto proviene dalla pagina 12 di security-guide.pdf con un punteggio di 0,92, il secondo dalla pagina 45 di un altro file a 0,87. Questi due valori sono sufficienti per costruire un’interfaccia che mostri la risposta e, subito sotto, un link “visualizza passaggio originale, pagina 12”. Il punteggio funge da soglia: molti team scartano qualsiasi risultato inferiore a 0,5 invece di lasciare che il modello ragioni sul rumore.
Cercare su più collezioni
Se collection_ids è un array, non è un caso. Una domanda del cliente spesso mescola diversi universi documentali e non vuoi fare tre chiamate per poi unire i risultati a mano.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Qui vengono interrogate insieme la documentazione del prodotto, le FAQ e i termini e condizioni. I risultati tornano uniti e ordinati per punteggio, indipendentemente dalla collezione di origine: un estratto delle FAQ a 0,94 si classificherà sopra un estratto dei T&C a 0,71. Incroci fonti eterogenee in un singolo round-trip di rete.
Costo
La ricerca nelle collezioni costa $2,50 per 1.000 chiamate e questa tariffa non cambia in base al numero di collezioni interrogate o alla dimensione dei documenti indicizzati. Confrontalo con gli allegati di file, quei singoli file passati tramite input_file, fatturati a $10 per 1.000 chiamate: non appena interroghi ripetutamente gli stessi documenti, le collezioni costano quattro volte meno. Un assistente interno che gestisce 20.000 domande al mese paga $50 con le collezioni contro $200 con gli allegati, ottenendo per di più risultati più veloci, poiché l’indice esiste già.
Prezzi aggiornati al 5 agosto 2026 — i prezzi cambiano regolarmente: prima di qualsiasi calcolo di budget, controlla il listino prezzi attuale sulla pagina ufficiale dei modelli e dei prezzi xAI.
Punti chiave
- L’endpoint
POST /v1/documents/searchinterroga le tue collezioni in linguaggio naturale. - Tre modalità di ricerca disponibili: keyword, semantic, hybrid.
- Puoi cercare su più collezioni simultaneamente.
- I risultati sono classificati per punteggio di rilevanza con il contenuto sorgente.
- Il costo è di $2,50 per 1.000 chiamate, quattro volte meno degli allegati di file.