Skip to main content
Source Code: src/gaia/
Table of Contents

​
Introduction

GAIA is an open-source framework that runs generative AI applications on AMD hardware. GAIA uses ONNX Runtime GenAI via Lemonade Server for running Large Language Models (LLMs). GAIA utilizes both NPU and iGPU on Ryzen AI systems for optimal performance on 300 series processors or above.

​
Before You Start

​
System Requirements

RequirementMinimumRecommended
OSWindows 11 Pro 24H2 / Ubuntu 22.04+-
RAM16GB64GB
CPURyzen AI 300-seriesRyzen AI MAX+ 395
Storage20GB free-
Driver Requirements:
ComponentMinimum Version
Radeon iGPU32.0.22029.1019
NPU32.0.203.314

​
Software Requirements

​
Setup and Installation

GAIA uses uv, a fast Python package manager that handles virtual environments, Python installation, and dependencies automatically.

​
Step 1: Install uv

Windows (PowerShell): 
irm https://astral.sh/uv/install.ps1 | iex
Linux: 
curl -LsSf https://astral.sh/uv/install.sh | sh

​
Step 2: Clone GAIA

git clone https://github.com/amd/gaia.git
cd gaia

​
Step 3: Create Virtual Environment

uv venv .venv --python 3.12
Note: uv will automatically download Python 3.12 if not already installed.

​
Step 4: Activate the Environment

Windows (PowerShell): 
.\.venv\Scripts\Activate.ps1
Windows (Command Prompt): 
.\.venv\Scripts\activate.bat
Linux: 
source .venv/bin/activate
You should see (.venv) in your terminal prompt when activated.

​
Step 5: Install Dependencies

Linux/WSL users: GAIA’s base dependencies (transformers, accelerate) require PyTorch. Always use --extra-index-url to install CPU-only PyTorch and avoid large CUDA packages (~2GB → ~200MB).
# Linux/WSL - CPU-only PyTorch (required for all installs)
uv pip install -e ".[dev]" --extra-index-url https://download.pytorch.org/whl/cpu
Windows: 
# Windows - default PyTorch
uv pip install -e ".[dev]"
With all extras: 
# Linux/WSL
uv pip install -e ".[dev,talk,rag]" --extra-index-url https://download.pytorch.org/whl/cpu

# Windows
uv pip install -e ".[dev,talk,rag]"

​
Deactivating

When done working: 
deactivate
See also: Chat SDK Documentation

​
Running GAIA

​
Verify Installation

gaia -v    # Check version
gaia -h    # View CLI options

​
Start Chatting

gaia chat -q "What is artificial intelligence?"
Note: GAIA automatically starts Lemonade Server when needed. For manual start: lemonade-server serve

​
Running Electron Applications

GAIA includes Electron-based GUI applications. To run the JAX (Jira Agent Experience) app: Windows: 
.\src\gaia\apps\jira\webui\run.ps1
Linux: 
./src/gaia/apps/jira/webui/run.sh

​
Troubleshooting

​
”uv” command not found (Windows)

After installing uv, the command may not be recognized because PATH hasn’t updated. Solution 1: Restart PowerShell (simplest) Solution 2: Update PATH in current session: 
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
Solution 3: Use full path: 
$env:USERPROFILE\.local\bin\uv.exe --version

​
Virtual Environment Activation Fails (Windows)

If you see a script execution error: 
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

​
Model Loading Issues

  1. Check available system memory
  2. Verify model compatibility with your hardware
  3. Ensure all dependencies are correctly installed

​
Environment Variable Issues

  1. Verify the virtual environment is activated (look for (.venv) prefix)
  2. Try restarting your terminal
  3. Re-run the activation command for your platform

​
Support

Report issues to [email protected] or create an issue on GitHub.