microdao-daarion/DATALAB-CHANDRA-INSTALLATION-GUIDE.md

# 📄 Встановлення Datalab Chandra на НОДА1

**Дата:** 2026-01-12

---

## ✅ Це нормально!

**Так, встановлення Datalab Chandra для обробки документів та таблиць — відмінна ідея!**

Chandra доповнить поточну обробку документів і надасть:
- ✅ Обробку складних таблиць (зберігає структуру)
- ✅ Розпізнавання рукописного тексту
- ✅ Обробку форм та документів
- ✅ Збереження макету документа (bounding boxes, метадані)
- ✅ Вихід у форматах: Markdown, HTML, JSON

---

## 📊 Поточна ситуація

### НОДА1:
- ✅ **GPU:** NVIDIA RTX 4000 SFF Ada (20GB VRAM) — достатньо для Chandra Small
- ✅ **Обробка документів:** `gateway-bot/services/doc_service.py`
- ✅ **Router:** має `OCR_URL` налаштування

### Що додасть Chandra:
- Покращена обробка таблиць
- Розпізнавання рукопису
- Обробка складних форм
- Детальні метадані документа

---

## 🔧 Встановлення

### Крок 1: Отримати Docker образ Chandra

**Варіант A: Офіційний Datalab образ (потрібна ліцензія)**
```bash
# Потрібно отримати доступ до Datalab registry
docker pull datalab/chandra-inference:latest
```

**Варіант B: HuggingFace модель (open-source)**
```bash
# Використати HuggingFace модель
# Створити власний Dockerfile з моделлю
```

### Крок 2: Налаштувати змінні оточення

Додати в `.env` або `docker-compose.node1.yml`:
```yaml
environment:
  - CHANDRA_LICENSE_KEY=${CHANDRA_LICENSE_KEY:-}  # Якщо потрібна ліцензія
  - CHANDRA_MODEL=chandra-small  # або chandra для повної версії
```

### Крок 3: Запустити сервіси

```bash
cd /opt/microdao-daarion
docker compose -f docker-compose.node1.yml up -d chandra-inference chandra-service
```

### Крок 4: Перевірити статус

```bash
# Перевірка health check
curl http://localhost:8002/health

# Перевірка моделей
curl http://localhost:8002/models
```

---

## 🔗 Інтеграція

### Router інтеграція:
- ✅ `OCR_URL` оновлено на `http://chandra-service:8002`
- ✅ Додано `CHANDRA_URL` для прямих викликів

### Gateway інтеграція:
- `doc_service.py` може використовувати Chandra через Router
- Або напряму через `chandra-service:8002`

---

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

### API виклик:
```python
import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://chandra-service:8002/process",
        files={"file": ("document.pdf", file_data)},
        data={
            "output_format": "markdown",  # або html, json
            "accurate_mode": "false"
        }
    )
    result = response.json()
```

### Інтеграція в doc_service:
```python
# В doc_service.py додати метод:
async def parse_with_chandra(
    self,
    doc_url: str,
    output_format: str = "markdown"
) -> Dict[str, Any]:
    """Parse document using Chandra OCR"""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://chandra-service:8002/process",
            json={
                "doc_url": doc_url,
                "output_format": output_format
            }
        )
        return response.json()
```

---

## ⚠️ Важливо

1. **Ліцензія:** Для повної версії Chandra потрібна ліцензія Datalab
2. **VRAM:** Chandra Small потребує ~8GB VRAM, повна версія ~16GB
3. **Час обробки:** Accurate mode повільніший, але точніший
4. **Docker образ:** Потрібно замінити placeholder на реальний образ Datalab

---

## 🔄 Наступні кроки

1. Отримати Docker образ Chandra (Datalab registry або HuggingFace)
2. Оновити `docker-compose.node1.yml` з правильним образом
3. Налаштувати ліцензію (якщо потрібна)
4. Протестувати обробку таблиць та форм
5. Інтегрувати в `doc_service.py`

---

**Оновлено:** 2026-01-12