Freelancer Data Analysis System

Система, которая анализирует статистические данные о доходах фрилансеров (Freelancer Earnings & Job Trends) и предоставляет ответы на запросы, сформулированные на естественном языке

Установка и запуск

1. Склонируйте репозиторий

git clone https://github.com/alexysxeightn/freelancer_da_system.git
cd freelancer_da_system

2. Установите зависимости

pip install -r requirements.txt

3. Создайте .env-файл, в который положите ключ API OpenAI

OPENAI_API_KEY=your_openai_api_key

4. Запустите консольное приложение

python main.py

5. Запуск тестов

python -m unittest tests.test_core -v

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

freelancer_da_system/
├── __init__.py
├── freelancer_earnings_bd.csv   # Данные для базы данных
├── .env                         # Ключ OpenAI API
├── requirements.txt             # Зависимости
├── README.md                    # Документация
├── main.py                      # Приложение
├── config.py                    # Конфигурация (пути до файлов, ключи, название модели)
├── schema.py                    # Схема базы данных (добавляется в промпт)
├── database.py                  # Работа с базой данных
├── llm_utils.py                 # Работа с LLM
├── logger.py                    # Логика логирования
├── cli.py                       # Логика консольного приложения
└── tests/                       # Тесты
    ├── __init__.py
    └── test_core.py

Подход к решению задачи

Система принимает вопросы на естественном языке, преобразует их в безопасные SQL-запросы, выполняет эти запросы над набором данных и возвращает человекочитаемый ответ.

Основные этапы решения:

• Загрузка датасета: данные из CSV файла загружаются в память как SQLite БД для удобства выполнения SQL-запросов.
• Генерация SQL-запроса: на основе вопроса пользователя и описания структуры данных модель GPT генерирует SQL-запрос.
• Проверка безопасности SQL: проверяем, не содержит ли запрос опасных операций (DROP, DELETE и т.д.).
• Выполнение SQL: Запрос выполняется через pandas.read_sql_query.
• Формирование ответа: результат обрабатывается GPT, который формирует понятный ответ на русском языке.
• Логирование: Все этапы логируются в JSON-lines файл для отладки и аудита.

Формат логов:

{
    'query': 'Текст вопроса',
    'llm_sql_query': 'Текст SQL-запроса, полученный от LLM',
    'result_sql_query': 'Результат выполнения SQL-запроса',
    'answer': 'Текст ответа, который отправляется пользователю'
}

Эффективность и точность работы системы:

В силу "неточности" естественного языка могут быть ситуации, когда модель выдает разные ответы на один и тот же вопрос. Например, в вопросе "Насколько выше доход у фрилансеров, принимающих оплату в криптовалюте, по сравнению с другими способами оплаты?" не понятно в каком формате ожидается ответ, в процентах, или в абсолютных величинах. Можно улучшить систему, чтобы для таких случаев она задавала уточняющие вопросы.

В плане эффективности в среднем система обрабатывает один запрос 2-3 секунды. Это значение может варьироваться в зависимости от скорости интернета и доступности OpenAI API.

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

Вопрос	Ответ модели	Корректность (проверена вручную через sql)
Насколько выше доход у фрилансеров, принимающих оплату в криптовалюте, по сравнению с другими способами оплаты?	Доход фрилансеров, принимающих оплату в криптовалюте, на 165,31 долларов США выше, чем у остальных.	✅
Как распределяется доход фрилансеров в зависимости от региона проживания?	Средний доход фрилансеров распределяется по регионам следующим образом: в Канаде он составляет 5350 долларов США, в Азии — 5172 доллара, в Великобритании — 5047 долларов, в Австралии — 4966 долларов, в Европе — 4891 доллар, в США — 4873 доллара и на Ближнем Востоке — 4871 доллар.	✅
Какой процент фрилансеров, считающих себя экспертами, выполнил менее 100 проектов?	33,85% фрилансеров, считающих себя экспертами, выполнили менее 100 проектов.	✅
Какой процент фрилансеров использует криптовалюту как основной способ оплаты?	26,36% фрилансеров используют криптовалюту как основной способ оплаты.	✅
Какой фрилансер в категории "Graphic Design" имеет самый высокий доход, и насколько он выше среднего по этой категории?	Фрилансер с ID 593 в категории "Graphic Design" имеет самый высокий доход — 9974 долларов США, что на 4837,13 долларов США выше среднего дохода по этой категории.	✅
Какие платформы имеют хотя бы одного фрилансера с доходом выше $10000?	Платформы с фрилансерами, имеющими доход выше 10 000 долларов США, отсутствуют.	✅
Каково соотношение начинающих и опытных фрилансеров на платформе Upwork, у которых менее 50 выполненных проектов?	Соотношение начинающих и опытных фрилансеров на платформе Upwork с менее чем 50 выполненными проектами составляет 20 к 22.	✅
Раздели фрилансеров на три группы по количеству выполненных проектов: до 50, от 50 до 200, больше 200. Сколько в каждой группе?	Фрилансеров, выполнивших до 50 проектов, 309 человек; от 50 до 200 проектов — 989 человек; больше 200 проектов — 652 человека.	✅
Какая категория имеет наибольшее суммарное число выполненных проектов, и какая — минимальное	Категория "Веб-разработка" имеет наибольшее суммарное число выполненных проектов — 39 262, а категория "Копирайтинг" — минимальное, всего 33 748 проектов.	✅
Найди всех фрилансеров из Европы или США, у которых уровень успеха выше 90%, и они зарабатывают больше максимального среднего дохода среди всех категорий.	Ниже приведён список фрилансеров из Европы или США с уровнем успеха выше 90%, которые зарабатывают больше максимального среднего дохода среди всех категорий. Их идентификаторы: 13, 68, 122, 141, 151, 183, 187, 253, 271, 379, 384, 513, 519, 531, 555, 578, 619, 708, 726, 749, 814, 938, 1005, 1049, 1051, 1102, 1111, 1172, 1231, 1272, 1278, 1310, 1323, 1335, 1396, 1407, 1441, 1445, 1456, 1469, 1477, 1481, 1513, 1545, 1560, 1574, 1665, 1666, 1674, 1684, 1728, 1756, 1839, 1845, 1859, 1865, 1871, 1882, 1907.	✅

Ни на одном из вопросов система не ошиблась (единственное замечание, отношение 20 к 22 выглядит странно, LLM не догадалась сократить на 2)

Методы и технологии

Используется:

• LangChain + ChatOpenAI - для генерации SQL и текстовых ответов
• SQLite - для быстрой обработка запросов
• Pandas - удобная работа с данными
• Rich CLI - более удобное и красивое консольное приложение
• Unit-тесты - для обнаружения ошибок при изменениях в проекте
• dotenv - для безопасного хранения API-ключа
• JSON-логирование - для диагностика ошибок (в том числе логических)

Изначально хотел использовать PythonREPLTool, но такой вариант тратит больше токенов и является более сложным для решения такой задачи, реализованный метод проще

Критерии оценки качества системы

Точность ответа - корректность итогового численного значения или текстового вывода

Читаемость ответа - ясность и грамматическая правильность ответа на русском языке

Безопасность SQL - отсутствие возможности выполнить вредоносный запрос

Производительность - быстрое выполнение запроса и получение результата

Логируемость - наличие записи всех этапов в лог

Поддерживаемость кода - простота расширения и изменения функциональности

Юзабилити - понятный интерфейс и подсказки

Что можно улучшить

Иногда GPT может генерировать некорректные SQL, можно добавить fallback на повторную попытку.

Система может долго отвечать, можно кэшировать часто задаваемые вопросы.

Также могут быть внутренние ошибки OpenAI, поэтому можно добавить автоматические retry с экспоненциальной задержкой.