Agentic RAG Service Setup Guide

🚀 Quick Start

Prerequisites

Python 3.11+ with uv package manager
config.yaml file in the root directory

Starting the Service

Option 1: Using the startup script (Recommended)

# Production mode (background)
./start_service.sh

# Development mode (with auto-reload)
./start_service.sh --dev

Option 2: Manual startup

# Make sure you're in the root directory with config.yaml
cd /home/fl/code/ai-solution/agentic-rag-4

# Start the service
uv run uvicorn service.main:app --host 127.0.0.1 --port 8000

Stopping the Service

./stop_service.sh

Configuration

The service expects a config.yaml file in the root directory. Example structure:

# Configuration
provider: azure  # or openai

openai:
  base_url: "${OPENAI_BASE_URL:-https://api.openai.com/v1}"
  api_key: "${OPENAI_API_KEY}"
  model: "gpt-4o"

azure:
  base_url: "https://your-azure-endpoint.com/..."
  api_key: "your-azure-api-key"
  deployment: "gpt-4o"
  api_version: "2024-11-20"

retrieval:
  endpoint: "http://your-retrieval-endpoint.com"
  api_key: "your-retrieval-api-key"

app:
  name: "agentic-rag"
  memory_ttl_days: 7
  max_tool_loops: 3
  cors_origins: ["*"]
  logging:
    level: "INFO"

llm:
  rag:
    temperature: 0.2
    max_tokens: 4000
    system_prompt: |
      # Your detailed system prompt here...
    user_prompt: |
      <user_query>{{user_query}}</user_query>
      # Rest of your user prompt template...

logging:
  level: "INFO"
  format: "json"

Service Endpoints

Once running, the service provides:

Health Check: http://127.0.0.1:8000/health
API Documentation: http://127.0.0.1:8000/docs
Chat API: http://127.0.0.1:8000/api/chat (POST with streaming response)

Environment Variables

The configuration supports environment variable substitution:

${OPENAI_API_KEY} - Your OpenAI API key
${OPENAI_BASE_URL:-https://api.openai.com/v1} - OpenAI base URL with default fallback

Troubleshooting

Service won't start

Check if config.yaml exists in the root directory
Verify the configuration syntax
Check if the port is already in use: lsof -i :8000
View logs: tail -f server.log

Configuration issues

Ensure all required fields are present in config.yaml
Check environment variables are set correctly
Validate YAML syntax

Performance issues

Monitor logs: tail -f server.log
Check retrieval service connectivity
Verify LLM provider configuration

Development

For development with auto-reload:

./start_service.sh --dev

This will watch for file changes and automatically restart the service.

📁 File Structure

/home/fl/code/ai-solution/agentic-rag-4/
├── config.yaml              # Main configuration file
├── start_service.sh          # Service startup script
├── stop_service.sh          # Service stop script
├── server.log               # Service logs (when running in background)
├── service/                 # Service source code
│   ├── main.py             # FastAPI application
│   ├── config.py           # Configuration handling
│   ├── graph/              # Workflow graph
│   ├── memory/             # Memory store
│   ├── tools/              # Retrieval tools
│   └── schemas/            # Data models
└── ...

3.4 KiB Raw Blame History