commit 2926e702d72dd013f691fe5a8c4f0209a576d4e7 Author: mrmamongo Date: Mon Apr 20 12:07:05 2026 +0300 docs: add Knowledge Base API guide Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus diff --git a/KB_API_Guide.md b/KB_API_Guide.md new file mode 100644 index 0000000..3f4dc03 --- /dev/null +++ b/KB_API_Guide.md @@ -0,0 +1,401 @@ +# Knowledge Base API — Руководство + +Базовый URL: `https://api.er-gpt.ru` + +Все запросы требуют авторизации (передавай токен в заголовке `Authorization: Bearer `). + +--- + +## 1. Базы знаний (Knowledge Base) + +### 1.1 Создать базу знаний + +```bash +curl -X POST https://api.er-gpt.ru/api/knowledge \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Моя база знаний", + "description": "Описание базы", + "config": { + "chunk_size": 1000, + "chunk_overlap": 200 + } + }' +``` + +**Параметры тела запроса:** + +| Поле | Тип | Обязательное | Описание | +|------|-----|-------------|----------| +| `name` | string | Да | Название базы знаний | +| `description` | string | Да | Описание базы знаний | +| `config.chunk_size` | integer | Да | Размер чанка (фрагмента текста) | +| `config.chunk_overlap` | integer | Да | Перекрытие между чанками | + +**Ответ:** объект `KnowledgeBase` + +```json +{ + "id": "uuid", + "name": "Моя база знаний", + "description": "Описание базы", + "config": { "chunk_size": 1000, "chunk_overlap": 200 }, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z", + "user_id": "uuid", + "documents_count": 0 +} +``` + +### 1.2 Получить список баз знаний + +```bash +curl -X GET "https://api.er-gpt.ru/api/knowledge?current=0&page_size=10" \ + -H "Authorization: Bearer " +``` + +**Query-параметры:** + +| Параметр | Тип | По умолчанию | Описание | +|----------|-----|-------------|----------| +| `search` | string | null | Поиск по названию/описанию | +| `current` | integer | 0 | Номер страницы (0-based) | +| `page_size` | integer | 10 | Количество элементов на странице | + +**Ответ:** + +```json +{ + "result": [ /* массив KnowledgeBase */ ], + "total": 42 +} +``` + +### 1.3 Получить одну базу знаний + +```bash +curl -X GET https://api.er-gpt.ru/api/knowledge/{id} \ + -H "Authorization: Bearer " +``` + +**Параметры пути:** + +| Параметр | Тип | Описание | +|----------|-----|----------| +| `id` | UUID | ID базы знаний | + +**Ответ:** объект `QueryKnowledgeBaseAggregate` (включает `documents_count`) + +### 1.4 Обновить базу знаний + +```bash +curl -X PATCH https://api.er-gpt.ru/api/knowledge/{id} \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Новое название", + "description": "Новое описание" + }' +``` + +**Параметры тела запроса:** + +| Поле | Тип | Обязательное | Описание | +|------|-----|-------------|----------| +| `name` | string | Да | Новое название | +| `description` | string | Да | Новое описание | + +### 1.5 Удалить базу знаний + +```bash +curl -X DELETE https://api.er-gpt.ru/api/knowledge/{id} \ + -H "Authorization: Bearer " +``` + +> **Важно:** удаление базы знаний каскадно удаляет все связанные с ней документы и чанки. + +--- + +## 2. Документы + +### 2.1 Загрузить документ в базу знаний + +```bash +curl -X POST https://api.er-gpt.ru/api/knowledge/upload/{kb_id} \ + -H "Authorization: Bearer " \ + -F "file=@/path/to/document.pdf" +``` + +**Параметры пути:** + +| Параметр | Тип | Описание | +|----------|-----|----------| +| `kb_id` | UUID | ID базы знаний | + +**Тело запроса:** `multipart/form-data` с полем `file` (бинарный файл) + +**Ответ:** объект `DocumentWithContentUrl` + +```json +{ + "id": "uuid", + "filename": "document.pdf", + "bucket": "documents", + "kb_id": "uuid", + "content_type": "application/pdf", + "size": 123456, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z", + "status": "PENDING", + "error": null, + "content_url": "https://..." +} +``` + +**Статусы документа:** +- `PENDING` — ожидает обработки +- `PROCESSING` — в процессе обработки +- `COMPLETED` — обработан успешно +- `FAILED` — ошибка обработки + +### 2.2 Получить список документов базы знаний + +```bash +curl -X GET "https://api.er-gpt.ru/api/knowledge/{kb_id}/documents?statuses=PENDING&statuses=FAILED¤t=0&page_size=10" \ + -H "Authorization: Bearer " +``` + +**Параметры пути:** + +| Параметр | Тип | Описание | +|----------|-----|----------| +| `kb_id` | UUID | ID базы знаний | + +**Query-параметры:** + +| Параметр | Тип | По умолчанию | Описание | +|----------|-----|-------------|----------| +| `statuses` | string[] | null | Фильтр по статусам (можно несколько) | +| `current` | integer | 0 | Номер страницы | +| `page_size` | integer | 10 | Размер страницы | + +**Ответ:** + +```json +{ + "result": [ /* массив DocumentWithContentUrl */ ], + "total": 15 +} +``` + +### 2.3 Удалить документ + +```bash +curl -X DELETE https://api.er-gpt.ru/api/knowledge/document/{document_id} \ + -H "Authorization: Bearer " +``` + +### 2.4 Массовое удаление документов + +```bash +curl -X DELETE "https://api.er-gpt.ru/api/knowledge/document/bulk?document_ids=uuid1&document_ids=uuid2&document_ids=uuid3" \ + -H "Authorization: Bearer " +``` + +**Query-параметры:** + +| Параметр | Тип | Описание | +|----------|-----|----------| +| `document_ids` | UUID[] | Массив ID документов для удаления | + +### 2.5 Перезапустить обработку документа + +```bash +curl -X POST https://api.er-gpt.ru/api/knowledge/{document_id}/retry \ + -H "Authorization: Bearer " +``` + +> Полезно, если документ застрял в статусе `FAILED` или `PENDING`. + +--- + +## 3. Чанки документов + +### 3.1 Получить чанки документа + +```bash +curl -X GET "https://api.er-gpt.ru/api/knowledge/documents/{document_id}/chunks?limit=10&cursor=" \ + -H "Authorization: Bearer " +``` + +**Параметры пути:** + +| Параметр | Тип | Описание | +|----------|-----|----------| +| `document_id` | UUID | ID документа | + +**Query-параметры:** + +| Параметр | Тип | По умолчанию | Описание | +|----------|-----|-------------|----------| +| `search` | string | null | Поисковый запрос по тексту чанков | +| `cursor` | string | null | Курсор для пагинации | +| `limit` | integer | 10 | Количество чанков за запрос | + +**Ответ:** + +```json +{ + "pagination": { + "cursor": "next_cursor_string", + "has_more": true + }, + "result": [ + { + "text": "Содержимое чанка...", + "document_id": "uuid", + "filename": "document.pdf", + "chunk_id": 0 + } + ] +} +``` + +--- + +## 4. Поиск по базе знаний + +### 4.1 Семантический поиск + +```bash +curl -X POST https://api.er-gpt.ru/api/knowledge/{kb_id}/search \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "query": "Как настроить авторизацию?", + "kb_id": "uuid", + "limit": 5, + "score_threshold": 0.2 + }' +``` + +**Параметры пути:** + +| Параметр | Тип | Описание | +|----------|-----|----------| +| `kb_id` | UUID | ID базы знаний | + +**Тело запроса:** + +| Поле | Тип | Обязательное | По умолчанию | Описание | +|------|-----|-------------|-------------|----------| +| `query` | string | Да | — | Поисковый запрос | +| `kb_id` | UUID | Да | — | ID базы знаний (дублирует путь) | +| `limit` | integer / null | Нет | null | Максимальное количество результатов | +| `score_threshold` | number | Нет | 0.2 | Минимальный порог релевантности (0.0–1.0) | + +**Ответ:** + +```json +{ + "chunks": [ + { + "id": "uuid", + "filename": "document.pdf", + "bucket": "documents", + "kb_id": "uuid", + "content_type": "application/pdf", + "size": 123456, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z", + "status": "COMPLETED", + "error": null, + "content_url": "https://...", + "chunks": [ + { + "text": "Релевантный фрагмент текста...", + "score": 0.85 + } + ] + } + ] +} +``` + +> Поиск возвращает документы с вложенными чанками, отсортированными по релевантности. Каждый чанк содержит `score` — степень соответствия запросу. + +--- + +## 5. Полная схема KnowledgeBase + +```json +{ + "id": "uuid", + "name": "string", + "description": "string", + "config": { + "chunk_size": 1000, + "chunk_overlap": 200 + }, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z", + "user_id": "uuid", + "documents_count": 0 +} +``` + +## 6. Полная схема DocumentWithContentUrl + +```json +{ + "id": "uuid", + "filename": "string", + "bucket": "string", + "kb_id": "uuid", + "content_type": "string", + "size": 0, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z", + "status": "PENDING | PROCESSING | COMPLETED | FAILED", + "error": "string | null", + "content_url": "string" +} +``` + +--- + +## 7. Обработка ошибок + +Все эндпоинты возвращают `422 Unprocessable Entity` при валидационных ошибках: + +```json +{ + "detail": [ + { + "loc": ["body", "name"], + "msg": "field required", + "type": "value_error.missing" + } + ] +} +``` + +--- + +## 8. Quick Reference + +| Действие | Метод | URL | +|----------|-------|-----| +| Создать базу знаний | `POST` | `/api/knowledge` | +| Получить список баз | `GET` | `/api/knowledge` | +| Получить базу | `GET` | `/api/knowledge/{id}` | +| Обновить базу | `PATCH` | `/api/knowledge/{id}` | +| Удалить базу | `DELETE` | `/api/knowledge/{id}` | +| Загрузить документ | `POST` | `/api/knowledge/upload/{kb_id}` | +| Получить документы базы | `GET` | `/api/knowledge/{kb_id}/documents` | +| Удалить документ | `DELETE` | `/api/knowledge/document/{document_id}` | +| Удалить документы bulk | `DELETE` | `/api/knowledge/document/bulk` | +| Перезапустить обработку | `POST` | `/api/knowledge/{document_id}/retry` | +| Получить чанки | `GET` | `/api/knowledge/documents/{document_id}/chunks` | +| Поиск | `POST` | `/api/knowledge/{kb_id}/search` |