Крайната точка за търсене на документи
На тази страница
Заявки към Вашите бази от знания
Досега изградихте контейнера: колекции, индексирани документи, метаданни. Нищо от това няма значение, освен ако не знаете как да зададете въпрос. Това е задачата на POST /v1/documents/search, който приема заявка на естествен език и връща откъсите от Вашите документи, които отговарят най-добре на нея. Представете си екип за поддръжка, който получава въпроса „Какъв е срокът за отказ?“. Вместо да карате агент да чете общите условия, Вие изпращате въпроса до крайната точка и извличате трите полезни параграфа, заедно с тяхната оценка и източник.
Структура на заявката
Първото нещо, което трябва да запомните, и това е често срещан източник на грешки: тази крайна точка се намира в стандартния API (api.x.ai), а не в Management API, който сте използвали за създаване на колекции. Удостоверявате се с обичайния си API ключ. Минималната заявка се свежда до три полета.
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"
}
}'
Основни параметри
- query: Вашият въпрос на естествен език. Колкото по-конкретен е въпросът, толкова по-релевантни са резултатите.
- source.collection_ids: масив от ID-та на колекции, които да се търсят. Можете да търсите в няколко колекции с една заявка.
- retrieval_mode.type: режимът на търсене, който да се използва (
keyword,semanticилиhybrid).
Четене на отговора
API не връща цели документи, а фрагменти – парчетата, създадени по време на индексирането, подредени от най-релевантните към най-малко релевантните.
{
"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
}
}
]
}
Всеки запис съдържа четири части информация:
- content: текстовият откъс от документа.
- score: оценка за релевантност между 0 и 1.
- document_id: ID-то на изходния файл.
- metadata: метаданните на документа (име, страница, персонализирани полета).
В горния пример първият откъс идва от страница 12 на security-guide.pdf с оценка 0.92, а вторият – от страница 45 на друг файл с оценка 0.87. Тези две стойности са достатъчни, за да изградите интерфейс, който показва отговора и точно под него връзка „виж оригиналния откъс, страница 12“. Оценката действа като праг: много екипи отхвърлят всеки резултат под 0.5, вместо да позволяват на модела да разсъждава върху шум.
Търсене в няколко колекции
Ако collection_ids е масив, това не е случайно. Въпрос на клиент често смесва няколко вселени от документи и Вие не искате да правите три обаждания, след което да обединявате резултатите на ръка.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Тук продуктовата документация, ЧЗВ и общите условия се търсят заедно. Резултатите се връщат обединени и сортирани по оценка, независимо от първоначалната им колекция: откъс от ЧЗВ с оценка 0.94 ще се класира по-високо от откъс от общите условия с оценка 0.71. Вие кръстосвате хетерогенни източници в едно единствено мрежово пътуване.
Разходи
Търсенето в колекции струва $2.50 на 1000 обаждания и тази тарифа не се променя въз основа на броя на търсените колекции или размера на индексираните документи. Сравнете това с прикачването на файлове – онези индивидуални файлове, предавани чрез input_file, таксувани на $10 на 1000 обаждания: щом започнете да търсите едни и същи документи многократно, колекциите струват четири пъти по-малко. Вътрешен асистент, обработващ 20 000 въпроса на месец, плаща $50 с колекции срещу $200 с прикачени файлове – и получава по-бързи резултати в добавка, тъй като индексът вече съществува.
Цени към 5 август 2026 г. – цените се променят редовно: преди всяко изчисление на бюджета проверете текущата ценова листа на официалната страница за модели и цени на xAI.
Ключови изводи
- Крайната точка
POST /v1/documents/searchправи заявки към Вашите колекции на естествен език. - Налични са три режима на търсене: ключови думи, семантичен, хибриден.
- Можете да търсите в няколко колекции едновременно.
- Резултатите се класират по оценка за релевантност със съдържанието на източника.
- Цената е $2.50 на 1000 обаждания, четири пъти по-евтино от прикачването на файлове.