COMPUTE_PLANE_ARCHITECTURE.md

=====================================================

Apckeyl Framework

COMPUTE PLANE ARCHITECTURE

Version 1.0

=====================================================

1. Purpose

Compute Plane — это слой Apckeyl Framework, который отвечает за выполнение реальных вычислительных задач через внешние Compute Modules.

Orchestrator не должен выполнять тяжёлые вычисления сам.

Orchestrator управляет задачей.

Compute Module выполняет задачу.

Основной принцип:

Control Plane
      ↓
Compute Plane
      ↓
External Compute Module

2. Architectural Principle

Apckeyl Orchestrator является Control Center.

Он не должен быть привязан к конкретному вычислительному серверу.

Compute Module может находиться:

• в отдельном Hugging Face Space;
• на другом бесплатном сервисе;
• на GPU-сервисе;
• на CPU-сервисе;
• в локальном окружении;
• на собственном сервере;
• на другом совместимом API.

Control Plane не должен зависеть от конкретного места размещения Compute Module.

3. Current Compute Module

Первым реальным Compute Module является:

Apckeyl_RealESRGAN

Назначение:

Image Upscaling

Тип:

image_upscaler

Основной capability:

image_upscale

Текущий Space:

Apckeyl_RealESRGAN

Этот Space сохраняется отдельно.

Orchestrator не заменяет Apckeyl_RealESRGAN.

Orchestrator управляет доступом к нему.

4. Separation of Responsibilities

Control Plane

Control Plane отвечает за:

• создание задач;
• идентификацию задач;
• выбор модуля;
• маршрутизацию;
• управление статусами;
• управление очередью;
• регистрацию Compute Modules;
• мониторинг;
• логирование;
• обработку ошибок;
• получение результатов.

Compute Plane

Compute Plane отвечает за:

• выполнение конкретной вычислительной операции;
• обработку входных данных;
• запуск модели;
• сохранение результата;
• возврат результата Orchestrator.

Compute Module

Compute Module является независимым исполнителем.

Например:

Apckeyl_RealESRGAN

получает задачу:

image_upscale

выполняет upscale

и возвращает результат.

5. Communication Model

На первом этапе используется HTTP/API-модель.

Общий поток:

User
  ↓
Client
  ↓
Orchestrator
  ↓
Control Plane
  ↓
Task Manager
  ↓
Module Registry
  ↓
Compute Module
  ↓
Result
  ↓
Orchestrator
  ↓
User

6. Important Rule

Control Plane не должен знать внутреннюю реализацию Compute Module.

Например:

Orchestrator не должен знать:

• какую AI-модель использует RealESRGAN;
• какие Python-библиотеки установлены;
• какой код находится внутри Space;
• какой GPU или CPU используется;
• каким образом происходит обработка изображения.

Orchestrator знает только контракт.

Например:

module_id
module_type
capabilities
endpoint
status

7. Compute Module Contract

Каждый Compute Module должен иметь стандартное описание.

Минимальный контракт:

module_id
module_name
module_type
capabilities
endpoint
status

Пример:

module_id:
    realesrgan

module_name:
    Apckeyl_RealESRGAN

module_type:
    image_upscaler

capabilities:
    image_upscale

status:
    available

8. Task Contract

Control Plane создаёт задачу.

Минимальная структура:

task_id
task_type
status
module_id
payload
created_at

Пример:

task_id:
    task_000001

task_type:
    image_upscale

status:
    created

module_id:
    realesrgan

9. Task Lifecycle

Основной жизненный цикл:

created
   ↓
queued
   ↓
dispatched
   ↓
processing
   ↓
completed

При ошибке:

processing
   ↓
failed

При отмене:

created
   ↓
cancelled

10. Dispatch

Dispatch — передача задачи выбранному Compute Module.

Например:

image_upscale
      ↓
Control Plane
      ↓
realesrgan
      ↓
Apckeyl_RealESRGAN

Dispatch не должен быть связан с конкретной реализацией модели.

11. Endpoint Abstraction

Compute Module должен рассматриваться как внешний endpoint.

Control Plane не должен зависеть от конкретного транспорта.

На первом этапе:

HTTP

В будущем возможно:

REST API
Webhook
Queue
Internal API
RPC
другие совместимые механизмы

12. Availability

Каждый Compute Module должен иметь статус.

Минимальные состояния:

available
unavailable
busy
error
disabled

Control Plane не должен отправлять задачу в модуль со статусом:

unavailable

или:

disabled

13. Health Check

В будущем Orchestrator должен периодически проверять Compute Modules.

Health Check должен определять:

• доступность endpoint;
• время ответа;
• корректность ответа;
• состояние модуля.

Пример:

available
    ↓
health check
    ↓
response OK
    ↓
available

При ошибке:

available
    ↓
health check
    ↓
error
    ↓
unavailable

14. Timeout

Каждый внешний Compute Module должен иметь ограничение времени ожидания.

Если Compute Module не отвечает в установленный период:

timeout

Control Plane не должен зависать бесконечно.

15. Retry

При временной ошибке возможен повторный запрос.

Пример:

dispatch
   ↓
timeout
   ↓
retry #1
   ↓
timeout
   ↓
retry #2
   ↓
failed

Количество повторов должно быть ограничено.

16. Result Handling

Compute Module возвращает результат.

Результат должен быть связан с исходным task_id.

Пример:

task_id:
    task_000001

status:
    completed

result:
    output_file

Orchestrator принимает результат и передаёт его следующему слою.

17. File Handling

Большие файлы не должны передаваться через Control Plane без необходимости.

В будущем предпочтительная схема:

User
  ↓
upload
  ↓
temporary storage
  ↓
task
  ↓
Compute Module
  ↓
result storage
  ↓
User

Это позволит уменьшить нагрузку на Orchestrator.

18. Resource Independence

Compute Module может использовать:

CPU
GPU
ZeroGPU
другой вычислительный ресурс

Orchestrator не должен предполагать, какой именно ресурс используется.

Например:

Orchestrator
      ↓
Apckeyl_RealESRGAN
      ↓
CPU Basic

или:

Orchestrator
      ↓
другой Compute Module
      ↓
GPU

Архитектура должна поддерживать оба варианта.

19. ZeroGPU Rule

Orchestrator не должен использовать ZeroGPU как обязательный вычислительный ресурс.

ZeroGPU рассматривается только как возможная инфраструктурная среда для конкретного модуля.

Это означает:

ZeroGPU ≠ Orchestrator architecture

Orchestrator должен продолжать работать как Control Plane независимо от наличия ZeroGPU.

20. Free Infrastructure Strategy

Apckeyl Framework проектируется с приоритетом бесплатной инфраструктуры.

При выборе Compute Modules необходимо предпочитать:

• бесплатные сервисы;
• бесплатные Hugging Face Spaces;
• бесплатные CPU/GPU ресурсы;
• бесплатные API;
• локальные ресурсы только при необходимости.

Платные сервисы не являются обязательной частью архитектуры.

21. Commercial Use

Для каждого AI Compute Module необходимо проверять лицензию используемой модели.

До подключения модели необходимо определить:

• model name;
• version;
• license;
• commercial use allowed;
• YouTube allowed;
• sale allowed.

Эта информация должна фиксироваться в документации проекта.

22. Compute Module Independence

Каждый Compute Module должен быть заменяемым.

Например:

Apckeyl_RealESRGAN
       ↓
   заменить
       ↓
другой Image Upscaler

Control Plane не должен требовать переписывания архитектуры.

23. Module Selection

Выбор Compute Module производится через Module Registry.

Пример:

task_type:
    image_upscale

      ↓

module_type:
    image_upscaler

      ↓

capability:
    image_upscale

      ↓

selected module:
    realesrgan

24. Multiple Modules

В будущем один capability может иметь несколько Compute Modules.

Например:

image_upscale

    ├── realesrgan
    ├── upscaler_2
    └── upscaler_3

Control Plane сможет выбирать доступный модуль.

25. Fallback

Если основной Compute Module недоступен:

realesrgan
    ↓
unavailable

Control Plane может выбрать другой совместимый модуль:

upscaler_2

Fallback является будущей функцией.

26. Priority

Compute Modules в будущем могут иметь приоритет.

Например:

realesrgan
    priority: 100

upscaler_2
    priority: 50

Control Plane выбирает модуль с учётом:

• availability;
• priority;
• health;
• capability;
• нагрузки.

27. Queue

Если Compute Module занят, задача не должна теряться.

Она должна перейти:

created
   ↓
queued

После освобождения модуля:

queued
   ↓
dispatched

28. Concurrency

Каждый Compute Module может иметь ограничение одновременных задач.

Например:

max_concurrent_tasks:
    1

или:

max_concurrent_tasks:
    2

Control Plane должен учитывать это при dispatch.

29. Error Isolation

Ошибка Compute Module не должна ломать Control Plane.

Например:

Apckeyl_RealESRGAN
       ↓
     ERROR

Orchestrator продолжает работать.

Статус модуля:

error

Задача:

failed

Control Plane:

running

30. Security

Endpoint Compute Module не должен считаться доверенным автоматически.

В будущем необходимо поддерживать:

• authentication;
• authorization;
• tokens;
• signed requests;
• HTTPS;
• ограничение доступа.

Секреты не должны храниться в исходном коде.

31. Logging

Каждый dispatch должен логироваться.

Минимально:

task_id
module_id
timestamp
status
duration
error

Пример:

task_000001
realesrgan
dispatched
processing
completed

32. Monitoring

Resource Monitor в будущем должен контролировать:

• количество задач;
• очередь;
• время обработки;
• ошибки;
• доступность модулей;
• latency;
• нагрузку.

33. Architecture Diagram

Общая схема:

┌───────────────────────────────┐
│            USER               │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│         ORCHESTRATOR          │
│                               │
│         CONTROL PLANE         │
│                               │
│  Task Manager                 │
│  Module Registry              │
│  Dispatcher                   │
│  Queue                        │
│  Logger                       │
│  Resource Monitor             │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│         COMPUTE PLANE         │
└───────────────┬───────────────┘
                │
      ┌─────────┼─────────┐
      │         │         │
      ▼         ▼         ▼
RealESRGAN   Image AI   Video AI
   Space       Space       Space

34. Current Architecture

На текущем этапе реализованы:

Module Registry
Control Plane
Task Manager
Control Plane Tests
Diagnostic Report

Следующий этап:

Dispatcher

После Dispatcher:

Compute Module Adapter

После Adapter:

Apckeyl_RealESRGAN connection

35. First Real Integration

Первым реальным внешним Compute Module остаётся:

Apckeyl_RealESRGAN

Интеграция должна выполняться через отдельный adapter.

Control Plane не должен содержать специфичный код RealESRGAN.

Архитектура:

Control Plane
      ↓
Compute Adapter
      ↓
Apckeyl_RealESRGAN

36. Future Compute Modules

Архитектура должна позволять подключать:

Image Generation
Video Generation
Story Character Studio
Image Upscaler
Video Upscaler
Stock Factory
другие AI-модули

Каждый модуль должен подключаться через единый контракт.

37. Final Principle

Apckeyl Orchestrator не является одним большим AI-приложением.

Он является системой управления независимыми Compute Modules.

Основная идея:

ORCHESTRATE
    NOT
COMPUTE

Control Plane управляет.

Compute Plane выполняет.

Compute Modules остаются независимыми.

=====================================================

End of COMPUTE_PLANE_ARCHITECTURE.md

Version 1.0

=====================================================