Enterprise Big Data Copilot

ИИ-копайлот, который превращает вопросы на естественном языке в проверенный Trino SQL с учётом схемы данных, используя RAG, MCP-инструменты и локальный инференс LLM.

Обзор

Enterprise Big Data Copilot позволяет пользователям запрашивать Big Data-платформы на простом английском языке. Конвейер на LangGraph извлекает релевантную документацию (RAG) и актуальные метаданные схемы (MCP), генерирует SQL с помощью локальной LLM (Ollama), проверяет его на соответствие правилам безопасности и схеме и — когда платформа доступна — выполняет его на Trino и возвращает реальные строки.

Related MCP server: Doris MCP Server

Возможности

• Генерация Text-to-SQL на естественном языке для Trino

• Локальный инференс LLM с Ollama (без облачного API)

• RAG-поиск по документации Trino / Hive / Iceberg (Qdrant)

• Генерация с учётом схемы на основе актуальных метаданных каталога

• Проверка SQL (только чтение SELECT, проверка парсинга, привязка к схеме) с автоматическим циклом повторной генерации

• Выполнение запросов и получение результатов из Trino (best-effort)

• MCP-сервер (Model Context Protocol), предоставляющий инструменты для работы с метаданными, запросами и профилированием

• API, совместимый с OpenAI, для Open WebUI

• Сквозная трассировка конвейера с LangSmith

Архитектура

flowchart LR
    User --> API
    API --> Agent
    Agent --> RAG
    RAG --> Qdrant
    Agent --> LLM
    Agent --> MCP
    MCP --> Trino
    Agent --> Validation
    Agent --> Response
    Response --> User

Технологический стек

Структура проекта

app/
├── agent/            # SQL agent + prompts (Ollama)
├── api/              # REST + OpenAI-compatible endpoints
├── core/             # Config, models, exceptions, logging
├── formatter/        # Response formatting
├── mcp/              # MCP server, client, catalog services
├── orchestrator/     # LangGraph pipeline
├── rag/              # Ingestion and retrieval (Qdrant)
├── services/         # Trino client
└── validator/        # SQL validation
tests/                # pytest suite
docker/               # App image + Trino config
docs/                 # RAG knowledge base
scripts/              # Document ingestion CLI

Начало работы

Предварительные требования

• Python 3.11 или 3.12 (3.13 не поддерживается)

• Docker + Docker Compose

• GPU опционально (Ollama может работать на CPU)

Установка

git clone https://github.com/hani-ben-dhaou/Enterprise-Big-Data-Copilot.git
cd entreprise-bigdata-copilot

python -m venv .venv
# Windows: .venv\Scripts\activate | macOS/Linux: source .venv/bin/activate

pip install -r requirements.txt
pip install -r requirements-dev.txt   # pytest

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

cp .env.example .env

Ключевые переменные (значения по умолчанию подходят для локальной разработки):

Запуск

# 1. Start infrastructure (Ollama, Qdrant, Trino)
docker compose up -d

# 2. Pull models and ingest documentation (Qdrant must be up)
docker exec -it copilot-ollama ollama pull llama3.2
docker exec -it copilot-ollama ollama pull mxbai-embed-large
python scripts/ingest_docs.py

# 3. Start the API
uvicorn app.main:app --reload --port 8000

# 4. Optional: standalone MCP server (SSE on :8001)
python -m app.mcp.server

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

Задайте вопрос на естественном языке:

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question":"Show me the top 10 customers by total revenue last month"}'

Ответ включает сгенерированный SQL, объяснение, оценку уверенности, предупреждения и — когда выполнение включено — строки результата:

{
  "question": "Show me the top 10 customers by total revenue last month",
  "sql": "SELECT ...",
  "explanation": "...",
  "confidence": 0.92,
  "warnings": [],
  "dialect": "trino",
  "results": [["42", "Acme", 98765.00]],
  "execution": {"status": "ok", "columns": ["id", "name", "revenue"], "row_count": 1, "truncated": false}
}

Другие конечные точки: GET /api/v1/schema (список каталога), GET /api/v1/health и POST /v1/chat/completions (совместимо с OpenAI, используется Open WebUI).

Тестирование

pytest

Набор тестов герметичен и работает без живого стека (146 тестов).

Трассировка и мониторинг

Каждый запрос конвейера (RAG-поиск, получение схемы, генерация SQL, циклы проверки, выполнение) можно отслеживать с помощью LangSmith. Создайте бесплатный аккаунт, получите API-ключ и задайте: LANGCHAIN_TRACING_V2=true, LANGCHAIN_API_KEY=<ваш ключ> и, при желании, LANGCHAIN_PROJECT=copilot. Трассировка остаётся выключенной, пока не настроен ключ.

Docker

docker compose запускает полный стек:

Именованные тома сохраняют модели Ollama, данные Qdrant и данные Open WebUI. Том ollama объявлен как external — создайте его один раз, если он отсутствует:

docker volume create ollama
docker compose up -d
docker compose ps
docker compose logs -f copilot-api
docker compose down

Примечание для Windows: MCP через реальный SSE может работать нестабильно в цикле событий Windows. Для локальной разработки на Windows оставьте MCP_TRANSPORT=inprocess; используйте SSE на Linux/Docker.