Skip to content

dev.md

Latest commit

 

History

History
133 lines (101 loc) · 4.85 KB

dev.md

File metadata and controls

133 lines (101 loc) · 4.85 KB

GAIA Development Guide

Table of Contents

Introduction

GAIA is an open-source framework that runs generative AI applications on AMD hardware. GAIA uses the ONNX Runtime GenAI (aka OGA) backend via Lemonade Server tool 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

  • OS: Windows 11 Pro, 24H2 or Ubuntu 22.04 LTS / 24.04 LTS (64-bit)
  • RAM: Minimum 16GB
  • CPU: Ryzen AI 300-series processor (e.g., Ryzen AI 9 HX 370)
  • NPU Driver Versions: 32.0.203.240 and newer
  • Storage: 20GB free space
  • Tested Configuration: ASUS ProArt (HN7306W) Laptop

Software

Windows Prerequisites

  1. Download and install Windows installer from Miniforge
    1. Check "Add Miniforge3 to my PATH environment variables" if you want it accessible in all terminals
  2. Download and install Lemonade Server
    1. Go to https://lemonade-server.ai/ and download the appropriate installer for your system
    2. Follow the installation instructions provided on the website
    3. Lemonade Server will be used as the backend for running LLMs with GAIA

Setup and Installation

  1. Clone GAIA repo: git clone https://github.com/amd/gaia.git

  2. Open a powershell prompt and go to the GAIA root: cd ./gaia

  3. Create and activate a conda environment:

    1. conda create -n gaiaenv python=3.10 -y
    2. conda activate gaiaenv

  4. Install GAIA dependencies:

    pip install -e .[dev]

    ⚠️ NOTE: If actively developing, use -e switch to enable editable mode and create links to sources instead.

    ⚠️ NOTE: Make sure you are in the correct virtual environment when installing dependencies. If not, run conda activate gaiaenv.

    ⚠️ NOTE: Check ./setup.py for additional packages that support extra features in the CLI tool, e.g. pip install -e .[dev,eval,talk]

  5. For detailed information about using the Chat SDK and CLI chat features, see the Chat SDK Documentation.

Running GAIA

Once the installation and environment variables are set, run the following:

  1. Start the Lemonade server (required for LLM operations):

    lemonade-server serve

    Keep this running in a separate terminal window.

  2. Run gaia -v in the terminal to verify the installation. You should see a similar output:

    0.10.0

  3. Run gaia -h to see CLI options.

  4. Try the chat feature with a simple query:

    gaia chat "What is artificial intelligence?"

    Or start an interactive chat session:

    gaia chat

Troubleshooting

Common Issues

pip Installation Errors

If you encounter pip installation errors:

  1. Ensure you're using the correct Python version (3.10)
  2. Try running: pip install --upgrade pip
  3. Try deleting pip cache typically under: C:\Users<username>\AppData\Local\pip\cache
  4. Make sure there are no spaces in your project or or pip file cache paths

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

If GAIA is not working correctly:

  1. Verify the installation completed successfully by checking the log files
  2. Ensure all dependencies are installed correctly
  3. Check that you're using the correct conda environment: 
    conda activate gaiaenv
  4. Try restarting your terminal or command prompt

Support

Report any issues to the GAIA team at gaia@amd.com or create an issue on the GAIA GitHub repo.

License

MIT License

Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved. SPDX-License-Identifier: MIT