Премини към основното съдържание
Български— Изберете език
Меню

Крайната точка за търсене на документи

Урок 9 от 16 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Заявки към Вашите бази от знания
  2. Структура на заявката
  3. Четене на отговора
  4. Търсене в няколко колекции
  5. Разходи
  6. Ключови изводи

Заявки към Вашите бази от знания

Досега изградихте контейнера: колекции, индексирани документи, метаданни. Нищо от това няма значение, освен ако не знаете как да зададете въпрос. Това е задачата на POST /v1/documents/search, който приема заявка на естествен език и връща откъсите от Вашите документи, които отговарят най-добре на нея. Представете си екип за поддръжка, който получава въпроса „Какъв е срокът за отказ?“. Вместо да карате агент да чете общите условия, Вие изпращате въпроса до крайната точка и извличате трите полезни параграфа, заедно с тяхната оценка и източник.

POST
/v1/documents/search
3 режима
ключови думи, семантичен, хибриден
$2.50
На 1000 обаждания
Множествен
Няколко колекции

Структура на заявката

Първото нещо, което трябва да запомните, и това е често срещан източник на грешки: тази крайна точка се намира в стандартния 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 обаждания, четири пъти по-евтино от прикачването на файлове.