Spaces:
Running
Running
| # 📖 Довідка - AI Асистент для роботи з правовими позиціями | |
| ## Зміст | |
| 1. [Огляд додатку](#огляд-додатку) | |
| 2. [Закладка: Генерація](#закладка-генерація) | |
| 3. [Закладка: Пошук](#закладка-пошук) | |
| 4. [Закладка: Аналіз](#закладка-аналіз) | |
| 5. [Закладка: Налаштування](#закладка-налаштування) | |
| 6. [Закладка: Пакетне тестування](#закладка-пакетне-тестування) | |
| 7. [Підтримувані провайдери](#підтримувані-провайдери) | |
| 8. [Часті питання](#часті-питання) | |
| 9. [Поради та рекомендації](#поради-та-рекомендації) | |
| --- | |
| ## Огляд додатку | |
| **AI Асистент** - це інтелектуальний інструмент для роботи з правовими позиціями Верховного Суду України. Додаток використовує сучасні AI моделі (GPT, Claude, Gemini, DeepSeek) для автоматичної генерації, пошуку та аналізу правових позицій. | |
| ### Основні можливості: | |
| - ✅ **Генерація** правових позицій з текстів судових рішень | |
| - ✅ **Налаштування моделей** (вибір провайдера/моделі + режими «роздумів») і **поле коментаря** для уточнення генерації | |
| - ✅ **Налаштування промптів** для персоналізації роботи AI | |
| - ✅ **Пакетне тестування** для масової обробки даних | |
| - 🟡 **Пошук / Аналіз** (опціонально): може бути вимкнено у поставці, якщо це не входить у ТЗ | |
| ⚠️ **Примітка про дані для пошуку:** якщо пошук увімкнений, індекси можуть завантажуватися з відкритого датасету `DocSA/legal-position-indexes`. Це тестовий snapshot приблизно **1.5 роки давності** і він може бути неактуальним. | |
| Докладніше: `docs/SCOPE_AND_DATA_FRESHNESS.md` | |
| --- | |
| ## Закладка: Генерація | |
| ### Призначення | |
| Автоматичне формування проекту правової позиції з тексту судового рішення. | |
| ### Як користуватися: | |
| #### 1. Вибір провайдера та моделі | |
| - **Провайдер AI**: Оберіть постачальника AI (OpenAI, Anthropic, Gemini, DeepSeek) | |
| - **Модель генерації**: Виберіть конкретну модель (наприклад, GPT-4o, Claude 3.5 Sonnet, Gemini 3.0 Flash) | |
| **Рекомендації:** | |
| - Для швидкої роботи: Gemini 3 Flash, GPT-5 Mini, GPT-4o-mini | |
| - Для якісних результатів: GPT-5.4, Claude Sonnet 4.6, GPT-4o | |
| - Для економії: DeepSeek Chat | |
| #### 2. Додаткові параметри (Температура, Thinking Mode, Verbosity) | |
| - **Температура генерації**: дозволяє налаштовувати креативність моделі від 0.0 (строга) до 2.0 (креативна). | |
| - **Режим Thinking (для OpenAI GPT-5+, Gemini 3+ та Claude 4.5/4.6)**: | |
| - Увімкніть для глибшого аналізу складних рішень. | |
| - **Тип Thinking (Claude)**: | |
| - **Adaptive**: модель сама обирає глибину міркувань (працює для моделей 4.6). | |
| - **Enabled**: класичний режим із жорстким бюджетом токенів (для моделей 4.5 та 4.6). | |
| - **Рівні Thinking (OpenAI / Gemini)**: none → low → medium → high → xhigh (у GPT-5.2) | |
| - **Verbosity (OpenAI GPT-5)**: керування багатослівністю (low, medium, high) | |
| - **Бюджет токенів (Claude 4.5 або Enabled)**: 1024-32000 | |
| #### 3. Спосіб вводу даних | |
| **Варіант А: Текстовий ввід** | |
| - Вставте текст судового рішення безпосередньо | |
| - Найшвидший спосіб | |
| - Підходить для коротких текстів | |
| **Варіант Б: URL посилання** | |
| - Вставте посилання на рішення з reyestr.court.gov.ua | |
| - Автоматичне витягування тексту | |
| - Зручно для онлайн-рішень | |
| **Варіант В: Завантаження файлу** | |
| - Завантажте TXT файл з текстом рішення | |
| - Підходить для збережених локально рішень | |
| - Підтримка UTF-8 та CP1251 | |
| #### 4. Коментар (опціонально) | |
| Додайте уточнення для AI, наприклад: | |
| - "Звернути увагу на процесуальні питання" | |
| - "Виділити позиції щодо строків позовної давності" | |
| - "Акцентувати на нормах ЦПК України" | |
| #### 5. Генерація | |
| Натисніть **"📝 Генерувати проект правової позиції"** | |
| ### Результат генерації: | |
| Ви отримаєте структуровану правову позицію з: | |
| - **Заголовок** - коротка назва позиції | |
| - **Текст** - зміст правової позиції | |
| - **Тип судочинства** - кримінальне, цивільне, господарське, адміністративне | |
| - **Категорія** - тематична класифікація | |
| ### Час обробки: | |
| - Швидкі моделі: 5-15 секунд | |
| - Потужні моделі: 15-30 секунд | |
| - З режимом Thinking: 30-60 секунд | |
| ### Для customer MVP | |
| - Основний підтримуваний сценарій поставки: **Генерація** + налаштування `provider/model/thinking/comment`. | |
| - Якщо retrieval-контур не входить у ТЗ або не підготовлені актуальні індекси, вкладки **Пошук** і **Аналіз** можуть бути вимкнені без втрати основної цінності MVP. | |
| --- | |
| ## Закладка: Пошук | |
| ### Призначення | |
| Знайти схожі правові позиції Верховного Суду у базі даних. | |
| ⚠️ **Статус функції:** пошук може бути **опціональним** у поставці (якщо він не входить у ТЗ). Якщо пошук вимкнено — це не впливає на роботу розділу «Генерація». | |
| ⚠️ **Актуальність бази:** якщо пошук увімкнений і використовує індекси з `DocSA/legal-position-indexes`, врахуйте що це тестовий snapshot приблизно **1.5 роки давності** і він може не містити нових/оновлених позицій після дати snapshot. | |
| ### Два типи пошуку: | |
| #### 1. Пошук на основі правової позиції | |
| - Використовує згенеровану позицію з закладки "Генерація" | |
| - **Коли використовувати**: після генерації позиції | |
| - **Як активувати**: кнопка стає доступною після генерації | |
| - Натисніть **"🔎 Пошук на основі правової позиції"** | |
| #### 2. Пошук на основі вхідного тексту | |
| - Використовує оригінальний текст судового рішення | |
| - **Коли використовувати**: для швидкого пошуку без генерації | |
| - **Як активувати**: доступна завжди | |
| - Натисніть **"🔎 Пошук на основі вхідного тексту"** | |
| ### Результати пошуку: | |
| Ви отримаєте список релевантних позицій з: | |
| - **Номер** у списку [1], [2], [3]... | |
| - **Заголовок** правової позиції | |
| - **Посилання** на позицію та судове рішення | |
| - **Score** - показник релевантності (чим вище, тим краще) | |
| ### Технологія пошуку: | |
| - Гібридний підхід: векторний пошук + BM25 | |
| - Автоматична дедуплікація результатів | |
| - Топ-10 найрелевантніших позицій | |
| --- | |
| ## Закладка: Аналіз | |
| ### Призначення | |
| Детальний порівняльний аналіз знайдених правових позицій. | |
| ### Як користуватися: | |
| #### 1. Попередні кроки | |
| ⚠️ Спочатку потрібно виконати пошук у закладці "Пошук" | |
| #### 2. Вибір моделі аналізу та налаштувань | |
| - Оберіть провайдер та модель для аналізу. | |
| - Рекомендовано: **GPT-5.4**, **Claude Sonnet 4.6**. | |
| - **Налаштування "Роздумів" (Thinking)**: аналогічно до режиму генерації, тепер ви можете увімкнути режим глибокого аналізу (Thinking) для складних порівнянь. | |
| - **Температура аналізу**: налаштування креативності порівняння. | |
| - **Max Tokens (ліміт відповіді)**: максимальний обсяг деталізації аналізу (від 512 до 32768). | |
| #### 3. Уточнююче питання (опціонально) | |
| Додайте конкретне питання для AI, наприклад: | |
| - "Чи підходять ці позиції для справ про відшкодування моральної шкоди?" | |
| - "Які з позицій стосуються процесуальних питань?" | |
| - "Чи є позиції щодо застосування норм ЦКУ?" | |
| #### 4. Запуск аналізу | |
| Натисніть **"⚖️ Аналіз результатів пошуку"**. | |
| *Система відобразить прогрес-бар та повідомлення про очікування, оскільки аналіз декількох позицій може тривати до 1-2 хвилин.* | |
| ### Результат аналізу: | |
| Для кожної релевантної позиції ви отримаєте: | |
| - **Номер позиції** у списку | |
| - **Детальне обґрунтування** релевантності | |
| - **Аналіз спільних аспектів** з вашим рішенням | |
| - **Рекомендації** щодо застосування | |
| ### Час обробки: | |
| - Залежить від кількості знайдених позицій | |
| - 1-3 позиції: 15-30 секунд | |
| - 5-10 позицій: 30-60 секунд | |
| --- | |
| ## Закладка: Налаштування | |
| ### Призначення | |
| Персоналізація промптів для AI відповідно до ваших потреб. | |
| ### Три типи промптів: | |
| #### 1. Системний промпт | |
| **Що це:** Визначає роль та базові інструкції для AI | |
| **Приклад стандартного:** | |
| ``` | |
| Ти - кваліфікований юрист-аналітик, експерт з правових позицій Верховного Суду. | |
| ``` | |
| **Коли змінювати:** | |
| - Для зміни стилю відповідей (формальний, академічний) | |
| - Для додавання спеціалізації (цивільне право, кримінальне) | |
| #### 2. Промпт генерації правової позиції | |
| **Що це:** Шаблон для створення правових позицій з судових рішень | |
| **Важливо:** Містить плейсхолдери: | |
| - `{court_decision_text}` - текст рішення | |
| - `{comment}` - ваш коментар | |
| **Коли змінювати:** | |
| - Для зміни структури позиції | |
| - Для додавання специфічних вимог | |
| - Для фокусу на певних аспектах | |
| #### 3. Промпт аналізу прецедентів | |
| **Що це:** Шаблон для порівняльного аналізу позицій | |
| **Важливо:** Містить плейсхолдери: | |
| - `{query}` - нова позиція | |
| - `{question}` - уточнююче питання | |
| - `{context_str}` - знайдені позиції | |
| **Коли змінювати:** | |
| - Для зміни критеріїв аналізу | |
| - Для глибшого порівняння | |
| ### Як редагувати: | |
| 1. Відредагуйте текст промпту у відповідному полі | |
| 2. Натисніть **"💾 Зберегти промпти"** | |
| 3. Побачите підтвердження: ✅ "Промпти успішно збережено" | |
| 4. Поверніться до генерації - тепер використовуються ваші промпти! | |
| ### Скинути до стандартних: | |
| Натисніть **"🔄 Скинути до стандартних"** для повернення дефолтних промптів. | |
| ### Важливо: | |
| - Промпти зберігаються тільки для вашої сесії | |
| - Час сесії: 30 хвилин без активності | |
| - Кожен користувач має свої власні промпти | |
| - Повна ізоляція між користувачами | |
| --- | |
| ## Закладка: Пакетне тестування | |
| ### Призначення | |
| Масова генерація правових позицій з CSV файлів для тестування та порівняння моделей. | |
| ### Покрокова інструкція: | |
| #### Крок 1: Підготовка CSV файлу | |
| Створіть CSV файл з обов'язковою колонкою `text`: | |
| ```csv | |
| id_lp,text | |
| 1,"Текст судового рішення 1..." | |
| 2,"Текст судового рішення 2..." | |
| 3,"Текст судового рішення 3..." | |
| ``` | |
| **Приклади:** дивіться `test_docs/test_sample.csv` | |
| #### Крок 2: Налаштування параметрів | |
| 1. **Провайдер AI** - оберіть постачальника (OpenAI, Anthropic, Gemini, DeepSeek) | |
| 2. **Модель генерації** - виберіть модель для тестування | |
| 3. **Пауза між запитами** - встановіть затримку (0-10 секунд) | |
| **Рекомендовані паузи:** | |
| - 1-10 рядків: 0.5-1 сек | |
| - 10-50 рядків: 1-2 сек | |
| - 50-100 рядків: 2-3 сек | |
| - 100+ рядків: 3-5 сек | |
| #### Крок 3: Завантаження файлу | |
| 1. Натисніть **"📁 Завантажте CSV файл з тестовими даними"** | |
| 2. Виберіть ваш CSV файл | |
| 3. Натисніть **"📂 Завантажити CSV/XLSX файл"** | |
| 4. Перевірте попередній перегляд: | |
| - Кількість рядків | |
| - Список колонок | |
| - Перші 3 рядки тексту | |
| #### Крок 4: Запуск тестування | |
| 1. Натисніть **"▶️ Запустити пакетне тестування"** | |
| 2. Слідкуйте за прогресом: | |
| - Прогрес-бар показує поточний стан | |
| - "Обробка рядка X з Y" | |
| #### Крок 5: Завантаження результатів | |
| Після завершення: | |
| 1. З'явиться кнопка **"📥 Завантажити результати"** | |
| 2. Файл збережено у `test_results/` | |
| 3. Назва файлу: `batch_test_results_{модель}_{дата_час}.csv` | |
| ### Формат результатів: | |
| Результуючий CSV містить: | |
| - Всі оригінальні колонки | |
| - Нова колонка з назвою моделі | |
| - У новій колонці - **повний JSON об'єкт**: | |
| ```json | |
| { | |
| "title": "Заголовок правової позиції", | |
| "text": "Текст правової позиції", | |
| "proceeding": "Тип судочинства", | |
| "category": "Категорія" | |
| } | |
| ``` | |
| ### Обробка результатів у Python: | |
| ```python | |
| import pandas as pd | |
| import json | |
| # Завантажити результати | |
| df = pd.read_csv('test_results/batch_test_results_gemini-3.0-flash_20260103_120000.csv') | |
| # Парсити JSON | |
| df['parsed'] = df['gemini-3.0-flash'].apply(json.loads) | |
| # Витягти поля | |
| df['title'] = df['parsed'].apply(lambda x: x['title']) | |
| df['text'] = df['parsed'].apply(lambda x: x['text']) | |
| ``` | |
| ### Час виконання: | |
| **Розрахунок:** `кількість_рядків × (час_запиту + пауза)` | |
| **Приклади:** | |
| - 10 рядків × (3 сек + 1 сек) = ~40 секунд | |
| - 100 рядків × (3 сек + 1 сек) = ~6.7 хвилин | |
| ### Поради: | |
| - Для великих обсягів (100+ рядків) використовуйте паузу 3-5 сек | |
| - При помилках rate limit - збільште паузу | |
| - Результати зберігаються автоматично навіть при помилках окремих рядків | |
| --- | |
| ## Підтримувані провайдери | |
| ### OpenAI | |
| **Моделі:** | |
| - **GPT-5.4 / GPT-5.3 Chat Latest** - найновіші флагманські моделі. | |
| - **GPT-5.2** - потужна модель з reasoning (рекомендована для аналізу). | |
| - **GPT-4o** - стабільна потужна модель. | |
| - **GPT-4o-mini** - баланс ціна/якість. | |
| - **Fine-tuned моделі** (наприклад, `GPT-4o Mini LP`) - власні налаштовані моделі для юридичної тематики. | |
| **Особливості:** | |
| - Швидка обробка. | |
| - Підтримка Reasoning Effort (до `xhigh`) та Verbosity. | |
| - Висока якість структурованих даних (JSON Schema). | |
| **API Key:** `OPENAI_API_KEY` | |
| ### Anthropic (Claude) | |
| **Моделі:** | |
| - **Claude Sonnet 4.6** - рекомендована (за замовчуванням). | |
| - **Claude Opus 4.6** - найпотужніша для найскладніших випадків. | |
| - **Claude Haiku 4.5** - надшвидка модель нового покоління. | |
| **Особливості:** | |
| - Найкращий юридичний аналіз та структурування. | |
| - **Adaptive Thinking** у серії 4.6 для розумного використання ресурсів. | |
| - **Extended Thinking** у серії 4.5. | |
| - Величезний контекст (до 200k+ токенів). | |
| **API Key:** `ANTHROPIC_API_KEY` | |
| ### Google (Gemini) | |
| **Моделі:** | |
| - **Gemini 3 Flash** - надзвичайно швидка. | |
| - **Gemini 3 Pro** - з повноцінним Thinking Mode. | |
| **Особливості:** | |
| - Інноваційний Thinking Mode для логічних висновків. | |
| - Висока швидкість генерації. | |
| **API Key:** `GEMINI_API_KEY` | |
| ### DeepSeek | |
| **Моделі:** | |
| - **DeepSeek Chat** - універсальна модель. | |
| **Особливості:** | |
| - Оптимальна вартість. | |
| - Висока якість роботи з українською мовою. | |
| **API Key:** `DEEPSEEK_API_KEY` | |
| --- | |
| ## Часті питання | |
| ### Загальні питання | |
| **Q: Чи потрібна реєстрація?** | |
| A: Ні, додаток працює без реєстрації. Кожна сесія автоматично ідентифікується. | |
| **Q: Скільки коштує використання?** | |
| A: Додаток безкоштовний, оплачується тільки API провайдерів (якщо використовуєте платні моделі). | |
| **Q: Чи зберігаються мої дані?** | |
| A: Дані зберігаються тільки на час сесії (30 хвилин). Після закриття - автоматично видаляються. | |
| **Q: Чи можуть інші користувачі бачити мої промпти?** | |
| A: Ні, повна ізоляція між користувачами. Кожна сесія унікальна. | |
| ### Генерація | |
| **Q: Яку модель обрати?** | |
| A: Для початку - Gemini 3.0 Flash (безкоштовно) або GPT-4o-mini (дешево). | |
| **Q: Чому генерація повільна?** | |
| A: Залежить від моделі і режиму Thinking. Вимкніть Thinking для швидшої роботи. | |
| **Q: Що робити з URL, які не працюють?** | |
| A: Скопіюйте текст вручну та вставте як "Текстовий ввід". | |
| ### Пошук | |
| **Q: Чому мало результатів?** | |
| A: База містить тільки позиції Верховного Суду. Не всі теми представлені. | |
| **Q: Що означає Score?** | |
| A: Показник схожості (0-1). Чим вище - тим релевантніше. | |
| ### Налаштування | |
| **Q: Промпти не працюють після збереження** | |
| A: Перевірте наявність плейсхолдерів `{court_decision_text}` і `{comment}`. | |
| **Q: Чи можу я зберегти промпти назавжди?** | |
| A: Поки що ні - тільки на час сесії. Скопіюйте їх у файл для збереження. | |
| ### Пакетне тестування | |
| **Q: Який максимальний розмір CSV?** | |
| A: Технічно необмежений, але рекомендовано до 500 рядків за раз. | |
| **Q: Що робити при помилках rate limit?** | |
| A: Збільште паузу між запитами до 3-5 секунд. | |
| **Q: Чи можна зупинити тестування?** | |
| A: Поки що ні - дочекайтеся завершення або оновіть сторінку. | |
| --- | |
| ## Поради та рекомендації | |
| ### Для генерації якісних позицій: | |
| 1. **Використовуйте повний текст рішення** | |
| - Не тільки мотивувальну частину | |
| - Включайте контекст справи | |
| 2. **Додавайте коментарі** | |
| - Вказуйте на що звернути увагу | |
| - Що важливо виділити | |
| 3. **Експериментуйте з моделями** | |
| - Різні моделі - різні стилі | |
| - Claude - детальний аналіз | |
| - GPT - структурованість | |
| - Gemini - баланс | |
| ### Для ефективного пошуку: | |
| 1. **Спочатку згенеруйте позицію** | |
| - Пошук на основі позиції точніший | |
| - Ніж пошук за сирим текстом | |
| 2. **Перевіряйте топ-3 результати** | |
| - Найвищий score = найрелевантніше | |
| - Нижче 0.7 - можливо нерелевантно | |
| ### Для налаштування промптів: | |
| 1. **Змінюйте поступово** | |
| - Не змінюйте все одразу | |
| - Тестуйте кожну зміну | |
| 2. **Зберігайте резервні копії** | |
| - Скопіюйте промпти у файл | |
| - Перед великими змінами | |
| 3. **Використовуйте приклади** | |
| - Додавайте конкретні приклади у промпт | |
| - Для кращих результатів | |
| ### Для пакетного тестування: | |
| 1. **Почніть з малого** | |
| - Спочатку 5-10 рядків | |
| - Перевірте якість | |
| - Потім збільшуйте обсяг | |
| 2. **Налаштуйте паузу правильно** | |
| - Краще довше, ніж rate limit | |
| - Оптимально 1-2 секунди | |
| 3. **Зберігайте результати** | |
| - Одразу завантажуйте файл | |
| - Назва містить дату/час | |
| --- | |
| ## Технічна підтримка | |
| Якщо виникли проблеми: | |
| 1. **Перезавантажте сторінку** - часто допомагає | |
| 2. **Перевірте API ключі** - чи налаштовані правильно | |
| 3. **Спробуйте іншу модель** - можливо проблема з конкретною | |
| 4. **Очистіть кеш браузера** - F12 → Application → Clear Storage | |
| --- | |
| **Дякуємо за використання AI Асистента!** 🎉 | |
| Для додаткової інформації дивіться: | |
| - [README.md](README.md) - технічна документація | |
| - [docs/batch/BATCH_TESTING_README.md](docs/batch/BATCH_TESTING_README.md) - детально про пакетне тестування | |
| - [PROMPT_EDITING.md](docs/PROMPT_EDITING.md) - глибоке занурення у промпти | |