Конфигурация¶

Детальное руководство по настройке всех компонентов Р13.Орбита.

Файлы конфигурации¶

Р13.Орбита использует два уровня конфигурации:

.env - переменные окружения (секреты, учетные данные)
config.yaml - основная конфигурация приложения

Переменные окружения (.env)¶

Создайте файл .env в корне проекта:

# LLM Provider
LLM_TYPE=openai-compatible
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-api-key-here
LLM_MODEL=gpt-4
LLM_TEMPERATURE=0.1

# ClickHouse
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=default
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

# Metadata Database
METADATA_DB_URL=postgresql://user:password@localhost:5432/orbita
# Или SQLite: sqlite:///${HOME}/.orbita/metadata.db

# API Server
API_HOST=0.0.0.0
API_PORT=8000

# Optional: Redis
REDIS_URL=redis://localhost:6379/0

# Optional: Keycloak
KEYCLOAK_SERVER_URL=http://localhost:8080
KEYCLOAK_REALM=orbita
KEYCLOAK_CLIENT_ID=orbita-api
KEYCLOAK_CLIENT_SECRET=your-secret-here

# Optional: Monitoring
JAEGER_AGENT_HOST=localhost
JAEGER_AGENT_PORT=6831

Конфигурация LLM провайдеров¶

OpenAI (рекомендуется)¶

# config.yaml
llm:
  type: openai-compatible
  base_url: https://api.openai.com/v1
  api_key: ${LLM_API_KEY}
  model: gpt-4
  temperature: 0.1

.env:

LLM_API_KEY=sk-your-openai-key

Nebius AI Studio (рекомендуется для tool calling)¶

llm:
  type: nebius
  api_key: ${LLM_API_KEY}
  model: Qwen/Qwen3-Coder-30B-A3B-Instruct
  temperature: 0.6

.env:

LLM_API_KEY=your-nebius-token

Получите токен на studio.nebius.ai

Ollama (локальный, бесплатный)¶

llm:
  type: ollama
  base_url: http://localhost:11434
  model: llama2
  temperature: 0.1

Не требует API ключа. Установите Ollama и загрузите модель:

ollama pull llama2

GigaChat (Сбер)¶

llm:
  type: gigachat
  credentials: ${GIGACHAT_CREDENTIALS}
  scope: GIGACHAT_API_PERS
  model: GigaChat
  verify_ssl_certs: false

.env:

GIGACHAT_CREDENTIALS=your-gigachat-auth-token
GIGACHAT_SCOPE=GIGACHAT_API_PERS

Конфигурация ClickHouse¶

# config.yaml
clickhouse:
  host: ${CLICKHOUSE_HOST:-localhost}
  port: ${CLICKHOUSE_PORT:-8123}
  database: ${CLICKHOUSE_DATABASE:-default}
  user: ${CLICKHOUSE_USER:-default}
  password: ${CLICKHOUSE_PASSWORD:-}
  pool_size: 10
  timeout: 30

.env:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=default
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=yourpassword

Несколько баз данных¶

Если данные в разных БД:

clickhouse:
  databases:
    ecommerce:
      host: localhost
      database: ecommerce_db
    logistics:
      host: logistics-server
      database: logistics_db

База данных метаданных¶

PostgreSQL (продакшн)¶

# config.yaml
metadata_db:
  url: ${METADATA_DB_URL}
  pool_size: 20
  max_overflow: 40
  pool_pre_ping: true

.env:

METADATA_DB_URL=postgresql://orbita_user:password@localhost:5432/orbita_meta

SQLite (разработка)¶

METADATA_DB_URL=sqlite:///${HOME}/.orbita/metadata.db

Домены данных¶

Домены описывают схему ваших данных в domains/*.yaml.

Пример: ecommerce.yaml¶

name: "ecommerce"
description: "Домен электронной коммерции"

schema:
  customers:
    - name: "id"
      type: "UInt64"
      description: "ID покупателя"
    - name: "name"
      type: "String"
      description: "Имя покупателя"
    - name: "city"
      type: "String"
      description: "Город"

  orders:
    - name: "id"
      type: "UInt64"
      description: "ID заказа"
    - name: "customer_id"
      type: "UInt64"
      description: "ID покупателя"
    - name: "order_date"
      type: "DateTime"
      description: "Дата заказа"
    - name: "total_amount"
      type: "Float64"
      description: "Сумма заказа"

rules:
  - "Для расчета среднего чека используй AVG(total_amount)"
  - "Города: Москва, Санкт-Петербург, Новосибирск"

Создание своего домена¶

Создайте файл domains/your_domain.yaml
Опишите таблицы и поля
Добавьте business rules
Перезапустите сервис

Оркестрация¶

orchestration:
  mode: ${ORCHESTRATION_MODE:-graph}  # graph или function_calling
  max_iterations: 10
  timeout_seconds: 60

graph - LangGraph с явными нодами (рекомендуется, быстрее)
function_calling - ReAct agent с function calling

Инструменты (Tools)¶

tools:
  enabled:
    - text2sql
    - execute_sql
    - dataset2chart
    - mark_dataset
    - list_datasets
    - view_dataset
    - company_info

  text2sql:
    model_override: null  # Использовать основной LLM
    few_shot_examples: 3

  execute_sql:
    max_rows: ${AUTO_LIMIT_ROWS:-1000}
    timeout: 30
    allowed_operations:
      - SELECT
      - WITH

  dataset2chart:
    default_format: png
    dpi: 300
    default_size: [10, 6]
    style: seaborn-v0_8

Безопасность¶

CORS¶

cors:
  allow_origins:
    - "*"  # ⚠️ Измените в продакшн!
  allow_methods:
    - GET
    - POST
    - PUT
    - DELETE
  allow_headers:
    - "*"
  allow_credentials: true

Продакшн:

cors:
  allow_origins:
    - "https://orbita.company.com"
    - "https://app.company.com"

Security Headers¶

security:
  headers:
    x_content_type_options: "nosniff"
    x_frame_options: "DENY"
    x_xss_protection: "1; mode=block"
    strict_transport_security: "max-age=31536000; includeSubDomains"

Rate Limiting¶

rate_limiting:
  enabled: true
  redis_url: ${REDIS_URL}
  default_limit: "100/minute"

  role_limits:
    admin: "1000/minute"
    analyst: "500/minute"
    viewer: "100/minute"

Аутентификация (Keycloak)¶

auth:
  enabled: ${AUTH_ENABLED:-false}
  provider: keycloak

  keycloak:
    server_url: ${KEYCLOAK_SERVER_URL}
    realm: ${KEYCLOAK_REALM}
    client_id: ${KEYCLOAK_CLIENT_ID}
    client_secret: ${KEYCLOAK_CLIENT_SECRET}
    verify_ssl: ${KEYCLOAK_VERIFY_SSL:-true}

  jwt:
    algorithm: RS256
    audience: orbita-api

.env:

AUTH_ENABLED=true
KEYCLOAK_SERVER_URL=http://localhost:8080
KEYCLOAK_REALM=orbita
KEYCLOAK_CLIENT_ID=orbita-api
KEYCLOAK_CLIENT_SECRET=your-client-secret

Мониторинг и логирование¶

OpenTelemetry¶

telemetry:
  enabled: ${TELEMETRY_ENABLED:-true}

  tracing:
    enabled: true
    service_name: orbita-api
    jaeger_endpoint: ${JAEGER_ENDPOINT:-http://localhost:14268/api/traces}

  metrics:
    enabled: true
    prometheus_port: 9090

.env:

TELEMETRY_ENABLED=true
JAEGER_ENDPOINT=http://localhost:14268/api/traces

Logging¶

logging:
  level: ${LOG_LEVEL:-INFO}  # DEBUG, INFO, WARNING, ERROR
  format: json  # json или console

  handlers:
    - type: console
      level: INFO
    - type: file
      level: DEBUG
      filename: logs/orbita.log
      max_bytes: 10485760  # 10MB
      backup_count: 5

API Server¶

api:
  host: ${API_HOST:-0.0.0.0}
  port: ${API_PORT:-8000}
  workers: ${API_WORKERS:-4}
  reload: ${API_RELOAD:-false}

  uvicorn:
    log_level: info
    access_log: true
    proxy_headers: true
    forwarded_allow_ips: "*"

Полный пример production конфигурации¶

app:
  name: "orbita"
  version: "1.0.0"
  environment: production
  debug: false

llm:
  type: openai-compatible
  base_url: https://api.openai.com/v1
  api_key: ${LLM_API_KEY}
  model: gpt-4
  temperature: 0.1

clickhouse:
  host: clickhouse-cluster.internal
  port: 8123
  database: analytics
  user: orbita_user
  password: ${CLICKHOUSE_PASSWORD}
  pool_size: 20

metadata_db:
  url: postgresql://orbita:${DB_PASSWORD}@postgres-ha:5432/orbita
  pool_size: 30

redis:
  url: redis://redis-cluster:6379/0

auth:
  enabled: true
  provider: keycloak
  keycloak:
    server_url: https://auth.company.com
    realm: company
    client_id: orbita-api
    client_secret: ${KEYCLOAK_SECRET}

cors:
  allow_origins:
    - "https://orbita.company.com"

rate_limiting:
  enabled: true
  default_limit: "100/minute"

telemetry:
  enabled: true
  tracing:
    enabled: true
    jaeger_endpoint: http://jaeger-collector:14268/api/traces

logging:
  level: INFO
  format: json

Проверка конфигурации¶

Проверьте корректность настроек:

# Проверка переменных окружения
env | grep -E "(LLM|CLICKHOUSE|METADATA)"

# Проверка YAML синтаксиса
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

# Тест подключений
python -m orbita_core.tools.health_check

Следующие шаги¶

Инфраструктура - развертывание Docker Compose
Решение проблем - диагностика ошибок конфигурации