3.4 配置管理与优化

配置散落在各处，出问题时你敢说改了哪一处？

在实践的收尾，我们把零散参数收拢到配置。LEANN 的取向是：凡是可能调的，都进配置；凡是进配置的，都有默认值与校验。

下面用一段 schema 风格的配置定义，把维度、索引类型、重排候选数、量化位宽集中起来，并带类型校验。

CONFIG_SCHEMA = {
    'dim':            {'type': int,   'default': 64},
    'index_kind':     {'type': str,   'default': 'hnsw', 'allowed': ['flat', 'hnsw', 'ivf']},
    'rerank_candidates': {'type': int, 'default': 30},
    'quant_bits':     {'type': int,   'default': 8,  'allowed': [8, 16, 32]},
}

def load_config(raw):
    cfg = {}
    for k, spec in CONFIG_SCHEMA.items():
        v = raw.get(k, spec['default'])
        if not isinstance(v, spec['type']):
            raise ValueError(f'{k} 类型应为 {spec["type"]}')
        if 'allowed' in spec and v not in spec['allowed']:
            raise ValueError(f'{k}={v} 不在 {spec["allowed"]}')
        cfg[k] = v
    return cfg

print(load_config({'dim': 64, 'index_kind': 'hnsw'}))
​

这段配置的取向是「失败在加载时」：类型错、取值非法，立刻报错，而不是在检索到一半才崩。我们主张配置校验宁可严格，也不要「默默用默认值」掩盖错误。

配置还要支持环境覆盖。下面给出「配置优先级」的实现：命令行 > 环境变量 > 文件默认值。

import os

def resolve(key, file_val):
    # 优先级：环境变量覆盖文件
    env = os.environ.get(f'LEANN_{key.upper()}')
    return int(env) if env is not None else file_val

print('dim 实际值:', resolve('dim', 64))   # 设 LEANN_DIM=128 即覆盖
​

案例：量化位宽写错进生产

• 背景：某次把 quant_bits 手改成 4（不支持），索引加载后召回全乱。
• 操作：接入上面的 load_config 校验，allowed 限制为 8/16/32，启动即报非法。
• 结果：错误被拦在加载阶段，没进生产，排查时间从数小时降到数秒。
• 解读：配置校验是低成本高回报的护栏，尤其多人协作时。
• 变式：可把配置 diff 接进评审，任何参数改动都留痕可追溯。

配置还会遇到「运行中要改」的需求。比如灰度时想临时把 rerank_candidates 调小观察延迟。下面给出最小化热加载：监听配置文件 mtime，变化即重校验并重载，不重启进程。

import os

class HotConfig:
    def __init__(self, path, schema):
        self.path = path
        self.schema = schema
        self.mtime = 0
        self.cfg = None
        self.reload()
    def reload(self):
        if os.path.getmtime(self.path) == self.mtime:
            return False
        self.mtime = os.path.getmtime(self.path)
        raw = _read(self.path)
        self.cfg = load_config(raw)   # 复用前面的校验
        return True

def _read(p):
    return {}

print('热加载骨架已定义')
​

热加载的坑在「中途失败」：新配置非法时，应保留旧配置继续服务，而不是让进程崩。我们主张校验不过就拒绝新值并告警通知，旧配置照常生效，可用性优先于「立即生效」。

配置管理还有一层容易被忽略：配置的「可读性」也是生产力。我们见过把上百个参数平铺成一长串的写法，改一个要在一屏幕里找半天。更好的做法是按模块分组，索引归索引、重排归重排、监控归监控，让人一眼能定位该改哪一块。分组不增加功能，但显著降低改错的概率。

另外，配置的变更要可回溯。生产环境出了事，第一句话往往是「谁改了什么」。如果配置散在多处、靠手改，根本答不上来。所以我们主张配置进版本控制，每次改动走评审，diff 就是天然的变更记录。结合上面讲的热加载，你能做到「改了但可回溯、生效但不用重启」，这才是配置管理的完整闭环。

配置评审还有个容易被忽略的对象：默认值本身。默认值是最常被「无意识采用」的配置，如果默认不安全或不省资源，大多数人会原样带着走。所以我们对默认值格外挑剔，宁可默认偏保守，让用户显式放宽，也不让宽松默认值悄悄进生产。

另一个经验是配置项的命名要自解释。见到 rerank_candidates 就知道是重排候选数，见到 rc 就要查文档。命名省的那两个字母，会在每次有人困惑时加倍奉还。配置的读者是人，可读性不是美化，是正确性的一部分。当配置项多到一定程度，要考虑分层：基础层锁住、调优层开放，既给灵活度又守底线。

我们还建议给关键配置项加一句注释说明「改它会影响什么」。配置散在文件里，改的人往往不是写的人，一句影响说明能避免大量误改。这和我们全书强调的「失败可见、改动可追溯」是一脉相承的。

配置管理的成熟度，最终体现在「新人改一个参数不心慌」。当分组清晰、默认值稳妥、变更可回溯，改配置从冒险变成日常，团队迭代速度自然就上来了。

顺带一提，配置的文档化常被低估。把每个配置项的含义、默认值、可调范围写进配置旁边而非另一份 wiki，改配置的人能就地看到来龙去脉。wiki 会过时，代码旁的说明起码和代码一起被评审。我们主张「配置即文档」，让说明和值待在一起，维护成本最低，误用概率也最低。

本节可考核点：能说出配置集中与校验的好处，并解释「优先级覆盖」如何兼顾默认值与环境差异。