graph_rag_server/docs/configuration.md

Configuration Management

Overview

The RAG System uses a unified configuration management system built with Pydantic BaseSettings. This provides type-safe configuration with validation, supporting multiple configuration sources with clear priority.

Configuration Priority

Configuration values are loaded in the following order (highest to lowest priority):

1. Environment Variables - Highest priority
2. .env File - Medium priority
3. Default Values - Lowest priority

Configuration Structure

Configuration is organized by functional domains:

• Application Settings - General app configuration
• Database Settings - MySQL/PostgreSQL configuration
• Vector Database Settings - Infinity and Elasticsearch configuration
• Model Settings - AI model configuration
• API Settings - API server configuration
• Ragflow Settings - Ragflow integration configuration
• MinIO Settings - Object storage configuration
• Tag Search Settings - Tag search configuration

Usage

Basic Usage

from src.config import get_settings

# Get settings singleton
settings = get_settings()

# Access configuration
print(settings.app_name)
print(settings.database.host)
print(settings.vector_db_type)
print(settings.api.port)

Accessing Sub-configurations

# Database configuration
db_config = settings.database
print(f"Connecting to {db_config.host}:{db_config.port}")

# Vector database configuration
if settings.vector_db_type == "infinity":
    infinity_config = settings.infinity
    print(f"Using Infinity at {infinity_config.host}:{infinity_config.port}")
elif settings.vector_db_type == "elasticsearch":
    es_config = settings.elasticsearch
    print(f"Using Elasticsearch at {es_config.nodes}")

# Model configuration
model_config = settings.model
print(f"Using {model_config.provider} with {model_config.chat_model_name}")

Environment-Specific Configuration

settings = get_settings()

if settings.environment == "production":
    # Production-specific logic
    assert not settings.api.debug, "Debug mode should be disabled in production"
elif settings.environment == "development":
    # Development-specific logic
    pass

Configuration File

Creating .env File

1. Copy the example file:

   cp .env.example .env
   

2. Edit .env with your values:

   # Application
   APP_NAME=My RAG System
   ENVIRONMENT=production
      
   # Database
   DB_HOST=db.example.com
   DB_PORT=3306
   DB_USERNAME=myuser
   DB_PASSWORD=mypassword
   DB_DATABASE=rag_db
      
   # Vector Database
   VECTOR_DB_TYPE=elasticsearch
   ES_NODES=["http://es1.example.com:9200", "http://es2.example.com:9200"]
   ES_USERNAME=elastic
   ES_PASSWORD=changeme
      
   # API
   API_PORT=8000
   API_LOG_LEVEL=INFO
   API_WORKERS=4
   

Environment Variables

You can override any configuration using environment variables:

# Linux/Mac
export DB_HOST=localhost
export API_PORT=9000
export VECTOR_DB_TYPE=infinity

# Windows PowerShell
$env:DB_HOST="localhost"
$env:API_PORT="9000"
$env:VECTOR_DB_TYPE="infinity"

# Windows CMD
set DB_HOST=localhost
set API_PORT=9000
set VECTOR_DB_TYPE=infinity

Configuration Validation

The configuration system validates all values on load:

Port Validation

# Valid
DB_PORT=3306
API_PORT=8000

# Invalid - will raise ValidationError
DB_PORT=99999  # Port must be between 1 and 65535

Log Level Validation

# Valid
API_LOG_LEVEL=INFO
API_LOG_LEVEL=DEBUG

# Invalid - will raise ValidationError
API_LOG_LEVEL=INVALID  # Must be DEBUG, INFO, WARNING, ERROR, or CRITICAL

Vector DB Type Validation

# Valid
VECTOR_DB_TYPE=infinity
VECTOR_DB_TYPE=elasticsearch
VECTOR_DB_TYPE=es  # Normalized to 'elasticsearch'

# Invalid - will raise ValidationError
VECTOR_DB_TYPE=invalid  # Must be infinity, elasticsearch, or es

Environment Validation

# Valid
ENVIRONMENT=development
ENVIRONMENT=testing
ENVIRONMENT=production

# Invalid - will raise ValidationError
ENVIRONMENT=staging  # Must be development, testing, or production

Testing Configuration

Clearing Cache

In tests, you may need to reload configuration:

from src.config import get_settings, clear_settings_cache

# Clear cache to reload settings
clear_settings_cache()
settings = get_settings()

Testing with Different Configurations

import os
from src.config import get_settings, clear_settings_cache

# Set test environment variables
os.environ['DB_HOST'] = 'test-db'
os.environ['VECTOR_DB_TYPE'] = 'elasticsearch'

# Clear cache and reload
clear_settings_cache()
settings = get_settings()

# Run tests
assert settings.database.host == 'test-db'
assert settings.vector_db_type == 'elasticsearch'

Migration from Old Configuration

If you're migrating from the old configuration system (src/conf/settings.py), here's the mapping:

Old Configuration

from src.conf.settings import model_settings, vector_db_settings

model_name = model_settings.chat_model_name
infinity_host = vector_db_settings.infinity_host

New Configuration

from src.config import get_settings

settings = get_settings()
model_name = settings.model.chat_model_name
infinity_host = settings.infinity.host

Environment Variable Changes

Old Variable	New Variable
MODEL_PROVIDER	MODEL_PROVIDER (same)
CHAT_MODEL_NAME	MODEL_CHAT_MODEL_NAME
EMBEDDING_MODEL_NAME	MODEL_EMBEDDING_MODEL_NAME
INFINITY_HOST	INFINITY_HOST (same)
MYSQL_HOST	DB_HOST
MYSQL_PORT	DB_PORT
MYSQL_USER	DB_USERNAME
MYSQL_PASSWORD	DB_PASSWORD
MYSQL_DATABASE	DB_DATABASE
LOG_LEVEL	API_LOG_LEVEL

Best Practices

1. Never commit .env file - It contains sensitive information
2. Always use .env.example - Keep it updated with all configuration options
3. Use environment variables in production - More secure than files
4. Validate early - Configuration is validated on application startup
5. Use type hints - The configuration system provides full type safety
6. Document changes - Update .env.example when adding new configuration

Troubleshooting

Configuration Not Loading

1. Check .env file exists and is in the project root
2. Verify environment variable names match the expected format
3. Check for validation errors in the logs

Validation Errors

# Example error
ValidationError: 1 validation error for Settings
vector_db_type
  Value error, Vector DB type must be one of ['infinity', 'elasticsearch', 'es']

Solution: Check the value matches one of the allowed options.

Cache Issues

If configuration changes aren't reflected:

from src.config import clear_settings_cache

clear_settings_cache()

Reference

For complete configuration options, see:

• src/config/settings.py - Configuration class definitions
• .env.example - All available configuration options with descriptions