Endpointul de căutare în documente
Pe această pagină
Interogarea bazelor dumneavoastră de cunoștințe
Până acum, ați construit containerul: colecții, documente indexate, metadate. Nimic din toate acestea nu contează dacă nu știți cum să puneți o întrebare. Acesta este rolul endpointului POST /v1/documents/search, care primește o interogare în limbaj natural și returnează pasajele din documentele dumneavoastră care răspund cel mai bine la aceasta. Imaginați-vă o echipă de suport care primește întrebarea „Care este perioada de retragere?“. În loc să obligați un agent să citească termenii și condițiile, trimiteți întrebarea către endpoint și recuperați cele trei paragrafe utile, complete cu scorul și sursa lor.
Structura cererii
Primul lucru de reținut, și aceasta este o sursă frecventă de erori: acest endpoint se află pe API-ul standard (api.x.ai), nu pe API-ul de Management pe care l-ați folosit pentru a crea colecții. Vă autentificați cu cheia dumneavoastră API obișnuită. Cererea minimă se reduce la trei câmpuri.
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"
}
}'
Parametrii principali
- query: întrebarea dumneavoastră în limbaj natural. Cu cât întrebarea este mai specifică, cu atât rezultatele sunt mai relevante.
- source.collection_ids: un tablou de ID-uri de colecții pentru interogare. Puteți căuta în mai multe colecții într-o singură cerere.
- retrieval_mode.type: modul de căutare de utilizat (
keyword,semanticsauhybrid).
Citirea răspunsului
API-ul nu returnează documente întregi, ci fragmente – chunk-urile create în timpul indexării – clasate de la cele mai relevante la cele mai puțin relevante.
{
"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
}
}
]
}
Fiecare intrare conține patru informații:
- content: extrasul de text din document.
- score: un scor de relevanță între 0 și 1.
- document_id: ID-ul fișierului sursă.
- metadata: metadatele documentului (nume, pagină, câmpuri personalizate).
În exemplul de mai sus, primul extras provine de la pagina 12 a fișierului security-guide.pdf cu un scor de 0,92, iar al doilea de la pagina 45 a unui alt fișier, cu 0,87. Aceste două valori sunt suficiente pentru a construi o interfață care afișează răspunsul și, chiar sub acesta, un link de tipul „vezi pasajul original, pagina 12“. Scorul acționează ca un prag: multe echipe elimină orice rezultat sub 0,5 în loc să permită modelului să raționeze pe baza zgomotului.
Căutarea în mai multe colecții
Dacă collection_ids este un tablou, acest lucru nu este întâmplător. O întrebare a clientului amestecă adesea mai multe universuri documentare, iar dumneavoastră nu doriți să faceți trei apeluri și apoi să îmbinați rezultatele manual.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Aici, documentația produsului, FAQ-ul și termenii și condițiile sunt interogate împreună. Rezultatele revin îmbinate și sortate după scor, indiferent de colecția lor originală: un extras din FAQ cu 0,94 se va clasa înaintea unui extras din Termeni și Condiții cu 0,71. Traversați surse eterogene într-o singură dus-întors prin rețea.
Cost
Căutarea în colecții costă 2,50 USD per 1.000 de apeluri, iar această rată nu se modifică în funcție de numărul de colecții interogate sau de dimensiunea documentelor indexate. Comparați acest lucru cu atașamentele de fișiere, acele fișiere individuale transmise prin input_file, facturate la 10 USD per 1.000 de apeluri: de îndată ce interogați aceleași documente în mod repetat, colecțiile costă de patru ori mai puțin. Un asistent intern care gestionează 20.000 de întrebări pe lună plătește 50 USD cu colecții, față de 200 USD cu atașamente – și obține rezultate mai rapide pe deasupra, deoarece indexul există deja.
Prețuri valabile la 5 august 2026 — prețurile se modifică regulat: înainte de orice calcul bugetar, verificați grila tarifară actuală pe pagina oficială a modelelor și prețurilor xAI.
Puncte cheie
- Endpointul
POST /v1/documents/searchinterogează colecțiile dumneavoastră în limbaj natural. - Trei moduri de căutare disponibile: keyword, semantic, hybrid.
- Puteți căuta în mai multe colecții simultan.
- Rezultatele sunt clasate după scorul de relevanță, împreună cu conținutul sursei.
- Costul este de 2,50 USD per 1.000 de apeluri, de patru ori mai ieftin decât atașamentele de fișiere.