> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置

> 基于 CM_HVNB 的作用域配置。

<Note>
  *一次尚可，两次可疑，三次就该把超参数做成数据。*
</Note>

配置是由持久化配置存储支撑的分层字典。你像读嵌套数据一样读取它，但 HeavenBase 会替你解析默认值、作用域层、版本历史与插值。

<br />

## 1. 为何需要配置

没有配置管理器时，每个最终会调用模型、后端、提示、缓存、基准测试或文件辅助函数的包装层都必须接受并透传相同旋钮：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def enrich_user(
    user_id: str,
    model: str = "ds-flash",
    temperature: float = 0.0,
    seed: int = 42,
    timeout: int = 120,
    embedding_batch_size: int = 256,
):
    ...
```

这种形态无法扩展。高层应用很快变成一串函数，各自携带并不属于自己的参数。改一个默认值就要检查每个包装层。新增一个后端或 LLM 选项会让无关代码的签名一起膨胀。

HeavenBase 用 `CM_HVNB` 把这些旋钮移入配置数据：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

model = CM_HVNB.get("heavenbase.llm.presets.chat.model")
timeout = CM_HVNB.get("heavenbase.llm.default_args.timeout", default=120)
```

应用代码现在可以读取当前默认值，而不必把每个函数变成配置透传载体。函数仍可保留因其他原因需要的重要参数，不重要的参数可从签名中移除：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def enrich_user(user_id: str, model: str = None, embedding_batch_size: int = None):
    model = str(model or CM_HVNB.get("heavenbase.llm.presets.chat.model", default="ds-flash"))
    temperature = float(CM_HVNB.get("heavenbase.llm.default_args.temperature", default=0.0))
    seed = int(CM_HVNB.get("heavenbase.llm.default_args.seed", default=42))
    timeout = int(CM_HVNB.get("heavenbase.llm.default_args.timeout", default=120))
    embedding_batch_size = int(embedding_batch_size or CM_HVNB.get("heavenbase.llm.default_args.embedding_batch_size", default=256))
    ...
```

旧式基于文件的形态也有硬上限。少量 local/global/default 文件对一名开发者够用，但一个包承载多个应用、环境、用户或实验时会变得混乱。HeavenBase 改为在数据库支持的存储中保留配置层，使每个作用域保留自己的历史，且只覆盖自己拥有的值。

<br />

## 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`，其余配置值会回退到更宽作用域，最终落到包默认模板。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

scope = "heavenbase.workspace.docs-demo"
CM_HVNB.set("heavenbase.query.near.default_top_k", 25, scope=scope)

with CM_HVNB.scoped("workspace.docs-demo"):
    assert CM_HVNB.scope == scope
    top_k = CM_HVNB.get("heavenbase.query.near.default_top_k")
```

这就是应用覆盖模式：一次性设置全局基础设施默认值，再为应用、环境、工作区、租户或测试创建子作用域。

<Tip>
  在构造会在 `__init__` 期间解析配置的对象之前进入作用域。若 `LLM`、工作区、后端或辅助函数在构造时快照配置，之后改作用域不会改写已构建对象。
</Tip>

<Info>
  作用域是应用代码唯一需要携带的东西。实际模型名、提供商默认值、后端路径、序列化默认值与提示语言可留在配置数据中，而不必穿过每个包装层。
</Info>

<br />

## 3. 读取当前默认值

只需一个值时，从 `get(...)` 开始：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

top_k = CM_HVNB.get("heavenbase.query.near.default_top_k", default=50)
metric = CM_HVNB.get("heavenbase.query.near.default_metric", default="cosine")
```

需要当前合并配置的可变副本时，使用 `load()`：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

config = CM_HVNB.load()
workspace_presets = config["heavenbase"]["workspace"]["presets"]
```

<Note>
  `load()` 返回副本。修改该字典不会写回配置存储。
</Note>

<br />

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

代码块应读取作用域值时，将 `scoped(...)` 用作上下文管理器：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

with CM_HVNB.scoped("workspace.docs-demo"):
    top_k = CM_HVNB.get("heavenbase.query.near.default_top_k")
```

同一辅助函数也可用作装饰器：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

@CM_HVNB.scoped("workspace.docs-demo")
def read_metric() -> str:
    return CM_HVNB.get("heavenbase.query.near.default_metric")
```

当活跃应用上下文决定作用域名称时，可由可调用对象提供动态作用域。

<br />

## 5. 复用快照

高吞吐读取路径中，保留快照并复用：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

snap = CM_HVNB.snapshot()
top_k = snap.get("heavenbase.query.near.default_top_k")
metric = snap.get("heavenbase.query.near.default_metric")
```

快照不可变。配置编辑不会修改你已持有的快照。诊断路径需要立即绕过缓存状态时，请求新快照或调用 `CM_HVNB.refresh()`。

<br />

## 6. 编辑作用域层

配置写入会立即持久化。demo 与测试使用作用域层，以免惊动基础配置层：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

scope = "heavenbase.workspace.docs-demo"

CM_HVNB.set("heavenbase.query.near.default_top_k", 25, scope=scope)
CM_HVNB.setdef("heavenbase.query.near.default_metric", "cosine", scope=scope)
CM_HVNB.unset("heavenbase.backends.vec", scope=scope)
```

列表编辑使用路径语法：

* `items[0]` 替换一项。
* `items[]` 追加。
* `items[2+]` 在索引 2 前插入。

`unset(...)` 写入 tombstone，使子作用域可隐藏从父作用域继承的值。字典可使用 `__HB_OVERWRITE__` 替换父字典，而非递归合并。

<Warning>
  `remove(...)`、`compact(..., reset=True)` 与 `setup(reset=True)` 会改变保留的配置数据。仅在你打算清理的作用域上使用它们。
</Warning>

<br />

## 7. 检查已存储层

需要父合并与插值前某作用域内原始层时，使用 `layer(...)`：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

layer = CM_HVNB.layer(scope="heavenbase.workspace.docs-demo")
history = CM_HVNB.history(scope="heavenbase.workspace.docs-demo", limit=5)
known_scopes = CM_HVNB.scopes()
```

每个作用域保留版本历史。默认 `heavenbase.config.versioning.keep_last_k` 为 `10`，因此普通编辑会保留近期历史而不会无限增长。

<br />

## 8. 使用资源与包路径

`resource(...)` 在可定位包时解析其 `resources/` 目录下的文件。`load_default()` 返回用于初始化作用域的内存默认配置模板。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import CM_HVNB

default_yaml = CM_HVNB.resource("configs", "default.yaml")
config_db = CM_HVNB.pj("%/config.db", abs=True)
default_template = CM_HVNB.load_default()
```

`CM_HVNB.pj(...)` 理解 HeavenBase 包别名，例如 `%/` 表示包本地数据、`&/` 表示包资源。普通调用方提供的路径请改用文件系统工具中的 `pj(...)`。详见[文件系统](/zh/features/utilities/file-system)。

<br />

## 9. 理解插值

OmegaConf 插值在编译快照时解析：

* `${env:VAR}` 默认允许。
* `${oc.env:VAR,default}` 通过 OmegaConf 工作。
* `${cmd:...}` 默认禁用，需要显式策略覆盖。

因此提供商默认值可以读取环境变量，而不必让每个调用点手工解析环境。

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [概览](/zh/features/utilities/overview) - 工具箱其余部分。
  * [文件系统](/zh/features/utilities/file-system) - 配置产物相关的路径与文件辅助函数。
  * [CLI 参考](/zh/reference/cli/overview) - 同一配置管理器上的 `hb config` 命令。
</Tip>

<br />