swanlab.Settings: 全局功能管理

[SAKURA-CAT]

正如 #883 所述，我们希望增加swanlab.Settings这个数据类型以提高swanlab功能的定制化需求。

[SAKURA-CAT]

可能的方案

这里主要讨论swanlab.Settings的实现方案，目前有两种：

1. 使用dataclasses实现
2. 使用pydantic实现

目前的方案是优先使用pydantic ，因为它提供了更可靠的参数校验逻辑，但是需要探索一下它的不可变模式的可行性（没怎么用过）这块需要测试一下，没问题就可以使用了。

---

下面是在ai帮助下的相关探索：

一、两种实现方案的对比

1. 方案 1：基于 dataclasses 的实现

from dataclasses import dataclass, replace

@dataclass(frozen=True)
class Settings:
    project: str = "default"
    experiment_name: str = "exp-1"
    max_retries: int = 3

    def update(self, **kwargs):
        return replace(self, **kwargs)

优点：

• 轻量级：无额外依赖，适合简单配置模型。
• 不可变性：frozen=True 天然保证实例安全。
• 语法简洁：replace 方法直接生成新实例。

缺点：

• 无内置校验：需手动在 __post_init__ 中添加校验逻辑。
• 类型转换缺失：无法自动处理 "5" → 5 的字符串到整型的转换。
• 序列化困难：需自行实现 to_dict() 或 to_json() 方法。
• 扩展性差：复杂类型（如 Union、嵌套模型）难以支持。

---

2. 方案 2：基于 pydantic 的实现

from pydantic import BaseModel, Field, field_validator

class Settings(BaseModel):
    project: str = Field(default="default", min_length=1)
    experiment_name: str = "exp-1"
    max_retries: int = Field(ge=1, le=10)

    @field_validator("experiment_name")
    def validate_name(cls, v):
        if "_" in v:
            raise ValueError("Name cannot contain underscores")
        return v

    # 启用不可变模式
    model_config = {"frozen": True}

    def update(self, **kwargs):
        return self.model_copy(update=kwargs)

优点：

• 内置校验：支持字段级校验（Field）和自定义校验器（@validator）。
• 自动类型转换：max_retries="5" 会被自动转为整型 5。
• 序列化原生支持：直接调用 .model_dump() 或 .model_dump_json()。
• 复杂类型支持：轻松处理嵌套模型、Union、Literal 等类型。
• 不可变模式：通过 model_config = {"frozen": True} 实现安全配置。

缺点：

• 依赖第三方库：需安装 pydantic。
• 性能略低：校验和转换带来微小开销（但对配置类场景可忽略）。

---

二、Pydantic 不可变模式的关键验证点

1. 不可变性的行为验证

settings = Settings(project="swanlab", max_retries=5)
settings.project = "new"  # 触发 ValidationError: "Settings" instance is frozen

2. 更新操作的可行性

new_settings = settings.model_copy(update={"project": "new_project"})
assert new_settings.project == "new_project"  # 生成新实例而非修改原对象

3. 嵌套模型的不可变性

class NestedSettings(Settings):
    tags: list[str] = []

nested = NestedSettings(tags=["ai", "ml"])
nested.tags.append("dl")  # 触发 ValidationError: 列表本身可变，需额外处理

解决方案：

• 对可变字段（如 list、dict）使用 immutables 库或冻结容器。
• 或使用 Pydantic 的 Strict 模式禁止直接修改：

  class StrictSettings(Settings):
      model_config = {"frozen": True, "strict": True}

---

三、Pydantic 方案的核心优势

1. 校验能力的可靠性

• 字段级约束：通过 Field(ge=1, regex="^[a-z]+$") 声明约束。
• 动态校验：使用 @field_validator 实现跨字段校验。
• 错误信息友好：自动生成清晰的错误提示：

  ValidationError: 1 validation error for Settings
  max_retries
    Input should be less than or equal to 10 [type=less_than_equal]
  

2. 序列化与反序列化

# 从 JSON 文件加载配置
with open("config.json") as f:
    settings = Settings.model_validate_json(f.read())

# 导出为环境变量
os.environ.update(settings.model_dump(by_alias=True))

3. 与生态系统的集成

• FastAPI 兼容：若未来需要暴露配置 API，可直接复用模型。
• IDE 支持：VS Code/PyCharm 对 Pydantic 字段类型和校验有智能提示。
• 文档生成：自动生成 JSON Schema，方便配置文档化。

---

四、总结

推荐采用 Pydantic 实现，其不可变模式完全满足配置类的安全需求，且在校验、序列化、类型系统等方面的能力远超 dataclasses。唯一需要验证的 嵌套可变字段 问题（如列表修改），可通过代码规范或辅助库规避。对于 SwanLab 的场景，Pydantic 能显著降低长期维护成本，并为未来扩展（如动态配置加载、API 集成）提供坚实基础。