Управление базами знаний

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

Адрес
Авторизация
Ключ управления с правами knowledge:read, knowledge:write

Что такое база знаний, какие файлы она принимает, как устроен поиск и сколько он стоит — в статье База знаний. Здесь — методы, которыми базы наполняются из кода. API-ключ базами не управляет: он только ищет в них — инструментом aitunnel:file_search и методом POST /v1/knowledge-bases/{id}/search. Поэтому утёкший API-ключ не может ни выгрузить базу, ни удалить её.

Методы

МетодПравоЧто делает
GET /knowledge-basesknowledge:readВсе базы аккаунта и сколько места занято
POST /knowledge-basesknowledge:writeСоздать базу
GET /knowledge-bases/{id}knowledge:readОдна база
PATCH /knowledge-bases/{id}knowledge:writeИзменить название, описание или rerank-модель
DELETE /knowledge-bases/{id}knowledge:writeУдалить базу со всеми файлами
GET /knowledge-bases/{id}/filesknowledge:readФайлы базы, постранично
POST /knowledge-bases/{id}/files?path=…knowledge:writeЗагрузить файл: тело запроса — сам файл
GET /knowledge-bases/{id}/files/{file}knowledge:readОдин файл и статус его индексации
DELETE /knowledge-bases/{id}/files/{file}knowledge:writeУдалить файл
POST /knowledge-bases/{id}/files/{file}/retryknowledge:writeПовторить индексацию, которая завершилась ошибкой

Создать базу

curl -X POST https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/knowledge-bases \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Поддержка",
    "description": "Инструкции для клиентов: доставка, возврат, гарантия"
  }'

Ответ 201 — база целиком:

JSON
{
  "id": "kb_podderzhka-x7k3p9",
  "name": "Поддержка",
  "description": "Инструкции для клиентов: доставка, возврат, гарантия",
  "embedding_model": "text-embedding-3-small",
  "rerank_model": null,
  "files": 0,
  "bytes": 0,
  "chunks": 0,
  "created_at": "2026-11-18T09:30:00.000Z",
  "updated_at": "2026-11-18T09:30:00.000Z",
  "last_used_at": "2026-11-18T09:30:00.000Z",
  "expires_at": "2027-02-16T09:30:00.000Z"
}
  • Обязательно только name. Принимаются name, description, embedding_model и rerank_model; остальные поля базы — только в ответе.
  • embedding_model — одна из моделей эмбеддингов, с которыми можно создать базу: их список — в usage.indexing.embedding_models ответа GET /knowledge-bases. Другая модель — 400. Выбирается один раз: чтобы сменить модель, создайте новую базу и загрузите файлы заново.
  • rerank_model — модель из rerank-моделей каталога, например rerank-5-pro. Неизвестная модель — 400 «Такой модели реранкинга нет в каталоге».
  • В аккаунте — до 20 баз. Создание сверх лимита — 409.

Поля базы

ПолеСмысл
idkb_, название базы латиницей и шесть случайных символов: kb_podderzhka-x7k3p9. Создаётся вместе с базой и не меняется, даже если её переименовать. Его называют в путях и в knowledge_base_ids инструмента aitunnel:file_search
nameНазвание, до 80 символов, уникальное в аккаунте. Его видит модель. Обязательно
descriptionЧто лежит в базе, до 1 000 символов. Модель видит описание рядом с названием и по нему решает, искать ли в базе. По умолчанию пустая строка
embedding_modelМодель эмбеддингов, которой индексируются файлы и запросы: одна из usage.indexing.embedding_models. Задаётся при создании базы и не меняется. По умолчанию text-embedding-3-small
rerank_modelRerank-модель из каталога, которая переранжирует результаты каждого поиска в базе, или null — поиск только по векторам. Отдельный поиск может её переопределить параметром rerank
files, bytes, chunksСколько в базе файлов, сколько они занимают и на сколько фрагментов разрезаны
created_at, updated_atКогда база создана и изменена
last_used_atПоследний поиск в базе; у новой базы — момент создания. Обновляется не чаще раза в сутки
expires_atКогда база будет удалена, если до этого в ней никто не будет искать: last_used_at плюс 90 дней

Список баз и лимиты

curl https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/knowledge-bases \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Ответ — { "data": [...], "usage": {...} }: базы, новые первыми, и сколько места занято и доступно. GET /knowledge-bases/{id} возвращает одну базу.

JSON
{
  "data": [
    {
      "id": "kb_podderzhka-x7k3p9",
      "name": "Поддержка",
      "description": "Инструкции для клиентов: доставка, возврат, гарантия",
      "embedding_model": "text-embedding-3-small",
      "rerank_model": null,
      "files": 12,
      "bytes": 4812300,
      "chunks": 1940,
      "created_at": "2026-11-18T09:30:00.000Z",
      "updated_at": "2026-11-18T10:02:41.000Z",
      "last_used_at": "2026-11-18T09:30:00.000Z",
      "expires_at": "2027-02-16T09:30:00.000Z"
    }
  ],
  "usage": {
    "bytes": 4812300,
    "chunks": 1940,
    "limits": {
      "bytes": 5368709120,
      "chunks": 3000000,
      "bases": 20,
      "files_per_base": 5000,
      "file_bytes": 104857600,
      "document_bytes": 33554432
    },
    "search": { "price": 0.1, "rerank_model": "rerank-5-pro" },
    "indexing": {
      "embedding_model": "text-embedding-3-small",
      "embedding_models": ["text-embedding-3-small", "text-embedding-3-large", "qwen3-embedding-8b"]
    }
  }
}
ПолеСмысл
usage.bytes, usage.chunksСколько байт и фрагментов занимают все базы аккаунта
usage.limits.bytes, usage.limits.chunksСколько аккаунту можно хранить: по умолчанию 5 ГБ и 3 млн фрагментов
usage.limits.basesСколько баз можно создать
usage.limits.files_per_baseСколько файлов помещается в одну базу
usage.limits.file_bytesНаибольший размер файла с текстом или кодом
usage.limits.document_bytesНаибольший размер документа (PDF, DOCX, XLSX и других): перед индексацией он преобразуется в текст, поэтому предел меньше
usage.search.priceЦена одного поискового запроса, ₽
usage.indexing.embedding_modelsМодели эмбеддингов, с которыми можно создать базу (embedding_model). В примере список сокращён
usage.indexing.embedding_modelМодель эмбеддингов по умолчанию: её получает база, созданная без embedding_model
usage.search.rerank_modelМодель реранкинга по умолчанию: ею пользуется поиск с rerank: true по базе, у которой своя модель не задана

Изменить и удалить базу

PATCH /knowledge-bases/{id} меняет переданные поля из name, description и rerank_model; "rerank_model": null выключает реранкинг базы. Ответ — база целиком.

curl -X PATCH https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/knowledge-bases/kb_podderzhka-x7k3p9 \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rerank_model": "rerank-5-pro"
  }'

DELETE /knowledge-bases/{id} отвечает 204 без тела. База исчезает сразу вместе со всеми файлами, её название и место освобождаются. Восстановить её нельзя.

Загрузить файл

POST /knowledge-bases/{id}/files?path=… — тело запроса и есть файл, без multipart/form-data. Путь файла в базе передаётся в параметре path.

curl -X POST "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/knowledge-bases/kb_podderzhka-x7k3p9/files?path=docs/returns.md" \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @returns.md

Ответ 201 — файл в статусе queued:

JSON
{
  "id": "file_0195c3f5d1c27a0e9f3b6a4d2c8e7f10",
  "path": "docs/returns.md",
  "bytes": 18432,
  "status": "queued",
  "error": null,
  "chunks": 0,
  "cost": 0,
  "created_at": "2026-11-18T09:31:10.000Z",
  "indexed_at": null
}
  • path — имя с папками через /: docs/returns.md. До 512 символов, без .. и управляющих символов. Вид файла определяется по расширению.
  • Content-Length обязателен и должен совпадать с телом: без него — 411, при расхождении — 400. Потоковая отправка без известной длины не подходит.
  • Размер — до 100 МБ, документ (PDF, DOCX, XLSX / XLS, ODT / ODS, HTML) — до 32 МБ. Архивы, картинки, аудио, видео, .doc и .pptx отклоняются с 400.
  • Путь уникален в базе. Чтобы обновить файл, удалите старый и загрузите новый.
  • Индексация идёт в фоне: небольшой файл — пару минут. Опрашивайте GET /knowledge-bases/{id}/files/{file}, пока status не станет ready или failed. ready значит, что поиск файл уже находит; удалённый файл перестаёт находиться сразу.
  • Индексация оплачивается как запросы эмбеддингов аккаунта, поэтому загрузка требует положительного баланса.

Поля файла

ПолеСмысл
idfile_ и 32 шестнадцатеричных символа
pathПуть файла в базе — имя с папками через /, как вы передали его в path. Его видит модель рядом с каждым найденным фрагментом
bytesРазмер файла
statusqueued — ждёт очереди, processing — индексируется, ready — по файлу идёт поиск, failed — индексация не удалась
errorПочему индексация не удалась, текстом для человека; у остальных статусов null
chunksСколько фрагментов проиндексировано
costСколько стоила индексация файла к этому моменту, ₽
created_atКогда файл загружен
indexed_atКогда индексация закончилась, или null

Список файлов

curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/knowledge-bases/kb_podderzhka-x7k3p9/files?limit=50" \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"
JSON
{
  "data": [
    {
      "id": "file_0195c3f5d1c27a0e9f3b6a4d2c8e7f10",
      "path": "docs/returns.md",
      "bytes": 18432,
      "status": "ready",
      "error": null,
      "chunks": 14,
      "cost": 0.02,
      "created_at": "2026-11-18T09:31:10.000Z",
      "indexed_at": "2026-11-18T09:31:24.000Z"
    }
  ],
  "next_cursor": null
}
  • Файлы идут в порядке загрузки, старые первыми.
  • limit — от 1 до 100, по умолчанию 100.
  • next_cursor — передайте его в cursor, чтобы получить следующую страницу; null — файлов больше нет.

Повторить индексацию и удалить файл

POST /knowledge-bases/{id}/files/{file}/retry снова ставит в очередь файл в статусе failed и возвращает его со статусом queued. Индексация продолжается с места, где остановилась. Для файла в другом статусе ответ 409.

curl -X POST https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/knowledge-bases/kb_podderzhka-x7k3p9/files/file_0195c3f5d1c27a0e9f3b6a4d2c8e7f10/retry \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Повтор помогает, когда причина устранена: пополнен баланс или освобождено место. Файл не в UTF-8 или скан без текста повтор не исправит — удалите его и загрузите исправленный. DELETE /knowledge-bases/{id}/files/{file} отвечает 204 без тела: файл сразу перестаёт находиться, а его путь освобождается.

Ошибки

СтатусСмысл
400invalid_request — неверное или неизвестное поле (в error.metadata.fields — каждое поле с объяснением), неподдерживаемый файл («Файлы «.zip» не поддерживаются…»), неверный path, «Файл пуст.» или тело не той длины, что в Content-Length
401authentication_failed — ключа нет, он неверный, отозван или истёк
402insufficient_balance — загрузка при нулевом балансе: индексация платная
403permission_denied — у ключа нет нужного права, IP не в списке разрешённых или метод вызван API-ключом
404not_found — «База знаний не найдена» или «Файл не найден». Так же отвечает база или файл другого аккаунта
408invalid_request — «Загрузка длилась слишком долго и была отменена. Повторите её.»
409invalid_request — база с таким названием уже есть (поле name), файл с таким путём уже есть (поле path), достигнут лимит баз, файлов в базе или объёма аккаунта, либо retry вызван для файла не в статусе failed
411invalid_request — «Передайте файл телом запроса и укажите его размер в заголовке Content-Length.»
413invalid_request — «Файл не должен превышать 100 МБ.» или «Документ не должен превышать 32 МБ.»
429rate_limited — «Достигнут суточный лимит загрузки файлов. Продолжите завтра.» или слишком частые запросы: больше 600 загрузок или 120 изменений в минуту. В заголовке Retry-After — через сколько секунд повторить
409
{
  "error": {
    "code": 409,
    "type": "invalid_request",
    "message": "Файл «docs/returns.md» уже есть в этой базе знаний. Удалите его, чтобы загрузить заново.",
    "metadata": {
      "fields": [
        {
          "field": "path",
          "message": "Файл «docs/returns.md» уже есть в этой базе знаний. Удалите его, чтобы загрузить заново."
        }
      ]
    },
    "request_id": "req-0J9fQk2vXc8LrT1mNbZa4e"
  }
}

Создание, изменение и удаление базы и удаление файла ключом управления видны владельцу в журнале активности.