跳转到主要内容
一次尚可，两次可疑，三次就该把超参数做成数据。
配置是由持久化配置存储支撑的分层字典。你像读嵌套数据一样读取它，但 HeavenBase 会替你解析默认值、作用域层、版本历史与插值。

​
1. 为何需要配置

没有配置管理器时，每个最终会调用模型、后端、提示、缓存、基准测试或文件辅助函数的包装层都必须接受并透传相同旋钮：
这种形态无法扩展。高层应用很快变成一串函数，各自携带并不属于自己的参数。改一个默认值就要检查每个包装层。新增一个后端或 LLM 选项会让无关代码的签名一起膨胀。 HeavenBase 用 CM_HVNB 把这些旋钮移入配置数据：
应用代码现在可以读取当前默认值，而不必把每个函数变成配置透传载体。函数仍可保留因其他原因需要的重要参数，不重要的参数可从签名中移除：
旧式基于文件的形态也有硬上限。少量 local/global/default 文件对一名开发者够用，但一个包承载多个应用、环境、用户或实验时会变得混乱。HeavenBase 改为在数据库支持的存储中保留配置层，使每个作用域保留自己的历史，且只覆盖自己拥有的值。

​
2. 核心思想：作用域层与应用覆盖

概括来说，HeavenBase 配置管理器使用 database backend 存储带作用域的 KV 字典。 作用域是命名的覆盖层。宽作用域持有共享默认值；窄作用域只覆盖差异部分。 例如，heavenbase.workspace.docs-demo 按以下顺序解析：
  1. heavenbase
  2. heavenbase.workspace
  3. heavenbase.workspace.docs-demo
若 docs demo 只覆盖 heavenbase.query.near.default_top_k，其余配置值会回退到更宽作用域，最终落到包默认模板。
这就是应用覆盖模式：一次性设置全局基础设施默认值，再为应用、环境、工作区、租户或测试创建子作用域。
在构造会在 __init__ 期间解析配置的对象之前进入作用域。若 LLM、工作区、后端或辅助函数在构造时快照配置，之后改作用域不会改写已构建对象。
作用域是应用代码唯一需要携带的东西。实际模型名、提供商默认值、后端路径、序列化默认值与提示语言可留在配置数据中，而不必穿过每个包装层。

​
3. 读取当前默认值

只需一个值时，从 get(...) 开始：
需要当前合并配置的可变副本时，使用 load()：
load() 返回副本。修改该字典不会写回配置存储。

​
4. 将作用域用作上下文

代码块应读取作用域值时，将 scoped(...) 用作上下文管理器：
同一辅助函数也可用作装饰器：
当活跃应用上下文决定作用域名称时，可由可调用对象提供动态作用域。

​
5. 复用快照

高吞吐读取路径中，保留快照并复用：
快照不可变。配置编辑不会修改你已持有的快照。诊断路径需要立即绕过缓存状态时，请求新快照或调用 CM_HVNB.refresh()。

​
6. 编辑作用域层

配置写入会立即持久化。demo 与测试使用作用域层，以免惊动基础配置层：
列表编辑使用路径语法：
  • items[0] 替换一项。
  • items[] 追加。
  • items[2+] 在索引 2 前插入。
unset(...) 写入 tombstone，使子作用域可隐藏从父作用域继承的值。字典可使用 __HB_OVERWRITE__ 替换父字典，而非递归合并。
remove(...)、compact(..., reset=True) 与 setup(reset=True) 会改变保留的配置数据。仅在你打算清理的作用域上使用它们。

​
7. 检查已存储层

需要父合并与插值前某作用域内原始层时，使用 layer(...)：
每个作用域保留版本历史。默认 heavenbase.config.versioning.keep_last_k 为 10，因此普通编辑会保留近期历史而不会无限增长。

​
8. 使用资源与包路径

resource(...) 在可定位包时解析其 resources/ 目录下的文件。load_default() 返回用于初始化作用域的内存默认配置模板。
CM_HVNB.pj(...) 理解 HeavenBase 包别名，例如 %/ 表示包本地数据、&/ 表示包资源。普通调用方提供的路径请改用文件系统工具中的 pj(...)。详见文件系统。

​
9. 理解插值

OmegaConf 插值在编译快照时解析：
  • ${env:VAR} 默认允许。
  • ${oc.env:VAR,default} 通过 OmegaConf 工作。
  • ${cmd:...} 默认禁用，需要显式策略覆盖。
因此提供商默认值可以读取环境变量，而不必让每个调用点手工解析环境。

​
进一步探索

相关资源：
  • 概览 - 工具箱其余部分。
  • 文件系统 - 配置产物相关的路径与文件辅助函数。
  • CLI 参考 - 同一配置管理器上的 hb config 命令。