AI Agents · Урок

Профили конфигурации для разработки и продакшена

Конфигурации для разных окружений, флаги функций и поэтапные развёртывания.

«Профили конфигурации для разработки и продакшена» — бесплатный урок AI Agents на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.

Почему важны профили Config

Агент для рабочей среды и агент для разработки должны вести себя по-разному: использовать разные уровни журналирования, разные уровни моделей (стоимость и качество), разные базы данных и разные лимиты частоты запросов. Профили конфигурации делают это автоматически: одна переменная окружения переключает все параметры одновременно.

Определение окружения с помощью переменной ENV

Стандартный подход заключается в считывании переменной ENV (или ENVIRONMENT), которая определяет текущий контекст развертывания. Затем код выбирает подходящий профиль конфигурации на основе этого значения.

import os

# Read the environment identifier
ENV = os.getenv('ENV', 'development').lower()

if ENV not in ('development', 'staging', 'production'):
    raise ValueError(
        f'Invalid ENV value: "{ENV}". '
        f'Must be: development, staging, or production'
    )

print(f'Running in {ENV} mode')

# Usage:
# ENV=development python agent.py   -> dev settings
# ENV=staging python agent.py       -> staging settings
# ENV=production python agent.py    -> prod settings
# python agent.py                   -> defaults to development

Классы Config для каждого окружения

Определите базовый класс конфигурации и производные классы для каждого окружения. Каждый производный класс переопределяет отличающиеся значения. Такой подход более понятен и лучше обеспечивает проверку типов, чем большой словарь с условными конструкциями.

import os

class BaseConfig:
    OPENAI_API_KEY: str = os.environ.get('OPENAI_API_KEY', '')
    MAX_STEPS: int = 20
    LOG_LEVEL: str = 'INFO'
    CACHE_ENABLED: bool = True
    CACHE_TTL_SECONDS: int = 3600

class DevelopmentConfig(BaseConfig):
    MODEL: str = 'gpt-4o-mini'  # cheaper in dev
    LOG_LEVEL: str = 'DEBUG'    # verbose logging in dev
    CACHE_ENABLED: bool = False  # fresh results in dev
    MAX_STEPS: int = 10          # shorter loops in dev

class StagingConfig(BaseConfig):
    MODEL: str = 'gpt-4o-mini'
    LOG_LEVEL: str = 'INFO'
    MAX_STEPS: int = 20

class ProductionConfig(BaseConfig):
    MODEL: str = 'gpt-4o'       # best quality in prod
    LOG_LEVEL: str = 'WARNING'  # less noise in prod
    MAX_STEPS: int = 30         # more steps allowed in prod

if __name__ == '__main__':
    for cls in (DevelopmentConfig, StagingConfig, ProductionConfig):
        c = cls()
        print(f'{cls.__name__}: model={c.MODEL} log_level={c.LOG_LEVEL} max_steps={c.MAX_STEPS} cache={c.CACHE_ENABLED}')

Фабрика Config: выбор подходящего профиля

Функция-фабрика конфигурации считывает переменную ENV и возвращает соответствующий класс конфигурации. Эта единственная функция содержит всю логику переключения окружения.

import os

def get_config():
    env = os.getenv('ENV', 'development').lower()
    configs = {
        'development': DevelopmentConfig,
        'staging': StagingConfig,
        'production': ProductionConfig
    }
    config_class = configs.get(env)
    if not config_class:
        raise ValueError(f'Unknown environment: {env}')
    return config_class()

# Usage throughout your agent:
config = get_config()
print(f'Model: {config.MODEL}')
print(f'Max steps: {config.MAX_STEPS}')
print(f'Log level: {config.LOG_LEVEL}')

# All code uses config.MODEL, config.LOG_LEVEL etc.
# Switching environments requires only changing ENV variable

Настройки Pydantic для типизированной конфигурации

pydantic-settings предоставляет мощный и безопасный с точки зрения типов способ определения конфигурации. Пакет автоматически считывает переменные окружения, проверяет типы и может загружать данные из файлов .env. Установите его с помощью команды pip install pydantic-settings.

# pip install pydantic-settings
from pydantic_settings import BaseSettings
from pydantic import Field
from typing import Literal

class AgentSettings(BaseSettings):
    # Required fields — raise error if not set
    openai_api_key: str
    search_api_key: str

    # Optional with defaults
    env: Literal['development', 'staging', 'production'] = 'development'
    model: str = 'gpt-4o-mini'
    max_steps: int = Field(default=20, ge=1, le=100)  # validated range
    log_level: str = 'INFO'
    cache_enabled: bool = True
    cache_ttl_seconds: int = Field(default=3600, ge=60)

    class Config:
        env_file = '.env'
        case_sensitive = False  # OPENAI_API_KEY -> openai_api_key

# settings = AgentSettings()  # raises ValidationError if required vars missing

Настройки Pydantic с переопределениями для конкретных окружений

Объединяйте Pydantic Settings с вычисляемыми свойствами, чтобы задавать значения по умолчанию для конкретного окружения, которые по-прежнему можно переопределить переменными окружения.

from pydantic_settings import BaseSettings
from pydantic import model_validator
import os

class AgentSettings(BaseSettings):
    openai_api_key: str
    env: str = 'development'
    model: str = ''
    log_level: str = ''
    max_steps: int = 0

    @model_validator(mode='after')
    def apply_env_defaults(self) -> 'AgentSettings':
        env_defaults = {
            'development': {'model': 'gpt-4o-mini', 'log_level': 'DEBUG', 'max_steps': 10},
            'staging':     {'model': 'gpt-4o-mini', 'log_level': 'INFO',  'max_steps': 20},
            'production':  {'model': 'gpt-4o',      'log_level': 'WARNING', 'max_steps': 30}
        }
        defaults = env_defaults.get(self.env, env_defaults['development'])
        if not self.model:     self.model     = defaults['model']
        if not self.log_level: self.log_level = defaults['log_level']
        if not self.max_steps: self.max_steps = defaults['max_steps']
        return self

    class Config:
        env_file = '.env'

Флаги функций для каждого окружения

Используйте профили конфигурации, чтобы включать или отключать функции в разных окружениях. Например, включайте отладочный интерфейс только при разработке, используйте реальные платежи только в рабочей среде и направляйте запросы к изолированным тестовым сервисам в промежуточной среде.

import os

class AgentFeatureFlags:
    env = os.getenv('ENV', 'development')

    # Enable memory persistence (requires DB)
    MEMORY_ENABLED: bool = env in ('staging', 'production')

    # Use real payment processing
    REAL_PAYMENTS: bool = env == 'production'

    # Enable verbose step-by-step output
    VERBOSE_STEPS: bool = env == 'development'

    # Use cheap model for unit test runs
    FORCE_MINI_MODEL: bool = os.getenv('CI') == 'true'

flags = AgentFeatureFlags()
print(f'Memory: {flags.MEMORY_ENABLED}')
print(f'Verbose: {flags.VERBOSE_STEPS}')
print(f'Payments: {flags.REAL_PAYMENTS}')

Проверка конфигурации при запуске

Проверяйте всю конфигурацию при запуске и выводите сводку, чтобы операторы могли убедиться в правильности настроек агента до начала обработки. Это предотвращает незаметные ошибки конфигурации в рабочей среде.

import os
import sys

def validate_and_print_config(config) -> None:
    print(f'=== Agent Configuration ===')
    print(f'Environment : {config.env}')
    print(f'Model       : {config.model}')
    print(f'Max steps   : {config.max_steps}')
    print(f'Log level   : {config.log_level}')
    print(f'Cache       : {"enabled" if config.cache_enabled else "disabled"}')
    print(f'OpenAI key  : ...{config.openai_api_key[-4:]}')
    print('===========================')

    # Critical validations
    if config.env == 'production' and config.log_level == 'DEBUG':
        print('WARNING: DEBUG logging in production exposes sensitive data!')

    if not config.openai_api_key:
        print('FATAL: OPENAI_API_KEY not set')
        sys.exit(1)

    print('Configuration validated.')

if __name__ == '__main__':
    from types import SimpleNamespace
    demo_config = SimpleNamespace(
        env='development', model='gpt-4o-mini', max_steps=10,
        log_level='DEBUG', cache_enabled=False, openai_api_key='sk-demo-1234'
    )
    validate_and_print_config(demo_config)

Переопределение значений Config для каждого окружения

В конвейерах CI/CD переопределяйте отдельные значения конфигурации, не изменяя весь профиль. Передавайте отдельные переменные вместе с переменной ENV, чтобы настроить параметры для конкретного развертывания.

# Staging deployment with custom model override:
# ENV=staging AGENT_MODEL=gpt-4o python agent.py

# Production with reduced max_steps for cost control:
# ENV=production AGENT_MAX_STEPS=15 python agent.py

# CI test run — use production profile but with cheap model:
# ENV=production AGENT_MODEL=gpt-4o-mini CI=true python agent.py

# The config class reads ENV first for the profile,
# then individual overrides take precedence:
import os

env = os.getenv('ENV', 'development')
config = get_config()  # loads base profile for env

# Individual overrides applied on top:
if os.getenv('AGENT_MODEL'):
    config.MODEL = os.getenv('AGENT_MODEL')
if os.getenv('AGENT_MAX_STEPS'):
    config.MAX_STEPS = int(os.getenv('AGENT_MAX_STEPS'))

print(f'Final model: {config.MODEL}')

Документирование профилей Config для коллег

Четко документируйте профили конфигурации: в комментариях к коду, в README или в обоих местах. Новым разработчикам необходимо понимать различия между окружениями, чтобы уверенно выполнять развертывание.

# config_profiles.py — Configuration per environment
#
# | Setting        | development    | staging        | production  |
# |----------------|----------------|----------------|-------------|
# | MODEL          | gpt-4o-mini    | gpt-4o-mini    | gpt-4o      |
# | MAX_STEPS      | 10             | 20             | 30          |
# | LOG_LEVEL      | DEBUG          | INFO           | WARNING     |
# | CACHE_ENABLED  | False          | True           | True        |
# | MEMORY_DB      | SQLite (local) | PostgreSQL     | PostgreSQL  |
#
# To switch environments:
#   ENV=staging python agent.py
#
# To override a single setting:
#   ENV=production AGENT_MAX_STEPS=15 python agent.py

print('Config profile table documents all per-environment differences')

Config в тестах: принудительный тестовый профиль

Тесты всегда должны выполняться с определенной тестовой конфигурацией, а не с настройками рабочей среды. Создайте тестовый конфигурационный fixture, который применяет подходящие параметры и предотвращает случайные вызовы API рабочей среды.

import os
import pytest

@pytest.fixture(autouse=True)
def test_environment(monkeypatch):
    'Force test configuration for all tests'
    monkeypatch.setenv('ENV', 'test')
    monkeypatch.setenv('AGENT_MODEL', 'gpt-4o-mini')
    monkeypatch.setenv('AGENT_MAX_STEPS', '5')  # short loops in tests
    monkeypatch.setenv('LOG_LEVEL', 'DEBUG')
    monkeypatch.setenv('CACHE_ENABLED', 'false')
    # Use a fake API key — tests should mock all LLM calls
    monkeypatch.setenv('OPENAI_API_KEY', 'test-key-not-real')

# This fixture runs before every test automatically
# Tests cannot accidentally use production settings

Проверка знаний: профили конфигурации

Проверьте свое понимание профилей конфигурации для разных окружений.

Итоги: профили конфигурации для разработки и рабочей среды

Теперь у вас есть полная стратегия управления конфигурацией агентов в разных окружениях:

Используйте переменную ENV, чтобы определить контекст развертывания
Определяйте классы конфигурации для каждого окружения с подходящими значениями по умолчанию
Используйте фабрику конфигурации для автоматического выбора подходящего профиля
Используйте pydantic-settings для безопасной с точки зрения типов и проверяемой конфигурации
Используйте флаги функций, чтобы включать и отключать функции в разных окружениях
Проверяйте и выводите конфигурацию при запуске, чтобы операторы могли убедиться в правильности настроек
Принудительно задавайте тестовую конфигурацию в фикстурах pytest, чтобы предотвратить вызовы рабочей среды

Грамотное управление конфигурацией позволяет безопасно развертывать одну и ту же кодовую базу в окружениях разработки, промежуточной и рабочей среде.

Часто задаваемые вопросы

Урок «Профили конфигурации для разработки и продакшена» бесплатный?

Да — полный текст урока «Профили конфигурации для разработки и продакшена» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.

Чему я научусь в уроке «Профили конфигурации для разработки и продакшена»?

Конфигурации для разных окружений, флаги функций и поэтапные развёртывания. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI Agents?

Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Профили конфигурации для разработки и продакшена»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI Agents?

Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Переменные окружения для агентов
Файлы .env и python-dotenv
Ротация секретов и безопасность
Профили конфигурации для разработки и продакшена

← Назад к AI Agents