Spaces:
Sleeping
Sleeping
|
Download docs/deployment/local.md from jm-vis/Final_Assignment_GAIAAgent: direct link, hf CLI and curl.
- Browser
- Download file 9.72 kB
-
https://huggingface.co/spaces/jm-vis/Final_Assignment_GAIAAgent/resolve/main/docs/deployment/local.md
- Command line
-
hf download hf://spaces/jm-vis/Final_Assignment_GAIAAgent/docs/deployment/local.md
-
curl -L -o local.md https://huggingface.co/spaces/jm-vis/Final_Assignment_GAIAAgent/resolve/main/docs/deployment/local.md
9.72 kB
| # Local Deployment Guide for GAIA | |
| This guide provides detailed instructions for deploying and running the GAIA agent on a local machine for development, testing, or personal use. | |
| ## Prerequisites | |
| Before deploying GAIA locally, ensure you have the following: | |
| 1. **Python Environment**: | |
| - Python 3.9 or higher installed | |
| - pip (Python package manager) | |
| - (Optional) virtualenv or conda for environment isolation | |
| 2. **API Keys**: | |
| - OpenAI API key for language models | |
| - Additional API keys based on your configuration (Serper, Perplexity, etc.) | |
| 3. **System Requirements**: | |
| - At least 4GB of RAM | |
| - At least 2GB of free disk space | |
| - Internet connection for API calls | |
| ## Installation | |
| ### Step 1: Clone the Repository | |
| ```bash | |
| # Clone the GAIA repository | |
| git clone https://github.com/your-organization/gaia.git | |
| cd gaia | |
| ``` | |
| ### Step 2: Set Up Python Environment | |
| ```bash | |
| # Option 1: Create a virtual environment with venv | |
| python -m venv venv | |
| # Activate the virtual environment | |
| # On Windows | |
| venv\Scripts\activate | |
| # On macOS/Linux | |
| source venv/bin/activate | |
| # Option 2: Create a conda environment | |
| conda create -n gaia python=3.9 | |
| conda activate gaia | |
| ``` | |
| ### Step 3: Install Dependencies | |
| ```bash | |
| # Install required packages | |
| pip install -r requirements.txt | |
| # For development, install development dependencies as well | |
| pip install -r requirements-dev.txt | |
| ``` | |
| ### Step 4: Configure Environment Variables | |
| Create a `.env` file in the root directory of the project: | |
| ```bash | |
| # Create .env file from template | |
| cp .env.example .env | |
| ``` | |
| Edit the `.env` file with your API keys and configuration: | |
| ``` | |
| # API Keys | |
| OPENAI_API_KEY=your-openai-api-key | |
| SERPER_API_KEY=your-serper-api-key | |
| PERPLEXITY_API_KEY=your-perplexity-api-key | |
| # Optional: Supabase configuration for memory | |
| SUPABASE_URL=your-supabase-url | |
| SUPABASE_KEY=your-supabase-key | |
| # Agent Configuration | |
| MODEL_NAME=gpt-4o | |
| VERBOSE=true | |
| # UI Configuration | |
| DEMO_MODE=true | |
| SIMPLE_UI=false | |
| ``` | |
| ## Basic Deployment | |
| ### Running the Web Interface | |
| The simplest way to deploy GAIA locally is to run the web interface: | |
| ```bash | |
| # Start the web interface | |
| python app.py | |
| ``` | |
| This will start a Gradio web server that you can access at `http://localhost:7860` in your browser. | |
| ### Running in Demo Mode | |
| For quick testing without setting up authentication: | |
| ```bash | |
| # Enable demo mode | |
| export DEMO_MODE=true # On Windows: set DEMO_MODE=true | |
| python app.py | |
| ``` | |
| ### Running with a Simplified UI | |
| For a more streamlined interface: | |
| ```bash | |
| # Enable simplified UI | |
| export SIMPLE_UI=true # On Windows: set SIMPLE_UI=true | |
| python app.py | |
| ``` | |
| ## Command-Line Usage | |
| GAIA can also be used directly from the command line: | |
| ```bash | |
| # Run a single query | |
| python -m src.gaia.cli "What is quantum computing?" | |
| # Run in interactive mode | |
| python -m src.gaia.cli --interactive | |
| # Run with specific configuration | |
| python -m src.gaia.cli --model "gpt-3.5-turbo" --verbose "What is climate change?" | |
| ``` | |
| ## Advanced Configuration | |
| ### Custom Configuration File | |
| For more advanced configuration, create a custom configuration file: | |
| ```bash | |
| # Create a config.json file | |
| cat > config.json << EOF | |
| { | |
| "api": { | |
| "openai": { | |
| "api_key": "your-openai-key" | |
| }, | |
| "serper": { | |
| "api_key": "your-serper-key" | |
| } | |
| }, | |
| "models": { | |
| "default": "gpt-4o", | |
| "fallback": "gpt-3.5-turbo" | |
| }, | |
| "tools": { | |
| "web_search": { | |
| "enabled": true, | |
| "default_provider": "serper" | |
| }, | |
| "academic_search": { | |
| "enabled": true | |
| } | |
| }, | |
| "memory": { | |
| "supabase": { | |
| "enabled": false | |
| } | |
| } | |
| } | |
| EOF | |
| # Run with custom configuration | |
| python app.py --config config.json | |
| ``` | |
| ### Enabling Memory with Supabase | |
| To use Supabase for persistent memory: | |
| 1. Create a Supabase project at [https://supabase.com](https://supabase.com) | |
| 2. Create the required tables using the provided SQL script: | |
| ```bash | |
| # Copy the SQL script | |
| cp docs/deployment/schema/supabase_tables.sql ./supabase_setup.sql | |
| # Manually execute this in your Supabase SQL editor | |
| # or use the Supabase CLI | |
| ``` | |
| 3. Update your `.env` file with Supabase credentials: | |
| ``` | |
| SUPABASE_URL=your-supabase-url | |
| SUPABASE_KEY=your-supabase-key | |
| SUPABASE_MEMORY_ENABLED=true | |
| ``` | |
| ## Running as a Service | |
| ### Using Systemd (Linux) | |
| To run GAIA as a background service on Linux using systemd: | |
| 1. Create a systemd service file: | |
| ```bash | |
| sudo nano /etc/systemd/system/gaia.service | |
| ``` | |
| 2. Add the following content: | |
| ``` | |
| [Unit] | |
| Description=GAIA Assessment Agent | |
| After=network.target | |
| [Service] | |
| User=your-username | |
| WorkingDirectory=/path/to/gaia | |
| Environment="PATH=/path/to/gaia/venv/bin" | |
| ExecStart=/path/to/gaia/venv/bin/python app.py | |
| Restart=on-failure | |
| RestartSec=5 | |
| StandardOutput=journal | |
| StandardError=journal | |
| [Install] | |
| WantedBy=multi-user.target | |
| ``` | |
| 3. Enable and start the service: | |
| ```bash | |
| sudo systemctl enable gaia | |
| sudo systemctl start gaia | |
| ``` | |
| 4. Check service status: | |
| ```bash | |
| sudo systemctl status gaia | |
| ``` | |
| ### Using PM2 (Cross-platform) | |
| For a more flexible service manager that works across platforms: | |
| 1. Install PM2: | |
| ```bash | |
| npm install -g pm2 | |
| ``` | |
| 2. Create an ecosystem file: | |
| ```bash | |
| cat > ecosystem.config.js << EOF | |
| module.exports = { | |
| apps: [{ | |
| name: "gaia", | |
| script: "app.py", | |
| interpreter: "./venv/bin/python", | |
| env: { | |
| OPENAI_API_KEY: "your-openai-key", | |
| SERPER_API_KEY: "your-serper-key", | |
| MODEL_NAME: "gpt-4o", | |
| VERBOSE: "true" | |
| } | |
| }] | |
| } | |
| EOF | |
| ``` | |
| 3. Start with PM2: | |
| ```bash | |
| pm2 start ecosystem.config.js | |
| ``` | |
| 4. Monitor and manage: | |
| ```bash | |
| pm2 status | |
| pm2 logs gaia | |
| pm2 restart gaia | |
| ``` | |
| ## Docker Deployment | |
| GAIA can also be deployed using Docker for better isolation and portability: | |
| ### Step 1: Create a Dockerfile | |
| ```bash | |
| cat > Dockerfile << EOF | |
| FROM python:3.9-slim | |
| WORKDIR /app | |
| COPY requirements.txt . | |
| RUN pip install --no-cache-dir -r requirements.txt | |
| COPY . . | |
| EXPOSE 7860 | |
| CMD ["python", "app.py"] | |
| EOF | |
| ``` | |
| ### Step 2: Create a Docker Compose File | |
| ```bash | |
| cat > docker-compose.yml << EOF | |
| version: '3' | |
| services: | |
| gaia: | |
| build: . | |
| ports: | |
| - "7860:7860" | |
| environment: | |
| - OPENAI_API_KEY=your-openai-key | |
| - SERPER_API_KEY=your-serper-key | |
| - PERPLEXITY_API_KEY=your-perplexity-key | |
| - MODEL_NAME=gpt-4o | |
| - VERBOSE=true | |
| - DEMO_MODE=true | |
| volumes: | |
| - ./logs:/app/logs | |
| EOF | |
| ``` | |
| ### Step 3: Build and Run with Docker Compose | |
| ```bash | |
| # Build the Docker image | |
| docker-compose build | |
| # Run the container | |
| docker-compose up -d | |
| # Check logs | |
| docker-compose logs -f | |
| ``` | |
| ## Performance Optimization | |
| ### Memory Usage | |
| To optimize memory usage: | |
| ```bash | |
| # Limit result cache size | |
| export MEMORY_RESULT_CACHE_SIZE=100 | |
| # Set a shorter TTL for cached results (in seconds) | |
| export MEMORY_TTL=1800 # 30 minutes | |
| ``` | |
| ### CPU Usage | |
| For lower CPU usage: | |
| ```bash | |
| # Disable verbose logging | |
| export VERBOSE=false | |
| # Use a lighter model | |
| export MODEL_NAME=gpt-3.5-turbo | |
| # Limit the number of tools enabled | |
| export WEB_SEARCH_ENABLED=true | |
| export ACADEMIC_SEARCH_ENABLED=false | |
| ``` | |
| ## Troubleshooting | |
| ### Common Issues | |
| 1. **API Key Issues**: | |
| ``` | |
| Error: Authentication error with OpenAI API | |
| ``` | |
| Solution: Check that your API key is correct and has sufficient credits. | |
| 2. **Port Conflicts**: | |
| ``` | |
| Error: Address already in use | |
| ``` | |
| Solution: Change the port using an environment variable: | |
| ```bash | |
| export PORT=7861 | |
| python app.py | |
| ``` | |
| 3. **Missing Dependencies**: | |
| ``` | |
| ImportError: No module named 'some_package' | |
| ``` | |
| Solution: Ensure all dependencies are installed: | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 4. **Memory Issues**: | |
| ``` | |
| MemoryError or Process killed | |
| ``` | |
| Solution: Limit memory usage as described in the Performance Optimization section. | |
| ### Logging | |
| Enable detailed logging for troubleshooting: | |
| ```bash | |
| # Enable debug logging | |
| export LOG_LEVEL=DEBUG | |
| python app.py | |
| ``` | |
| Log files are stored in the `logs/` directory by default. | |
| ### Diagnostic Commands | |
| Use these commands to diagnose issues: | |
| ```bash | |
| # Check environment variables | |
| python -c "import os; print(os.environ.get('OPENAI_API_KEY', 'Not set'))" | |
| # Test API connections | |
| python -m src.gaia.utils.cli.verify_connections | |
| # Test memory connections | |
| python -m src.gaia.utils.cli.verify_memory | |
| ``` | |
| ## Security Considerations | |
| When deploying GAIA locally, consider these security practices: | |
| 1. **API Key Management**: | |
| - Store API keys in environment variables or a secure `.env` file | |
| - Never commit API keys to version control | |
| - Consider using a secret management solution for production | |
| 2. **Network Security**: | |
| - By default, the web interface only listens on localhost | |
| - To expose to other machines, use `--host 0.0.0.0` with caution | |
| - Consider using a reverse proxy with authentication for wider access | |
| 3. **Data Privacy**: | |
| - Be aware of what data is being sent to external APIs | |
| - Consider privacy implications when using memory features | |
| - Regularly clear cached data for sensitive applications | |
| ## Upgrading | |
| To upgrade your GAIA installation: | |
| ```bash | |
| # Pull the latest changes | |
| git pull | |
| # Update dependencies | |
| pip install -r requirements.txt | |
| # Run migration scripts if available | |
| python -m src.gaia.utils.cli.run_migrations | |
| # Restart the service | |
| # If using systemd: | |
| sudo systemctl restart gaia | |
| # If using PM2: | |
| pm2 restart gaia | |
| ``` | |
| ## Conclusion | |
| You now have GAIA running locally on your machine. For more advanced deployment options, check out the [Hugging Face Deployment Guide](huggingface.md) or explore the [API documentation](../api/agent.md) to integrate GAIA into your own applications. | |
| For any issues or questions, please refer to the [troubleshooting section](#troubleshooting) or create an issue on the project's GitHub repository. |