Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
325 lines (230 loc) · 6.33 KB

GETTING_STARTED.md

File metadata and controls

325 lines (230 loc) · 6.33 KB
Raw

Getting Started - Multilingual KB System

Quick Start Guide

This guide will help you get the Multilingual Agentic Retrieval System up and running on your local machine.

Prerequisites

Ensure you have the following installed:

  • Node.js 20+ and npm
  • Python 3.11+
  • Docker Desktop (for containerized development)
  • Git
  • Azure CLI (for Azure deployment)

Setup Instructions

1. Clone and Configure

# Clone the repository
git clone <your-repo-url>
cd az-ai-agentic-retrieval

# Copy environment variables
cp .env.example .env

# Edit .env with your Azure credentials
# Required: Azure OpenAI, Storage, Cosmos DB credentials

2. Local Development with Docker (Recommended)

# Start all services with Docker Compose
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

Services will be available at:

3. Manual Setup (Alternative)

Backend API (Node.js)

cd backend/api

# Install dependencies
npm install

# Create logs directory
mkdir -p logs

# Start development server
npm run dev

# API will be available at http://localhost:3000

Processing Service (Python)

cd backend/processing

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start development server
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

# Service will be available at http://localhost:8000

Frontend (React)

cd frontend

# Install dependencies
npm install

# Start development server
npm start

# Frontend will be available at http://localhost:3001

4. Initialize Database

The PostgreSQL database will be automatically initialized with the init-db.sql script when using Docker Compose.

For manual setup:

# Connect to PostgreSQL
psql -h localhost -U postgres -d vector db

# Run initialization script
\i backend/processing/scripts/init-db.sql

Configuration

Required Environment Variables

Update your .env file with actual values:

# Azure OpenAI (Required)
AZURE_OPENAI_ENDPOINT=https://your-instance.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-ada-002

# Azure Storage (Required)
AZURE_STORAGE_CONNECTION_STRING=your-connection-string

# Azure Cosmos DB (Required)
COSMOS_DB_ENDPOINT=https://your-cosmos.documents.azure.com:443/
COSMOS_DB_KEY=your-key

# Azure AI Search (Required)
AZURE_SEARCH_ENDPOINT=https://your-search.search.windows.net
AZURE_SEARCH_API_KEY=your-api-key

Verify Installation

1. Health Checks

# Check API health
curl http://localhost:3000/health

# Check Processing Service health
curl http://localhost:8000/health

2. Test Document Upload

# Upload a test document
curl -X POST http://localhost:3000/api/v1/documents/upload \
  -F "file=@/path/to/test.pdf" \
  -F "title=Test Document"

3. Test Query

# Submit a test query
curl -X POST http://localhost:3000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is this about?", "language": "en"}'

Development Workflow

Running Tests

# Backend API tests
cd backend/api
npm test

# Python tests
cd backend/processing
pytest

# Frontend tests
cd frontend
npm test

Code Formatting

# Backend API
cd backend/api
npm run lint:fix

# Python
cd backend/processing
black src/

# Frontend
cd frontend
npm run lint:fix

Building for Production

# Build API
cd backend/api
npm run build

# Build Frontend
cd frontend
npm run build

# Build Docker images
docker-compose build

Common Issues and Solutions

Port Already in Use

If ports 3000, 3001, or 8000 are already in use:

# Find and kill process using the port (Windows)
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Linux/Mac
lsof -ti:3000 | xargs kill -9

Database Connection Issues

# Restart PostgreSQL container
docker-compose restart postgres

# Check PostgreSQL logs
docker-compose logs postgres

Azure Connection Issues

Verify your Azure credentials and ensure:

  1. Services are properly provisioned
  2. Firewall rules allow your IP
  3. API keys are valid and not expired

Next Steps

  1. Upload Documents: Use the Document Manager to upload test documents
  2. Test Chat: Try asking questions in the Chat Interface
  3. Monitor Analytics: Check the Analytics dashboard for insights
  4. Deploy to Azure: Follow the DEPLOYMENT_OPERATIONS_GUIDE.md

Useful Commands

# Stop all services
docker-compose down

# Rebuild and restart
docker-compose up --build -d

# View service logs
docker-compose logs -f [service-name]

# Clean up volumes
docker-compose down -v

# Execute command in running container
docker-compose exec api sh
docker-compose exec processing bash

Getting Help

Project Structure

az-ai-agentic-retrieval/
├── backend/
│   ├── api/              # Node.js Express API
│   ├── processing/       # Python FastAPI service
│   └── functions/        # Azure Functions
├── frontend/             # React application
├── infrastructure/       # IaC templates
├── docs/                 # Documentation
└── docker-compose.yml    # Local development setup

Development Tips

  1. Use Docker Compose for consistent development environment
  2. Enable Hot Reload for faster development
  3. Check Logs regularly for errors
  4. Test APIs with tools like Postman or curl
  5. Monitor Resources with Docker Desktop

Production Deployment

For production deployment to Azure, refer to:

Support

For questions or issues: