Das Endpunkt für Dokumentensuchen
Auf dieser Seite
Abfragen Ihrer Wissensdatenbanken
Bisher haben Sie den Container aufgebaut: Sammlungen, indizierte Dokumente, Metadaten. All dies ist jedoch bedeutungslos, wenn Sie nicht wissen, wie Sie eine Frage stellen. Dies ist die Aufgabe des Endpunkts POST /v1/documents/search, der eine natürliche Sprachabfrage entgegennimmt und die Abschnitte aus Ihren Dokumenten zurückgibt, die diese am besten beantworten. Stellen Sie sich ein Support-Team vor, das die Frage „Was ist die Rückgabefrist?” erhält. Anstatt einen Agenten anweisen zu lassen, die Allgemeinen Geschäftsbedingungen zu lesen, senden Sie die Frage an den Endpunkt und erhalten die drei nützlichen Abschnitte zurück, vollständig mit ihrem Score und der Quelle.
Anforderungsstruktur
Erinnern Sie sich zunächst an einen wichtigen Punkt, der eine häufige Fehlerquelle ist: Dieser Endpunkt befindet sich auf der Standard-API (api.x.ai) und nicht auf der Management-API, die Sie zur Erstellung von Sammlungen verwendet haben. Sie authentifizieren sich mit Ihrem üblichen API-Schlüssel. Die minimale Anforderung reduziert sich auf drei Felder.
curl -X POST https://api.x.ai/v1/documents/search \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Wie konfiguriere ich die OAuth-Authentifizierung?",
"source": {
"collection_ids": ["col_xyz789"]
},
"retrieval_mode": {
"type": "hybrid"
}
}'
Hauptparameter
- query: Ihre Frage in natürlicher Sprache. Je spezifischer die Frage, desto relevanter sind die Ergebnisse.
- source.collection_ids: Ein Array von Sammlungs-IDs, die abgefragt werden sollen. Sie können über mehrere Sammlungen in einer einzigen Anforderung suchen.
- retrieval_mode.type: Der Suchmodus, der verwendet werden soll (
keyword,semanticoderhybrid).
Antwort lesen
Die API gibt keine vollständigen Dokumente zurück, sondern Fragmente, die während der Indizierung erstellt wurden, sortiert von höchster zu niedrigster Relevanz.
{
"results": [
{
"content": "Um OAuth zu konfigurieren, beginnen Sie mit...",
"score": 0,92,
"document_id": "file_abc123",
"metadata": {
"filename": "security-guide.pdf",
"page": 12
}
},
{
"content": "Der OAuth 2,0-Flow verwendet...",
"score": 0,87,
"document_id": "file_def456",
"metadata": {
"filename": "api-reference.pdf",
"page": 45
}
}
]
}
Jeder Eintrag enthält vier Informationen:
- content: Der Textausschnitt aus dem Dokument.
- score: Ein Relevanzscore zwischen 0 und 1.
- document_id: Die ID der Quelldatei.
- metadata: Die Dokumentmetadaten (Name, Seite, benutzerdefinierte Felder).
Im obigen Beispiel stammt der erste Ausschnitt aus Seite 12 von security-guide.pdf mit einem Score von 0,92, der zweite aus Seite 45 einer anderen Datei mit 0,87. Diese beiden Werte reichen aus, um eine Schnittstelle zu erstellen, die die Antwort anzeigt und direkt darunter einen Link „Originalpassage anzeigen, Seite 12”. Der Score fungiert als Schwellenwert: Viele Teams verwerfen jedes Ergebnis unter 0,5, anstatt dem Modell zu erlauben, auf Rauschen zu schließen.
Suche über mehrere Sammlungen hinweg
Wenn collection_ids ein Array ist, liegt das nicht am Zufall. Eine Kundenfrage mischt oft mehrere Dokumentuniversen, und Sie möchten nicht drei Aufrufe tätigen und die Ergebnisse dann manuell zusammenführen.
{
"query": "Rückgabepolitik",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Hier werden Produktdokumentation, die FAQ und die Allgemeinen Geschäftsbedingungen gemeinsam abgefragt. Die Ergebnisse kommen zurück, zusammengeführt und nach Score sortiert, unabhängig von ihrer ursprünglichen Sammlung: Ein FAQ-Ausschnitt mit 0,94 wird über einem AGB-Ausschnitt mit 0,71 rangieren. Sie durchsuchen heterogene Quellen in einer einzigen Netzwerk-Rundreise.
Kosten
Die Suche in Sammlungen kostet $2,50 pro 1.000 Aufrufe, und dieser Satz ändert sich nicht basierend auf der Anzahl der abgefragten Sammlungen oder der Größe der indizierten Dokumente. Vergleichen Sie dies mit Dateianhängen, diesen einzelnen Dateien, die über input_file übermittelt werden, die mit $10 pro 1.000 Aufrufe abgerechnet werden: Sobald Sie dieselben Dokumente wiederholt abfragen, kosten Sammlungen viermal weniger. Ein interner Assistent, der 20.000 Fragen pro Monat bearbeitet, zahlt $50 mit Sammlungen gegenüber $200 mit Anhängen – und erhält zudem schnellere Ergebnisse, da der Index bereits existiert.
Preise Stand 5. August 2026 — Preise ändern sich regelmäßig: Bevor Sie eine Budgetberechnung durchführen, überprüfen Sie den aktuellen Tarif auf der offiziellen Seite für xAI-Modelle und Preise.
Kernaussagen
- Der Endpunkt
POST /v1/documents/searchabfragt Ihre Sammlungen in natürlicher Sprache. - Drei Suchmodi verfügbar: Keyword, semantisch, hybrid.
- Sie können gleichzeitig über mehrere Sammlungen suchen.
- Ergebnisse werden nach Relevanzscore mit Quellinhalt sortiert.
- Kosten betragen $2,50 pro 1.000 Aufrufe, viermal günstiger als Dateianhänge.