Source Code:
installer/GAIA Installation (Windows Only)
GAIA is specifically designed for AMD Ryzen AI systems and uses Lemonade Server for optimal hardware utilization including NPU and iGPU capabilities.Prerequisites
Required Components
-
Python Environment (All Modes)
- Python 3.12 will be automatically installed if missing
- Creates a virtual environment for GAIA
-
Ryzen AI Driver (Ryzen AI Systems Only)
- Required version: Latest available
- Will be automatically downloaded and installed if needed
- Installer checks current version and offers updates
Installation Process
1. Pre-Installation Checks
- Verifies system requirements
- Checks for existing GAIA installation
- Removes previous versions if found
- Initializes installation logging
- Detects CPU compatibility for Ryzen AI systems
2. Environment Setup
The installer automatically:- Checks for and installs Python 3.12 if needed
- Creates a dedicated virtual environment
- Sets required environment variables
- Creates activation scripts
3. Additional Components
- Downloads required LLM artifacts
- For Ryzen AI systems:
- Checks Ryzen AI driver version
- Offers automatic driver updates
- Installs Ryzen AI wheel packages
- Configures settings.json for optimal performance
Command-Line Installation
For silent or automated installations, use command-line parameters:/S- Silent installation (no UI)/D=<path>- Set installation directory (must be last parameter)
CI/CD Environments
For continuous integration and deployment scenarios, use:Building the Installer
To build the installer from source:- Install NSIS 3.10
- Navigate to the installer directory
- Run
"C:\Program Files (x86)\NSIS\makensis.exe" Installer.nsito compile the installer - The compiled installer will be created as
gaia-windows-setup.exe
Debugging
Debugging the installer could be tricky on a workflow since NSIS does not log anything that happens inside anexecWait when running on a GitHub Workflow. To go around that, simply run the installer locally. To debug locally you have two options:
Option 1: GUI installation
- Change all
ExecWaits insideInstaller.nsitoExec. This will make sure terminals are not closed once something fails. - Compile and run normally
Option 2: Silent mode through terminal
- From a
Command Promptconsole, rungaia-windows-setup.exe /S. All logs will be shown on the screen. - To log detailed output, use
gaia-windows-setup.exe /S /LOG=install_log.txt
Troubleshooting
If you encounter installation issues:- Check the installation logs - you can generate detailed logs by running
gaia-windows-setup.exe /LOG=install_log.txt - Verify system requirements are met
- For Ryzen AI systems, verify your processor and drivers are properly detected
- Hardware Compatibility: The installer detects available hardware capabilities
- Driver Incompatibility: For Ryzen AI systems, ensure you have compatible NPU drivers
- Installation Path: Avoid paths with special characters or very long directory names
Environment Variable Handling
PATH Environment Variable
The installer automatically adds two directories to your system PATH:<install_dir>\bin- Contains GAIA command-line tools and scripts<install_dir>\python\Scripts- Contains Python executable scripts
- Uses direct registry manipulation to avoid Windows
setxcommand’s 1024-character limit - Preserves all existing PATH entries
- Handles scenarios like empty PATH or very long PATH values
- Avoids duplicate entries if reinstalling
- Includes error handling with user prompts if registry operations fail
- A warning message will be displayed
- You can choose to continue or abort installation
- If you continue, you may need to add GAIA directories to PATH manually
Manual PATH Management
If you need to manually add GAIA to your system PATH:- Open System Properties > Advanced > Environment Variables
- Edit the ‘Path’ variable in User Variables
- Add
<install_dir>\binand<install_dir>\python\Scripts - Click OK to save changes
Other Environment Variables
The installer also sets:GAIA_INSTALL_DIR- Points to the main installation directory