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 та векторного пошуку для покращення релевантності результатів |