FractalCore README

README проекта с github.com/Fractal-Compute-Orchestrations/FractalCore. Одним файлом markdown: README.md.

Fractal Server Header

FractalCore

High-Performance Orchestration Engine, Federated Aggregator, and Model Graph Slicer

Version License Open In Colab Design Security Entity

FractalCore is the central server, control plane, and model compilation engine for the Fractal decentralized compute ecosystem.

Overview | Quickstart SDK | Key Results & Benchmarks | Industry & Community Recognition | Control Plane UI | Architecture | Core Components | Data Flow | API Summary | Deployment | Security | Theoretical Foundations


Quickstart SDK & CLI

Install the lightweight runtime package (numpy core codec + CLI, optional server and slicer extras) and run the reproducible outlier-resilience benchmark locally in seconds:

pip install -e ".[server]"
fractal doctor
fractal bench
python scripts/quickstart_demo.py

Or run the zero-setup walkthrough in examples/colab_quickstart.ipynb.


Overview

Executive Summary: Core Purpose & Bottom Line

The Problem: Centralized federated aggregators face network ingress bandwidth saturation when orchestrating edge fleets: receiving uncompressed FP32 checkpoints from hundreds of mobile devices consumes gigabits of bandwidth and triggers severe client timeout drops (>5 minutes per round). Naive 4-bit compression destroys model attention layers (Layer 5 collapses to 0.6990).

The FractalCore Achievement:

  • 7.11x Ingress Bandwidth Relief: Compresses model broadcast and client upload payloads by 85.9%, dropping round latency from 321.2s to 46.2s at 10 Mbps.
  • Zero Accuracy Degradation: 64-element micro-block quantization isolates outliers, sustaining 0.9878 mean cosine similarity and guaranteeing stable FedAvg/FedProx convergence.
  • Automated Model Slicing: ATen graph compiler slices multi-billion parameter models into memory-safe ExecuTorch .pte sub-graphs sized dynamically to client RAM budgets.

FractalCore serves as the centralized orchestration backbone that coordinates decentralized edge nodes (FractalAndroid). It handles the end-to-end lifecycle of distributed machine learning tasks, executing two primary operations:

  1. Federated Learning Orchestration: Multi-tenant data binning, task scheduling, client checkpoint verification, and deterministic parameter aggregation via Federated Averaging (FedAvg).
  2. Foundation Model Slicing: Offline neural graph surgery, INT4 weight quantization, static ATen graph tracing, and XNNPACK lowering (inference-model-maker/slicer) to produce memory-safe .pte layer partitions for mobile nodes.

Empirical Benchmarks & Performance Evaluation

FractalCore model slicer and parameter aggregation engine are benchmarked across 253,755,392 real transformer parameters from TinyLlama-1.1B (22 layers, 2048 hidden dimension, 5632 intermediate dimension) and MobileNetV3. All metrics are calculated directly from matrix quantization operations and physical network transmission models.

Executive Performance Summary

Metric Dimension Uncompressed Baseline (FP32) Half-Precision (FP16) Standard Uniform INT8 (QSGD) Global Tensor INT4 FRACTAL Micro-Block INT4 Empirical Impact
TinyLlama Wire Payload 4,196 MB 2,098 MB 1,049 MB 524 MB 590 MB 7.1x wire payload reduction
Reconstruction Fidelity 1.0000 >0.9999 0.9924 0.8296 (Fails) 0.9878 Zero divergence across 22 layers
Mean Squared Error (MSE) 0.000000 <0.000001 0.000018 0.000433 0.000043 10x lower error vs Global INT4
10 Mbps Uplink Latency (100M) 321.2 s 161.2 s 81.2 s 41.2 s 46.2 s 86% reduction in radio duty cycle
Training Viability Lossless (Stable) Lossless (Stable) High Fidelity (Stable) Catastrophic Divergence Pareto Optimal (Stable) Enables true 4-bit edge convergence

Parameter Payload & Round Latency Benchmark

Method / Framework Target Representation TinyLlama-1.1B Payload Wire Reduction Ratio Mean Layer Cosine Sim 10 Mbps Uplink Latency Physical Hardware Impact Edge Index (EOI) Training Viability
FRACTAL (Micro-Block INT4) Packed Int4 + Scale 590 MB 7.1x 0.9878 46.2 s mmap streaming (Zero LMK) 92 / 100 PARETO OPTIMAL (Stable)
Flower (QSGD INT8) Uniform Int8 1,049 MB 4.0x 0.9924 81.2 s Standard Python/JVM heap 71 / 100 High Fidelity (Stable)
NVIDIA FLARE (Enterprise) Float16 (16-bit) 2,098 MB 2.0x >0.9999 161.2 s High Ingress Saturation 65 / 100 Lossless (Stable)
FedML (HeteroFL Slicing) Dynamic FP16 ~1,500 MB 2.8x 0.9650 ~110.0 s Sub-graph slicing overhead 61 / 100 Moderate Fidelity
PySyft (OpenMined INT8) Int8 Encrypted 1,049 MB 4.0x 0.9900 81.2 s Cryptographic CPU drain 56 / 100 Secure Aggregation (Stable)
TensorFlow Federated (TFF) Float32 Baseline 4,196 MB 1.0x 1.0000 321.2 s Frequent Mobile LMK Eviction 48 / 100 Severe Edge Stragglers
PyTorch RPC (Uncompressed) Float32 Baseline 4,196 MB 1.0x 1.0000 321.2 s Thermal Throttling (>42°C) 44 / 100 Raw Socket (Unsafe Edge)
Global Tensor INT4 Standard Int4 524 MB 8.0x 0.8296 41.2 s Low wire, zero convergence 21 / 100 FAILS: Severe Divergence

Critical Note on Global INT4 vs FRACTAL: While Global INT4 appears 5 seconds faster on paper (41.2s vs 46.2s), it is completely unviable in practice. Single attention outliers inflate the global scale factor, forcing 99.9% of normal weights into zero bins and causing model output to collapse (cosine similarity dropping to 0.699 in deeper layers). FRACTAL pays a negligible 5-second scale overhead to rescue fidelity from 0.8296 back to 0.9878, making 4-bit edge training actually converge.


Empirical Visualizations & In-Depth Technical Analysis

Figure 1: Distributed Parameter Wire Payload Across Foundation Model Scales

Distributed Parameter Wire Payload vs Precision Format

Figure 4: The Distributed Compute & Quantization Frontier (Pareto Optimality Map)

The Distributed Compute and Quantization Frontier Pareto Optimality Map

Figure 5: Distributed Edge Efficiency Index (Artificial Analysis Style Frontier Ranking)

Distributed Edge Efficiency Index Leaderboard

Figure 2: Layer-Wise Numerical Fidelity and Transformer Outlier Collapse

Layer-Wise Reconstruction Fidelity Across Transformer Depth

Edge Round Parameter Synchronization Latency vs Uplink Bandwidth

Reproducing the Benchmarks

# Reproduce benchmarks and generate figures
python scripts/benchmark_evaluation.py

Mathematical Formulation: Outlier Isolation via Micro-Block Dynamic Scaling (MB-DS)

In transformer architectures, linear projections across multi-head self-attention and feed-forward networks (FFN) govern the primary parameter volume: $$W_q, W_k, W_v, W_o \in \mathbb{R}^{d_{\text{model}} \times d_{\text{model}}}, \quad W_{\text{gate}}, W_{\text{up}} \in \mathbb{R}^{d_{\text{ffn}} \times d_{\text{model}}}, \quad W_{\text{down}} \in \mathbb{R}^{d_{\text{model}} \times d_{\text{ffn}}}$$ During model training and adaptation, these matrices exhibit emergent heavy-tailed feature outliers where a minute fraction of parameters (less than 0.1%) reach magnitudes exceeding ten times the layer standard deviation ($|w| > 10\sigma_W$).

1. Outlier Collapse in Global Uniform Quantization

Standard uniform 4-bit quantization computes a single global scale across the entire weight tensor $W \in \mathbb{R}^{M \times N}$: $$\gamma_{\text{global}} = \frac{\max_{w \in W} |w|}{7.0}$$ When an extreme outlier satisfies $|w^*| \ge 10\sigma_W$, the global divisor becomes $\gamma_{\text{global}} \ge 1.43\sigma_W$. For normal in-distribution parameters satisfying $|w_i| \le 0.5\sigma_W$, the normalized quotient falls below the quantization threshold: $$\left| \frac{w_i}{\gamma_{\text{global}}} \right| \le \frac{0.5\sigma_W}{1.43\sigma_W} \approx 0.35 < 0.50$$ The nearest-integer rounding operator maps these parameters directly to zero: $$q_i = \text{clamp}\left( \left\lfloor \frac{w_i}{\gamma_{\text{global}}} \right\rceil, -8, 7 \right) = 0$$ This dynamic range collapse decimates $99.9%$ of active weight trajectories. Layer cosine similarity craters to 0.8296 overall (and 0.6990 in deeper self-attention projections), destroying gradient directionality and inducing catastrophic divergence during federated weight averaging.

2. The FRACTAL Micro-Block Solution and Spatial Error Confinement

FractalCore slicer and parameter aggregation engine partition flattened parameter arrays into micro-blocks of $B_k \in \mathbb{R}^{64}$: $$\gamma_k = \frac{\max_{w \in B_k} |w|}{7.0}$$ $$q_i = \text{clamp}\left( \left\lfloor \frac{w_i}{\gamma_k} \right\rceil, -8, 7 \right), \quad \forall w_i \in B_k$$ Pairs of signed 4-bit values $q_{2j}$ and $q_{2j+1}$ are bit-packed into single uint8 bytes: $$\text{packed}j = (q{2j} \ & \ \text{0x0F}) \ | \ ((q_{2j+1} \ & \ \text{0x0F}) \ll 4)$$


Industry & Community Recognition

The architectural breakthroughs, hardware telemetry gating, and sub-byte parameter quantization methods introduced in FractalCore have garnered significant independent analysis from systems engineering communities and edge artificial intelligence researchers.

Technical Analysis Series (CSDN GitBlog)

A multi-part architectural deep dive published on CSDN GitBlog examines FractalCore's low-level systems implementation across edge orchestration, memory management, and model graph compilation:

  1. System Architecture & Distributed Workspace Topology: Architectural evaluation of Fractal's decoupled repository structure, master-worker control plane separation, and distributed coordination between server infrastructure and edge Android runtimes.
  2. Hardware-Telemetry Protection Gating & Battery Preservation: Systems analysis of consumer device protection policies, including 80% battery capacity gating, sub-40°C thermal cutoffs, and unmetered network policies designed to prevent device wear.
  3. Model Compilation & ATen Graph Slicing into Memory-Safe PTE: Deep dive into the inference-model-maker/slicer toolchain, covering ATen static tracing, XNNPACK backend lowering, and dynamic .pte sub-graph generation tailored for edge memory limits.
  4. Zero-Copy Memory-Mapped Execution (mmap) & Android LMK Protection: Examination of native memory mapping techniques that eliminate process termination triggered by the Android Low Memory Killer (LMK), enabling multi-billion parameter partition execution on consumer hardware.
  5. Control Plane Security, Stateless Token Ingress, and REST API: Comprehensive review of FractalCore's stateless X-Auth-Token ingress gateway, filesystem-level tenant data isolation, and single-use task dispatch replay protection.
  6. Decentralized Scheduling & Deterministic Parameter Aggregation: Mathematical and architectural audit of master-worker task queues, client checkpoint validation mechanisms, and deterministic Federated Averaging (FedAvg) synchronization.

Media & Community Features


Control Plane Web Interface

FractalCore provides a hardware-accelerated, high-density Web UI engineered for orchestrating federated learning tasks, monitoring compute budgets, and isolating tenant silos:

Tenant Operations Dashboard
Tenant Dashboard

Real-Time Tenant Dashboard: Live TFLOPs quota gauge, dynamic round progress, active mobile node telemetry, and streaming activity log.

Admin Fleet Console Node Authentication Portal
Admin Console

Admin Console: Tenant creation, TFLOPs computation caps, MB reward rates, and multi-tenant fleet roster.

Login Portal

Authentication Gate: Tab-isolated per-session tokenized access control with Genos typography.


System Architecture

FractalCore decouples tenant session control from compute dispatching and storage silos:

graph TD
    subgraph ClientFleet ["Edge Client Fleet (FractalAndroid)"]
        Node1["Android Node 1"]
        Node2["Android Node 2"]
        NodeN["Android Node N"]
    end

    subgraph FractalCoreServer ["FractalCore Control Plane"]
        API["REST Gateway & Route Handlers"]
        AuthModule["X-Auth-Token Session Manager"]
        TenantMgr["Multi-Tenant Isolation Manager"]
        TaskScheduler["Task Queue & Segment Dispatcher"]
        AggEngine["Federated Averaging Engine (FedAvg)"]
        SlicerPipeline["Model Slicer & INT4 Quantizer"]
        RewardService["Liquid MB Reward Processor"]
    end

    subgraph StorageLayer ["Persistence & State"]
        FirestoreDB[("Firestore (Tenants / Devices / Ledger)")]
        DiskStorage[("Local Silos (tenants/username/bins, uploads, models)")]
    end

    %% Client Connections
    Node1 & Node2 & NodeN <-->|"REST HTTPS (X-Auth-Token / Task / Checkpoint)"| API

    %% Internal Wiring
    API --> AuthModule
    AuthModule --> TenantMgr
    TenantMgr --> TaskScheduler
    TaskScheduler --> DiskStorage
    TaskScheduler --> AggEngine
    AggEngine --> DiskStorage
    SlicerPipeline --> DiskStorage
    RewardService --> FirestoreDB
    API --> RewardService

Core Components

1. Multi-Tenant Orchestrator (src/fractal_server/server.py)

2. Federated Aggregation Engine

3. Model Slicing Compiler (src/inference-model-maker/slicer/)


Data Flow and Lifecycle

sequenceDiagram
    autonumber
    actor Admin as Tenant / Admin
    participant Server as FractalCore API
    participant Aggregator as FedAvg Engine
    participant Android as FractalAndroid Node
    participant Firestore as Firestore Ledger

    Admin->>Server: POST /api/admin/login (Credentials)
    Server-->>Admin: X-Auth-Token
    Admin->>Server: POST /api/admin/tenants (Create Tenant + Set TFLOP Quota)
    Admin->>Server: POST /api/tenant/init-data (Upload Dataset & Target Model)

    loop Model Training Iteration
        Android->>Server: GET /api/task/current (Header: X-Auth-Token)
        Server-->>Android: ActiveTask (Model Slices + Assigned Bins)
        Note over Android: Execute Local Gradient Descent on Device
        Android->>Server: POST /api/model/upload (Checkpoint Delta .ckpt)
        Server->>Aggregator: Register Checkpoint Delta
        Server->>Firestore: Increment Liquid MBs for Device ID
        opt Round Threshold Reached
            Aggregator->>Aggregator: Compute Parameter Summation (FedAvg)
            Aggregator->>Server: Deploy New Model Checkpoint
        end
    end

API Reference Summary

All administrative and client communications occur over standard REST endpoints. Secured routes strictly require X-Auth-Token authentication:

Endpoint Method Access Level Description
/api/admin/login POST Public Authenticates administrator and yields scoped session token.
/api/admin/tenants GET Admin Lists active tenant silos, quotas, and node activity.
/api/admin/tenants POST Admin Provisions a new isolated tenant namespace with allocated compute quotas.
/api/task/current GET Node Fetches assigned computation task descriptor and target model parameters.
/api/model/upload POST Node Ingests client checkpoint delta payload (.ckpt) for federated aggregation.
/api/node/register POST Node Enrolls device hardware configuration and initial telemetry baseline.

Directory Structure

FractalCore/
|-- Dockerfile                     # Production container build specification
|-- docker-compose.yml             # Local multi-service orchestrator
|-- requirements.txt               # Pinned Python package dependencies
|-- .env.example                   # Environment configuration template
|-- scripts/                       # Verification scripts & synthetic benchmarks
|   `-- benchmark_evaluation.py    # Empirical benchmark suite & chart generator
|-- src/
|   |-- fractal_server/            # Control Plane Server & API Routes
|   |   |-- server.py              # Main Flask application & endpoint handlers
|   |   |-- templates/             # Server-rendered administrative and tenant dashboards
|   |   `-- static/                # CSS styling, asset libraries, and telemetry scripts
|   `-- inference-model-maker/     # Model Compilation & Graph Slicer
|       |-- run.py                 # CLI entry point for graph partitioning
|       `-- slicer/                # Core slicing, INT4 quantization, and export pipeline
`-- docs/                          # Architecture diagrams, benchmark reports, and schemas

Deployment and Execution

Docker Deployment (Production Standard)

# 1. Configure Environment Variables
cp .env.example .env

# 2. Build and Launch Container
docker-compose up --build -d

# 3. Stream Container Logs
docker-compose logs -f

Manual Host Execution

# 1. Create Virtual Environment
python3 -m venv venv
source venv/bin/activate

# 2. Install Dependencies
pip install -r requirements.txt

# 3. Launch with Gunicorn WSGI
gunicorn --bind 0.0.0.0:5000 src.fractal_server.server:app

Code Formatting & Quality Verification

All Python source files must adhere to black formatting and flake8 standards:

# Format Python source files
black .

# Check formatting compliance
black --check .

# Lint source files
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics

Security Model

For full vulnerability reporting procedures, refer to SECURITY.md.


Theoretical Foundations & References

FractalCore aggregation engine, model graph slicing pipeline, and multi-tenant task scheduler are grounded in landmark research across federated optimization and distributed model execution:

Federated Aggregation & Optimization

Adaptive Edge Resource Allocation

Sub-Byte Quantization & Efficient Parameter Packing

Distributed Systems & Scalable FL Engines


Governance, Entity Ownership & Licensing

FractalCore is source-available research and systems software owned exclusively by Fractal Compute Orchestrations and governed by the FRACTAL Proprietary Source-Available & Non-Commercial Restrictive License v3.1 (see NOTICE and CITATION.cff).

For commercial licensing or institutional partnerships, contact Fractal Compute Orchestrations ([email protected]).


FractalCore is engineered and governed by Fractal Compute Orchestrations.

FractalCore (Fractal-Compute-Orchestrations/FractalCore)

Ищем в базе…

Что это?FractalCore — центральный серверный оркестратор децентрализованной вычислительной экосистемы Fractal. Он координирует задачи федеративного обучения на периферийных узлах Android, управляет бюджетами TFLOPs для нескольких арендаторов и выполняет агрегацию весов FedAvg для создания глобальной модели.
Это приложение, которое я устанавливаю, или сервер, который я запускаю сам?Это серверная часть на Python/Flask, которую вы развёртываете самостоятельно, с веб-панелью администратора и панелью арендатора; это не настольное и не мобильное приложение. Вы запускаете её как сервер, с которым мобильные периферийные узлы общаются через API.
Как запустить сервер?В README описано развёртывание через Docker как стандарт для продакшена; в качестве альтернативы можно запустить сервер Flask напрямую на хосте вручную.
Какой стек использует сервер?Он построен на Python/Flask, использует TensorFlow и NumPy для агрегации FedAvg, torchao/ExecuTorch/XNNPACK для нарезки моделей и Google Cloud Firestore для учёта наград.
Можно ли использовать это в коммерческих целях?Нет. Исходный код доступен для просмотра, но это проприетарное ПО, а лицензия прямо запрещает коммерческое использование без письменного разрешения автора.
Какими устройствами он управляет?Он управляет периферийными узлами Android (из сопутствующего проекта FractalAndroid), которые обучаются локально и загружают контрольные точки, а этот репозиторий — центральный координатор, которому они отчитываются.
Видит ли сервер или сохраняет ли он мои необработанные данные для обучения?Нет. Модель безопасности заявляет нулевой входящий поток данных: необработанные данные пользователя никогда не покидают периферийное устройство, на сервер попадают только контрольные точки и агрегированные веса.
Что на самом деле делает агрегация FedAvg?Она проверяет загруженные контрольные точки клиентов по реестру активных задач и детерминированно усредняет их веса, как только раунд обучения достигает порога; в результате получается следующая контрольная точка глобальной модели.
Для чего нужен модуль нарезки моделей?Он принимает полные модели с Hugging Face, например Llama 3 8B или TinyLlama, применяет квантование INT4 и статическую трассировку графа ATen, а затем с помощью XNNPACK преобразует их в небольшие разделы .pte, которые мобильные узлы могут отобразить в память через mmap, не превышая отведённый им объём памяти.
Что такое Liquid MB?Это токены вознаграждения, которые зачисляются в профиль арендатора в Firestore после того, как телеметрия оборудования мобильного узла и контрольная точка подтверждены как реальный вклад вычислительной мощности.
Как не дать арендаторам видеть данные друг друга?Каждый арендатор получает физически отдельный путь хранения на диске и должен проходить аутентификацию с помощью заголовка X-Auth-Token для каждой сессии, поэтому общих состояний куки и доступа к файловой системе между арендаторами нет.
Размер
72.1 MB
Звёзды
5K
Возраст
6 мес
Коммиты · 90 дней