docs/HF_DATASET_SETUP.md

📦 Налаштування Hugging Face Dataset для індексів

Крок 1: Створення датасету на Hugging Face

1. Перейдіть на: https://huggingface.co/new-dataset

2. Заповніть форму:

   • Owner: DocSA
   • Dataset name: legal-position-indexes
   • License: MIT
   • Visibility: Private або Public (на ваш вибір)

3. Натисніть: Create dataset

Крок 2: Клонування та налаштування

# Клонуйте створений датасет
git clone https://huggingface.co/datasets/DocSA/legal-position-indexes
cd legal-position-indexes

# Налаштуйте Git LFS для великих файлів
git lfs install

# Додайте треки для різних типів файлів індексів
git lfs track "*.json"
git lfs track "*.jsonl"
git lfs track "*.npy"
git lfs track "*.mmindex.json"
git lfs track "*.csc.index.npy"
git lfs track "*.index.json"

# Збережіть конфігурацію LFS
git add .gitattributes
git commit -m "Configure Git LFS"

Крок 3: Завантаження індексів

# Скопіюйте індекси з вашого проєкту
cp -r ../Save_Index_Ivan/* ./

# Перевірте розмір
du -sh .

# Створіть README
cat > README.md << 'EOF'
---
license: mit
task_categories:
- text-retrieval
language:
- uk
tags:
- legal
- ukraine
- embeddings
- bm25
size_categories:
- n<1K
---

# Legal Position Indexes

Індекси для пошуку правових позицій Верховного Суду України.

## 📊 Вміст

- **BM25 Retriever**: Індекси для пошуку за ключовими словами
- **Document Store**: База судових рішень
- **Vector Embeddings**: Векторні представлення для семантичного пошуку

## 📁 Структура

legal-position-indexes/ ├── docstore_es_filter.json # Document store ├── bm25_retriever/ # BM25 індекси │ ├── corpus.jsonl │ ├── corpus.mmindex.json │ ├── data.csc.index.npy │ ├── indices.csc.index.npy │ ├── indptr.csc.index.npy │ ├── params.index.json │ ├── retriever.json │ └── vocab.index.json ├── bm25_retriever_meta/ # BM25 з метаданими └── bm25_retriever_short/ # BM25 короткий

## 🚀 Використання

### Python

\`\`\`python
from huggingface_hub import snapshot_download

# Завантажити всі індекси
snapshot_download(
    repo_id="DocSA/legal-position-indexes",
    repo_type="dataset",
    local_dir="Save_Index_Ivan"
)
\`\`\`

### В проєкті Legal Position AI Analyzer

\`\`\`python
from index_loader import load_indexes_with_fallback

# Автоматично завантажить з HF Datasets
load_indexes_with_fallback()
\`\`\`

## 📊 Статистика

- **Розмір:** ~530 MB
- **Документів:** ~[NUMBER]
- **Мова:** Українська
- **Оновлено:** 10 лютого 2026 р.

## 📝 Ліцензія

MIT License

## 👥 Автори

Проєкт Legal Position AI Analyzer для Верховного Суду України
EOF

# Додайте всі файли
git add .

# Закомітьте
git commit -m "Add legal position indexes v1.0

- BM25 retrievers
- Document store
- Vector embeddings
- Total size: ~530MB"

# Завантажте на HF
git push

Крок 4: Перевірка

1. Перейдіть на: https://huggingface.co/datasets/DocSA/legal-position-indexes

2. Перевірте:

   • ✅ Всі файли завантажені
   • ✅ README відображається
   • ✅ LFS файли правильно трекаються

Крок 5: Інтеграція в проєкт

Оновіть main.py або components.py:

from index_loader import load_indexes_with_fallback

def initialize_components() -> bool:
    """Initialize all necessary components for the application."""
    try:
        # Завантажити індекси з HF Datasets (з fallback на S3)
        if not load_indexes_with_fallback():
            logger.error("Failed to load indexes")
            return False
        
        # Решта ініціалізації...
        # ...
        
        return True
    except Exception as e:
        logger.error(f"Error initializing components: {str(e)}")
        return False

Оновіть app.py для HF Spaces:

#!/usr/bin/env python3
import os
from index_loader import load_indexes_with_fallback

# Завантажити індекси при старті
print("📥 Loading indexes...")
if load_indexes_with_fallback():
    print("✅ Indexes loaded successfully!")
else:
    print("⚠️ Warning: Indexes not available. Search will not work.")

# Запуск додатку
from interface import create_gradio_interface

if __name__ == "__main__":
    demo = create_gradio_interface()
    demo.launch(
        server_name="0.0.0.0",
        server_port=7860,
        share=False,
        show_error=True,
        enable_queue=True
    )

Крок 6: Налаштування для приватного датасету (опціонально)

Якщо ваш датасет приватний:

На HF Spaces:

1. Settings > Variables and secrets
2. Додайте:

   HF_TOKEN=hf_xxxxxxxxxxxxx
   

В коді:

import os

load_indexes_with_fallback(
    token=os.getenv("HF_TOKEN")
)

🔄 Оновлення індексів

Коли потрібно оновити індекси:

cd legal-position-indexes

# Оновіть файли
cp -r ../Save_Index_Ivan/* ./

# Закомітьте зміни
git add .
git commit -m "Update indexes v1.1"
git push

# Індекси автоматично оновляться на всіх інсталяціях

✅ Переваги цього підходу

• ✅ Безкоштовно - HF Datasets безкоштовний
• ✅ Швидко - CDN для швидкого завантаження
• ✅ Просто - Нативна інтеграція з HF Spaces
• ✅ Версіонування - Git історія змін
• ✅ Fallback - Автоматичний перехід на S3 при помилці
• ✅ Оновлення - Легко оновлювати індекси

📊 Порівняння з AWS S3

Параметр	HF Datasets	AWS S3
Вартість	$0	~$0.02/міс
Setup	Простий	Середній
Швидкість	Швидко	Швидко
Інтеграція з HF Spaces	Відмінна	Потребує credentials
Версіонування	Так (Git)	Ні (окремо)

---

Дата: 10 лютого 2026 р.