no title

Софтлайн Классификатор. Справочник API

Введение

О документе

Данный документ является справочником по REST API сервиса Софтлайн Классификатор — системы автоматической категоризации текстовых обращений, изображений и аудиозаписей на основе больших языковых моделей (LLM) и технологии RAG (Retrieval-Augmented Generation).

Документ предназначен для разработчиков, которые интегрируют Классификатор во внешние системы или автоматизируют работу с ним без использования веб-интерфейса. Здесь описаны все доступные конечные точки (endpoints), форматы запросов и ответов, правила аутентификации и коды ошибок.

Зачем нужен API

Веб-интерфейс Классификатора ориентирован на ручную работу операторов и администраторов. API предоставляет программный доступ к тем же возможностям и открывает дополнительные сценарии использования:

  • Пакетная обработка. Передача большого объёма обращений на категоризацию без участия оператора.
  • Интеграция с CRM, Service Desk и другими системами. Автоматическая классификация поступающих заявок и маршрутизация их в нужные очереди.
  • Автоматизация модерации и ведения базы знаний. Управление жизненным циклом запросов — от категоризации до добавления в базу знаний RAG — по расписанию или по событию.
  • Встраивание в пайплайны обработки данных. Использование Классификатора как микросервиса внутри более сложных аналитических или операционных процессов.

Архитектурный контекст

Все вызовы API направляются на адрес веб-сервера Классификатора. Веб-сервер проксирует запросы на внутренний бэкенд, обеспечивая единую точку входа с аутентификацией по токену. Прямой доступ к бэкенду из внешних сетей не предполагается.

Базовый URL 

https://<FQDN_Классификатора>/api

Аутентификация

Все запросы требуют API токен в заголовке:

X-API-Token: your_api_token_here

Получить API токен можно через веб-интерфейс в настройках пользователя.

Перечень методов

№ Метод Endpoint Описание
1 POST /api/categorize Категоризация запроса (текст, изображения, аудио)
2 GET /api/requests Получение списка запросов с пагинацией и поиском
3 PUT /api/requests/{id}/moderate Модерация запроса (одобрение или отклонение)
4 POST /api/requests/{id}/kb Добавление запроса в базу знаний RAG
5 DELETE /api/requests/{id}/kb Удаление запроса из базы знаний RAG

Endpoints

1. Категоризация запроса

Основной метод для категоризации текстовых запросов, изображений и аудио.

Endpoint: POST /api/categorize

Headers:

  • X-API-Token: string (обязательно)
  • Content-Type: application/json или multipart/form-data

Вариант 1: JSON с текстом 

{ "query": "Текст запроса", "generation_model": "gemini-2.0-flash-exp", "use_rag_count": true }

Вариант 2: JSON с base64 изображениями 

{ "query": "Описание изображения", "generation_model": "gemini-2.0-flash-exp", "use_rag_count": true, "vision_model": "gemini-2.0-flash-exp", "images": [ "data:image/jpeg;base64,/9j/4AAQSkZJRg...", "data:image/png;base64,iVBORw0KGgo..." ] }

Вариант 3: Multipart form-data с файлами 

Content-Type: multipart/form-data

query: "Текст запроса"
generation_model: "gemini-2.0-flash-exp"
use_rag_count: true
vision_model: "gemini-2.0-flash-exp"
images: [File, File]
audio: [File]

Параметры:

Параметр Тип Обязательный Описание
query string нет* Текстовый запрос
generation_model string да Модель для генерации ответа
use_rag_count boolean нет Использовать ли RAG для подсчета категорий
vision_model string условно** Модель для анализа изображений
images File[] или string[] нет Изображения (файлы или base64)
audio File[] нет Аудио файлы

* Требуется хотя бы один из: query, images, audio
** Обязательно если предоставлены изображения

Response:

{ "llm_text":"<КАТЕГОРИЯ>Обращения, петиции</КАТЕГОРИЯ>", "rag_answer": { "Фейк + спам":30, "Жалобы":9, "Правонарушения":4, "Оперативка":3, "Ошибки на ресурсах":2, "ЖКХ":1, "Обращения, петиции":1 }, "answer":"Обращения, петиции", "request_id":5 }

Примеры запросов:

# Простой текстовый запрос curl -X POST https://your-domain.com/api/categorize \ -H "X-API-Token: your_token" \ -H "Content-Type: application/json" \ -d '{
    "query": "Как подключить интернет?",
    "generation_model": "gemini-2.0-flash-exp",
    "use_rag_count": true
  }' # С изображением (base64) curl -X POST https://your-domain.com/api/categorize \ -H "X-API-Token: your_token" \ -H "Content-Type: application/json" \ -d '{
    "query": "Что на изображении?",
    "generation_model": "gemini-2.0-flash-exp",
    "use_rag_count": true,
    "vision_model": "gemini-2.0-flash-exp",
    "images": ["data:image/jpeg;base64,/9j/4AAQ..."]
  }' # С файлами curl -X POST https://your-domain.com/api/categorize \ -H "X-API-Token: your_token" \ -F "query=Анализ изображения" \ -F "generation_model=gemini-2.0-flash-exp" \ -F "use_rag_count=true" \ -F "vision_model=gemini-2.0-flash-exp" \ -F "images=@/path/to/image.jpg"

2. Получение списка запросов

Получить список всех запросов категоризации.

Endpoint: GET /api/requests

Headers:

  • X-API-Token: string (обязательно)

Query Parameters:

Параметр Тип Обязательный По умолчанию Описание
limit number нет 30 Количество запросов (1-100)
offset number нет 0 Смещение для пагинации
search string нет - Поиск по тексту

Response:

{ "status": "success", "data": [ { "id": 123, "text": "Текст запроса", "final_answer": "Категория А", "moderated": true, "moderated_answer": "Категория А", "kb_inserted": true, "kb_id": -1, "start_time": "2024-01-01T12:00:00.000Z", "end_time": "2024-01-01T12:00:01.500Z" } ], "total_count": 500, "limit": 30, "offset": 0 }

Пример запроса:

curl -X GET "https://your-domain.com/api/requests?limit=50&offset=0&search=интернет" \ -H "X-API-Token: your_token"

3. Модерация запроса

Модерировать запрос (одобрить или отклонить).

Endpoint: PUT /api/requests/{id}/moderate

Headers:

  • X-API-Token: string (обязательно)
  • Content-Type: application/json

Body:

{ "moderated": true, "moderated_answer": "Категория А" }

Параметры:

Параметр Тип Обязательный Описание
moderated boolean да true - одобрить, false - отклонить
moderated_answer string условно* Модерированный ответ

* Обязательно если moderated=true

Response:

{ "status": "success", "message": "Запрос 123 прошёл модерацию" }

Важно: Нельзя модерировать запрос, который уже находится в базе знаний. Сначала нужно удалить его из БЗ.

Пример запроса:

# Одобрить запрос curl -X PUT https://your-domain.com/api/requests/123/moderate \ -H "X-API-Token: your_token" \ -H "Content-Type: application/json" \ -d '{
    "moderated": true,
    "moderated_answer": "Категория А"
  }' # Отклонить запрос curl -X PUT https://your-domain.com/api/requests/123/moderate \ -H "X-API-Token: your_token" \ -H "Content-Type: application/json" \ -d '{
    "moderated": false,
    "moderated_answer": null
  }'

4. Добавление запроса в базу знаний

Добавить модерированный запрос в базу знаний для использования в RAG.

Endpoint: POST /api/requests/{id}/kb

Headers:

  • X-API-Token: string (обязательно)

Требования:

  • Запрос должен быть одобрен модератором (moderated=true)
  • Запрос должен иметь moderated_answer

Response:

{ "status": "success", "message": "Запрос успешно добавлен в базу знаний (3 чанков)", "kb_id": -1 }

Пример запроса:

curl -X POST https://your-domain.com/api/requests/123/kb \ -H "X-API-Token: your_token"

5. Удаление запроса из базы знаний

Удалить запрос из базы знаний.

Endpoint: DELETE /api/requests/{id}/kb

Headers:

  • X-API-Token: string (обязательно)

Response:

{ "status": "success", "message": "Запрос успешно удален из базы знаний (3 чанков)", "kb_id": null }

Пример запроса:

curl -X DELETE https://your-domain.com/api/requests/123/kb \ -H "X-API-Token: your_token"

Коды ошибок

Код Описание
400 Неверные параметры запроса
401 Отсутствует или неверный API токен
404 Запрос не найден
500 Внутренняя ошибка сервера