Управление базами знаний
Создавать базы знаний, загружать в них файлы и следить за индексацией через API. База знаний — файлы, по которым модель ищет инструментом aitunnel:file_search.
Что такое база знаний, какие файлы она принимает, как устроен поиск и сколько он стоит — в статье База знаний. Здесь — методы, которыми базы наполняются из кода. API-ключ базами не управляет: он только ищет в них — инструментом aitunnel:file_search и методом POST /v1/knowledge-bases/{id}/search. Поэтому утёкший API-ключ не может ни выгрузить базу, ни удалить её.
Методы
| Метод | Право | Что делает |
|---|---|---|
GET /knowledge-bases | knowledge:read | Все базы аккаунта и сколько места занято |
POST /knowledge-bases | knowledge:write | Создать базу |
GET /knowledge-bases/{id} | knowledge:read | Одна база |
PATCH /knowledge-bases/{id} | knowledge:write | Изменить название, описание или rerank-модель |
DELETE /knowledge-bases/{id} | knowledge:write | Удалить базу со всеми файлами |
GET /knowledge-bases/{id}/files | knowledge: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}/retry | knowledge: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 — база целиком:
{
"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.
Поля базы
| Поле | Смысл |
|---|---|
id | kb_, название базы латиницей и шесть случайных символов: 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_model | Rerank-модель из каталога, которая переранжирует результаты каждого поиска в базе, или 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} возвращает одну базу.
{
"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:
{
"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значит, что поиск файл уже находит; удалённый файл перестаёт находиться сразу. - Индексация оплачивается как запросы эмбеддингов аккаунта, поэтому загрузка требует положительного баланса.
Поля файла
| Поле | Смысл |
|---|---|
id | file_ и 32 шестнадцатеричных символа |
path | Путь файла в базе — имя с папками через /, как вы передали его в path. Его видит модель рядом с каждым найденным фрагментом |
bytes | Размер файла |
status | queued — ждёт очереди, 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"{
"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 без тела: файл сразу перестаёт находиться, а его путь освобождается.
Ошибки
| Статус | Смысл |
|---|---|
400 | invalid_request — неверное или неизвестное поле (в error.metadata.fields — каждое поле с объяснением), неподдерживаемый файл («Файлы «.zip» не поддерживаются…»), неверный path, «Файл пуст.» или тело не той длины, что в Content-Length |
401 | authentication_failed — ключа нет, он неверный, отозван или истёк |
402 | insufficient_balance — загрузка при нулевом балансе: индексация платная |
403 | permission_denied — у ключа нет нужного права, IP не в списке разрешённых или метод вызван API-ключом |
404 | not_found — «База знаний не найдена» или «Файл не найден». Так же отвечает база или файл другого аккаунта |
408 | invalid_request — «Загрузка длилась слишком долго и была отменена. Повторите её.» |
409 | invalid_request — база с таким названием уже есть (поле name), файл с таким путём уже есть (поле path), достигнут лимит баз, файлов в базе или объёма аккаунта, либо retry вызван для файла не в статусе failed |
411 | invalid_request — «Передайте файл телом запроса и укажите его размер в заголовке Content-Length.» |
413 | invalid_request — «Файл не должен превышать 100 МБ.» или «Документ не должен превышать 32 МБ.» |
429 | rate_limited — «Достигнут суточный лимит загрузки файлов. Продолжите завтра.» или слишком частые запросы: больше 600 загрузок или 120 изменений в минуту. В заголовке Retry-After — через сколько секунд повторить |
{
"error": {
"code": 409,
"type": "invalid_request",
"message": "Файл «docs/returns.md» уже есть в этой базе знаний. Удалите его, чтобы загрузить заново.",
"metadata": {
"fields": [
{
"field": "path",
"message": "Файл «docs/returns.md» уже есть в этой базе знаний. Удалите его, чтобы загрузить заново."
}
]
},
"request_id": "req-0J9fQk2vXc8LrT1mNbZa4e"
}
}Создание, изменение и удаление базы и удаление файла ключом управления видны владельцу в журнале активности.