# ML Core Generation API

Сервис для генерации спецификаций с использованием контекстного поиска и языковых моделей.

## Содержание
- [Обзор](#обзор)
- [Функционал](#функционал)
- [Архитектура](#архитектура)
- [Установка](#установка)
- [Использование](#использование)
- [API Endpoints](#api-endpoints)
- [Конфигурация](#конфигурация)

## Обзор

ML Core Generation API — это сервис на базе FastAPI, который генерирует бизнес-аналитические документы с использованием современных методов обработки естественного языка и контекстного поиска.

Сервис объединяет несколько ML-компонентов, включая векторный поиск релевантной информации из базы знаний, переранжирование результатов для повышения точности и генерацию текста с использованием языковых моделей. Это позволяет создавать высококачественные документы на основе предоставленного контекста и бизнес-требований.

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

## Функционал

- **Контекстный поиск**: извлечение релевантной информации из векторной базы данных с помощью эмбеддингов
- **Переранжирование результатов**: улучшение релевантности контекста с помощью кросс-энкодера
- **Генерация текста**: создание документов на основе контекста с использованием LLM
- **Поиск информации о таблицах**: извлечение структурной информации о таблицах из базы данных
- **Few-shot обучение**: использование примеров для улучшения качества генерации
- **Суммаризация предыдущих генераций**: учет результатов предыдущих итераций
- **Интеграция с LightRAG**: получение дополнительного контекста из графовой базы знаний
- **Логирование в PostgreSQL**: отслеживание генераций, метрик и контекстов
- **Мониторинг через Prometheus**: сбор метрик производительности и статуса компонентов

## Архитектура

Проект имеет следующую структуру:
```
├── README.MD
├── app.py                # Основной файл приложения с FastAPI
├── config/              
│   └── default_config.yaml  # Конфигурация приложения
├── data/                 # Модули для работы с данными
│   ├── loaders.py        # Загрузка данных из файлов
│   └── processors.py     # Обработка и подготовка данных
├── deploy/               # Файлы для развертывания
│   ├── Dockerfile
│   ├── Makefile
│   └── requirements.txt
├── docker-compose.yml    # Конфигурация для Docker Compose
├── models/               # Работа с ML-моделями
│   ├── embeddings.py     # Сервис для работы с эмбеддингами
│   ├── llm.py            # Взаимодействие с языковыми моделями
│   └── reranker.py       # Переранжирование результатов
├── pipeline/             # Компоненты пайплайна обработки
│   ├── context.py        # Получение контекста
│   └── generation.py     # Генерация текста
├── storage/              # Взаимодействие с хранилищами
│   └── milvus_client.py  # Клиент для работы с Milvus
└── utils/                # Вспомогательные утилиты
    ├── db_logger.py      # Логирование в PostgreSQL
    ├── logging.py        # Настройка логирования
    └── metrics.py        # Утилиты для расчета метрик
```

## Установка

### Ручная установка

#### Сборка образа

```bash
make build
```

#### Запуск контейнера

```bash
make run
```

После выполнения сервис будет доступен по адресу http://localhost:8001.

## Использование

После запуска сервиса доступна автоматическая документация по адресу:
- **Swagger UI**: http://localhost:8888/docs

### Пример запроса на генерацию

```bash
curl -X POST "http://localhost:8001/generate" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "Функциональные требования",
    "project": "krp",
    "page_name": "Доработка \"Назначение заместителей\"",
    "jira_text": "Необходимо добавить возможность назначения заместителей руководителям подразделений",
    "previous_generations": [],
    "attached_link": "https://confluence.example.com/pages/pageId=12345"
  }'
```

### Пример ответа

```json
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": "# Функциональные требования\n\n## 1. Назначение заместителей\n\n1.1. Система должна предоставлять возможность назначения заместителей для руководителей подразделений...",
  "metrics": {
    "ragas":   {
        "response_relevancy": 0.85,
        "context_utilization": 0.76,
        "answer_accuracy": 0.92,
        "non_llm_string_similarity": 0.63
    },
  },
  "timing": {
    "embedding": 0.45,
    "reranking": 0.32,
    "generation": 2.15,
    "table_search": 0.18,
    "graph_search": 0.28
  },
  "used_summary": false,
  "context_documents": [
    {
      "page_link": "https://confluence.example.com/pages/pageId=54321",
      "page_title": "Структура подразделений"
    },
    {
      "page_link": "https://confluence.example.com/pages/pageId=67890",
      "page_title": "Права доступа пользователей"
    }
  ]
}
```


## API Endpoints

### Генерация документа

**URL**: `/generate`  
**Метод**: POST  
**Описание**: Генерирует документ на основе запроса, проектных данных и контекста.

**Запрос**:
- `document_type` (обязательный) - Тип документа для генерации
- `project` (обязательный) - Имя проекта
- `page_name` (обязательный) - Название страницы
- `jira_text` (обязательный) - Текст бизнес-постановки из Jira
- `previous_generations` (опциональный) - Список предыдущих генераций
- `reference_answer` (опциональный) - Эталонный ответ для расчета метрик
- `attached_link` (опциональный) - Ссылка на прикрепленную страницу

**Ответ**:
- `request_id` - Уникальный идентификатор запроса
- `result` - Сгенерированный текст документа
- `metrics` - Метрики качества генерации
- `timing` - Информация о времени выполнения различных этапов
- `used_summary` - Флаг использования суммаризации предыдущих генераций
- `context_documents` - Список использованных документов контекста

## Конфигурация

Сервис настраивается через YAML-файл конфигурации (config/default_config.yaml) и переменные окружения:

### Основные параметры конфигурации:

- `gen_params` - Параметры генерации (использовать ли few-shot, context, summary, table, graph)
- `models_names` - Имена используемых моделей (embedder, reranker, LLM)
- `models_params` - Параметры для моделей (embedder_out_chunks, reranker_out_chunks, attached_out_chunks, num_table_out, graph_out_chunks)
- `project_params` - Параметры, специфичные для проекта (example_project, example_page)
- `system_message` - Системное сообщение для языковой модели

### Переменные окружения:

#### Основные url сервисов
- `URL_LLM` - URL API для языковой модели
- `LLM_API_KEY` - API ключ для доступа к языковой модели
- `URL_EMBEDDER` - URL API для эмбеддинг-модели
- `URL_RERANKER` - URL API для модели переранжирования
- `URL_LIGHTRAG` - URL API для LightRAG
- `URL_EVAL` - URL API для оценки качества генерации

#### Векторная база данных milvus
- `MILVUS_HOST` - Хост для Milvus
- `MILVUS_PORT` - Порт для Milvus
- `DATABASE_NAME` - Имя базы данных Milvus

#### База данных PostgreSQL для логов
- `POSTGRES_DB` - Имя базы данных PostgreSQL
- `POSTGRES_USER` - Пользователь PostgreSQL
- `POSTGRES_PASSWORD` - Пароль PostgreSQL
- `POSTGRES_HOST` - Хост PostgreSQL
- `POSTGRES_PORT` - Порт PostgreSQL

---

Если у вас возникнут вопросы или потребуется помощь, не стесняйтесь обращаться!