FractalAndroid README

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

FractalAndroid Header

FractalAndroid

Resource-Aware Edge Compute Node and Mobile Execution Engine

Kotlin Version Android API Design Architecture License Android CI

FractalAndroid is the distributed compute client and edge execution runtime for the Fractal decentralized intelligence framework.

Overview | Edge Benchmarks | Design Showcase | App UI Tour | WiFi Bank Rewards | Design Case Study | Architecture | Telemetry Gating | Lifecycle | Build & Setup | References


Overview

Executive Summary: Core Purpose & Bottom Line

The Problem: Running machine learning workloads on consumer smartphones traditionally causes rapid battery drain, thermal throttling (>42°C), user UI lag, and process termination by the Android Low Memory Killer (LMK).

The FractalAndroid Achievement:

  • Hardware-Gated Compute: Automatically pauses execution if SoC temperature exceeds 40°C, battery drops below 80%, or unmetered Wi-Fi is disconnected.
  • Zero LMK Evictions: Directly streams 4-bit partitioned .pte sub-graphs into unified LPDDR memory via mmap, avoiding JVM Garbage Collection overhead and keeping RAM usage well beneath device thresholds.
  • 85.6% Less RF Power: Slashes parameter upload time from 321.2s to 46.2s over 10 Mbps links, eliminating radio power amplifier heating and conserving device battery health.

FractalAndroid turns Android mobile devices into autonomous, privacy-preserving compute nodes within the Fractal distributed network. Operating in coordination with the central server (FractalCore), the application executes localized machine learning workloads, including on-device federated training (TFLite) and partitioned batch dataset training, without exposing user data or degrading host device performance.

The client is designed with strict resource empathy: the engine continuously monitors physical hardware telemetry (SoC temperature, battery level, charging status, RAM pressure) and dynamically gates computation to guarantee zero impact on user experience or battery longevity.


Mobile UI Design & Hardware Showcase

Active Node Telemetry Model Training Metrics Platform Architecture Dock Iconography
Active Compute Node
Live training telemetry & diamond meter
Model Training Metrics
Performance curves & parameter transfer
Platform Architecture
Decentralized cloud & studio identity
Dock Iconography
Light & dark adaptive icon variants

Mobile Application Interface

1. Onboarding, Device Authorization & Binding

Get Started Device Authorization Registered Info
Get Started: Platform onboarding introducing the decentralized compute harvesting paradigm. Device Authorization: Firebase auth & hardware ID binding (`ANDROID_ID`, CPU, RAM). Registered Info: Confirmed registration profile and assigned compute node telemetry.

2. Node Fleet States & Real-Time Compute

Home Inactive Home Active Node Settings
Home (Standby / Inactive): Idle state awaiting task assignment with live hardware monitors. Home (Active Compute): Active local training with pulsing fractal diamond indicator. Node Settings & Preferences: Autonomous telemetry thresholds and charging policies.

3. Telemetry, Analytics & Training Insights

Usage Insights Device Insights Model Training
Usage Insights: Time-series telemetry graphs for CPU, RAM, battery, and thermals. Device Insights: Detailed hardware profiling with one-tap memory optimization. Model Training: Live loss convergence curves, parameter transfer rates, and epoch progress.

WiFi Bank & Bandwidth Rewards

Fractal transforms idle consumer mobile hardware into active decentralized compute infrastructure through a fair, transparent reward exchange:

Internet Bank 0 GB Internet Bank 0.5 GB Internet Bank 0.7 GB Internet Bank 1.0 GB Internet Bank 1.5 GB Internet Bank 1.8 GB Internet Bank 2.0 GB
0.0 GB
Initial / Empty
0.5 GB
Wave Rising
0.7 GB
Accumulating
1.0 GB
50% Capacity
1.5 GB
75% Capacity
1.8 GB
90% Capacity
2.0 GB
Full Balance

System Architecture

The client application follows a decoupled Model-View-ViewModel (MVVM) architecture with strict separation between UI telemetry rendering, hardware gating controllers, execution runtimes, and network synchronization layers.

graph TD
    subgraph CentralServer ["FractalCore Control Plane"]
        TaskDistributor["Task & Segment Dispatcher"]
        ModelAggregator["Federated Model Aggregator"]
    end

    subgraph FractalAndroidClient ["FractalAndroid Compute Node"]
        direction TB

        subgraph PresentationLayer ["Presentation Layer (MVVM)"]
            UI["Dashboard, Insights & Telemetry UI"]
            VM["Telemetry & Task ViewModels"]
        end

        subgraph GatingLayer ["Hardware Governance"]
            OperationControl["OperationControl (Thermal & SoC Gating)"]
            TelemetrySensors["Battery, Thermal & Network Monitors"]
        end

        subgraph ExecutionLayer ["Compute Execution Engine"]
            ImageTrainer["Image_Trainer (TFLite Engine)"]
            DataManager["DataManager (ByteBuffer Batch Loader)"]
            CheckpointMgr["CheckpointManager (.ckpt Serialization)"]
        end

        subgraph NetworkLayer ["Data & Transport Tier"]
            ServerDAO["Server_DAO (Task Poller)"]
            Transmitter["ModelTransmitter (TLS Weight Egress)"]
        end
    end

    %% Wiring
    TaskDistributor <-->|"REST HTTPS (/api/task/current)"| ServerDAO
    ServerDAO --> OperationControl
    OperationControl --> TelemetrySensors
    TelemetrySensors --> VM
    VM --> UI

    OperationControl -->|"Permit: GRANTED"| ImageTrainer
    ImageTrainer --> DataManager
    ImageTrainer --> CheckpointMgr
    CheckpointMgr --> Transmitter
    Transmitter -->|"POST /api/model/upload"| ModelAggregator

Edge Performance Benchmarks & Transmission Efficiency

FractalAndroid is engineered to run foundation model training and inference within the physical constraints of consumer mobile hardware. The client runtime enforces strict memory bounds, thermal limits, and communication efficiency:

On-Device Metric Benchmarks

Metric / Dimension Uncompressed Baseline (FP32) Standard Uniform INT8 (QSGD) Global Tensor INT4 FRACTAL Block-wise INT4 Edge Benefit
TinyLlama Wire Checkpoint 4,196 MB 1,049 MB 524 MB 590 MB 7.1x smaller payload
10 Mbps Sync Latency (100M) 321.2 s 81.2 s 41.2 s 46.2 s 86% reduction in radio active duty cycle
Model Weight Fidelity (Cosine Sim) 1.0000 0.9924 0.8296 (Fails) 0.9878 Full numerical convergence sustained
Model Slice Memory Bound >1,000 MB ~500 MB <150 MB <150 MB Zero Android LMK (Low Memory Killer) evictions
Activation Frame Overhead 16.4 KB 4.1 KB N/A <=4,100 bytes Fits single non-fragmented Wi-Fi packet

Hardware Co-Design & Edge Longevity Engineering


Hardware Telemetry Gating

The client enforces strict multi-variable gating via OperationControl before and during computation:

Telemetry Parameter Operational Threshold Action on Violation
Battery State-of-Charge Level $\ge$ 50% or Charging == True Workload paused until charging connected
Battery Temperature Temp $\le$ 40.0 C Execution paused until thermal normalization
Network Connectivity Unmetered Wi-Fi Connected Checkpoint upload deferred
Memory Pressure System Memory Low == False Batch buffer size throttled

Execution Lifecycle

The lifecycle of a single federated compute round on the mobile client proceeds through automated telemetry checks, training execution, and encrypted checkpoint transmission.

sequenceDiagram
    participant Server as FractalCore Server
    participant Net as Server_DAO / Transmitter
    participant Gate as OperationControl
    participant Engine as Image_Trainer
    participant Storage as CheckpointManager

    Note over Net,Engine: Standby & Periodic Task Polling
    Net->>Server: GET /api/task/current (device_id)
    Server-->>Net: ActiveTask Payload (URLs + Hyperparams)

    Net->>Gate: Request Execution Permit
    Gate->>Gate: Sample Battery SoC, Thermals & Charging
    alt Thermals > 40C or Battery < 50%
        Gate-->>Net: Permit DENIED (Backoff & Sleep)
    else Hardware Telemetry Healthy
        Gate-->>Net: Permit GRANTED
    end

    Net->>Server: Download Model (.tflite) + Binary Data Bins
    Net->>Engine: Initialize Weights & Segment Inputs

    loop Epoch Loop
        Engine->>Engine: Execute Local Gradient Descent Batch
        Gate->>Gate: Continuous Thermal Check
        alt Thermal Spike Detected
            Gate->>Engine: Signal PAUSE (Preserve State)
            Note over Engine: Wait for Thermal Normalization
            Gate->>Engine: Signal RESUME
        end
    end

    Engine->>Storage: Serialize Local Weight Checkpoint (.ckpt)
    Storage->>Net: Pass Parameter Deltas
    Net->>Server: POST /api/model/upload (task_Id, device_id, .ckpt)
    Server-->>Net: 200 OK (Liquid MB Reward Credited)

Module Breakdown

FractalAndroid/
|-- app/src/main/java/
|   |-- AppBackend/
|   |   |-- DataManager/             # Dataset binary segment parsing and caching
|   |   |-- LocalTrainingModule/     # TFLite Gradient Descent, Image_Trainer
|   |   |-- Network/                 # Server_DAO, ModelTransmitter (TLS HTTP)
|   |   |-- ResourceManagement/      # OperationControl, Battery & Thermal Telemetry
|   |   |-- TaskContainer/           # ActiveTask DTOs and JSON serialization
|   |   `-- Validator/               # Accuracy validation & inference assertions
|   |-- AppFrontend/
|   |   |-- Auth/                    # Node Registration & Binding UI
|   |   |-- Home/                    # Real-Time Compute & Training Dashboard
|   |   |-- Insights/                # Real-Time Telemetry & Hardware Charts
|   |   `-- Settings/                # Target Server URL & Threshold Configuration
|   `-- AppGlobal/                   # Cross-cutting Constants & Utility Helpers
|-- build.gradle.kts                 # Root Kotlin DSL Build Configuration
|-- app/build.gradle.kts             # Application Module Build Configuration
`-- docs/                            # Architecture Diagrams (.drawio) and Assets

Technical Pipeline Specifications

Pipeline Stage Java/Kotlin Implementation Responsibility
Ingress Server_DAO Polling task endpoints with exponential backoff and payload decoding.
Gating OperationControl Real-time multi-variable telemetry gating (Thermal, Battery, RAM).
Execution Image_Trainer On-device gradient calculation using optimized TFLite mobile kernels.
Data Parsing DataManager / FileOperations Loading binary dataset batches into direct ByteBuffer structures.
Persistence CheckpointManager Serialization of intermediate parameter matrices (.ckpt).
Egress ModelTransmitter Encrypted transmission of .ckpt parameter updates to FractalCore.

Development and Build

Prerequisites

Build Workflow

# 1. Clone the repository
git clone https://github.com/Fractal-Compute-Orchestrations/FractalAndroid.git
cd FractalAndroid

# 2. Run JVM Unit Tests (FRQ4/FRQD codec, thermal gating, path safety)
./gradlew testDebugUnitTest

# 3. Build Debug APK
./gradlew assembleDebug

# 4. Install and Run on Connected Device
./gradlew installDebug

Wire-Compatible INT4 Codec & Storage Hardening


Security & Privacy Guarantee


FractalAndroid hardware-aware execution model, on-device telemetry gating, and mobile parameter exchange draw from key literature in mobile edge computing and on-device machine learning:

Resource-Aware On-Device Execution

Wireless Communication & Parameter Compression


Governance & Licensing

FractalAndroid is maintained and owned by Fractal Compute Orchestrations.

FractalAndroid (Fractal-Compute-Orchestrations/FractalAndroid)

正在搜索数据库…

这是什么?FractalAndroid 是一个 Android 客户端,可以把手机变成一个保护隐私的边缘计算节点,用于 Fractal 分布式智能网络。它在设备端运行联邦学习(TFLite)训练,并与一个名为 FractalCore 的中央服务器协同工作。
这是独立应用,还是需要服务器?它是一个移动应用,但无法独立运行:它会轮询任务接口,并把加密的模型检查点上传到一个名为 FractalCore 的独立后端,而该后端不包含在本仓库中。
我该如何在手机上构建并运行它?用 Android Studio 2023.3.1(Jellyfish)或更新版本打开项目,设置 Compile SDK 34,然后在真实的 Android 设备上构建并运行,因为温度和传感器反馈需要真实硬件。
构建之前需要准备什么工具链?你需要 Android Studio 2023.3.1+、Compile SDK 34 和 Min SDK 24 的 Android SDK,以及 JDK 17(Gradle 8+ 推荐使用)。
它会耗光我的电池,或者一直在运行吗?不会。遥测门控系统(OperationControl)会在以下条件不满足时暂停训练:电池正在充电或电量高于 50%,电池温度不高于 40°C,设备连接的是不计流量的 Wi-Fi,并且内存压力较低。
我的本地数据(照片、传感器数据)会被上传到别处吗?不会。原始用户数据保留在设备上;只有数学意义上的模型参数检查点会通过 TLS 加密的 HTTPS 发送到服务器。
我可以将它用于商业用途或进行修改吗?不可以。它是专有软件,源代码可见但采用严格限制的非商业许可证,保留所有权利;未经书面授权,严格禁止商业用途。
这个应用实际上会在我的设备上训练什么?它使用优化过的 TFLite 移动端内核(通过 ImageTrainer 模块)在设备端进行梯度计算,训练数据是加载到 ByteBuffer 结构中的分批数据集,然后将得到的参数序列化为 .ckpt 文件。
客户端内部采用什么架构?它遵循 MVVM 模式,分为几个不同的层:ServerDAO 负责任务轮询,OperationControl 负责硬件门控,ImageTrainer 负责执行,CheckpointManager 负责持久化,ModelTransmitter 负责加密外发。
大小
15.6 MB
星标
4.9K
时长
11个月
提交 · 90 天