Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Het eindpunt voor documentzoekopdrachten

Les 9 van 16 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Uw kennisbanken bevragen
  2. Structuur van het verzoek
  3. Het antwoord lezen
  4. Zoeken in meerdere collecties
  5. Kosten
  6. Belangrijkste punten

Uw kennisbanken bevragen

Tot nu toe heeft u de container gebouwd: collecties, geïndexeerde documenten en metadata. Dit alles is nutteloos tenzij u weet hoe u een vraag moet stellen. Dat is de taak van POST /v1/documents/search. Dit eindpunt accepteert een query in natuurlijke taal en retourneert de fragmenten uit uw documenten die het beste antwoord geven. Stel u een supportteam voor dat de vraag “Wat is de bedenktijd?” ontvangt. In plaats van een agent de algemene voorwaarden te laten lezen, stuurt u de vraag naar het eindpunt en haalt u de drie bruikbare alinea’s op, compleet met hun score en bron.

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

Structuur van het verzoek

Onthoud als eerste, en dit is een veelvoorkomende foutenbron: dit eindpunt bevindt zich op de standaard-API (api.x.ai), niet op de Management-API die u gebruikte om collecties aan te maken. U verifieert zich met uw gebruikelijke API-sleutel. Het minimale verzoek komt neer op drie velden.

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"
    }
  }'

Belangrijkste parameters

  • query: uw vraag in natuurlijke taal. Hoe specifieker de vraag, hoe relevanter de resultaten.
  • source.collection_ids: een array van collectie-ID’s om te bevragen. U kunt in één verzoek door meerdere collecties zoeken.
  • retrieval_mode.type: de te gebruiken zoekmodus (keyword, semantic of hybrid).

Het antwoord lezen

De API retourneert geen volledige documenten, maar fragmenten: de chunks die tijdens het indexeren zijn gemaakt, gerangschikt van meest naar minst relevant.

{
  "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
      }
    }
  ]
}

Elke vermelding bevat vier informatieonderdelen:

  • content: het tekstfragment uit het document
  • score: een relevantiescore tussen 0 en 1
  • document_id: de ID van het bronbestand
  • metadata: de documentmetadata (naam, pagina, aangepaste velden)

In het bovenstaande voorbeeld komt het eerste fragment van pagina 12 van security-guide.pdf met een score van 0,92; het tweede van pagina 45 van een ander bestand met 0,87. Deze twee waarden volstaan om een interface te bouwen die het antwoord weergeeft en direct daaronder een link “bekijk origineel fragment, pagina 12”. De score fungeert als drempelwaarde: veel teams verwerpen elk resultaat onder de 0,5 in plaats van het model op ruis te laten redeneren.

Zoeken in meerdere collecties

Als collection_ids een array is, is dat geen toeval. Een klantvraag combineert vaak verschillende documentwerelden, en u wilt niet drie oproepen doen en de resultaten vervolgens handmatig samenvoegen.

{
  "query": "Refund policy",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Hier worden productdocumentatie, de veelgestelde vragen (FAQ) en de algemene voorwaarden samen bevraagd. De resultaten komen samengevoegd en gesorteerd op score terug, ongeacht hun oorspronkelijke collectie: een FAQ-fragment met 0,94 staat hoger dan een fragment uit de algemene voorwaarden met 0,71. U doorzoekt heterogene bronnen in één netwerkomloop.

Kosten

Het doorzoeken van collecties kost $2,50 per 1.000 oproepen. Dit tarief verandert niet op basis van het aantal bevraagde collecties of de grootte van de geïndexeerde documenten. Vergelijk dit met bijlagen: individuele bestanden die via input_file worden doorgegeven en gefactureerd worden tegen $10 per 1.000 oproepen. Zodra u dezelfde documenten herhaaldelijk bevraagt, zijn collecties vier keer goedkoper. Een interne assistent die 20.000 vragen per maand afhandelt, betaalt $50 met collecties tegenover $200 met bijlagen – en krijgt bovendien snellere resultaten, omdat de index al bestaat.

Prijzen per 5 augustus 2026 – prijzen wijzigen regelmatig: controleer voor elke budgetberekening de actuele tarievenlijst op de officiële xAI-pagina voor modellen en prijzen.

Belangrijkste punten

  • Het eindpunt POST /v1/documents/search bevraagt uw collecties in natuurlijke taal
  • Drie zoekmodi beschikbaar: trefwoord, semantisch, hybride
  • U kunt gelijktijdig door meerdere collecties zoeken
  • Resultaten worden gerangschikt op relevantiescore met broninhoud
  • Kosten bedragen $2,50 per 1.000 oproepen, vier keer goedkoper dan bestandsbijlagen