docs: add Knowledge Base API guide
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
mrmamongo
commit
2926e702d7
1 changed files with 401 additions and 0 deletions
401
KB_API_Guide.md
Normal file
401
KB_API_Guide.md
Normal file
|
|
@ -0,0 +1,401 @@
|
|||
# Knowledge Base API — Руководство
|
||||
|
||||
Базовый URL: `https://api.er-gpt.ru`
|
||||
|
||||
Все запросы требуют авторизации (передавай токен в заголовке `Authorization: Bearer <token>`).
|
||||
|
||||
---
|
||||
|
||||
## 1. Базы знаний (Knowledge Base)
|
||||
|
||||
### 1.1 Создать базу знаний
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
```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 <token>"
|
||||
```
|
||||
|
||||
**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 <token>"
|
||||
```
|
||||
|
||||
**Параметры пути:**
|
||||
|
||||
| Параметр | Тип | Описание |
|
||||
|----------|-----|----------|
|
||||
| `id` | UUID | ID базы знаний |
|
||||
|
||||
**Ответ:** объект `QueryKnowledgeBaseAggregate` (включает `documents_count`)
|
||||
|
||||
### 1.4 Обновить базу знаний
|
||||
|
||||
```bash
|
||||
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 Удалить базу знаний
|
||||
|
||||
```bash
|
||||
curl -X DELETE https://api.er-gpt.ru/api/knowledge/{id} \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
> **Важно:** удаление базы знаний каскадно удаляет все связанные с ней документы и чанки.
|
||||
|
||||
---
|
||||
|
||||
## 2. Документы
|
||||
|
||||
### 2.1 Загрузить документ в базу знаний
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
```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 <token>"
|
||||
```
|
||||
|
||||
**Параметры пути:**
|
||||
|
||||
| Параметр | Тип | Описание |
|
||||
|----------|-----|----------|
|
||||
| `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 <token>"
|
||||
```
|
||||
|
||||
### 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 <token>"
|
||||
```
|
||||
|
||||
**Query-параметры:**
|
||||
|
||||
| Параметр | Тип | Описание |
|
||||
|----------|-----|----------|
|
||||
| `document_ids` | UUID[] | Массив ID документов для удаления |
|
||||
|
||||
### 2.5 Перезапустить обработку документа
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.er-gpt.ru/api/knowledge/{document_id}/retry \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
> Полезно, если документ застрял в статусе `FAILED` или `PENDING`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Чанки документов
|
||||
|
||||
### 3.1 Получить чанки документа
|
||||
|
||||
```bash
|
||||
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 | Количество чанков за запрос |
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```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 <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) |
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```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` |
|
||||
Loading…
Reference in a new issue