项目的 README,来自 github.com/Fractal-Compute-Orchestrations/FractalWorkspace。合并为一个 markdown 文件:README.md。

A unified distributed systems framework bridging centralized model orchestration with decentralized edge intelligence.
Overview | Key Results & Benchmarks | Industry & Community Recognition | Subsystems | Architecture | Operational Paradigms | Global Contracts | Academic Foundations | Getting Started
The Problem: Foundation models (TinyLlama, Llama-3, Mistral) cannot participate in decentralized edge federated learning because consumer mobile devices face three compounding physical bottlenecks:
- The Uplink Bottleneck: Transmitting uncompressed model checkpoints (4.2 GB to 30.5 GB) over consumer Wi-Fi/LTE (5 to 10 Mbps) requires 5 to 10 minutes per client, triggering aggregator timeouts (120s cutoff) and dropping edge nodes.
- The Dynamic Range Collapse: Standard 4-bit quantization breaks modern attention projections; emergent outliers inflate global scales, squashing 99.9% of normal weights into zero bins, collapsing Layer 5 cosine fidelity to 0.6990, and inducing catastrophic training divergence.
- The Mobile Memory Wall (LMK): Checkpoint loading exceeds mobile RAM limits, triggering immediate Android Low Memory Killer (LMK) process evictions and battery overheating.
The FRACTAL Achievement: FRACTAL breaks all three physical walls through hardware-aligned algorithmic co-design:
- 7.11x Wire Payload Reduction (85.94% Wire Cut): Parameter payload drops from 4,196 MB down to 590 MB for TinyLlama-1.1B, and from 30.5 GB down to 4.29 GB for Llama-3 8B.
- Sub-60s Transmission Guarantee: Slashes 10 Mbps upload duration from 321.2 seconds down to 46.2 seconds, beating the 120s federated aggregation deadline by 73.8 seconds.
- Zero Accuracy Collapse (0.9878 Fidelity Preserved): Micro-block dynamic scaling (64-element tiles) confines attention projection outliers locally, sustaining 0.9878 mean cosine similarity and 4.3e-5 MSE across all 22 layers, matching lossless 16-bit convergence.
- Zero Mobile LMK Crashes: Native memory-mapped execution (mmap) and an 85.6% reduction in radio transmission time keep mobile nodes thermally cool and crash-free.
Fractal is a high-performance distributed computing ecosystem engineered to harvest fragmented consumer compute across mobile edge devices while strictly preserving user privacy and device health. The framework treats edge devices not merely as remote processors, but as autonomous, resource-constrained nodes operating under human-centric constraints.
Centralized foundation model training and inference face compounding physical and financial bottlenecks:
Fractal resolves these compounding bottlenecks through two unified, production subsystems:
To rigorously evaluate FRACTAL under real-world distributed constraints, we benchmarked our block-wise dynamic INT4 quantization and partitioned model execution pipeline across 253,755,392 float32 parameters from TinyLlama-1.1B (22 layers, 2048 hidden dimension, 5632 intermediate dimension) and MobileNetV3. All metrics are directly calculated from matrix tensor operations and physical network transport models.
| 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 |
| 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.
The empirical evaluation of FRACTAL measures physical transmission payloads, numerical reconstruction fidelity, and wireless uplink synchronization latencies using real matrix parameters extracted from TinyLlama-1.1B and MobileNetV3.
The complete benchmark suite executes directly on CPU using real matrix tensors and requires no external GPU clusters:
# Run matrix evaluation and regenerate all publication figures
python scripts/benchmark_evaluation.py
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$).
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.
FRACTAL eliminates global dynamic range collapse by partitioning 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)$$
The architectural breakthroughs, hardware telemetry gating, and sub-byte parameter quantization methods introduced in Fractal have garnered significant independent analysis from systems engineering communities and edge artificial intelligence researchers.
A multi-part architectural deep dive published on CSDN GitBlog examines Fractal's low-level systems implementation across edge orchestration, memory management, and model graph compilation:
inference-model-maker/slicer toolchain, covering ATen static tracing, XNNPACK backend lowering, and dynamic .pte sub-graph generation tailored for edge memory limits.X-Auth-Token ingress gateway, filesystem-level tenant data isolation, and single-use task dispatch replay protection.| Central Server (FractalCore) | Edge Compute Node (FractalAndroid) |
|---|---|
Multi-Tenant Dashboard: Real-time fleet tracking, segment dispatch, and live aggregation telemetry. |
Edge Node: On-device training & telemetry. |
Fractal operates on a hierarchical Master-Worker architecture designed to isolate control signals from mathematical payloads.
graph TD
subgraph ControlPlane ["Control Plane (FractalCore Server)"]
direction TB
API["REST Gateway & Auth Controller"]
TM["Tenant Isolation Manager"]
TS["Task Scheduler & Segment Dispatcher"]
FA["Federated Weight Aggregator (FedAvg)"]
Slicer["Graph Slicer & INT4 Quantizer"]
Budget["TFLOPs Budget Controller"]
end
subgraph DataPlane ["Data Plane (FractalAndroid Edge Nodes)"]
direction TB
N1["Android Node A (Layers 0-7 / Worker)"]
N2["Android Node B (Layers 8-15 / Worker)"]
N3["Android Node C (Layers 16-23 / Worker)"]
N4["Android Node D (Layers 24-31 / Worker)"]
end
subgraph PersistenceLayer ["Persistence & Ledger"]
FS[("Firestore Ledger (Tokens / Rewards / Nodes)")]
Disk[("Physical Data Silos (Bins / Checkpoints / PTE Slices)")]
end
%% Control Plane Internal Flow
API --> TM
TM --> TS
TS --> Budget
FA --> Disk
Slicer --> Disk
API --> FS
%% Network Interactions
N1 & N2 & N3 & N4 <-->|"REST API / TLS (Task Polling & Weight Uploads)"| API
N1 -->|"INT8 Activation Stream (Wi-Fi Socket)"| N2
N2 -->|"INT8 Activation Stream (Wi-Fi Socket)"| N3
N3 -->|"INT8 Activation Stream (Wi-Fi Socket)"| N4
Fractal executes distributed machine learning through two foundational paradigms:
In the federated learning lifecycle, raw training datasets are never transferred to the central server. The server partitions data indices into segment bins, dispatches task descriptors to registered Android nodes, and waits for computed checkpoint deltas (.ckpt).
sequenceDiagram
participant Tenant as Tenant / Administrator
participant Server as FractalCore Server
participant Node as FractalAndroid Node
participant Firestore as Firestore Registry
Tenant->>Server: Initialize Session (Dataset + TFLOP Budget)
Server->>Server: Partition Dataset into Binary Segment Bins
Note over Server: Queue Tasks in Tenant Silo
Node->>Server: GET /api/task/current (Hardware Telemetry Proof)
Server-->>Node: ActiveTask (Model URL + Data Bin URL + Hyperparams)
Node->>Node: Evaluate Telemetry Permit (Battery >= 50%, Thermals <= 40C)
Node->>Server: Download Model Weights (.tflite) + Binary Bins
Node->>Node: Execute Local Gradient Descent (TFLite Engine)
Node->>Server: POST /api/model/upload (Checkpoint Delta .ckpt)
Server->>Firestore: Credit Liquid MBs to Node Device ID
Server->>Server: Federated Averaging (FedAvg Summation)
Server->>Server: Increment Global Model Round
To execute foundation models (such as Llama 3 8B or TinyLlama) across edge devices without triggering the Android Low Memory Killer (LMK), Fractal Core slices the monolithic model into memory-bounded partitions (layer_[N].pte <= 150MB). Each Android node memory-maps (mmap) an assigned partition and transmits quantized activation tensors across an ad-hoc local mesh.
flowchart LR
subgraph CoreSlicer ["FractalCore Compiler"]
M16["Monolithic 16GB FP16 Checkpoint"] --> Ingest["Ingestion & Block Isolation"]
Ingest --> Quant["INT4 Weight Quantization (torchao)"]
Quant --> Trace["ATen Dialect Graph Trace (torch.export)"]
Trace --> Lower["XNNPACK Hardware Delegation"]
Lower --> Out["32x Mapped Partitions (layer_N.pte <= 150MB)"]
end
subgraph EdgeMesh ["Android Compute Mesh"]
Out -.->|"Deploy Layer Partition"| NodeA["Node A (Input / Layer 0-7)"]
NodeA -->|"INT8 Activations (<= 4.1KB)"| NodeB["Node B (Layer 8-15)"]
NodeB -->|"INT8 Activations (<= 4.1KB)"| NodeC["Node C (Layer 16-23)"]
NodeC -->|"INT8 Activations (<= 4.1KB)"| NodeD["Node D (Output / Layer 24-31)"]
end
The ecosystem maintains strict operational boundaries governed by mathematical contracts:
| Contract | Target Subsystem | Strict Specification | Failure Behavior |
|---|---|---|---|
| Weight Contract | Model Slicing & Storage | Binary partition (.pte / .tflite) strictly $\le$ 150MB |
Slicer compilation rejected |
| Activation Contract | Pipeline Inter-Node Network | 4096-dim INT8 tensor + 1 Float scale strictly $\le$ 4,100 bytes | Network frame dropped and re-requested |
| Telemetry Permit | On-Device Execution Gate | Battery $\ge$ 50%, Charging == True, Battery Temp $\le$ 40.0 C | Training paused immediately |
| Authentication Contract | REST Ingress Gateway | X-Auth-Token required for all tenant and administrative routes |
HTTP 401 / 403 response |
| Upload Validation | Federated Aggregation Gate | task_Id must match an active unconsumed dispatch record |
HTTP 400 Unknown task_Id |
Fractal builds upon foundational research in distributed systems, federated learning, and resource-constrained edge computing. Key works that inform our architectural design include:
The Fractal ecosystem is partitioned across dedicated modular repositories:
.
|-- FractalApp/
| `-- FractalAndroid/ # Client Application & Compute Node (Kotlin)
| |-- app/src/main/java/ # Native MVVM Architecture
| | |-- AppBackend/ # Telemetry, TFLite Engine, Checkpointing, DAOs
| | `-- AppFrontend/ # Telemetry Dashboard, Insights & Settings
| |-- build.gradle.kts # Android Build Configuration (Kotlin DSL)
| `-- docs/ # Architecture diagrams and specifications
|
|-- FractalCore/ # Server & Control Plane (Python)
| |-- src/
| | |-- fractal_server/ # Multi-Tenant Flask API & Federated Aggregator
| | `-- inference-model-maker/ # Slicer Compiler & Model Partitioning Pipeline
| |-- scripts/ # Operational Sweepers, Testers & Reward Audits
| |-- docs/ # API schemas, deployment, and security specs
| |-- Dockerfile # Production Container Definition
| `-- docker-compose.yml # Multi-Container Orchestration Stack
|
|-- docs/ # Unified Project Whitepapers & Reports
`-- private.envs/ # Private Environment Configurations & Service Keys
To initialize the entire workspace including all submodule repositories:
git clone --recursive https://github.com/Fractal-Compute-Orchestrations/FractalWorkspace.git
If the repository was cloned without --recursive, initialize submodules manually:
git submodule update --init --recursive
# Install the standalone quantization and federated aggregation SDK
pip install -e ./FractalCore
# Verify codec compression fidelity, CLI telemetry, and FedAvg/Krum round
fractal doctor
fractal bench --layers 4 --hidden-size 256
python FractalCore/scripts/quickstart_demo.py
# Run coordinator test suite
pytest FractalCore/tests -v
cd FractalApp/FractalAndroid
# Run JVM unit tests (FRQ4/FRQD cross-language wire check, thermal gating, storage safety)
./gradlew testDebugUnitTest
# Build Debug APK
./gradlew assembleDebug
# Install on connected physical device
./gradlew installDebug
.frqd wire bundles are transmitted.X-Auth-Token or Authorization: Bearer request header. Tokens are cryptographically generated (secrets.token_hex(32)) and validated consistently via constant-time comparison._safe_join on Python and FractalPaths on Android). Each tenant's datasets, bins, and intermediate checkpoints are sandboxed in isolated directory trees (data/tenants/{username}/).task_Id. Stale or duplicate uploads are rejected at the ingress gate.FRACTAL is engineered, maintained, and owned by Fractal Compute Orchestrations.