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 聚合究竟做了什么?一旦某轮训练达到阈值,它会根据当前活动的任务注册表验证客户端上传的检查点,然后对它们的权重进行确定性平均,生成下一个全局模型检查点。
模型切片器有什么用?它会读取 Llama 3 8B 或 TinyLlama 等完整的 Hugging Face 模型,应用 INT4 量化和静态 ATen 计算图追踪,然后通过 XNNPACK 将其降级为小型 .pte 分片,使移动节点能够以内存映射方式加载,而不会超出其内存预算。
Liquid MB 是什么?它们是奖励代币,在移动节点的硬件遥测数据和检查点被验证为真实的贡献算力之后,会被记入租户的 Firestore 账户。
如何防止不同租户之间查看彼此的数据?每个租户在磁盘上都有物理隔离的存储路径,并且必须通过每个会话专属的 X-Auth-Token 请求头进行身份验证,因此不存在共享的 Cookie 状态,也不存在跨租户的文件系统访问。
大小
72.1 MB
星标
5K
时长
6个月
提交 · 90 天