Справочник API: блоки и теги

Блок (chunk) — минимальная единица поиска, теги используются для классификации документов. Обе группы эндпоинтов относятся к ресурсам базы знаний и используют те же правила прав, что и базы знаний и знания: чтение — Viewer+ и право read на родительскую KB (API key retrieve); запись — «создатель KB OR Admin+» и право write (API key ingest); обе ограничены белым списком KB у API key.

Общие соглашения (Base URL, аутентификация, коды ошибок, пагинация) см. в Обзоре API.

Блоки (/api/v1/chunks)

Handler: internal/handler/chunk.go. Чтение: Viewer+ и read на родительскую KB (API key retrieve/full); запись: создатель KB OR Admin+ и write на родительскую KB (API key ingest/full).

GET /api/v1/chunks/:knowledge_id

Назначение: список блоков знания.

Параметр запроса	Тип	Обязательный	Описание
page	int	Нет	По умолчанию 1
page_size	int	Нет	По умолчанию 10, максимум 100
chunk_type	string	Нет	Можно повторять; фильтр по типу блока

Ответ: 200 {"success":true,"data":[Chunk],"total","page","page_size"}

curl "$BASE/api/v1/chunks/k-1?page=1" -H "Authorization: Bearer $TOKEN"

GET /api/v1/chunks/by-id/:id

Назначение: получить один блок по chunk ID (без knowledge_id).

Ответ: 200 {"success":true,"data":{Chunk}}. Chunk.source_locators — позиция блока в исходном файле; структура описана в разделе source_locators в Обзоре API.

curl $BASE/api/v1/chunks/by-id/c-1 -H "Authorization: Bearer $TOKEN"

PUT /api/v1/chunks/:knowledge_id/:id

Назначение: редактирование содержимого блока или его включение/отключение (начиная с migration 000078 — версионируемое оптимистичное обновление).

Поле	Тип	Обязательное	Описание
content	string	Нет	Новое содержимое; после удаления начальных и конечных пробелов не должно быть пустым; максимум 200000 байт
is_enabled	bool	Нет	Включить/отключить этот блок
expected_revision	int	Нет	Ожидаемый content_revision для оптимистичного контроля параллелизма

Ограничения и побочные эффекты:

• редактировать можно только блоки типа text; для других типов возвращается 400;
• при несовпадении expected_revision с текущим content_revision возвращается 409 (Chunk was modified by another user; refresh and retry);
• нельзя добавлять при редактировании URL изображений, которых нет в исходном содержимом; удаление Markdown-изображения одновременно отключает соответствующий дочерний блок OCR/caption;
• после успешного редактирования content_revision увеличивается на 1, старая версия записывается в таблицу chunk_revisions, а index_status последовательно проходит processing → ready; если переиндексация не удалась, строка всё равно сохраняется, но index_status = failed; повторная отправка того же содержимого запускает повторную попытку;
• при редактировании дочернего блока содержимое родительского блока перезаписывается по смещению (source_content родительского блока остаётся неизменным);
• изменение содержимого или состояния включения ставит в очередь обновление сводки документа.

Ответ: 200 {"success":true,"data":{Chunk},"summary_status":"pending","description":"..."}

curl -X PUT $BASE/api/v1/chunks/k-1/c-1 -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"content":"Исправленное содержимое","expected_revision":2}'

GET /api/v1/chunks/:knowledge_id/:id/revisions

Назначение: список исторических версий блока (таблица chunk_revisions, по revision в порядке убывания).

Ответ: 200 {"success":true,"data":[{ChunkRevision}]}, каждая запись содержит revision, content, is_enabled, editor_id, edit_source, edited_at.

curl $BASE/api/v1/chunks/k-1/c-1/revisions -H "Authorization: Bearer $TOKEN"

POST /api/v1/chunks/:knowledge_id/:id/revert

Назначение: откат к исторической версии. Сам откат — тоже новое редактирование: content_revision продолжает увеличиваться, а текущее содержимое сохраняется как новая историческая версия.

Поле	Тип	Обязательное	Описание
revision	int	Да	Номер целевой исторической версии (неотрицательный)
expected_revision	int	Нет	Оптимистичная блокировка, семантика та же; при конфликте возвращается 409

Ответ: 200 {"success":true,"data":{Chunk},"summary_status":"...","description":"..."}

curl -X POST $BASE/api/v1/chunks/k-1/c-1/revert -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"revision":1}'

DELETE /api/v1/chunks/:knowledge_id/:id

Назначение: удалить один блок.

Ответ: 200 {"success":true,"message":"Chunk deleted"}

curl -X DELETE $BASE/api/v1/chunks/k-1/c-1 -H "Authorization: Bearer $TOKEN"

DELETE /api/v1/chunks/:knowledge_id

Назначение: удалить все блоки знания.

Ответ: 200 {"success":true,"message":"All chunks under knowledge deleted"}

curl -X DELETE $BASE/api/v1/chunks/k-1 -H "Authorization: Bearer $TOKEN"

DELETE /api/v1/chunks/by-id/:id/questions

Назначение: удалить один сгенерированный вопрос у этого блока. Тело запроса: {"question_id":"..."} (binding:"required").

Ответ: 200 {"success":true,"message":"Generated question deleted"}

curl -X DELETE $BASE/api/v1/chunks/by-id/c-1/questions -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"question_id":"q-1"}'

PUT /api/v1/chunks/by-id/:id/questions

Назначение: добавить или изменить один сгенерированный вопрос у этого блока. Тело запроса: {"question":"...","question_id":"..."}; question обязателен; пустой question_id означает создание.

Ответ: 200 {"success":true,"data":{GeneratedQuestion}}

curl -X PUT $BASE/api/v1/chunks/by-id/c-1/questions -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"question_id":"q-1","question":"Как настроить векторное хранилище в aihelpme.ru?"}'

POST /api/v1/chunks/by-id/:id/questions/regenerate

Назначение: заново сгенерировать поисковые вопросы на основе текущего содержимого блока. После редактирования содержимого существующие вопросы не удаляются, а помечаются как «устаревшие» (revision не совпадает с текущим текстом); их можно обновить этим эндпоинтом.

Ответ: 200 {"success":true,"data":[{GeneratedQuestion}]}

curl -X POST $BASE/api/v1/chunks/by-id/c-1/questions/regenerate -H "Authorization: Bearer $TOKEN"

Теги (/api/v1/knowledge-bases/:id/tags)

Handler: internal/handler/tag.go. Чтение: Viewer+ + KB read (API key retrieve/full); запись: создатель KB OR Admin+ + KB write (API key ingest/full).

GET /api/v1/knowledge-bases/:id/tags

Назначение: список тегов. Параметры запроса: page, page_size, keyword (все необязательны).

Ответ: 200 {"success":true,"data":[KnowledgeTag]}

curl $BASE/api/v1/knowledge-bases/kb-1/tags -H "Authorization: Bearer $TOKEN"

POST /api/v1/knowledge-bases/:id/tags

Назначение: создать тег.

Поле	Тип	Обязательное	Описание
name	string	Да (binding:"required")	Имя тега
color	string	Нет	Цвет
sort_order	int	Нет	Сортировка

Ответ: 200 {"success":true,"data":{KnowledgeTag}}

curl -X POST $BASE/api/v1/knowledge-bases/kb-1/tags -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"Послепродажное обслуживание"}'

PUT /api/v1/knowledge-bases/:id/tags/:tag_id

Назначение: обновить тег (tag_id принимает UUID или целочисленный seq_id). Тело запроса: name/color/sort_order (поля-указатели, все необязательны).

Ответ: 200 {"success":true,"data":{KnowledgeTag}}

curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/tags/t-1 -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"Послепродажная поддержка"}'

DELETE /api/v1/knowledge-bases/:id/tags/:tag_id

Назначение: удалить тег. Параметры запроса: force (bool, удалить тег вместе с документами или записями FAQ, всё ещё ссылающимися на него), content_only (bool, удалить только содержимое тега, сохранив сам тег). Тело запроса (необязательно): {"exclude_ids":[int64]} — перечисляет seq_id записей FAQ, которые нужно сохранить при удалении. Если force не передан, а на тег всё ещё ссылаются знания или записи FAQ, возвращается 400 и документы не удаляются.

Некорректный формат тела запроса или ID, не являющийся положительным целым, — 400; несуществующий ID — 404; ID записи FAQ, не принадлежащей текущей базе знаний, — 403.

Ответ: 200 {"success":true}

curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/tags/t-1 -H "Authorization: Bearer $TOKEN"

Отладка разбиения на блоки

POST /api/v1/chunker/preview

Назначение: предпросмотр разбиения на блоки без сохранения состояния (панель отладки редактора KB). Права: Viewer+; API key retrieve/ingest/full. Handler: internal/handler/chunker_debug.go

Поле	Тип	Обязательное	Описание
text	string	Да (проверка на непустоту в коде, ≤64k символов)	Образец текста
chunking_config.chunk_size	int	Нет	Число символов в блоке
chunking_config.chunk_overlap	int	Нет	Перекрытие
chunking_config.separators	[]string	Нет	Разделители
chunking_config.strategy	string	Нет	auto/heading/heuristic/recursive/legacy
chunking_config.token_limit	int	Нет	Лимит token
chunking_config.languages	[]string	Нет	Подсказки по языкам
chunking_config.enable_parent_child	bool	Нет	Пробное разбиение по схеме родитель-потомок; возвращаются дочерние блоки (совпадает с гранулярностью поиска)
chunking_config.parent_chunk_size / child_chunk_size	int	Нет	Размер родительского/дочернего блока; по умолчанию 4096 / 384

Встроенный HTML <table> в образце текста сначала преобразуется в Markdown-таблицу — так же, как при загрузке в базу.

Ответ: 200 {"success":true,"data":{"selected_tier","tier_chain","rejected","profile","chunks":[...],"stats":{count,avg_chars,min_chars,max_chars,stddev_chars,truncated_to}}}; слишком длинный текст — 413; тайм-аут разбиения (5s) — 504.

curl -X POST $BASE/api/v1/chunker/preview -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"text":"# Заголовок\nТекст...","chunking_config":{"chunk_size":512}}'

Справочник по реализации

Регистрация маршрутов: RegisterChunkRoutes, RegisterKnowledgeTagRoutes, RegisterChunkerDebugRoutes в internal/router/routes_knowledge.go.