L-endpoint ta' tfittxija tad-dokumenti
F'din il-paġna
Tistaqsi l-bażijiet tal-għarfien tiegħek
S’issa bnejt il-kontenitur: kollezzjonijiet, dokumenti indiċjati, metadata. Xejn minn dan ma jimporta jekk ma tkunx taf kif tistaqsi mistoqsija. Din hija l-ħidma ta’ POST /v1/documents/search, li jieħu mistoqsija b’lingwa naturali u jirritorna l-passaġġi mid-dokumenti tiegħek li jwieġbuha l-aħjar. Imaġina tim ta’ appoġġ li jirċievi “X’inhu l-perjodu ta’ rtirar?” Minflok ma tħalli aġent jaqra t-termini u l-kundizzjonijiet, tibgħat il-mistoqsija lill-endpoint u tirrikupra t-tliet paragrafi utli, kompleti bil-punteġġ u s-sors tagħhom.
Struttura tat-talba
L-ewwel ħaġa li għandek tiftakar, u din hija sors komuni ta’ żbalji: dan l-endpoint jinsab fuq l-API standard (api.x.ai), mhux fuq il-Management API li użajt biex toħloq il-kollezzjonijiet. Tawtentika bl-API key tas-soltu tiegħek. It-talba minima tinżel għal tliet oqsma.
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 ewlenin
- query: il-mistoqsija tiegħek b’lingwa naturali. Kemm tkun aktar speċifika l-mistoqsija, ikunu aktar rilevanti r-riżultati
- source.collection_ids: array ta’ IDs tal-kollezzjonijiet li trid tistaqsi. Tista’ tfittex f’diversi kollezzjonijiet f’talba waħda
- retrieval_mode.type: il-modalità ta’ tfittxija li għandek tuża (
keyword,semantic, jewhybrid)
Kif taqra r-rispons
L-API ma tirritornax dokumenti sħaħ iżda frammenti, il-biċċiet maħluqa waqt l-indiċjar, ikklassifikati mill-aktar rilevanti għall-inqas.
{
"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
}
}
]
}
Kull entrata ġġorr erba’ biċċiet ta’ informazzjoni:
- content: l-estratt tat-test mid-dokument
- score: punteġġ ta’ rilevanza bejn 0 u 1
- document_id: l-ID tal-fajl tas-sors
- metadata: il-metadata tad-dokument (isem, paġna, oqsma personalizzati)
Fl-eżempju hawn fuq, l-ewwel estratt ġej mill-paġna 12 ta’ security-guide.pdf b’punteġġ ta’ 0.92, it-tieni mill-paġna 45 ta’ fajl ieħor b’0.87. Dawn iż-żewġ valuri huma biżżejjed biex tibni interfaċċa li turi t-tweġiba u, eżatt taħtha, link “ara l-passaġġ oriġinali, paġna 12”. Il-punteġġ jaġixxi bħala limitu: ħafna timijiet jarmaw kwalunkwe riżultat taħt 0.5 minflok ma jħallu l-mudell jirraġuna fuq storbju.
Tfittxija f’diversi kollezzjonijiet
Jekk collection_ids huwa array, dan mhux aċċident. Mistoqsija ta’ klijent spiss taħlit diversi universi ta’ dokumenti, u ma tridx tagħmel tliet sejħiet imbagħad tgħaqqad ir-riżultati bl-idejn.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Hawnhekk, id-dokumentazzjoni tal-prodott, il-FAQ, u t-termini u l-kundizzjonijiet jiġu mistoqsija flimkien. Ir-riżultati jerġgħu lura magħquda u ssortjati skont il-punteġġ, irrispettivament mill-kollezzjoni oriġinali tagħhom: estratt mill-FAQ b’0.94 se jkun ikklassifikat ‘il fuq minn estratt mit-T&C b’0.71. Inti taqsam sorsi eteroġenji f’vjaġġ wieħed tan-netwerk.
Kost
It-tfittxija fil-kollezzjonijiet tispiċċa $2.50 kull 1,000 sejħa, u din ir-rata ma tinbidilx ibbażata fuq in-numru ta’ kollezzjonijiet mistoqsija jew id-daqs tad-dokumenti indiċjati. Qabbel dan mal-annessjonijiet tal-fajls, dawk il-fajls individwali mgħoddija permezz ta’ input_file, iffatturati b’$10 kull 1,000 sejħa: malli tistaqsi l-istess dokumenti ripetutament, il-kollezzjonijiet jiswew erba’ darbiet inqas. Assistent intern li jittratta 20,000 mistoqsija fix-xahar iħallas $50 bil-kollezzjonijiet meta mqabbel ma’ $200 bl-annessjonijiet—u jikseb riżultati aktar mgħaġġla bħala bonus, peress li l-indiċi diġà jeżisti.
Prezzijiet sal-5 ta’ Awwissu 2026 — il-prezzijiet jinbidlu regolarment: qabel kwalunkwe kalkolu tal-baġit, iċċekkja l-karta tar-rati attwali fuq il-paġna uffiċjali tal-mudelli u l-prezzijiet ta’ xAI.
Punti Ewlenin
- L-endpoint
POST /v1/documents/searchjistaqsi l-kollezzjonijiet tiegħek b’lingwa naturali - Tliet modalitajiet ta’ tfittxija disponibbli: keyword, semantic, hybrid
- Tista’ tfittex f’diversi kollezzjonijiet simultanjament
- Ir-riżultati huma kklassifikati skont il-punteġġ ta’ rilevanza bil-kontenut tas-sors
- Il-kost huwa $2.50 kull 1,000 sejħa, erba’ darbiet irħas mill-annessjonijiet tal-fajls