sdk/KB_API_Guide.md

Knowledge Base API — Руководство

Базовый URL: https://api.er-gpt.ru

Все запросы требуют авторизации (передавай токен в заголовке Authorization: Bearer <token>).

---

1. Базы знаний (Knowledge Base)

1.1 Создать базу знаний

curl -X POST https://api.er-gpt.ru/api/knowledge \
  -H "Authorization: Bearer <token>" \
  -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

{
  "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 Получить список баз знаний

curl -X GET "https://api.er-gpt.ru/api/knowledge?current=0&page_size=10" \
  -H "Authorization: Bearer <token>"

Query-параметры:

Параметр	Тип	По умолчанию	Описание
search	string	null	Поиск по названию/описанию
current	integer	0	Номер страницы (0-based)
page_size	integer	10	Количество элементов на странице

Ответ:

{
  "result": [ /* массив KnowledgeBase */ ],
  "total": 42
}

1.3 Получить одну базу знаний

curl -X GET https://api.er-gpt.ru/api/knowledge/{id} \
  -H "Authorization: Bearer <token>"

Параметры пути:

Параметр	Тип	Описание
id	UUID	ID базы знаний

Ответ: объект QueryKnowledgeBaseAggregate (включает documents_count)

1.4 Обновить базу знаний

curl -X PATCH https://api.er-gpt.ru/api/knowledge/{id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Новое название",
    "description": "Новое описание"
  }'

Параметры тела запроса:

Поле	Тип	Обязательное	Описание
name	string	Да	Новое название
description	string	Да	Новое описание

1.5 Удалить базу знаний

curl -X DELETE https://api.er-gpt.ru/api/knowledge/{id} \
  -H "Authorization: Bearer <token>"

Важно: удаление базы знаний каскадно удаляет все связанные с ней документы и чанки.

---

2. Документы

2.1 Загрузить документ в базу знаний

curl -X POST https://api.er-gpt.ru/api/knowledge/upload/{kb_id} \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf"

Параметры пути:

Параметр	Тип	Описание
kb_id	UUID	ID базы знаний

Тело запроса: multipart/form-data с полем file (бинарный файл)

Ответ: объект DocumentWithContentUrl

{
  "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 Получить список документов базы знаний

curl -X GET "https://api.er-gpt.ru/api/knowledge/{kb_id}/documents?statuses=PENDING&statuses=FAILED&current=0&page_size=10" \
  -H "Authorization: Bearer <token>"

Параметры пути:

Параметр	Тип	Описание
kb_id	UUID	ID базы знаний

Query-параметры:

Параметр	Тип	По умолчанию	Описание
statuses	string[]	null	Фильтр по статусам (можно несколько)
current	integer	0	Номер страницы
page_size	integer	10	Размер страницы

Ответ:

{
  "result": [ /* массив DocumentWithContentUrl */ ],
  "total": 15
}

2.3 Удалить документ

curl -X DELETE https://api.er-gpt.ru/api/knowledge/document/{document_id} \
  -H "Authorization: Bearer <token>"

2.4 Массовое удаление документов

curl -X DELETE "https://api.er-gpt.ru/api/knowledge/document/bulk?document_ids=uuid1&document_ids=uuid2&document_ids=uuid3" \
  -H "Authorization: Bearer <token>"

Query-параметры:

Параметр	Тип	Описание
document_ids	UUID[]	Массив ID документов для удаления

2.5 Перезапустить обработку документа

curl -X POST https://api.er-gpt.ru/api/knowledge/{document_id}/retry \
  -H "Authorization: Bearer <token>"

Полезно, если документ застрял в статусе FAILED или PENDING.

---

3. Чанки документов

3.1 Получить чанки документа

curl -X GET "https://api.er-gpt.ru/api/knowledge/documents/{document_id}/chunks?limit=10&cursor=<cursor>" \
  -H "Authorization: Bearer <token>"

Параметры пути:

Параметр	Тип	Описание
document_id	UUID	ID документа

Query-параметры:

Параметр	Тип	По умолчанию	Описание
search	string	null	Поисковый запрос по тексту чанков
cursor	string	null	Курсор для пагинации
limit	integer	10	Количество чанков за запрос

Ответ:

{
  "pagination": {
    "cursor": "next_cursor_string",
    "has_more": true
  },
  "result": [
    {
      "text": "Содержимое чанка...",
      "document_id": "uuid",
      "filename": "document.pdf",
      "chunk_id": 0
    }
  ]
}

---

4. Поиск по базе знаний

4.1 Семантический поиск

curl -X POST https://api.er-gpt.ru/api/knowledge/{kb_id}/search \
  -H "Authorization: Bearer <token>" \
  -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)

Ответ:

{
  "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

{
  "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

{
  "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 при валидационных ошибках:

{
  "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