《AI Agent 工程实战》2.1 分层配置：pydantic-settings 加载与校验

# 反面写法：配置散落、无校验
import os

MODEL = os.environ.get("MODEL", "claude-sonnet-4-5")
TIMEOUT = float(os.environ.get("TIMEOUT", "30"))
MAX_STEPS = int(os.environ.get("MAX_STEPS", "8"))
DB = os.environ["DATABASE_URL"]  # 缺了就在这里 KeyError

# researchcopilot/config.py
from __future__ import annotations

from typing import Literal

from pydantic import Field
from pydantic_settings import (
    BaseSettings,
    JsonConfigSettingsSource,
    PydanticBaseSettingsSource,
    SettingsConfigDict,
)


class Settings(BaseSettings):
    """ResearchCopilot 的运行时配置。"""

    model_config = SettingsConfigDict(
        env_prefix="RESEARCH_",
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )

    # 推理
    model_name: str = "claude-sonnet-4-5"
    max_steps: int = Field(default=8, ge=1, le=32)
    request_timeout_s: float = Field(default=30.0, gt=0)

    # 数据层
    database_url: str = "postgresql://postgres:postgres@localhost:15435/research"
    redis_url: str = "redis://localhost:16380/0"

    # 路由
    log_level: Literal["debug", "info", "warning", "error"] = "info"
    use_fake_model: bool = True

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        # 优先级从高到低：显式参数 > 环境变量 > .env > research.json > 默认值
        return (
            init_settings,
            env_settings,
            dotenv_settings,
            JsonConfigSettingsSource(settings_cls, json_file="research.json"),
            file_secret_settings,
        )

# run_config_demo.py
import json
import os
import tempfile
from pathlib import Path

from pydantic import ValidationError

from researchcopilot.config import Settings

work = Path(tempfile.mkdtemp(prefix="rc-cfg-"))
os.chdir(work)


def show(tag: str, s: Settings) -> None:
    print(f"{tag:<14} model_name={s.model_name:<18} max_steps={s.max_steps:<3} log_level={s.log_level}")


print("== 四级来源合并（优先级 低 -> 高） ==")
show("① 默认值", Settings())

(work / "research.json").write_text(
    json.dumps({"model_name": "claude-haiku-4-5", "max_steps": 12}), encoding="utf-8"
)
show("② 配置文件", Settings())

os.environ["RESEARCH_MODEL_NAME"] = "claude-opus-4-1"
os.environ["RESEARCH_LOG_LEVEL"] = "debug"
show("③ 环境变量", Settings())

show("④ 显式参数", Settings(model_name="claude-sonnet-4-5", max_steps=4))

print()
print("== 非法值被拒绝 ==")
try:
    Settings(max_steps=0)
except ValidationError as e:
    print(e)

== 四级来源合并（优先级 低 -> 高） ==
① 默认值          model_name=claude-sonnet-4-5  max_steps=8   log_level=info
② 配置文件         model_name=claude-haiku-4-5   max_steps=12  log_level=info
③ 环境变量         model_name=claude-opus-4-1    max_steps=12  log_level=debug
④ 显式参数         model_name=claude-sonnet-4-5  max_steps=4   log_level=debug

== 非法值被拒绝 ==
1 validation error for Settings
max_steps
  Input should be greater than or equal to 1 [type=greater_than_equal, input_value=0, input_type=int]
    For further information visit https://errors.pydantic.dev/2.14/v/greater_than_equal

# 反面写法：模块顶层读环境变量
import os

DB = os.environ["DATABASE_URL"]  # 导入即执行，无法在测试里替换


class RetrievalService:
    def query(self, q: str) -> list[str]:
        return _hit(os.environ["DATABASE_URL"], q)  # 又一次全局读取

# 正面写法：依赖注入
from researchcopilot.config import Settings


class RetrievalService:
    def __init__(self, settings: Settings) -> None:
        self._dsn = settings.database_url
        self._timeout = settings.request_timeout_s

    def query(self, q: str) -> list[str]:
        return _hit(self._dsn, q, timeout=self._timeout)

# researchcopilot/config.py（续）
from functools import lru_cache


@lru_cache(maxsize=1)
def get_settings() -> Settings:
    return Settings()