Справочник API: базы знаний и знания
Создание баз знаний, импорт и управление документами, а также запрос прогресса обработки, копирование или перемещение содержимого.
Краткая шпаргалка по правам: маршруты чтения — Viewer+ и требуется право read на KB (собственный/общий в организации/видимый через общий Agent); маршруты записи — «создатель KB OR Admin+» и требуется право write. API key: для чтения нужен retrieve, для записи содержимого — ingest, для жизненного цикла KB — manage_kbs (все могут быть перекрыты full-access), и действует ограничение белого списка KB.
Эндпоинты блоков, тегов и предпросмотра разбиения (/chunks, /knowledge-bases/:id/tags, /chunker/preview) — в блоки и теги.
Базы знаний (/api/v1/knowledge-bases)
POST /api/v1/knowledge-bases
Назначение: создание базы знаний. Права: Contributor+; API key manage_kbs/full. Handler: internal/handler/knowledgebase.go
Тело запроса (types.KnowledgeBase):
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
name | string | Да | Название |
description | string | Нет | Описание |
type | string | Нет | document (по умолчанию)/faq/wiki |
embedding_model_id | string | Нет | ID Embedding-модели |
chunking_config | object | Нет | Конфигурация разбиения на блоки (chunk_size/overlap/separators/strategy…) |
image_processing_config | object | Нет | Конфигурация наблюдения свойств изображений: model_id / image_attrs_enabled / image_actions ({ ocr: { on: [...], on_unobserved: bool } }) / image_vector_enabled (векторная индексация и поиск изображений, по умолчанию false, см. возможности базы знаний) |
storage_provider_config | object | Нет | Конфигурация хранилища |
vector_store_id | string | Нет | Привязка векторного хранилища (недопустимая возвращает code 2200/2201) |
faq_config / wiki_config / extract_config / indexing_strategy | object | Нет | Конфигурации, зависящие от типа |
summary_model_id | string | Нет | Модель для резюме, а также модель по умолчанию для автоматических тегов и AI-описания |
auto_tag_config / profile_config | object | Нет | Автоматические теги, AI-описание базы знаний (только тип document, см. ниже) |
Ответ: 201 {"success":true,"data":{KnowledgeBase}}
Переключатели, не указанные в indexing_strategy, остаются со значениями по умолчанию: векторный и keyword-поиски включены, Wiki и граф — выключены. Выключить их можно, только явно передав false.
curl -X POST $BASE/api/v1/knowledge-bases -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"документация продукта","type":"document"}'Конфигурация автоматических тегов и AI-описания
При создании базы знаний auto_tag_config, profile_config располагаются на верхнем уровне; при обновлении — в config.auto_tag_config, config.profile_config. Оба поддерживаются только базами знаний типа document, по умолчанию enabled=false.
auto_tag_config (автоматические теги):
| Поле | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
enabled | bool | false | После разбора асинхронно выбирать из существующих тегов |
model_id | string | пусто | Если пусто, используется summary_model_id базы знаний |
max_tags | int | 3 | Максимум привязок на документ, верхняя граница 10 |
skip_if_tagged | bool | true | Если тег уже есть, пропускать; false разрешает дополнять теги |
После включения действует на вновь разобранные/повторно разобранные документы, не сканирует автоматически все старые документы. При отсутствии тегов-кандидатов или доступной модели приём в базу не блокируется.
profile_config (AI-описание базы знаний):
| Поле | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
enabled | bool | false | После включения при добавлении, удалении, перемещении документов или обновлении резюме автоматически обновляется generated_profile |
model_id | string | пусто | Если пусто, используется summary_model_id базы знаний |
custom_instructions | string | пусто | Дополнительные требования, добавляемые к генерирующему промпту |
generated_profile — поле только для чтения, записывается системой и не перекрывает написанное вручную description; также можно сгенерировать сразу через profile/generate (см. ниже). Пример обновления:
curl -X PUT "$BASE/api/v1/knowledge-bases/kb-1" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"документация продукта","config":{"auto_tag_config":{"enabled":true,"max_tags":3,"skip_if_tagged":true}}}'GET /api/v1/knowledge-bases
Назначение: список баз знаний. Права: Viewer+; API key retrieve/full.
| Параметр запроса | Тип | Обязательный | Описание |
|---|---|---|---|
agent_id | string | Нет | Фильтр по KB, видимым некоторым общим Agent |
agent_source_tenant_id | uint64 | Нет | Когда Agent с одинаковым именем опубликован несколькими пространствами, указывает пространство-источник; значение проверяется по отношению публикации, недопустимое значение сразу 400 |
creator | string | Нет | mine / others |
Ответ: 200 {"success":true,"data":[KnowledgeBase],"total","page","page_size"}
curl $BASE/api/v1/knowledge-bases -H "X-API-Key: $API_KEY"GET /api/v1/knowledge-bases/:id
Назначение: сведения о базе знаний (у общей KB несёт my_permission). Права: Viewer+, KB read. Параметры запроса: agent_id (необязательно).
Ответ: 200 {"success":true,"data":{KnowledgeBase}}
curl $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/knowledge-bases/:id
Назначение: обновление базы знаний. Права: создатель OR Admin+, KB write; API key manage_kbs/full.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
name | string | Да (binding:"required") | Название |
description | string | Нет | Описание |
config | object | Нет | Частичное обновление конфигурации: chunking_config, image_processing_config, faq_config, wiki_config, auto_tag_config, profile_config, indexing_strategy. Если image_processing_config не передан, он остаётся без изменений; при передаче заменяется целиком (непереданные поля вроде image_vector_enabled возвращаются в false) |
vlm_config | object | Нет | Конфигурация мультимодальности, заменяется целиком: берутся только enabled, model_id (должен быть VLLM-моделью), description_language, custom_instructions (≤4000 символов); непереданные поля обрабатываются как пустые, не хотите менять — не передавайте. Для общей базы знаний требуется право владельца пространства или администратора общего доступа (editor получает 403). Старые встроенные поля model_name/base_url/api_key/interface_type не записываются: при включении управляемой model_id или выключении сохранённая старая конфигурация очищается, но чисто старая база (без сохранённого model_id, только model_name/base_url) возвращает результат GET как есть (enabled=false, а model_name/base_url совпадают с хранилищем) и считается неизменённой; у остальных баз enabled=true без model_id возвращает 400 |
Ответ: 200 {"success":true,"data":{KnowledgeBase}}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"документация продукта v2"}'PATCH /api/v1/knowledge-bases/:id
Назначение: изменение только настроек, присутствующих в запросе, остальные сохраняются. Это поля названия, описания, моделей, хранилища, разбиения, переключателей индексации, FAQ, Wiki, автоматических тегов, AI-описания, изображений, речи и извлечения графа: поля вложенных объектов, не указанные в них, тоже сохраняют прежние значения. Права те же, что у PUT; при изменении embedding-модели, модели резюме, мультимодальности или речи для общей базы знаний дополнительно требуется право администратора общего доступа. Экземпляр хранилища может изменить только пространство-владелец базы знаний, а если в базе уже есть файлы — сначала необходимо перенести хранилище; администратор общего доступа может вернуть текущий ID хранилища как есть, но не может его заменить. embedding_model_id нельзя изменить, когда в базе уже есть документы. vector_store_id задаётся только при создании. Переданный name не может быть пустым; пустая строка в description очищает описание.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
name | string | Нет | Новое название |
description | string | Нет | Новое описание; пустая строка очищает |
embedding_model_id / summary_model_id / storage_backend_id | string | Нет | Модель или экземпляр хранилища |
chunking_config | object | Нет | Перезаписывает только указанные поля разбиения |
indexing_strategy | object | Нет | Перезаписывает только указанные переключатели; должна остаться хотя бы одна индексация |
vlm_config / asr_config / image_processing_config | object | Нет | Мультимодальность, речь, изображения |
faq_config / wiki_config / auto_tag_config / profile_config | object | Нет | Настройки, зависящие от типа |
extract_config / question_generation_config | object | Нет | Извлечение графа, генерация вопросов к блокам |
Ответ: 200 {"success":true,"data":{KnowledgeBase}}
curl -X PATCH $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"продуктовая документация v2"}'DELETE /api/v1/knowledge-bases/:id
Назначение: удаление базы знаний (жёстко привязано к пространству-владельцу + Admin; общий editor удалить не может). Права: создатель OR Admin+, KB write; API key manage_kbs/full.
Ответ: 200 {"success":true,"message":"Knowledge base deleted successfully"}
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/knowledge-bases/:id/pin
Назначение: закрепить/снять закрепление (хранится в разрезе пользователя). Права: Viewer+, KB read. Без тела запроса.
Ответ: 200 {"success":true,"data":{KnowledgeBase(is_pinned переключён)}}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/pin -H "Authorization: Bearer $TOKEN"POST /api/v1/knowledge-bases/:id/hybrid-search (совместим с GET)
Назначение: низкоуровневый recall внутри KB (вектор+ключевые слова), по умолчанию без rerank, возвращает оценку recall; rerank можно включить опционально. Подходит для сценариев вроде оценки recall или передачи предвычисленных векторов, где нужно контролировать исходный recall; для обычного поиска используйте knowledge-search, способ выбора см. в как выбрать эндпоинт поиска. Права: Viewer+, KB read; API key retrieve/full. GET с JSON body только для обратной совместимости (#1727), рекомендуется POST.
Параметры запроса: resource_urls=handle|public (public заменяет resource:// в content / image_info результата на загружаемую прямую ссылку, подробнее в обзоре API).
Тело запроса (types.SearchParams):
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
query_text | string | Условно обязательный | Текст запроса (если не передан query_embedding; обязателен при включённом rerank) |
query_embedding | []float32 | Нет | Предвычисленный вектор |
vector_threshold / keyword_threshold | float64 | Нет | Пороги совпадения |
match_count | int | Нет | Верхняя граница числа результатов (по умолчанию 50) |
disable_keywords_match / disable_vector_match | bool | Нет | Отключить один из путей recall |
knowledge_base_ids | []string | Нет | Поиск сразу по нескольким базам знаний; :id из пути должен входить в них; embedding-модели этих баз знаний должны совпадать, иначе возвращается 400 |
knowledge_ids | []string | Нет | Ограничить записями знаний |
tag_ids | []string | Нет | Фильтр по тегам (OR) |
only_recommended | bool | Нет | Для FAQ только рекомендованные записи |
skip_context_enrichment | bool | Нет | Пропустить обогащение родительского блока/контекста |
rerank | object | Нет | Передача включает rerank ({} использует модель из конфигурации пространства), поля см. в объект rerank |
Ответ: 200 {"success":true,"data":[SearchResult]}; при наличии rerank добавляется meta.rerank (см. диагностика meta.rerank).
curl -X POST "$BASE/api/v1/knowledge-bases/kb-1/hybrid-search?resource_urls=public" -H "X-API-Key: $API_KEY" \
-H 'Content-Type: application/json' -d '{"query_text":"процесс возврата","match_count":5}'
# Зафиксировать параметры recall, затем rerank указанной моделью
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/hybrid-search -H "X-API-Key: $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"query_text":"процесс возврата","vector_threshold":0.3,"match_count":5,"rerank":{"model_id":"rr-1","threshold":0.2}}'POST /api/v1/knowledge-bases/copy
Назначение: копирование содержимого между KB (асинхронная задача). Права: Contributor+; API key manage_kbs/full (белые списки исходной/целевой KB проверяются в handler).
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
source_id | string | Да (binding:"required") | Исходная KB |
target_id | string | Нет | Целевая KB (если пусто, создаётся автоматически) |
task_id | string | Нет | Пользовательский ID задачи |
Ответ: 200 {"success":true,"data":{"task_id","source_id","target_id","message"}}
curl -X POST $BASE/api/v1/knowledge-bases/copy -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"source_id":"kb-1"}'POST /api/v1/knowledge-bases/:id/duplicate
Назначение: создание копии KB (копируются только настройки, без содержимого/индекса/публикаций). Права: Contributor+, исходная KB read; API key manage_kbs/full. Без тела запроса.
Ответ: 201 {"success":true,"data":{"source_id","target_id","message","knowledge_base":{...}}}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/duplicate -H "Authorization: Bearer $TOKEN"POST /api/v1/knowledge-bases/:id/profile/generate
Назначение: немедленно перегенерировать AI-описание базы знаний (generated_profile); синхронно выполняет одну агрегацию профиля документов и один вызов небольшой модели, не изменяя написанное вручную description. Права: как при обновлении базы знаний (создатель/Admin и KB write); API key manage_kbs/full. Без тела запроса. Только тип document; если модель не настроена, возвращается 400.
Ответ: 200 {"success":true,"data":{"gist","topics":[...],"typical_questions":[...],"stats":{"document_count",...},"status":"ready","model_id","generated_at"}}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/profile/generate -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge-bases/copy/progress/:task_id
Назначение: запрос прогресса копирования (задачи изолированы по пространствам). Права: Viewer+; API key retrieve/manage_kbs/full.
Ответ: 200 {"success":true,"data":{status,progress,message,...}}
curl $BASE/api/v1/knowledge-bases/copy/progress/task-1 -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge-bases/:id/move-targets
Назначение: список KB, которые могут быть целями перемещения (тот же тип/тот же embedding). Права: Viewer+, KB read.
Ответ: 200 {"success":true,"data":[KnowledgeBase]}
curl $BASE/api/v1/knowledge-bases/kb-1/move-targets -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge-bases/:id/files
Назначение: файловый прокси в области KB (отрисовка изображений в содержимом общей KB; tenant контекста уже перезаписан на владельца KB). Права: Viewer+; KB read; ограниченный KB key отклоняется, полнопространственный retrieve/full key пропускается. Зарегистрирован в serveKBScopedFiles (internal/router/files.go).
| Параметр запроса | Тип | Обязательный | Описание |
|---|---|---|---|
file_path | string | Да | Путь хранилища provider://... (запрещено ..) |
Ответ: 200 файловый поток (Content-Type выводится по расширению; Cache-Control: private).
curl "$BASE/api/v1/knowledge-bases/kb-1/files?file_path=local://1/exports/chart.png" \
-H "Authorization: Bearer $TOKEN" -o chart.pngЗнания (содержимое KB, /api/v1/knowledge-bases/:id/knowledge и /api/v1/knowledge)
POST /api/v1/knowledge-bases/:id/knowledge/file
Назначение: создать знание загрузкой файла. Права: создатель KB OR Admin+, KB write; API key ingest/full. Handler: internal/handler/knowledge.go
Поля multipart/form-data:
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
file | file | Да | Загружаемый файл |
fileName | string | Нет | Пользовательское отображаемое имя или относительный путь с каталогами, например docs/spec/design.md; часть с каталогами используется для классификации, последний сегмент — имя файла |
metadata | JSON-строка | Нет | Пользовательские метаданные |
enable_multimodel | bool | Нет | Переключатель мультимодальной обработки |
tag_ids | string | Нет | ID тегов через запятую |
channel | string | Нет | Канал приёма |
process_config | JSON-строка | Нет | Переопределение конфигурации разбора (KnowledgeProcessOverrides), см. таблицу ниже |
Часто используемые поля process_config (все необязательны; при пропуске используется конфигурация базы знаний):
| Поле | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
summary_enabled | bool | true | Генерировать ли резюме для документов этой загрузки; после отключения разбор, индексация и прочая обработка выполняются как обычно |
parser_engine_rules | []object | конфигурация базы знаний | Указать движок разбора по типу файла |
parser_engine_overrides | map[string]string | пусто | Параметры движка, например pdf_force_scanned |
chunking_config | object | конфигурация базы знаний | Параметры разбиения на блоки |
enable_multimodel / vlm_config / asr_config | - | конфигурация базы знаний | Мультимодальность и распознавание речи |
question_generation_config | object | конфигурация базы знаний | Генерация вопросов |
graph_enabled / extract_config | - | конфигурация базы знаний | Извлечение графа |
Ответ: 200 {"success":true,"data":{Knowledge}}; повторный файл возвращает 409, а data — уже существующий Knowledge. Одноимённые файлы, которые удаляются или у которых разбор не удался, не считаются дубликатами.
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/file \
-H "X-API-Key: $API_KEY" -F 'file=@./manual.pdf' -F 'enable_multimodel=true'Загрузка в заданный каталог: передайте в fileName путь относительно корня базы знаний, разделяя каталоги / и сохраняя имя файла с расширением. Отдельного поля folder_path у интерфейса загрузки нет.
curl -X POST "$BASE/api/v1/knowledge-bases/kb-1/knowledge/file" \
-H "X-API-Key: $API_KEY" \
-F 'file=@./design.md' \
-F 'fileName=docs/spec/design.md'Этот запрос относит документ к docs/spec; в возвращаемом Knowledge folder_path равно docs/spec, а file_name — design.md. file=@./design.md задаёт локальный файл, fileName — путь классификации в базе знаний. Если fileName опущен или содержит только имя файла, документ оказывается в корне базы знаний.
Каталоги документальной базы знаний выводятся из folder_path документов и не требуют предварительного создания: после загрузки по новому пути каталог и все промежуточные уровни появляются в дереве. Сейчас нельзя отдельно создать и сохранить пустые каталоги без документов или с документами только в подкаталогах. Интерфейс создания каталогов Wiki относится к каталогам Wiki и для документальных баз знаний не используется.
После загрузки дерево каталогов можно посмотреть через GET /api/v1/knowledge-bases/:id/knowledge/folders (см. ниже). Уже существующие документы можно перенести в новый путь через POST /api/v1/knowledge/folder без повторной загрузки; только этот интерфейс перемещения принимает поле запроса folder_path.
POST /api/v1/knowledge-bases/:id/knowledge/url
Назначение: создать знание, захватив по URL. Права/API key как выше.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
url | string | Да (binding:"required") | Адрес для захвата |
file_name / file_type / title | string | Нет | Переопределяющая информация |
enable_multimodel | *bool | Нет | Переключатель мультимодальности |
tag_ids | []string | Нет | Теги |
channel | string | Нет | Канал |
process_config | object | Нет | Переопределение разбора |
Ответ: 201 {"success":true,"data":{Knowledge}}; повторный URL возвращает 409.
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/url -H "X-API-Key: $API_KEY" \
-H 'Content-Type: application/json' -d '{"url":"https://example.com/doc"}'POST /api/v1/knowledge-bases/:id/knowledge/manual
Назначение: создание ручного (Markdown) знания. Права/API key как выше.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
title | string | Нет | Заголовок |
content | string | Нет | Содержимое Markdown |
status | string | Нет | draft / publish |
tag_ids | []string | Нет | Теги |
channel | string | Нет | Канал |
process_config | object | Нет | Переопределение разбора |
Ответ: 200 {"success":true,"data":{Knowledge}}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/manual -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"title":"Сводка FAQ","content":"# содержимое","status":"publish"}'GET /api/v1/knowledge-bases/:id/knowledge
Назначение: список знаний в KB. Права: Viewer+, KB read; API key retrieve/full.
| Параметр запроса | Тип | Обязательный | Описание |
|---|---|---|---|
page / page_size | int | Нет | Пагинация (по умолчанию 1/20) |
tag_ids | string | Нет | Теги через запятую (OR) |
keyword | string | Нет | Ключевое слово |
file_type | string | Нет | Фильтр по типу файла |
parse_status | string | Нет | pending/processing/completed/failed |
source | string | Нет | Канал или manual/url |
start_time / end_time | string | Нет | RFC3339, фильтр по updated_at |
folder_path | string | Нет | Фильтр по папке; пустая строка означает корневой каталог базы знаний, при пропуске фильтрация по папке не применяется |
folder_recursive | bool | Нет | Работает вместе с folder_path; при true включать документы из подпапок |
sort_by | string | Нет | Поле сортировки: updated_at, created_at или file_name; по умолчанию created_at |
sort_order | string | Нет | Направление сортировки: asc или desc; по умолчанию desc |
Если параметры сортировки не переданы, сортировка по created_at desc; значение вне указанного диапазона возвращает 400. При использовании updated_at порядок зависит от повторного разбора, редактирования или изменения статуса; при использовании file_name сортировка по отображаемому имени файла без учёта регистра, а при пустом имени файла последовательно берутся заголовок и источник. При одинаковых значениях сортировки порядок по ID знания, что обеспечивает стабильность постраничных результатов.
Ответ: 200 {"success":true,"data":[Knowledge],"total","page","page_size"}
curl "$BASE/api/v1/knowledge-bases/kb-1/knowledge?page=1&parse_status=completed" -H "X-API-Key: $API_KEY"POST /api/v1/knowledge-bases/:id/knowledge/batch-download
Назначение: упаковать исходные файлы нескольких документов одной базы знаний в ZIP для загрузки. Права как при загрузке одного файла: Contributor+ и KB write (общий Viewer в организации не может скачать); API key retrieve/full.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
ids | []string | Да | Список ID знаний, от 1 до 200 |
Поведение:
- Суммарный объём исходных файлов не более 512 MiB, при превышении возвращается 400;
- Записи без исходных файлов (например, импортированные веб-страницы) пропускаются; если ни у одной из выбранных записей нет исходного файла, возвращается 400;
- Внутри ZIP сохраняется структура папок базы знаний, к одноимённым файлам автоматически добавляется номер;
- Если любой ID не существует или не принадлежит этой базе знаний, возвращается 404; сбой чтения возвращает 500; архив с отсутствующими файлами не создаётся;
- Один экземпляр одновременно обрабатывает не более 4 пакетных загрузок, при превышении возвращается 429.
Ответ: 200 файловый поток application/zip, имя файла вида knowledge-files-20260923-150405.zip.
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/batch-download \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"ids":["k-1","k-2"]}' -o knowledge-files.zipGET /api/v1/knowledge-bases/:id/knowledge/folders
Назначение: получение дерева каталогов базы знаний. При загрузке всего каталога структура каталогов сохраняется (начиная с migration 000079 существует столбец knowledges.folder_path; пути из исторического file_name уже перенесены в это поле). Права: Viewer+ + KBAccessRead.
Дерево каталогов формируется сводкой по folder_path записей знаний; промежуточные каталоги без собственных документов, но с документами в подкаталогах, тоже возвращаются. Как только последний документ каталога и все документы его подкаталогов переносятся, каталог исчезает из дерева.
Ответ: 200. Пример (есть только загруженный выше docs/spec/design.md):
{
"success": true,
"data": {
"root_document_count": 0,
"total_document_count": 1,
"folders": [{
"path": "docs",
"name": "docs",
"document_count": 0,
"total_count": 1,
"children": [{
"path": "docs/spec",
"name": "spec",
"document_count": 1,
"total_count": 1
}]
}]
}
}root_document_count — число документов в корне базы знаний, total_document_count — общее число документов базы знаний; у узлов каталогов document_count считает только непосредственные документы, а total_count включает документы всех подкаталогов.
curl $BASE/api/v1/knowledge-bases/kb-1/knowledge/folders -H "Authorization: Bearer $TOKEN"PUT /api/v1/knowledge-bases/:id/knowledge/folders
Назначение: переименование или перемещение папки; путь изменяется вместе со всеми её подкаталогами. Если целевой путь уже существует, две папки объединяются; перемещение в собственный подкаталог запрещено. Права: KB owner или Admin+ + KBAccessWrite.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
from | string | Да | Исходный путь |
to | string | Да | Новый путь |
Ответ: 200 {"success":true}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/knowledge/folders -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"from":"проектная документация/старая версия","to":"архив/проектная документация"}'DELETE /api/v1/knowledge-bases/:id/knowledge
Назначение: очистить всё содержимое KB (деструктивно). Права: Admin+, KB write; API key только full-access.
Ответ: 200 {"success":true,"message":"Knowledge base contents clear task submitted","data":{"deleted_count":N}}
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/knowledge -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge/batch
Назначение: пакетное получение знаний по ID (кросс-KB, доступ проверяется в handler самостоятельно). Права: Viewer+; API key retrieve/full.
| Параметр запроса | Тип | Обязательный | Описание |
|---|---|---|---|
ids | []string | Да | ID знаний (можно повторять параметр или через запятую) |
kb_id | string | Нет | Ограничить KB |
agent_id | string | Нет | Область общего Agent |
agent_source_tenant_id | uint64 | Нет | Селектор пространства-источника общего Agent, проверяется по отношению публикации |
Ответ: 200 {"success":true,"data":[Knowledge]}. Знания в статусе pending/processing/finalizing дополнительно несут last_activity_at (RFC3339) — берётся более позднее из updated_at строки и последней записи по всем span этого знания. Знания без прогресса более 20 минут дополнительно несут stall_state: queued означает, что задачи всё ещё ждут в очереди asynq или в постоянной очереди Wiki (накопление), stalled означает, что нет задач, способных продвинуть его (предположительно зависло). Логика определения та же, что у определения накопления в housekeeping; на стороне очереди это однократное сканирование всей очереди, разделяемое всеми запросами с кэшем 60 секунд. При сбое зондирования stall_state не возвращается, и фронтенд отображает его как обычный разбор.
curl "$BASE/api/v1/knowledge/batch?ids=k-1&ids=k-2" -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge/:id
Назначение: сведения о знании. Права: Viewer+, родительская KB read.
Ответ: 200 {"success":true,"data":{Knowledge}}
curl $BASE/api/v1/knowledge/k-1 -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge/:id/stages и GET /api/v1/knowledge/:id/spans
Назначение: этапы разбора/trace (оба пути — один handler GetKnowledgeSpans). Права: Viewer+, родительская KB read. Параметр запроса: attempt (int, 0=последняя попытка).
Ответ: 200 {"success":true,"data":{"knowledge_id","attempt","latest_attempt","parse_status","current_stage","last_activity_at","stall_state","trace":{...},"last_error":{...}}}
last_activity_at возвращается только во время выполнения разбора, берётся более позднее из updated_at строки и последней записи по всем span текущей попытки; смысл stall_state как выше. current_stage — этап, который всё ещё выполняется; если выполняющихся этапов нет (например, finalizing, когда этапы постобработки закрыты, а подзадачи вроде резюме всё ещё выполняются), берётся этап, к которому принадлежит всё ещё выполняющийся дочерний span. У знаний, признанных housekeeping зависшими, span места зависания помечается как неуспешный с TASK_STALLED, и last_error в первую очередь указывает на него.
curl $BASE/api/v1/knowledge/k-1/spans -H "Authorization: Bearer $TOKEN"DELETE /api/v1/knowledge/:id
Назначение: удаление знания (асинхронно). Права: создатель KB OR Admin+, KB write; API key ingest/full.
Ответ: 200 {"success":true,"message":"Delete task submitted","data":{"task_id"}}
curl -X DELETE $BASE/api/v1/knowledge/k-1 -H "X-API-Key: $API_KEY"PUT /api/v1/knowledge/:id
Назначение: обновление метаинформации знания. Права как выше. Тело запроса (подмножество types.Knowledge): title, description, tags, custom_metadata (все необязательны). Пропуск description сохраняет прежнее резюме, явная пустая строка очищает резюме, непустое значение сохраняет ручное резюме; в интерфейсе можно редактировать на странице содержимого документа.
custom_metadata — описательные метаданные, заполняемые пользователем (хранятся отдельно от metadata, используемых внутри системы, migration 000078); правила валидации см. в internal/application/service/knowledge.go:
| Ограничение | Значение |
|---|---|
| Число полей | ≤ 20 |
| Длина ключа | 1-64 символа, не может быть пробельным |
| Тип значения | string / number / boolean / null |
| Длина значения | ≤ 1000 символов |
Обновление целиком перезаписью (переданный объект заменяет прежний объект). Если метаданные изменились и у документа уже есть резюме, автоматически ставится в очередь одно обновление резюме (summary_status переходит в pending). Текст метаданных участвует в генерации резюме и в контексте модели уровня документа (Knowledge.CustomMetadataText()).
Ответ: 200 {"success":true,"message":"Knowledge updated successfully","data":{Knowledge}}
curl -X PUT $BASE/api/v1/knowledge/k-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"title":"новый заголовок","custom_metadata":{"отдел":"центр разработки","уровень секретности":"внутренний","версия":3}}'POST /api/v1/knowledge/:id/regenerate-summary
Назначение: перегенерировать резюме этого документа после редактирования содержимого блока или пользовательских метаданных. Права: KB owner или Admin+, и есть право write на родительскую KB.
Поведение бывает двух видов: если у документа ранее не было резюме (summary_status пусто или none), генерация запускается синхронно; если резюме уже есть, вместо этого ставится в очередь задача обновления, summary_status переходит в pending, и она выполняется асинхронно через knowledge_summary_refresh.go.
Ответ: 200 {"success":true,"data":{Knowledge}}
curl -X POST $BASE/api/v1/knowledge/k-1/regenerate-summary -H "Authorization: Bearer $TOKEN"PUT /api/v1/knowledge/manual/:id
Назначение: полная замена вручную введённого Markdown (подмножество ManualKnowledgePayload: title/content/status/...). Применяется только к ручным знаниям; содержимое загруженных файлов этим интерфейсом изменить нельзя. content — полный текст, пустое содержимое отклоняется. status — draft (не попадает в поиск) или publish (строится индекс); если status не передан, запись сохраняется как черновик. Права как выше.
Ответ: 200 {"success":true,"data":{Knowledge}}
curl -X PUT $BASE/api/v1/knowledge/manual/k-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"content":"# обновлённое содержимое","status":"publish"}'POST /api/v1/knowledge/:id/reparse
Назначение: повторный разбор знания. Права как выше. Тело запроса (необязательно): {"process_config":{...}}.
Ответ: 200 {"success":true,"message":"Reparse task submitted","data":{Knowledge}}
curl -X POST $BASE/api/v1/knowledge/k-1/reparse -H "X-API-Key: $API_KEY"POST /api/v1/knowledge/:id/cancel-parse
Назначение: отмена разбора. Права как выше. Без тела запроса.
Ответ: 200 {"success":true,"message":"Knowledge parse cancelled","data":{Knowledge}}
curl -X POST $BASE/api/v1/knowledge/k-1/cancel-parse -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge/:id/download
Назначение: загрузка исходного файла (строже, чем предпросмотр: Contributor+ и KB write; общий Viewer в организации не может скачать исходный файл). API key retrieve/full.
Ответ: 200 бинарный поток (application/octet-stream).
curl -OJ $BASE/api/v1/knowledge/k-1/download -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge/:id/preview
Назначение: предпросмотр содержимого файла после разбора. Права: Viewer+, KB read.
Ответ: 200 поток предпросмотра (текст/HTML).
curl $BASE/api/v1/knowledge/k-1/preview -H "Authorization: Bearer $TOKEN"PUT /api/v1/knowledge/image/:id/:chunk_id
Назначение: обновление информации об изображениях некоторого блока (caption/OCR и т. п.). Права: создатель KB OR Admin+, KB write. Параметры пути: id — ID знания, chunk_id — ID блока. Тело запроса — JSON с информацией об изображениях.
Ответ: 200 {"success":true,...}
curl -X PUT $BASE/api/v1/knowledge/image/k-1/c-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"caption":"схема архитектуры"}'GET /api/v1/knowledge/search
Назначение: поиск файлов по всем KB (селектор @файл в сессии). Права: Viewer+; API key retrieve/full.
| Параметр запроса | Тип | Обязательный | Описание |
|---|---|---|---|
keyword / query | string | Условно обязательный | Ключевое слово (оба равнозначны); при пустом значении обязательно передать recent=true, иначе возвращается 400 |
file_types | string | Нет | Фильтр по расширениям через запятую, например csv,xlsx |
offset / limit | int | Нет | Пагинация; limit по умолчанию 20, диапазон от 1 до 100 |
recent | bool | Нет | При пустом ключевом слове возвращать последние файлы |
agent_id | string | Нет | Область общего Agent |
agent_source_tenant_id | uint64 | Нет | Селектор пространства-источника общего Agent, проверяется по отношению публикации |
Ответ: 200 {"success":true,"data":[Knowledge],"has_more":bool,"total":N}
curl "$BASE/api/v1/knowledge/search?keyword=отчёт&limit=20" -H "Authorization: Bearer $TOKEN"GET /api/v1/knowledge/move/progress/:task_id
Назначение: запрос прогресса задачи перемещения. Права: Viewer+; API key retrieve/full.
Ответ: 200 {"success":true,"data":{MoveProgress}}
curl $BASE/api/v1/knowledge/move/progress/task-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/knowledge/tags
Назначение: пакетное обновление тегов знаний. Права: Contributor+; API key ingest/full (белый список KB проверяется в handler). Два способа взаимоисключающие: updates либо knowledge_ids вместе с tag_ids.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
updates | map[string][]string | одно из двух с knowledge_ids | knowledge_id → tag_ids, заменяет существующие теги документа |
kb_id | string | Нет | Ограничить KB; если не передан, выводится из первого знания |
knowledge_ids | []string | одно из двух с updates | максимум 20 документов, одна и та же группа тегов |
tag_ids | []string | обязательно при knowledge_ids | максимум 50; пустой массив очищает теги |
Ответ: 200 {"success":true}
curl -X PUT $BASE/api/v1/knowledge/tags -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"updates":{"k-1":["t-1"]},"kb_id":"kb-1"}'POST /api/v1/knowledge/batch-reparse
Назначение: пакетный повторный разбор. Права: Contributor+; API key ingest/full.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
kb_id | string | Да (binding:"required") | KB ID |
ids | []string | Да (binding:"required") | Список ID знаний |
process_config | object | Нет | Переопределение разбора |
Ответ: 200 {"success":true,"message":"Batch reparse task submitted","data":{"task_id"}}
curl -X POST $BASE/api/v1/knowledge/batch-reparse -H "X-API-Key: $API_KEY" \
-H 'Content-Type: application/json' -d '{"kb_id":"kb-1","ids":["k-1","k-2"]}'POST /api/v1/knowledge/batch-delete
Назначение: пакетное удаление (≤200 записей). Права: Contributor+; API key ingest/full.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
kb_id | string | Да (binding:"required") | KB ID |
ids | []string | Да (binding:"required") | Список ID знаний (≤200) |
Ответ: 200 {"success":true,"message":"Batch delete task submitted","data":{"task_id","deleted_count"}}
curl -X POST $BASE/api/v1/knowledge/batch-delete -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"kb_id":"kb-1","ids":["k-1"]}'POST /api/v1/knowledge/folder
Назначение: отнести несколько документов в указанную папку (меняется только классификация; принадлежность к базе знаний и повторный разбор не затрагиваются). Права: Contributor+ / API key ingest.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
kb_id | string | Да | ID базы знаний |
knowledge_ids | []string | Да | Перемещаемые документы |
folder_path | string | Нет | Путь целевой папки относительно корня базы знаний, например docs/spec; новый путь не нужно создавать заранее, пустая строка означает перенос в корень базы знаний |
Ответ: 200 {"success":true}
curl -X POST $BASE/api/v1/knowledge/folder -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"kb_id":"kb-1","knowledge_ids":["k-1","k-2"],"folder_path":"проектная документация"}'POST /api/v1/knowledge/move
Назначение: перемещение знаний между KB (асинхронно). Права: Contributor+; API key ingest/full (и исходная, и целевая KB должны быть в белом списке).
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
knowledge_ids | []string | Да (binding:"required,min=1") | Перемещаемые знания |
source_kb_id | string | Да (binding:"required") | Исходная KB |
target_kb_id | string | Да (binding:"required") | Целевая KB |
mode | string | Да (binding:"required,oneof=reuse_vectors reparse") | Переиспользовать векторы или повторно разобрать |
Ответ: 200 {"success":true,"data":{"task_id","source_kb_id","target_kb_id","knowledge_count","message"}}
curl -X POST $BASE/api/v1/knowledge/move -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"knowledge_ids":["k-1"],"source_kb_id":"kb-1","target_kb_id":"kb-2","mode":"reuse_vectors"}'Галерея и свойства изображений
Чтение галереи требует Viewer+ и права чтения на целевую базу знаний; API-ключ — retrieve или full, с соблюдением области базы знаний. Переключатели галереи и векторного индекса изображений независимы; в список входят описания извлечённых изображений, OCR и источник.
GET /api/v1/knowledge-bases/:id/gallery-config
Возвращает {"success":true,"data":{"attribute_sources":[...],"attributes":[...],"mode":"...","status":{...}}}. Клиент строит поиск, фильтрацию и сортировку по возвращённым определениям свойств и политикам их использования; не хардкодьте доступные свойства. ID свойств имеют префикс источника, например builtin:caption, system:contain.text.
GET /api/v1/knowledge-bases/:id/images
| Параметр запроса | Описание |
|---|---|
page / page_size | по умолчанию 1 / 20, page_size максимум 1000 |
keyword / search_in | поиск подстроки без учёта регистра; search_in — ID искомых свойств через запятую, по умолчанию описание и OCR |
sort_by / sort_order | ID сортируемого свойства, по умолчанию created_at / desc; поддерживаются также старые значения created_at, updated_at, caption |
knowledge_ids | ID исходных документов через запятую; GET берёт только первые 50, для большего числа документов используйте POST |
is_enabled | true / false, фильтр по состоянию включения принадлежащего блока |
attr_filters | JSON-объект: ID свойства → массив допустимых значений; по одному свойству OR, между свойствами AND |
attr_rules | JSON-объект: ID свойства → значение → on/off; принудительный показ через on имеет приоритет над off, изображения, не попавшие в правила, сохраняются |
Принимаются только поля поиска, фильтрации и сортировки, признанные применимыми в gallery-config; неприменимые поля отбрасываются. Ответ {"success":true,"data":[ImageAsset],"total":N,"page":1,"page_size":20}. Каждый элемент содержит id, chunk_id, knowledge_id, source_name, url, original_url, caption, ocr_text, attrs, is_enabled, status и метки времени.
POST /api/v1/knowledge-bases/:id/images
Тот же read-only запрос, что и GET, но параметры передаются в JSON body; knowledge_ids и search_in — массивы строк, attr_filters / attr_rules передаются объектами напрямую. Исходных документов — максимум 1000, при превышении возвращается 400; удобно при полном выделении фильтра по источнику, чтобы URL не оказался слишком длинным.
curl -X POST "$BASE/api/v1/knowledge-bases/kb-1/images" -H "X-API-Key: $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"page":1,"page_size":20,"knowledge_ids":["k-1","k-2"],"keyword":"архитектура"}'GET /api/v1/image-attrs/schema
Глобальный read-only реестр свойств наблюдения за изображениями; требуется Viewer+, API-ключ retrieve/full, привязки к базе знаний в пути нет. Редактор базы знаний использует его для настройки условий наблюдения за изображениями и OCR; фактическое применение поиска и фильтрации в галерее определяется gallery-config конкретной базы знаний.
Справочник по реализации
Регистрация маршрутов: RegisterKnowledgeBaseRoutes, RegisterKnowledgeRoutes в internal/router/routes_knowledge.go. Handler: internal/handler/knowledgebase.go, internal/handler/knowledge.go.