🤖 Knoovo - AI Q&A Categorization with YandexGPT

Автоматическая категоризация вопросов и ответов с использованием YandexGPT API. Полноценное Node.js приложение для обработки больших объемов Q&A данных с генерацией интерактивных отчетов.

✨ Возможности

• 📖 Загрузка из нескольких файлов - поддержка форматов с разделителями | и [TAB]
• 🤖 AI категоризация - автоматическое определение категорий вопросов с помощью YandexGPT
• 🏷️ Генерация тегов - создание 3-5 релевантных тегов для каждого вопроса
• ⚡ Батчевая обработка - оптимизация API запросов для обработки больших объемов
• 💾 Множество форматов вывода - JSON, CSV (с корректной кириллицей), интерактивный HTML
• 📊 Подробная статистика - распределение по категориям, прогресс-бары, логирование
• 🎨 Современный UI - красивая HTML страница с поиском, фильтрами и адаптивным дизайном

🚀 Быстрый старт

Требования

• Node.js 12.0 или выше
• API ключ Yandex Cloud
• Folder ID из Yandex Cloud

Установка

# Клонируйте репозиторий
git clone <repository-url>
cd knoovo

# Никаких дополнительных зависимостей не требуется!
# Используются только встроенные модули Node.js

Настройка

1. Получите API ключ Yandex Cloud:

   • Зайдите в Yandex Cloud Console
   • Создайте или выберите существующий сервисный аккаунт
   • Перейдите в раздел "API ключи"
   • Нажмите "Создать API-ключ"
   • Скопируйте полученный ключ

2. Получите Folder ID:

   • В консоли Yandex Cloud откройте нужный каталог
   • Folder ID отображается в URL или в информации о каталоге
   • Формат: b1g************ (обычно начинается с b1g)

3. Настройте приложение:

   • Откройте файл index.js
   • Найдите секцию CONFIG в начале файла
   • Замените YOUR_API_KEY_HERE на ваш API ключ
   • Замените YOUR_FOLDER_ID_HERE на ваш Folder ID
   • При необходимости настройте пути к входным файлам

4. Подготовьте файлы с вопросами:

   • Создайте текстовые файлы в одном из поддерживаемых форматов:
     • Вопрос|Ответ (разделитель - вертикальная черта)
     • Вопрос[TAB]Ответ (разделитель - табуляция)
   • Укажите пути к файлам в CONFIG.INPUT_FILES

Запуск

node index.js

📁 Формат входных файлов

Формат с вертикальной чертой (|)

Какая самая высокая гора в мире?|Эверест, её высота составляет 8848 метров над уровнем моря
Столица Франции?|Париж является столицей Франции

Формат с табуляцией

Кто изобрел первый компьютер?	Чарльз Бэббидж считается изобретателем первого механического компьютера
Какой химический элемент имеет символ Au?	Золото имеет химический символ Au

📊 Выходные файлы

1. JSON (results.json)

Структурированные данные с метаинформацией:

{
  "metadata": {
    "totalQuestions": 15,
    "processedAt": "2024-01-15T10:30:00.000Z",
    "categories": 8,
    "processingTimeSeconds": 45
  },
  "categoriesStats": {
    "География": 3,
    "История": 2,
    "Наука": 5
  },
  "questions": [
    {
      "question": "Какая самая высокая гора в мире?",
      "answer": "Эверест, её высота составляет 8848 метров",
      "category": "География",
      "tags": ["горы", "Эверест", "рекорды", "география"]
    }
  ]
}

2. CSV (results.csv)

Таблица для Excel с корректной кириллицей (BOM):

Вопрос,Ответ,Категория,Теги
"Какая самая высокая гора в мире?","Эверест...","География","горы, Эверест, рекорды"

3. HTML (results.html)

Интерактивная веб-страница с:

• 🎨 Современным дизайном с градиентами
• 🔍 Поиском по вопросам, ответам и тегам
• 🏷️ Фильтрацией по категориям
• 📊 Статистическими карточками
• 📱 Адаптивной версткой для мобильных устройств
• ⚡ Анимациями и плавными переходами

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

Все настройки находятся в объекте CONFIG в начале файла index.js:

const CONFIG = {
  // API ключ Yandex Cloud
  YANDEX_API_KEY: 'YOUR_API_KEY_HERE',
  
  // Folder ID из Yandex Cloud
  YANDEX_FOLDER_ID: 'YOUR_FOLDER_ID_HERE',
  
  // Входные файлы
  INPUT_FILES: [
    './questions1.txt',
    './questions2.txt',
    './questions3.txt'
  ],
  
  // Выходные файлы
  OUTPUT_JSON: './results.json',
  OUTPUT_CSV: './results.csv',
  OUTPUT_HTML: './results.html',
  
  // Размер батча (вопросов в одном запросе)
  BATCH_SIZE: 5,
  
  // Задержка между запросами (миллисекунды)
  DELAY_BETWEEN_REQUESTS: 2000,
  
  // Максимальное количество токенов в ответе
  MAX_TOKENS: 1000,
  
  // Предопределенные категории
  CATEGORIES: [
    'География',
    'История',
    'Наука',
    // ...
  ]
};

🔧 Технические детали

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

• Язык: Pure Node.js (без npm пакетов)
• Модули: Только встроенные (fs, readline, https)
• API: YandexGPT API v1
• Авторизация: API-ключ или IAM-токен

Архитектура

┌─────────────────┐
│  Входные файлы  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Загрузка Q&A   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Батчевая обраб. │◄─────── YandexGPT API
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Категоризация + │
│  Генерация тегов│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Сохранение рез. │
│ JSON/CSV/HTML   │
└─────────────────┘

Обработка ошибок

• ✅ Проверка наличия файлов
• ✅ Валидация API ключа и Folder ID
• ✅ Обработка сетевых ошибок
• ✅ Парсинг некорректных ответов AI
• ✅ Автоматическое присвоение категории при ошибках
• ✅ Подробное логирование с эмодзи

Оптимизация

• Батчевая обработка: Группировка нескольких вопросов в один запрос
• Rate limiting: Задержки между запросами для избежания блокировок
• Потоковое чтение: Эффективная работа с большими файлами
• Прогресс-бары: Визуализация прогресса в реальном времени

📖 Примеры использования

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

# После настройки CONFIG просто запустите:
node index.js

Обработка больших объемов

Для 100,000+ вопросов рекомендуется:

const CONFIG = {
  BATCH_SIZE: 10,              // Увеличить размер батча
  DELAY_BETWEEN_REQUESTS: 1000, // Уменьшить задержку (осторожно!)
  MAX_TOKENS: 2000            // Увеличить лимит токенов
};

Использование IAM-токена

const CONFIG = {
  YANDEX_API_KEY: 't1.9euelZqXjp6czYyRy5KLl8uTipKSnu3rnpWa...',
  // IAM-токены начинаются с "t1."
};

🎨 Кастомизация

Добавление категорий

const CONFIG = {
  CATEGORIES: [
    'Ваша категория 1',
    'Ваша категория 2',
    // ...
  ]
};

Изменение промпта для AI

Найдите функцию categorizeWithYandexGPT() и измените переменную prompt.

Кастомизация HTML

Найдите функцию saveHTML() и измените встроенный HTML/CSS.

🐛 Устранение неполадок

Ошибка: "Необходимо настроить YANDEX_API_KEY"

Решение: Откройте index.js и замените YOUR_API_KEY_HERE на ваш реальный API ключ.

Ошибка: "Файл не найден"

Решение: Проверьте пути к файлам в CONFIG.INPUT_FILES. Используйте абсолютные пути или относительные от текущей директории.

Ошибка: "HTTP 401: Unauthorized"

Решение:

• Проверьте правильность API ключа
• Убедитесь, что ключ активен в Yandex Cloud Console
• Проверьте, что у сервисного аккаунта есть роль ai.languageModels.user

Ошибка: "HTTP 429: Too Many Requests"

Решение: Увеличьте DELAY_BETWEEN_REQUESTS в CONFIG (например, до 3000-5000 мс).

Проблемы с кириллицей в CSV

Решение: CSV файл использует BOM (Byte Order Mark) для корректного отображения кириллицы в Excel. Если проблемы остались, откройте CSV в LibreOffice Calc с кодировкой UTF-8.

📝 Логирование

Приложение использует эмодзи для удобного отслеживания процесса:

• ℹ️ Информационные сообщения
• ✅ Успешные операции
• ❌ Ошибки
• 🔄 Процессы в работе
• 🤖 AI операции
• 💾 Операции с файлами
• 📊 Прогресс-бары

🤝 Вклад в проект

Приветствуются pull requests и issues! Пожалуйста:

1. Fork репозитория
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Commit изменения (git commit -m 'Add amazing feature')
4. Push в branch (git push origin feature/amazing-feature)
5. Откройте Pull Request

📄 Лицензия

MIT License - см. файл LICENSE

🙏 Благодарности

• Yandex Cloud за предоставление YandexGPT API
• Сообщество Node.js за отличную документацию
• Всем контрибьюторам проекта

📧 Контакты

При возникновении вопросов создайте Issue в репозитории.

---

Сделано с ❤️ для автоматизации работы с Q&A данными