|
Download README.md from xdAILabs/edge-deployment-resource-optimization: direct link, hf CLI and curl.
- Browser
- Download file 5.66 kB
-
https://huggingface.co/spaces/xdAILabs/edge-deployment-resource-optimization/resolve/main/README.md
- Command line
-
hf download hf://spaces/xdAILabs/edge-deployment-resource-optimization/README.md
-
curl -L -o README.md https://huggingface.co/spaces/xdAILabs/edge-deployment-resource-optimization/resolve/main/README.md
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 | |
| --- | |