Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Slutpunkten för dokumentsökning

Lektion 9 av 16 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Fråga dina kunskapsbaser
  2. Struktur för begäran
  3. Läsa svaret
  4. Söka över flera samlingar
  5. Kostnad
  6. Viktiga punkter

Fråga dina kunskapsbaser

Hittills har du byggt containern: samlingar, indexerade dokument och metadata. Inget av detta spelar någon roll om du inte vet hur du ställer en fråga. Det är jobbet för POST /v1/documents/search, som tar en fråga på naturligt språk och returnerar de utdrag från dina dokument som bäst besvarar den. Tänk dig ett supportteam som får frågan “Vad är ångerrätten?”. Istället för att låta en agent läsa igenom de allmänna villkoren skickar du frågan till slutpunkten och hämtar de tre användbara styckena, kompletta med deras poäng och källa.

POST
/v1/documents/search
3 lägen
nyckelord, semantisk, hybrid
$2.50
Per 1 000 anrop
Multi
Flera samlingar

Struktur för begäran

Det första du måste komma ihåg, och detta är en vanlig felkälla: denna slutpunkt finns på det vanliga API:t (api.x.ai), inte på hanterings-API:t som du använde för att skapa samlingar. Du autentiserar med din vanliga API-nyckel. Den minimala begäran reduceras till tre fält.

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

Huvudparametrar

  • query: din fråga på naturligt språk. Ju mer specifik frågan är, desto mer relevanta blir resultaten.
  • source.collection_ids: en array med samlings-ID:n att söka i. Du kan söka över flera samlingar i en enda begäran.
  • retrieval_mode.type: sökläget som ska användas (keyword, semantic eller hybrid).

Läsa svaret

API:t returnerar inte hela dokument utan fragment, de bitar som skapades under indexeringen, rankade från mest till minst relevanta.

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

Varje post innehåller fyra informationsbitar:

  • content: textutdraget från dokumentet
  • score: en relevanspoäng mellan 0 och 1
  • document_id: ID:t för källfilen
  • metadata: dokumentets metadata (namn, sida, anpassade fält)

I exemplet ovan kommer det första utdraget från sida 12 i security-guide.pdf med en poäng på 0,92, och det andra från sida 45 i en annan fil med 0,87. Dessa två värden räcker för att bygga ett gränssnitt som visar svaret och, strax under det, en länk “visa ursprungligt utdrag, sida 12”. Poängen fungerar som ett tröskelvärde: många team kasserar alla resultat under 0,5 istället för att låta modellen resonera kring brus.

Söka över flera samlingar

Att collection_ids är en array är ingen slump. En kundfråga blandar ofta flera dokumentuniversum, och du vill inte göra tre anrop och sedan slå ihop resultaten manuellt.

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

Här frågas produktdokumentation, FAQ och allmänna villkor av samtidigt. Resultaten returneras sammanslagna och sorterade efter poäng, oavsett vilken samling de ursprungligen kom från: ett FAQ-utdrag på 0,94 rankas högre än ett utdrag från de allmänna villkoren på 0,71. Du korsar heterogena källor i en enda nätverksomgång.

Kostnad

Att söka i samlingar kostar $2,50 per 1 000 anrop, och denna taxa ändras inte baserat på antalet samlingar som frågas eller storleken på de indexerade dokumenten. Jämför detta med filbilagor, de enskilda filer som skickas via input_file, som debiteras med $10 per 1 000 anrop: så snart du frågar samma dokument upprepade gånger kostar samlingar fyra gånger mindre. En intern assistent som hanterar 20 000 frågor per månad betalar $50 med samlingar jämfört med $200 med bilagor – och får snabbare resultat på köpet, eftersom indexet redan finns.

Priser från och med den 5 augusti 2026 — priser ändras regelbundet: innan du gör någon budgetberäkning, kontrollera den aktuella prislistan på den officiella sidan för xAI-modeller och prissättning.

Viktiga punkter

  • Slutpunkten POST /v1/documents/search frågar dina samlingar på naturligt språk
  • Tre söklägen tillgängliga: nyckelord, semantisk, hybrid
  • Du kan söka över flera samlingar samtidigt
  • Resultaten rankas efter relevanspoäng med källinnehåll
  • Kostnaden är $2,50 per 1 000 anrop, fyra gånger billigare än filbilagor