База знаний

Готовое хранилище для RAG: вы загружаете файлы, AITUNNEL режет их на фрагменты и индексирует, а модель ищет по ним сама.

Где создать
Поиск моделью
{ "type": "aitunnel:file_search" } в tools запроса к /chat/completions, /responses или /messages
Поиск из кода
POST https://aitunnel.83.141.93.205.nip.io/__api/v1/knowledge-bases/{id}/search с API-ключом
Цена
Хранение бесплатно, индексация — по цене эмбеддингов, поиск — 0,1 ₽ за запрос
Срок
База без поиска 90 дней удаляется, за 7 дней приходит письмо

Модель ищет по базе серверным инструментом aitunnel:file_search, ваш код — методом POST /knowledge-bases/{id}/search. Своя векторная база и свой пайплайн индексации не нужны.

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

  1. Создайте базу

    Откройте Панель → База знаний, задайте название и описание. Описание видит модель: по нему она решает, стоит ли искать в базе.

  2. Загрузите файлы

    Тексты, код, Markdown, CSV, JSON и документы PDF, DOCX, XLSX, ODT, HTML. Файл индексируется сам: небольшой — за пару минут, большой — дольше. Статус «готов» значит, что поиск его уже находит.

  3. Добавьте инструмент в запрос

    Нужен 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-модель не ответила, результаты остаются в векторном порядке, а реранкинг не оплачивается.

JSON
{
  "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
  }'
ПолеТипОписание
querystring или string[]Один запрос или массив до 5 запросов, каждый до 2 000 символов. Каждый ищется отдельно. Обязательно
max_resultsintegerСколько фрагментов вернуть на каждый запрос: 1–20, по умолчанию 8
rerankboolean или objecttrue, false или { "model": "rerank-5-pro" } — как у инструмента. Не указан — решает настройка базы

Ответ:

JSON
{
  "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-модель:

JSON
{
  "query": [
    "срок возврата товара",
    "кто оплачивает доставку при возврате"
  ],
  "max_results": 5,
  "rerank": { "model": "rerank-5-pro" }
}

В data — по одному элементу на запрос, в том же порядке.

Ошибки:

Статусerror.typeКогда
400invalid_requestНеверное тело: пустой запрос, больше 5 запросов, max_results вне 1–20, неизвестное поле
400model_not_foundВ rerank.model модель, которой нет среди rerank-моделей каталога
402insufficient_balance, budget_exceededНе хватает баланса или бюджета ключа
403permission_deniedМодель из rerank.model не входит в белый список моделей ключа
404not_found«База знаний не найдена» — базы нет, она удалена или принадлежит другому аккаунту
503service_unavailable«Поиск по базам знаний временно недоступен. Повторите запрос позже.»

Метод ищет в одной базе. Сразу в нескольких (до 5) ищет инструмент aitunnel:file_search.

Лимиты

ЧтоСколько
Размер файла100 МБ; документ (PDF, DOCX, XLSX и другие) — 32 МБ
Объём всех баз аккаунта5 ГБ и 3 млн фрагментов
Баз на аккаунт20
Файлов в одной базе5 000
Загрузка за сутки20 ГБ, считая удалённые файлы; сутки — по UTC
Баз в одном aitunnel:file_search5
Запросов в одном поиске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.

См. также