База знаний
Готовое хранилище для RAG: вы загружаете файлы, AITUNNEL режет их на фрагменты и индексирует, а модель ищет по ним сама.
{ "type": "aitunnel:file_search" } в tools запроса к /chat/completions, /responses или /messagesPOST https://aitunnel.83.141.93.205.nip.io/__api/v1/knowledge-bases/{id}/search с API-ключомМодель ищет по базе серверным инструментом aitunnel:file_search, ваш код — методом POST /knowledge-bases/{id}/search. Своя векторная база и свой пайплайн индексации не нужны.
Быстрый старт
Создайте базу
Откройте Панель → База знаний, задайте название и описание. Описание видит модель: по нему она решает, стоит ли искать в базе.
Загрузите файлы
Тексты, код, Markdown, CSV, JSON и документы PDF, DOCX, XLSX, ODT, HTML. Файл индексируется сам: небольшой — за пару минут, большой — дольше. Статус «готов» значит, что поиск его уже находит.
Добавьте инструмент в запрос
Нужен 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"]
}
}
]
}'Клиент получает один готовый ответ — как на обычный запрос. Базы и файлы можно создавать и из кода: управление базами знаний.
Какие файлы можно загрузить
| Вид | Что входит | Размер файла |
|---|---|---|
| Текст и разметка | .txt, .md, .csv, .json, .xml, .yaml и любой другой текстовый файл | 100 МБ |
| Исходный код | .py, .js, .ts, .go, .java, .php, .sql и другие языки | 100 МБ |
| Документы | PDF, DOCX, XLSX / XLS, ODT / ODS, HTML — перед индексацией превращаются в текст | 32 МБ |
- Текст должен быть в кодировке UTF-8.
- Не принимаются архивы (
.zip,.rar,.7z), картинки, аудио и видео, программы, а также.doc,.ppt,.pptx,.rtf,.epub: такой файл отклоняется при загрузке. - Скан без текстового слоя (PDF из картинок) не индексируется: в нём нет текста.
- У файла есть путь в базе — имя с папками, например
docs/returns.md, до 512 символов. Путь уникален в базе, его видит модель рядом с каждым фрагментом.
Статус файла:
| Статус | Что значит |
|---|---|
queued | Файл принят и ждёт своей очереди |
processing | Режется на фрагменты и индексируется |
ready | Проиндексирован, по нему идёт поиск |
failed | Индексация не удалась. Причина — в поле error; после исправления её можно повторить, работа продолжится с места остановки |
Как устроен поиск
Индексация. Файл режется на фрагменты около 1 600 символов (примерно 400 токенов): по заголовкам, затем по пустым строкам, затем по концам строк. Соседние фрагменты текста немного перекрываются, чтобы предложение на границе не потерялось; код режется без перекрытия. Каждый фрагмент хранится вместе с путём файла и заголовками, под которыми он стоит. Эмбеддинги считает модель, выбранная при создании базы: по умолчанию text-embedding-3-small. Сменить её у созданной базы нельзя.
Поиск. Запрос превращается в вектор той же моделью, и возвращаются max_results ближайших по смыслу фрагментов. Точное совпадение слов не требуется: «вернуть покупку» найдёт раздел «Возврат товара».
Реранкинг. Векторный поиск быстрый и приблизительный. С реранкингом берутся 50 ближайших фрагментов, rerank-модель сравнивает каждый с запросом напрямую и оставляет max_results лучших. Это точнее на больших базах и стоит отдельного запроса rerank. Какая модель работает:
rerankне указан — модель, заданная в настройках базы (rerank_model); если её нет, реранкинга нет;"rerank": true— модель базы, а если её нет —rerank-5-pro;"rerank": { "model": "…" }— указанная модель из каталога;"rerank": false— без реранкинга, даже если у базы модель задана.
Если rerank-модель не ответила, результаты остаются в векторном порядке, а реранкинг не оплачивается.
Инструмент aitunnel:file_search
{
"tools": [
{
"type": "aitunnel:file_search",
"parameters": {
"knowledge_base_ids": ["kb_podderzhka-x7k3p9"],
"max_results": 8,
"rerank": true,
"max_uses": 3
}
}
]
}- Обязателен только
knowledge_base_ids— от 1 до 5 баз. Остальное —max_results,rerankиmax_uses— необязательно. - Модель видит названия и описания баз и за один вызов может задать до 5 поисковых запросов. Каждый запрос — 0,1 ₽.
- Найденные фрагменты читает модель; в ответе клиенту их нет. Нужны сами фрагменты — вызовите поиск из кода.
Все параметры, где работает инструмент, цена, поля usage и ошибки — в статье Поиск по базе знаний.
Поиск из кода
POST /knowledge-bases/{id}/search возвращает фрагменты без вызова модели — для своего RAG-пайплайна, поиска по документации или проверки базы. Нужен обычный API-ключ.
curl https://aitunnel.83.141.93.205.nip.io/__api/v1/knowledge-bases/kb_podderzhka-x7k3p9/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-aitunnel-xxx" \
-d '{
"query": "За сколько дней можно вернуть товар?",
"max_results": 5
}'| Поле | Тип | Описание |
|---|---|---|
query | string или string[] | Один запрос или массив до 5 запросов, каждый до 2 000 символов. Каждый ищется отдельно. Обязательно |
max_results | integer | Сколько фрагментов вернуть на каждый запрос: 1–20, по умолчанию 8 |
rerank | boolean или object | true, false или { "model": "rerank-5-pro" } — как у инструмента. Не указан — решает настройка базы |
Ответ:
{
"id": "kbs-0J9fQk2vXc8LrT1mNbZa4e",
"object": "list",
"data": [
{
"query": "За сколько дней можно вернуть товар?",
"results": [
{
"knowledge_base_id": "kb_podderzhka-x7k3p9",
"file_id": "file_0195c3f5d1c27a0e9f3b6a4d2c8e7f10",
"path": "docs/returns.md",
"text": "docs/returns.md — Возврат > Сроки\n\nВернуть товар можно в течение 14 дней со дня получения.",
"score": 0.71
}
]
}
],
"rerank_model": null,
"usage": {
"searches": 1,
"cost": 0.1,
"cost_rub": 0.1,
"cost_details": { "search_rub": 0.1, "rerank_rub": 0 },
"balance": 1249.9
}
}| Поле | Смысл |
|---|---|
data[].query | Запрос, как вы его передали |
data[].results[] | Найденные фрагменты, лучшие первыми. Фрагмент, найденный несколькими запросами, остаётся только у того, которому подходит лучше |
knowledge_base_id, file_id, path | Откуда фрагмент: база, файл и его путь в базе |
text | Фрагмент: путь файла и заголовки, под которыми он стоит, пустая строка, затем сам текст |
score | Близость к запросу, больше — ближе. Без реранкинга это косинусная близость векторов, с ним — оценка rerank-модели |
rerank_model | Модель, которая переранжировала результаты, или null, если порядок векторный |
usage.searches | Сколько запросов выполнено и оплачено |
usage.cost_rub | Сколько списано всего, ₽. usage.cost_details делит сумму на поиск (search_rub) и реранкинг (rerank_rub) |
usage.balance | Баланс после списания |
Несколько запросов за один вызов и своя rerank-модель:
{
"query": [
"срок возврата товара",
"кто оплачивает доставку при возврате"
],
"max_results": 5,
"rerank": { "model": "rerank-5-pro" }
}В data — по одному элементу на запрос, в том же порядке.
Ошибки:
| Статус | error.type | Когда |
|---|---|---|
400 | invalid_request | Неверное тело: пустой запрос, больше 5 запросов, max_results вне 1–20, неизвестное поле |
400 | model_not_found | В rerank.model модель, которой нет среди rerank-моделей каталога |
402 | insufficient_balance, budget_exceeded | Не хватает баланса или бюджета ключа |
403 | permission_denied | Модель из rerank.model не входит в белый список моделей ключа |
404 | not_found | «База знаний не найдена» — базы нет, она удалена или принадлежит другому аккаунту |
503 | service_unavailable | «Поиск по базам знаний временно недоступен. Повторите запрос позже.» |
Метод ищет в одной базе. Сразу в нескольких (до 5) ищет инструмент aitunnel:file_search.
Лимиты
| Что | Сколько |
|---|---|
| Размер файла | 100 МБ; документ (PDF, DOCX, XLSX и другие) — 32 МБ |
| Объём всех баз аккаунта | 5 ГБ и 3 млн фрагментов |
| Баз на аккаунт | 20 |
| Файлов в одной базе | 5 000 |
| Загрузка за сутки | 20 ГБ, считая удалённые файлы; сутки — по UTC |
Баз в одном aitunnel:file_search | 5 |
| Запросов в одном поиске | 5, каждый до 2 000 символов |
| Результатов на запрос | 20 |
Сколько занято и сколько доступно, показывает панель и поле usage в GET /aitunnel/knowledge-bases.
Срок хранения
База, в которой 90 дней никто не искал, удаляется вместе со всеми файлами. За 7 дней до удаления владельцу аккаунта приходит письмо.
Любой поиск — запросом с aitunnel:file_search, методом /search или кнопкой «Проверить поиск» в панели — начинает срок заново. У новой базы срок идёт от создания. Дата, когда база будет удалена, — поле expires_at базы.
Цены
| Что | Сколько стоит |
|---|---|
| Хранение файлов и векторов | Бесплатно |
| Индексация | Обычные запросы эмбеддингов вашего аккаунта: модель эмбеддингов базы (по умолчанию text-embedding-3-small) по цене каталога. В истории запросов — метод embeddings |
| Поиск | 0,1 ₽ за каждый поисковый запрос. Три запроса в одном вызове — 0,3 ₽ |
| Реранкинг | По цене rerank-модели из каталога, отдельным запросом rerank в истории |
- Сколько стоила индексация файла, показывает поле
costфайла. - Поиск методом
/search— запросknowledge/searchв истории. Поиск инструментом входит в стоимость вызова модели:usage.cost_details.file_search_rubиrerank_rub. - Найденные фрагменты попадают в промпт модели и оплачиваются как входные токены.
max_results× ~400 токенов — ориентир, сколько добавит один поисковый запрос. - Загрузка и индексация требуют положительного баланса. Если деньги кончились посреди индексации, файл получит статус
failed; после пополнения её можно повторить.
Вопросы
Файл получил статус failed с ошибкой «Файл не является текстом в кодировке UTF-8». Пересохраните файл в UTF-8 (например, из Windows-1251) и загрузите заново.
PDF не индексируется: «В документе нет текста. Сканы без текстового слоя не поддерживаются». Это скан — страницы-картинки. Распознайте текст (OCR) и загрузите результат как PDF с текстовым слоем или как текстовый файл.
Нужно загрузить .doc или презентацию. Пересохраните .doc как .docx, презентацию экспортируйте в PDF.
Как обновить файл? Удалите его и загрузите новый с тем же путём. Загрузка поверх существующего пути отклоняется с 409.
Можно ли задать несколько запросов сразу? Да: до 5 в массиве query метода /search; модель через инструмент тоже может задать до 5 за вызов. Каждый запрос ищется и оплачивается отдельно.
Модель не ищет в базе. Заполните описание базы: модель видит его и по нему понимает, что там лежит. Можно сказать об этом и в системном промпте. В /chat/completions "tool_choice": "required" заставит модель начать с вызова инструмента.
Можно ли скачать файл обратно? Нет: база отдаёт найденные фрагменты, а не исходные файлы.
Работает ли с маскировкой персональных данных? Нет: у API-ключа с включённой защитой данных запрос с aitunnel:file_search отклоняется с 400.
См. также
- Управление базами знаний — создание баз и загрузка файлов ключом управления
- Поиск по базе знаний — инструмент
aitunnel:file_search: параметры, цена,usageи ошибки - Серверные инструменты — как AITUNNEL исполняет инструменты, лимиты и стриминг
- RAG — тот же пайплайн своими руками: эмбеддинги, rerank и чат
- Ранжирование — rerank-модели
- Пресеты — база знаний, подключённая к имени модели