Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-endpoint ta' tfittxija tad-dokumenti

Lezzjoni 9 / 16 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Tistaqsi l-bażijiet tal-għarfien tiegħek
  2. Struttura tat-talba
  3. Kif taqra r-rispons
  4. Tfittxija f’diversi kollezzjonijiet
  5. Kost
  6. Punti Ewlenin

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.

POST
/v1/documents/search
3 modes
keyword, semantic, hybrid
$2.50
Per 1,000 calls
Multi
Multiple collections

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, jew hybrid)

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/search jistaqsi 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