FractalWorkspace README

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

Fractal Banner

Fractal

Distributed Compute Orchestration and Edge Intelligence Framework

License Platform Design Status Architecture Maintainer

A unified distributed systems framework bridging centralized model orchestration with decentralized edge intelligence.

Overview | Design Case Study | Architecture | Core Paradigms | Repository Topology | Getting Started | Security


Fractal-Compute-Orchestrations%2FFractalWorkspace | Trendshift Fractal-Compute-Orchestrations%2FFractalWorkspace | Trendshift

Overview

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.

The ecosystem resolves the computational and memory walls of foundation models through two distinct, unified systems:

  1. FractalCore (Central Server & Orchestrator): The Python-based control plane responsible for multi-tenant isolation, dataset segment allocation, model graph compilation/slicing, deterministic federated weight aggregation (FedAvg), compute budgeting, and tokenized reward distribution.
  2. FractalAndroid (Edge Compute Node & Application): The native Kotlin/Android execution engine running on mobile hardware. It performs hardware-gated on-device training and memory-mapped inference, dynamically pausing workloads if thermals or battery thresholds are exceeded.

Ecosystem Subsystems

Central Server (FractalCore) Edge Compute Node (FractalAndroid)
Tenant Dashboard

Multi-Tenant Dashboard: Real-time fleet tracking, segment dispatch, and live aggregation telemetry.

Android Active Node

Edge Node: On-device training & telemetry.


System Architecture

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

Operational Paradigms

Fractal executes distributed machine learning through two foundational paradigms:

1. Federated Learning (On-Device Training)

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

2. Decentralized Pipeline Parallelism (Large Foundation Model Inference)

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

Global System Contracts

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

Repository Topology

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

Getting Started

Prerequisites

Cloning with Submodules

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

Initializing the Orchestrator (FractalCore)

cd FractalCore
cp .env.example .env

# Launch production server via Docker Compose
docker-compose up --build -d

# Verify server status
curl http://localhost:5000/api/admin/tenants

Initializing the Edge Client (FractalAndroid)

cd FractalApp/FractalAndroid

# Build project with Gradle
./gradlew assembleDebug

# Install on connected physical device
./gradlew installDebug

Security and Privacy


Governance & Licensing

Fractal is architected and owned by Ahmad Hassan (B-Ted).

FractalWorkspace (AhmadHassan-BTed/FractalWorkspace)

正在搜索数据库…

这是什么?Fractal 是一个面向联邦学习的分布式计算生态系统,它利用移动边缘设备上的闲置算力,同时将原始用户数据保留在设备本地。它将基于 Python 的中央协调器与原生 Android 客户端配对,客户端在本地训练模型,只回传权重检查点。
这是一个应用,还是客户端-服务器系统?它由两个相互关联的子系统组成,作为独立仓库发布,并通过 git 子模块引入:FractalCore 是运行在服务器上的 Python 控制平面,FractalAndroid 是一个 Kotlin/Android 应用,在手机上完成训练和推理。
我该如何让整个工作区运行起来?使用 --recursive 克隆仓库以拉取所有子模块(或之后运行 'git submodule update --init'),然后在服务器端初始化 FractalCore,并在 Android Studio 中单独构建 FractalAndroid。
试用之前,我需要安装哪些东西?FractalCore 需要 Python 3.10+;客户端需要 Android Studio 2023.3.1 (Jellyfish) 或更新版本;还需要一台支持 API 24+ 的实体 Android 设备(推荐 ARM64),以及一个已启用 Firestore 的 Firebase 项目。
应用一打开,训练就会自动运行吗?不会。边缘节点设有硬件限制:只有在设备充电、电量高于某个阈值且温度处于安全范围内时才会进行训练;若温度或电量超出安全范围,训练会立即暂停。
我的原始数据会离开我的手机吗?不会。服务器的设计是「零数据输入」,只传输经过编译的数学权重检查点,并且租户数据会进一步隔离在服务器上每个用户独立的沙盒目录树中。
我可以将它用于商业用途吗?不可以。Fractal 采用专有的、源码可见的许可证,明确禁止在未获得作者书面授权的情况下用于商业用途。
FedAvg 在这里起什么作用?FractalCore 使用 FedAvg 对边缘节点上传的权重增量检查点进行确定性聚合,生成更新后的全局模型,且全程无需接触背后的原始训练数据。
它能否跨手机运行 Llama 3 8B 这样的大模型?可以,通过去中心化流水线并行实现:FractalCore 将大型基础模型切分为每块不超过 150MB 的分区,每个 Android 节点以内存映射方式加载一个分区,并通过本地网状网络交换 INT8 量化的激活张量。
为什么要严格限制分区大小为 150MB?这样可以让每个内存映射的模型分片足够小,在手机上加载时不会触发 Android 的低内存终止机制(Low Memory Killer),否则该机制会终止推理进程。
服务器上不同租户的数据如何保持隔离?每个租户的数据集、分段存储桶和中间检查点都存放在物理上相互隔离的目录树(data/tenants/{username}/)中,而非共享存储。
大小
49.9 MB
星标
6K
更新
提交Nov 13
时长
4个月
提交 · 90 天