dvbits's picture
Update README.md
47a1b1c verified
|
Raw History Blame Contribute Delete
5.66 kB
---
title: Edge Deployment Resource Optimization
emoji: πŸ¦€
colorFrom: pink
colorTo: blue
sdk: docker
pinned: false
license: apache-2.0
short_description: Deploying production AI models to edge hardware.
tags:
- openenv
---
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
# EdgeResourceEnv: Edge Deployment Resource Management
## πŸ“– Description
The **EdgeResourceEnv** is a high-fidelity, real-world task simulation designed to evaluate AI agents acting as system resource governors on constrained edge devices.
**Motivation:**
Deploying production AI models to edge hardware (smartphones, IoT sensors) presents a unique engineering trade-off between inference accuracy and system stability. If an agent is too aggressive with resources, it drains the battery; if it is too passive, the device suffers from Out-of-Memory (OOM) crashes. This environment provides a safe, simulated environment to test these "Resource-Aware" strategies before they are shipped to physical hardware.
---
## πŸ“ Project Structure
```text
edge-deployment-env/
β”œβ”€β”€ server/
β”‚ └── app.py # Backend/API logic
β”œβ”€β”€ .dockerignore # Docker build exclusions
β”œβ”€β”€ Dockerfile # Containerization for HF Spaces execution
β”œβ”€β”€ env.py # Core environment, simulation, and grading logic
β”œβ”€β”€ inference.py # Mandatory baseline LLM agent script
β”œβ”€β”€ models.py # Pydantic schemas for Spec compliance
β”œβ”€β”€ openenv.yaml # Environment metadata and task definitions
β”œβ”€β”€ pyproject.toml # Build system and project metadata
β”œβ”€β”€ README.md # Documentation
β”œβ”€β”€ requirements.txt # Python dependencies
└── uv.lock # Exact dependency versions for reproducible builds
```
---
## πŸ›°οΈ Space Definitions
The environment interface is built using strictly typed Pydantic models to ensure full **OpenEnv spec compliance**. These models define how the agent perceives and interacts with the simulated edge hardware.
### Observation Space (`EdgeObservation`)
The observation provides a high-fidelity snapshot of the device's physical state at each discrete time step.
| Attribute | Type | Description |
| :--- | :--- | :--- |
| `ram_usage` | `float` | Percentage of total RAM occupied (0.0–100.0). High values trigger OOM risks. |
| `battery_level` | `float` | Remaining battery percentage (0.0–100.0). Impacts CPU frequency availability. |
| `active_processes` | `int` | Count of concurrent background tasks competing for CPU priority. |
| `latency` | `float` | Current inference delay in milliseconds. Impacted by CPU throttling and queue size. |
### Action Space (`EdgeAction`)
The agent must select a combination of the following booleans to mitigate system failure or optimize performance.
* **`kill_process`**: Immediately terminates the lowest-priority background process to reclaim ~15% RAM but incurs a small "reboot" penalty in future steps.
* **`throttle_cpu`**: Reduces the simulated CPU clock speed. Decreases battery drain by 40% but doubles inference `latency`.
* **`route_to_cloud`**: Offloads the current task to an external server. Reduces local RAM/Battery usage to near-zero but adds a fixed +150ms network latency.
---
## 🎯 Task Descriptions
The environment features a curriculum of three tasks designed to test the agent's ability to generalize across different stress conditions.
### 1. Task: `task_stable_edge` (Easy)
* **Scenario**: Standard operating conditions with consistent background noise.
* **Grader Logic**: `score = 1.0 - (steps_crashed / total_steps)`. A deterministic score from 0.0–1.0 based on survival.
### 2. Task: `task_fluctuating_memory` (Medium)
* **Scenario**: Simulates a user opening and closing heavy apps (e.g., Camera, Games), causing RAM usage to spike unpredictably.
* **Grader Logic**: Weighted average of **Survival** (50%) and **Efficiency** (50%, measured by keeping RAM usage between 60% and 85%).
### 3. Task: `task_low_battery_spike` (Hard)
* **Scenario**: High-priority request burst (5x normal) while battery is below 15%.
* **Grader Logic**: Binary survival check combined with a latency penalty. If the system crashes (OOM) or dies (Battery=0), the score is 0.0.
---
## πŸ› οΈ Setup & Usage
### Prerequisites
* **Docker:** Required for containerized execution.
* **Python 3.10+**.
* **openenv-core library:** For spec validation.
### Local Installation
1. **Clone the repository and build the container:**
```bash
docker build -t edge-deployment-env .
```
2. **Validate the environment specification:**
```bash
openenv validate
```
### Configuration
The baseline inference script reads configuration strictly from environment variables.
* **`API_BASE_URL`**: Your LLM endpoint URL.
* **`MODEL_NAME`**: The specific model identifier for inference (e.g., `llama3.1`).
* **`HF_TOKEN`**: Your Hugging Face API key.
### Running the Baseline
To execute the benchmark and produce the mandatory **STDOUT logs** for validation:
```bash
export API_BASE_URL="your_url"
export MODEL_NAME="your_model"
export HF_TOKEN="your_token"
python inference.py
```
Upon completion, the script will output the standard `[END]` line containing your final reproducible scores.
## πŸ“Š Baseline Scores
The following reproducible scores were achieved using the provided `inference.py` script with the **Llama 3.1** baseline agent. All scores are normalized between 0.0 and 1.0.
* **Task 1 (Stable Edge):** 0.65
* **Task 2 (Fluctuating Memory):** 0.82
* **Task 3 (Low Battery Spike):** 0.35
---