Spaces:
Running
Running
| # Jira AI Assistant - Керівництво користувача | |
| ## Загальна інформація | |
| Jira AI Assistant — це потужний інструмент для аналізу, візуалізації та інтелектуальної обробки даних Jira за допомогою штучного інтелекту. Додаток дозволяє імпортувати дані з CSV-експорту Jira, аналізувати їх, створювати різноманітні візуалізації та використовувати можливості AI для глибокого розуміння стану проєкту. | |
| ### Основні можливості | |
| - Аналіз CSV-експорту з Jira з виявленням ключових метрик | |
| - Генерація візуалізацій різних типів для кращого розуміння даних | |
| - AI-аналіз даних з використанням моделей OpenAI та Google Gemini | |
| - Гібридний чат з відповідями на питання про проєкт | |
| - Автоматична генерація структурованих звітів на основі даних | |
| - Збереження результатів аналізу та візуалізацій | |
| ## Інтерфейс користувача | |
| Інтерфейс додатку складається з кількох вкладок, кожна з яких відповідає за певну функціональність: | |
| 1. **CSV Аналіз** - завантаження, ініціалізація та аналіз даних з CSV-файлів | |
| 2. **Візуалізації** - створення та налаштування візуальних представлень даних | |
| 3. **AI Асистенти** - робота з AI моделями для аналізу та генерації контенту | |
| 4. **Jira API** - прямий зв'язок з Jira API (у розробці) | |
| 5. **Інтеграції** - інтеграція з іншими сервісами (у розробці) | |
| ## CSV Аналіз | |
| Ця вкладка призначена для роботи з даними Jira у форматі CSV. | |
| ### Завантаження CSV-файлу | |
| 1. Перейдіть на вкладку "CSV Аналіз" | |
| 2. У блоці "Завантаження CSV" натисніть кнопку для вибору файлу або перетягніть файл у відповідну область | |
| 3. Встановіть значення "Кількість днів для визначення неактивних тікетів" (за замовчуванням 14 днів) | |
| ### Робота з локальними файлами | |
| Програма може працювати з CSV-файлами, що зберігаються в директорії `current_data`: | |
| 1. Натисніть кнопку "Оновити список файлів" для відображення доступних локальних файлів | |
| 2. У випадаючому списку "Виберіть файли з директорії current_data" виберіть один або кілька файлів | |
| 3. Для перегляду вмісту конкретного файлу: | |
| - Виберіть файл у списку "Виберіть файл для перегляду" | |
| - Натисніть кнопку "Переглянути" | |
| ### Ініціалізація та аналіз даних | |
| Для аналізу даних натисніть кнопку "Ініціалізація та Аналіз". Процес виконає наступні кроки: | |
| 1. Завантаження та об'єднання вибраних файлів (якщо вибрано кілька) | |
| 2. Обробка даних для аналізу | |
| 3. Генерація статистики та виявлення неактивних тікетів | |
| 4. Відображення звіту з результатами | |
| Звіт містить: | |
| - Загальну статистику проєкту (кількість тікетів, розподіл за статусами, типами, пріоритетами) | |
| - Аналіз неактивних тікетів (тікети без змін протягом вказаного періоду) | |
| - Рекомендації | |
| ### Очищення тимчасових даних | |
| У розділі "Обслуговування" можна виконати очищення тимчасових даних: | |
| 1. Розгорніть секцію "Обслуговування" | |
| 2. Натисніть кнопку "Очистити тимчасові дані" | |
| Ця функція видаляє всі тимчасові файли, включаючи індекси, сесії та звіти, але не видаляє файли в директорії `current_data`. | |
| ## Візуалізації | |
| Вкладка "Візуалізації" дозволяє створювати різні графічні представлення даних. | |
| ### Створення візуалізацій | |
| 1. Виберіть тип візуалізації зі списку: | |
| - **Статуси** - розподіл тікетів за статусами | |
| - **Пріоритети** - розподіл тікетів за пріоритетами | |
| - **Типи тікетів** - розподіл за типами (Bugs, Tasks, Stories тощо) | |
| - **Призначені користувачі** - розподіл тікетів за виконавцями | |
| - **Активність створення** - кількість нових тікетів за період | |
| - **Активність оновлення** - кількість оновлених тікетів за період | |
| - **Кумулятивне створення** - наростаюча кількість тікетів з часом | |
| - **Неактивні тікети** - аналіз тікетів без руху | |
| - **Теплова карта: Типи/Статуси** - взаємозв'язок між типами та статусами | |
| - **Часова шкала проекту** - загальна шкала активності | |
| - **Склад статусів з часом** - зміна складу статусів з часом | |
| 2. Налаштуйте параметри візуалізації (в акордеоні "Параметри візуалізації"): | |
| - **Ліміт для топ-візуалізацій** - кількість елементів для відображення (для топ-списків) | |
| - **Групування для часових діаграм** - рівень деталізації (день, тиждень, місяць) | |
| 3. Натисніть кнопку "Генерувати" для створення візуалізації | |
| ### Збереження візуалізацій | |
| Щоб зберегти створену візуалізацію: | |
| 1. Введіть ім'я файлу (або залиште порожнім для автоматичного імені) | |
| 2. Натисніть кнопку "Зберегти візуалізацію" | |
| 3. Візуалізація буде збережена в директорії `reports/visualizations` | |
| ## AI Асистенти | |
| Вкладка "AI Асистенти" надає доступ до функцій аналізу даних за допомогою штучного інтелекту. | |
| ### Налаштування параметрів | |
| Для всіх режимів AI можна налаштувати: | |
| - **Модель LLM** - вибір між моделями: | |
| - `gemini` - використовує Google Gemini моделі | |
| - `openai` - використовує OpenAI моделі (GPT) | |
| - **Температура** - параметр для контролю креативності відповідей (вищі значення = більше креативності, нижчі = більше детермінованості) | |
| ### Ініціалізація індексів | |
| Перед використанням режиму Гібридного чату необхідно створити індекси для ефективного пошуку: | |
| 1. Переконайтеся, що дані вже завантажені через вкладку "CSV Аналіз" | |
| 2. Натисніть кнопку "Ініціалізувати індекси" | |
| 3. Дочекайтеся повідомлення про успішне створення індексів | |
| Цей крок створює: | |
| - Векторні індекси FAISS для семантичного (смислового) пошуку | |
| - BM25 індекси для пошуку за ключовими словами | |
| ### Режими роботи з AI | |
| #### Q/A з повним контекстом | |
| Режим для загальних питань про проєкт, який надає доступ до всіх даних одночасно: | |
| 1. Введіть питання у відповідне поле | |
| 2. Натисніть "Отримати відповідь" | |
| 3. Система аналізує всі дані та надає комплексну відповідь | |
| Приклади питань: | |
| - "Які тікети мають найвищий пріоритет?" | |
| - "Скільки помилок було виправлено за останній місяць?" | |
| - "Хто найактивніший розробник у проєкті?" | |
| #### Гібридний чат | |
| Режим діалогу з системою, який використовує комбінацію BM25 і векторного пошуку: | |
| 1. Введіть питання у поле для повідомлення | |
| 2. Натисніть Enter або Shift+Enter для відправки | |
| 3. Система відповідає на основі аналізу даних | |
| 4. Можна вести діалог з послідовними питаннями | |
| Переваги: | |
| - Підтримує контекст розмови (враховує попередні питання та відповіді) | |
| - Показує релевантні документи/тікети для кожної відповіді | |
| - Оптимальний для детальних специфічних запитань | |
| #### Генерація звіту | |
| Режим для автоматичного створення структурованого аналітичного звіту: | |
| 1. Виберіть формат звіту (markdown або html) | |
| 2. Натисніть "Згенерувати звіт" | |
| 3. Система аналізує всі дані та створює детальний звіт | |
| Звіт зазвичай містить: | |
| - Короткий огляд проєкту | |
| - Аналіз поточного стану | |
| - Виявлені проблеми та ризики | |
| - Рекомендації для покращення процесу | |
| - Висновки та наступні кроки | |
| ## Експорт даних з Jira у CSV-формат | |
| Для коректної роботи з Jira AI Assistant необхідно правильно експортувати дані з Jira у форматі CSV. Нижче наведено детальні інструкції з експорту. | |
| ### Пошук та налаштування даних для експорту | |
| 1. **Відкрийте Jira** та авторизуйтеся у системі | |
| 2. **Перейдіть до функції пошуку**: натисніть "Issues" у верхньому меню, потім виберіть "Search for issues" | |
| 3. **Налаштуйте фільтри пошуку** для відбору потрібних тікетів: | |
| - Виберіть проєкт (наприклад, "IEE DS") з випадаючого списку | |
| - Вкажіть тип завдань ("Type") або залиште "All" | |
| - Вкажіть статус завдань ("Status") або залиште "All" | |
| - За потреби вкажіть виконавця ("Assignee") | |
| - Використовуйте поле пошуку для конкретного тексту | |
| - Для більш складних запитів натисніть "Advanced" і використовуйте JQL-запити | |
| 4. **Натисніть кнопку "Search"** для отримання результатів | |
| ### Експорт результатів пошуку у CSV | |
| 1. **У результатах пошуку натисніть кнопку "Export"** (знаходиться у правому верхньому куті) | |
| 2. **Виберіть "CSV (Current fields)"** або "CSV (All fields)" залежно від того, які дані вам потрібні: | |
| - "Current fields" - експортує тільки поля, що відображаються у поточному представленні | |
| - "All fields" - експортує всі доступні поля (рекомендовано для повного аналізу) | |
| 3. **Налаштуйте опції експорту**: | |
| - Переконайтеся, що включені всі важливі поля: Issue key, Summary, Status, Issue Type, Priority, Created, Updated, Description, Assignee, Reporter | |
| - Якщо використовуєте власні поля (custom fields), переконайтеся, що вони також включені | |
| 4. **Підтвердіть експорт** і збережіть CSV-файл на вашому комп'ютері | |
| ### Рекомендації щодо експорту | |
| - **Експортуйте всі можливі поля**, особливо якщо плануєте використовувати AI аналіз. Більше даних дозволяє отримати більш глибокі та точні інсайти. | |
| - **Включіть поле Description** для аналізу текстового вмісту тікетів. | |
| - **Включіть поля з коментарями**, якщо вони доступні у вашій конфігурації Jira. | |
| - **Експортуйте вкладення або посилання**, якщо вони важливі для аналізу. | |
| - **Для великих проєктів** розгляньте можливість створення кількох експортів з різними наборами фільтрів для більш цілеспрямованого аналізу. | |
| ## Поради з використання | |
| ### Оптимальні практики | |
| 1. **Підготовка даних**: | |
| - Експортуйте з Jira максимально повний набір даних з усіма важливими полями | |
| - Упевніться, що CSV-файл містить колонки: Issue key, Summary, Status, Issue Type, Priority, Created, Updated | |
| 2. **Правильна послідовність дій**: | |
| - Спочатку завантажте і проаналізуйте дані (вкладка "CSV Аналіз") | |
| - Створіть необхідні візуалізації (вкладка "Візуалізації") | |
| - Ініціалізуйте індекси перед використанням AI асистентів | |
| - Використовуйте функції AI для глибшого аналізу | |
| 3. **Вибір режиму AI**: | |
| - "Q/A з повним контекстом" - для загальних питань про проєкт | |
| - "Гібридний чат" - для детальних питань з контекстом розмови | |
| - "Генерація звіту" - для створення структурованих звітів | |
| ### Вирішення поширених проблем | |
| 1. **Не вдається завантажити CSV**: | |
| - Перевірте формат CSV-файлу та наявність необхідних колонок | |
| - Переконайтеся, що файл не порожній і не пошкоджений | |
| - Спробуйте скопіювати файл у директорію `current_data` і використати через локальні файли | |
| 2. **Помилки при створенні індексів**: | |
| - Переконайтеся, що встановлені всі необхідні бібліотеки для AI | |
| - Очистіть тимчасові дані та спробуйте знову | |
| - Перевірте наявність достатньої кількості вільного місця на диску | |
| 3. **AI асистент не відповідає**: | |
| - Перевірте наявність та валідність API ключів (OpenAI або Gemini) | |
| - Для гібридного чату переконайтеся, що індекси успішно ініціалізовані | |
| ## Додаткова інформація | |
| Для додаткових запитань і технічної підтримки звертайтеся до розробника (szabolotnii@healthprecision.com). | |
| --- | |
| ### Глосарій | |
| - **CSV-файл** - формат файлу для зберігання табличних даних, який можна експортувати з Jira | |
| - **Неактивні тікети** - тікети, які не оновлювалися протягом визначеного періоду | |
| - **FAISS** - бібліотека для ефективного пошуку схожих векторів, використовується для семантичного пошуку | |
| - **BM25** - алгоритм ранжування для пошуку за ключовими словами | |
| - **Гібридний пошук** - комбінація BM25 та векторного пошуку для покращення релевантності результатів |