Поиск по базе знаний
Серверный инструмент aitunnel:file_search ищет по файлам, которые вы загрузили в базу знаний: модель формулирует запросы, получает найденные фрагменты и отвечает по ним.
Поиск исполняет AITUNNEL — своя векторная база и свой код поиска не нужны.
aitunnel:file_search в массиве toolsknowledge_base_ids — от 1 до 5 баз/chat/completions, /responses, /messagesСначала — база знаний
Для запроса нужен 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.
Параметры
{
"tools": [
{
"type": "aitunnel:file_search",
"parameters": {
"knowledge_base_ids": ["kb_podderzhka-x7k3p9"],
"max_results": 8,
"rerank": true,
"max_uses": 3
}
}
]
}| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
knowledge_base_ids | string[] | — | Базы, по которым ищет модель: от 1 до 5. Обязательно |
max_results | integer | 8 | Сколько фрагментов вернуть на каждый поисковый запрос: 1–20 |
rerank | boolean или object | — | true — переранжировать результаты моделью базы или rerank-5-pro; false — никогда; { "model": "…" } — этой моделью. Не указан — решает настройка базы |
max_uses | integer | 10 | Сколько раз модель может вызвать поиск за один запрос: 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 ответа:
{
"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" заставит модель начать с вызова инструмента.
См. также
- База знаний — создание базы, загрузка файлов, лимиты, срок хранения и поиск из кода
- Управление базами знаний — базы и файлы ключом управления
- Серверные инструменты — как AITUNNEL исполняет инструменты, лимиты, стриминг и
usage - Дата и время —
aitunnel:datetime, если ответ зависит от сегодняшней даты - Ранжирование — rerank-модели