microdao-daarion/SWAPPER-SERVICE-SETUP.md

# Swapper Service - Setup Guide for Node #2

**Version:** 1.0.0  
**Date:** 2025-11-22  
**Status:** ✅ Ready for Deployment

---

## ✅ Що було зроблено

### 1. Створено Swapper Service
- ✅ Основна логіка сервісу (`app/main.py`)
- ✅ API endpoints для керування моделями
- ✅ Cabinet API для відображення в кабінетах (`app/cabinet_api.py`)
- ✅ Dockerfile та requirements.txt
- ✅ Конфігураційний файл (`config/swapper_config.yaml`)
- ✅ Додано в `docker-compose.yml`

### 2. Функціональність
- ✅ Динамічне завантаження/вивантаження моделей
- ✅ Single-active mode (одна модель за раз)
- ✅ Відстеження uptime моделей (в годинах)
- ✅ Метрики (request count, uptime, load/unload times)
- ✅ Інтеграція з Ollama
- ✅ API для кабінетів Node #1 та Node #2

### 3. Документація
- ✅ README.md з повним описом API
- ✅ SWAPPER-CABINET-INTEGRATION.md з прикладами інтеграції
- ✅ Відповідь на питання про vLLM vs Swapper

---

## 🚀 Швидкий старт

### 1. Запуск Swapper Service на Node #2

```bash
cd /Users/apple/github-projects/microdao-daarion

# Build та запуск
docker-compose up -d swapper-service

# Перевірка статусу
curl http://localhost:8890/health

# Перевірка статусу для кабінету
curl http://localhost:8890/api/cabinet/swapper/status
```

### 2. Перевірка роботи

```bash
# Список моделей
curl http://localhost:8890/models

# Завантажити модель
curl -X POST http://localhost:8890/models/deepseek-r1-70b/load

# Статус
curl http://localhost:8890/status

# Метрики
curl http://localhost:8890/metrics
```

---

## 📊 Відповіді на питання

### 1. Чи працює Swapper на Node #2?

**Відповідь:** Тепер так! Swapper Service створено та готовий до запуску.

**Як перевірити:**
```bash
# Перевірити чи запущений
docker ps | grep swapper-service

# Перевірити health
curl http://localhost:8890/health
```

### 2. За один раз завантажується тільки 1 модель?

**Відповідь:** Так, в режимі `single-active` (за замовчуванням) завантажується тільки одна модель за раз. Це оптимізує використання пам'яті.

**Як змінити:**
```yaml
# config/swapper_config.yaml
swapper:
  mode: multi-active  # Дозволити кілька моделей одночасно
  max_concurrent_models: 3  # Максимум 3 моделі
```

### 3. Swapper Service та vLLM - це різні сервіси?

**Відповідь:** Так, це різні сервіси:

| Swapper Service | vLLM |
|----------------|------|
| Керує завантаженням/вивантаженням моделей | Високопродуктивний інференс-движок |
| Single-active mode (одна модель) | Continuous serving (моделі завжди завантажені) |
| Оптимізація пам'яті | Оптимізація throughput |
| Працює з Ollama | Пряма робота з GPU |
| Легкий, простий API | Складний, production-grade |

**Коли використовувати Swapper:**
- Обмежена пам'ять (Node #2 MacBook)
- Потрібно перемикатися між моделями
- Ресурси обмежені

**Коли використовувати vLLM:**
- Максимальна продуктивність
- Моделі завантажені довго
- Є виділені GPU ресурси
- Production serving

---

## 🎨 Інтеграція в кабінети

### API Endpoints для кабінетів

1. **GET /api/cabinet/swapper/status**
   - Повний статус Swapper Service
   - Активна модель
   - Список всіх моделей з метриками

2. **GET /api/cabinet/swapper/models**
   - Детальна інформація про всі моделі
   - Можливість завантажити/вивантажити

3. **GET /api/cabinet/swapper/metrics/summary**
   - Підсумкові метрики
   - Найбільш використовувана модель
   - Загальна статистика

### Приклад використання в кабінеті

```typescript
// Fetch Swapper status
const response = await fetch('http://localhost:8890/api/cabinet/swapper/status');
const data = await response.json();

// Display active model
console.log('Active Model:', data.active_model.name);
console.log('Uptime:', data.active_model.uptime_hours, 'hours');

// Display all models
data.models.forEach(model => {
  console.log(`${model.name}: ${model.status} (${model.uptime_hours}h)`);
});
```

Детальні приклади див. в `docs/SWAPPER-CABINET-INTEGRATION.md`

---

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

### Для Node #2 (MacBook)

1. ✅ Swapper Service створено
2. ⏳ Запустити сервіс: `docker-compose up -d swapper-service`
3. ⏳ Перевірити роботу: `curl http://localhost:8890/health`
4. ⏳ Інтегрувати в кабінет Node #2

### Для Node #1 (Production Server)

1. ⏳ Додати Swapper Service в docker-compose.yml на Node #1
2. ⏳ Налаштувати конфігурацію для Node #1
3. ⏳ Інтегрувати в кабінет Node #1

### Для кабінетів

1. ⏳ Додати Swapper секцію в адмін-консоль
2. ⏳ Створити компоненти для відображення:
   - Активна модель
   - Список моделей з метриками
   - Кнопки завантаження/вивантаження
   - Графіки uptime
3. ⏳ Додати real-time оновлення (polling або WebSocket)

---

## 🔧 Конфігурація

### Environment Variables

```bash
OLLAMA_BASE_URL=http://172.17.0.1:11434  # Для Docker
SWAPPER_CONFIG_PATH=/app/config/swapper_config.yaml
SWAPPER_MODE=single-active
MAX_CONCURRENT_MODELS=1
MODEL_SWAP_TIMEOUT=30
```

### Config File

Файл: `services/swapper-service/config/swapper_config.yaml`

```yaml
swapper:
  mode: single-active
  max_concurrent_models: 1
  model_swap_timeout: 30
  gpu_enabled: true
  metal_acceleration: true

models:
  deepseek-r1-70b:
    path: ollama:deepseek-r1:70b
    type: llm
    size_gb: 42
    priority: high
  # ... інші моделі
```

---

## 📊 Метрики в кабінетах

### Що відображається:

1. **Активна модель:**
   - Назва моделі
   - Час роботи (uptime в годинах)
   - Кількість запитів
   - Час завантаження

2. **Список моделей:**
   - Всі доступні моделі
   - Статус кожної (loaded/unloaded)
   - Uptime кожної моделі
   - Можливість завантажити/вивантажити

3. **Підсумкові метрики:**
   - Загальна кількість моделей
   - Загальний uptime
   - Найбільш використовувана модель
   - Загальна кількість запитів

---

## 🐛 Troubleshooting

### Swapper Service не запускається

```bash
# Перевірити логи
docker logs swapper-service

# Перевірити чи Ollama доступний
curl http://localhost:11434/api/tags

# Перевірити конфігурацію
cat services/swapper-service/config/swapper_config.yaml
```

### Модель не завантажується

```bash
# Перевірити чи модель є в Ollama
curl http://localhost:11434/api/tags | grep "model_name"

# Перевірити статус Swapper
curl http://localhost:8890/status

# Спробувати завантажити вручну
curl -X POST http://localhost:8890/models/model_name/load
```

### API не відповідає

```bash
# Перевірити чи сервіс запущений
docker ps | grep swapper

# Перевірити health
curl http://localhost:8890/health

# Перевірити порт
lsof -i :8890
```

---

## 📚 Документація

- **README.md** - Повний опис API та використання
- **SWAPPER-CABINET-INTEGRATION.md** - Детальна інтеграція в кабінети
- **INFRASTRUCTURE.md** - Оновлено з інформацією про Swapper Service

---

## ✅ Чеклист готовності

- [x] Swapper Service код створено
- [x] Dockerfile та requirements.txt
- [x] Конфігураційний файл
- [x] Додано в docker-compose.yml
- [x] Cabinet API endpoints
- [x] Документація
- [ ] Запуск на Node #2 (потрібно виконати)
- [ ] Інтеграція в кабінет Node #2 (потрібно виконати)
- [ ] Інтеграція в кабінет Node #1 (потрібно виконати)

---

**Last Updated:** 2025-11-22  
**Maintained by:** Ivan Tytar & DAARION Team  
**Status:** ✅ Service Ready — Awaiting Deployment