Punkt końcowy wyszukiwania dokumentów
Na tej stronie
Odpytywanie Twoich baz wiedzy
Do tej pory zbudowałeś kontener: kolekcje, zindeksowane dokumenty, metadane. Nic z tego nie ma znaczenia, jeśli nie wiesz, jak zadać pytanie. To właśnie zadanie dla POST /v1/documents/search, który przyjmuje zapytanie w języku naturalnym i zwraca fragmenty Twoich dokumentów, które najlepiej na nie odpowiadają. Wyobraź sobie zespół wsparcia, który otrzymuje pytanie: „Jaki jest okres odstąpienia od umowy?“. Zamiast kazać agentowi czytać regulamin, wysyłasz to pytanie do punktu końcowego i pobierasz trzy przydatne akapity, wraz z ich wynikiem i źródłem.
Struktura żądania
Pierwsza rzecz, o której musisz pamiętać, a która jest częstym źródłem błędów: ten punkt końcowy znajduje się w standardowym API (api.x.ai), a nie w API zarządzania, którego używałeś do tworzenia kolekcji. Uwierzytelniasz się za pomocą swojego zwykłego klucza API. Minimalne żądanie sprowadza się do trzech pól.
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"
}
}'
Główne parametry
- query: Twoje pytanie w języku naturalnym. Im bardziej szczegółowe pytanie, tym trafniejsze wyniki.
- source.collection_ids: tablica identyfikatorów kolekcji do odpytania. Możesz przeszukiwać wiele kolekcji w ramach jednego żądania.
- retrieval_mode.type: tryb wyszukiwania do użycia (
keyword,semanticlubhybrid).
Analiza odpowiedzi
API nie zwraca całych dokumentów, lecz fragmenty – bloki utworzone podczas indeksowania – uszeregowane od najbardziej do najmniej trafnych.
{
"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
}
}
]
}
Każdy wpis zawiera cztery informacje:
- content: fragment tekstu z dokumentu
- score: wynik trafności od 0 do 1
- document_id: identyfikator pliku źródłowego
- metadata: metadane dokumentu (nazwa, strona, pola niestandardowe)
W powyższym przykładzie pierwszy fragment pochodzi ze strony 12 pliku security-guide.pdf z wynikiem 0,92, a drugi ze strony 45 innego pliku z wynikiem 0,87. Te dwie wartości wystarczą, aby zbudować interfejs wyświetlający odpowiedź, a tuż pod nim link „zobacz oryginalny fragment, strona 12“. Wynik działa jako próg: wiele zespołów odrzuca każdy wynik poniżej 0,5, zamiast pozwalać modelowi rozumować na szumie.
Wyszukiwanie w wielu kolekcjach
Fakt, że collection_ids jest tablicą, nie jest przypadkowy. Pytanie klienta często dotyczy kilku różnych obszarów dokumentacji, a Ty nie chcesz wykonywać trzech oddzielnych wywołań, by potem ręcznie scalać wyniki.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Tutaj dokumentacja produktu, FAQ oraz regulamin są odpytywane jednocześnie. Wyniki wracają scalone i posortowane według wyniku, niezależnie od ich oryginalnej kolekcji: fragment z FAQ z wynikiem 0,94 znajdzie się wyżej niż fragment z regulaminu z wynikiem 0,71. Łączysz heterogeniczne źródła w ramach jednego cyklu sieciowego.
Koszt
Wyszukiwanie w kolekcjach kosztuje 2,50 USD za 1000 wywołań, a stawka ta nie zmienia się w zależności od liczby odpytywanych kolekcji ani rozmiaru zindeksowanych dokumentów. Porównaj to z załącznikami plików, czyli pojedynczymi plikami przekazywanymi przez input_file, rozliczanymi po 10 USD za 1000 wywołań: gdy tylko zaczniesz wielokrotnie odpytywać te same dokumenty, kolekcje są czterokrotnie tańsze. Wewnętrzny asystent obsługujący 20 000 pytań miesięcznie zapłaci 50 USD przy użyciu kolekcji wobec 200 USD przy użyciu załączników – i to w dodatku uzyska szybsze wyniki, ponieważ indeks już istnieje.
Cennik z dnia 5 sierpnia 2026 r. – ceny zmieniają się regularnie: przed jakimkolwiek obliczeniem budżetu sprawdź aktualny cennik na oficjalnej stronie modeli i cennika xAI.
Kluczowe wnioski
- Punkt końcowy
POST /v1/documents/searchodpytuje Twoje kolekcje w języku naturalnym - Dostępne są trzy tryby wyszukiwania: słowa kluczowe, semantyczny, hybrydowy
- Możesz przeszukiwać wiele kolekcji jednocześnie
- Wyniki są rankowane według wyniku trafności wraz z treścią źródłową
- Koszt wynosi 2,50 USD za 1000 wywołań, co jest czterokrotnie tańsze niż załączniki plików