Поиск по базе знаний

Серверный инструмент aitunnel:file_search ищет по файлам, которые вы загрузили в базу знаний: модель формулирует запросы, получает найденные фрагменты и отвечает по ним.

Поиск исполняет AITUNNEL — своя векторная база и свой код поиска не нужны.

Тип
aitunnel:file_search в массиве tools
Обязательный параметр
knowledge_base_ids — от 1 до 5 баз
Где работает
/chat/completions, /responses, /messages
Цена
0,1 ₽ за поисковый запрос; реранкинг — по цене rerank-модели

Сначала — база знаний

Для запроса нужен id базы: он начинается с kb_ и собран из её названия, например kb_podderzhka-x7k3p9. Заполните описание базы: модель видит название и описание и по ним решает, искать ли в ней.

Быстрый старт

curl https://aitunnel.83.141.93.205.nip.io/__api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "user", "content": "Кто оплачивает доставку при возврате?" }
    ],
    "tools": [
      {
        "type": "aitunnel:file_search",
        "parameters": {
          "knowledge_base_ids": ["kb_podderzhka-x7k3p9"]
        }
      }
    ]
  }'

Модель сама решает, искать ли, формулирует запросы, читает найденные фрагменты и отвечает. Клиент получает один готовый ответ — как на обычный запрос. Найденных фрагментов в нём нет: их читает модель. Нужны сами фрагменты — вызовите поиск из кода, POST /knowledge-bases/{id}/search.

Параметры

JSON
{
  "tools": [
    {
      "type": "aitunnel:file_search",
      "parameters": {
        "knowledge_base_ids": ["kb_podderzhka-x7k3p9"],
        "max_results": 8,
        "rerank": true,
        "max_uses": 3
      }
    }
  ]
}
ПараметрТипПо умолчаниюОписание
knowledge_base_idsstring[]—Базы, по которым ищет модель: от 1 до 5. Обязательно
max_resultsinteger8Сколько фрагментов вернуть на каждый поисковый запрос: 1–20
rerankboolean или object—true — переранжировать результаты моделью базы или rerank-5-pro; false — никогда; { "model": "…" } — этой моделью. Не указан — решает настройка базы
max_usesinteger10Сколько раз модель может вызвать поиск за один запрос: 1–10

Как работает реранкинг и какая rerank-модель выбирается при rerank: true — в разделе как устроен поиск.

Инструмент можно сохранить в пресете — параметр file_search: тогда клиенту достаточно назвать пресет в поле model.

Сколько запросов за вызов

  • За один вызов инструмента модель может задать до 5 поисковых запросов. Каждый ищется отдельно, по всем базам из knowledge_base_ids, и возвращает до max_results фрагментов.
  • Рядом с каждым фрагментом модель видит путь файла в базе.
  • Вызовов за запрос — до max_uses (по умолчанию 10). Общий лимит вызовов file_search и datetime в запросе — max_tool_calls: см. лимиты вызовов.
  • Повторный вызов с теми же аргументами не исполняется и не оплачивается второй раз: модель получает первый результат.
  • Если поиск завершился ошибкой, модель об этом узнаёт, вызов ничего не стоит, а запрос продолжается.

Где работает

  • В /chat/completions, /responses и /messages, с любой моделью, которая умеет вызывать функции.
  • Не работает через адрес для Cursor (/v1/cursor) и с API-ключом, у которого включена защита данных: найденное в файлах ушло бы модели без маскировки. С моделями GigaChat тоже: они не вызывают функции, запрос вернёт ошибку 400.
  • Можно класть в один tools с aitunnel:datetime, веб-поиском и своими функциями: см. вместе с вашими функциями.
  • Со stream: true ответ стримится по токенам; пока идёт поиск, приходят SSE-комментарии : aitunnel-progress: см. стриминг.
  • Каждый поиск начинает заново 90-дневный срок хранения базы.

Цена и учёт

  • Поиск — 0,1 ₽ за каждый поисковый запрос модели. Три запроса в одном вызове — 0,3 ₽.
  • Реранкинг — по цене rerank-модели из каталога, отдельным запросом rerank в истории. Если rerank-модель не ответила, результаты остаются в векторном порядке, а реранкинг не оплачивается.
  • Токены модели. Найденные фрагменты попадают в промпт модели и оплачиваются как входные токены. max_results × ~400 токенов — ориентир, сколько добавит один поисковый запрос. Чтобы прочитать результат, модель вызывается ещё раз; каждый вызов модели оплачивается как отдельный запрос.

Итог — в usage ответа:

JSON
{
  "usage": {
    "prompt_tokens": 4120,
    "completion_tokens": 236,
    "total_tokens": 4356,
    "cost_rub": 1.46,
    "cost_details": {
      "model_rub": 1.12,
      "file_search_rub": 0.3,
      "rerank_rub": 0.04
    },
    "server_tool_use": {
      "tool_calls_requested": 1,
      "tool_calls_executed": 1,
      "file_search_requests": 3,
      "rerank_requests": 3
    },
    "rounds": 2
  }
}
ПолеСмысл
cost_details.file_search_rubЗа поисковые запросы: 0,1 ₽ за каждый. Поля нет, если поиска не было
cost_details.rerank_rubЗа реранкинг. Поля нет, если реранкинга не было
server_tool_use.file_search_requestsСколько поисковых запросов выполнено: за один вызов модель может задать до 5
server_tool_use.rerank_requestsСколько из них переранжировано
server_tool_use.tool_calls_requested, tool_calls_executedСколько раз модель вызвала серверные инструменты и сколько вызовов исполнено
cost_rubСписание за запрос целиком: все вызовы модели, поиск и реранкинг

Остальные поля — в учёте серверных инструментов.

Ошибки

Что не такСообщение
База не вашего аккаунта или её нет«База знаний «kb_…» не найдена. Проверьте knowledge_base_ids в запросе и в пресете, если запрос идёт через пресет.»
Нет knowledge_base_ids, в нём больше 5 баз, параметр вне диапазона или неизвестное полеЧто не так с полем; поля перечислены в error.metadata.fields
Инструмент указан дважды«Серверный инструмент aitunnel:file_search указан дважды.»
Ваша функция названа file_search«Имя функции file_search занято серверным инструментом aitunnel:file_search.»
Запрос через адрес для Cursor (/v1/cursor)«Инструмент aitunnel:file_search в этом методе недоступен.»
У API-ключа включена защита данных«Инструмент aitunnel:file_search не работает с ключом, у которого включено скрытие чувствительных данных.»

Модель не ищет в базе. Заполните описание базы: модель видит его и по нему понимает, что там лежит. Можно сказать об этом и в системном промпте. В /chat/completions "tool_choice": "required" заставит модель начать с вызова инструмента.

См. также