Skip to content

Latest commit

 

History

History
192 lines (131 loc) · 4.9 KB

README.md

File metadata and controls

192 lines (131 loc) · 4.9 KB
Raw

Vertex RAG Flask

Python 3.11+ Code style: black License: MIT Tests

Flask application for building RAG (Retrieval Augmented Generation) systems using Google Vertex AI. Process PDFs with layout-aware parsing, chat with documents in multiple languages, and build AI-powered document analysis systems.

Installation

  1. Clone the repository:
git clone https://github.com/cherninlab/vertex-rag-flask.git
cd vertex-rag-flask
  1. Set up Python environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install --upgrade pip
  1. Install the project:
pip install -e ".[dev]"
  1. Configure environment:
cp .env.example .env
# Edit .env with your configuration:
# - Add your Google Cloud Project ID
# - Set path to service account credentials
  1. Run the application:
flask run

Google Cloud Setup

  1. Create a new project in Google Cloud Console

  2. Enable required APIs:

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

# Enable Cloud Storage API
gcloud services enable storage.googleapis.com

# Enable IAM API
gcloud services enable iam.googleapis.com
  1. Create and configure service account:
# Create service account
gcloud iam service-accounts create vertex-rag-sa --display-name="Vertex RAG Service Account"

# Grant Vertex AI user role
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID --member="serviceAccount:vertex-rag-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user"

# Grant Storage Admin role (for bucket and file management)
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID --member="serviceAccount:vertex-rag-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.admin"

# Download credentials
gcloud iam service-accounts keys create credentials.json --iam-account=vertex-rag-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

Important Notes:

  • Keep your credentials.json secure and never commit it to version control
  • The service account needs both Vertex AI and Storage permissions to function properly
  • You can use more granular permissions instead of storage.admin if needed

Usage

  1. Start the application:
flask run
# FLASK_DEBUG=1 FLASK_APP=src/app flask run --debug

  1. Open http://localhost:5000 in your browser

  2. Upload a document

  3. After processing, you'll be redirected to the chat interface

Development

Project Structure

vertex-rag-flask/
├── src/
│   ├── app/
│   │   ├── routes/      # API and web routes
│   │   ├── services/    # Business logic
│   │   ├── templates/   # HTML templates
│   │   └── utils/       # Helper functions
│   └── config/          # Configuration
├── tests/               # Test files
├── uploads/             # Temporary upload directory
├── credentials.json     # GCP service account key
├── pyproject.toml       # Project dependencies
└── README.md

System Requirements

  • Python 3.11+
  • Google Cloud Project with enabled APIs
  • Service account with appropriate permissions

Running Tests

# Run pytest
pytest

# Run type checking
mypy .

# Run linting
flake8 .

Code Style

The project uses several tools to maintain code quality:

  • black: Code formatting
  • isort: Import sorting
  • flake8: Style guide enforcement
  • mypy: Static type checking

These are automatically run as pre-commit hooks when you commit changes.

Using Dev Containers

If you use VS Code:

  1. Install the "Remote - Containers" extension
  2. Open the project
  3. Click "Reopen in Container" when prompted
  4. VS Code will set up the development environment automatically

Troubleshooting

Common Issues

  1. Permission Denied Errors

    • Verify that your service account has all required roles
    • Check if credentials.json is properly configured
    • Ensure APIs are enabled in your project

  2. Upload Failures

    • Verify the file format is supported
    • Check if the selected bucket exists
    • Ensure your service account has storage permissions

  3. Chat Not Working

    • Verify Vertex AI API is enabled
    • Check if the model has access to your document
    • Ensure proper network connectivity

Contributing

Contributions are welcome!

License

Distributed under the MIT License. See LICENSE for more information.

⭐ If you find this project useful, please consider giving it a star! It helps make the project more visible and encourages development.