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

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. Перевірка роботи

# Список моделей
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 створено та готовий до запуску.

Як перевірити:

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

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

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

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

Як змінити:

# 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

   • Підсумкові метрики
   • Найбільш використовувана модель
   • Загальна статистика

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

// 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

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

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 не запускається

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

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

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

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

# Перевірити чи модель є в 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 не відповідає

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

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

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

---

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

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

---

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

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

---

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