5.2 部署与配置指南

配置即策略

本节在实践章的第二站：把底座变成能跑的任务，靠一份配置。全册里这份配置把第二章的模块职责（2.2）和第三章的算法参数（3.1 奖励、3.2 预算）翻译成可改的旋钮。我们给一个直接定义：配置文件是"研究策略的结构化声明"——它不说怎么实现，只说要什么行为。改配置不改代码，是工程成熟度的标志。

一份最小配置包含五类旋钮。其一，模型：规划/抽取/成文各用什么（呼应 3.5 分工）。其二，检索后端：接哪个搜索接口、网页代理是否启用。其三，循环上限：最大检索步数，防无限循环。其四，早停阈值：信息增益低于此值就结束（呼应 3.2 预算）。其五，诚实护栏：不确定占比超阈值转人工（呼应 4.4）。下面用代码给出一份可校验的配置结构与默认值。

# 研究任务配置：五类旋钮 + 默认值校验
DEFAULT_CFG = {
    "models": {"planner": "strong", "extractor": "mid", "writer": "strong"},
    "retrieval": {"search_api": "on", "web_agent": "on", "max_sources": 30},
    "loop": {"max_steps": 20, "early_stop_gain": 0.05},
    "honesty": {"uncertain_gate": 0.3, "route_human": True},
    "budget": {"token_cap": 200000},
}

def validate_cfg(cfg: dict) -> list:
    problems = []
    if cfg["loop"]["max_steps"] <= 0:
        problems.append("max_steps 必须为正")
    if not (0 < cfg["honesty"]["uncertain_gate"] < 1):
        problems.append("uncertain_gate 应在 0 到 1 之间")
    if cfg["retrieval"]["max_sources"] > 50:
        problems.append("max_sources 过大 易灌水降质")
    if cfg["budget"]["token_cap"] <= 0:
        problems.append("token_cap 必须为正")
    return problems

# 运行示例：一份合理配置
print(validate_cfg(DEFAULT_CFG))   # []
# 一份错误配置
bad = {**DEFAULT_CFG, "honesty": {"uncertain_gate": 1.5, "route_human": True}}
print(validate_cfg(bad))           # ['uncertain_gate 应在 0 到 1 之间']
​

运行输出先空列表（配置合法），后指出 uncertain_gate 越界。这类校验能在启动前拦掉"护栏失效"的配置——比如把不确定闸门设成 1.5，等于永不触发人工，诚实护栏形同虚设。配置即策略，校验即安全闸。

我们主张：配置必须可版本化、可对比。每次调参都提交一份配置，配第四章的综合分（4.5），你才能说清"哪次改动让研究变好"。口头调参无法复现，是部署阶段最常见的烂账。把旋钮写进文件，研究质量才可被实验。

混合部署（呼应 2.1 定位）在配置里体现为"数据分级路由"。敏感数据走本地模型，公开检索走云端。下面演示路由逻辑：

# 混合部署路由：按数据标签选模型位置
def route(query_tags: list, cfg: dict) -> str:
    if "internal" in query_tags or "confidential" in query_tags:
        return cfg["models"]["planner"] + "@local"   # 敏感留本地
    return cfg["models"]["planner"] + "@cloud"        # 公开上云端

print(route(["internal"], DEFAULT_CFG))   # strong@local
print(route(["public"], DEFAULT_CFG))     # strong@cloud
​

输出 strong@local 与 strong@cloud——同一 planner 因数据标签不同落到不同位置。路由依据不是模型能力，是数据敏感性，这正是 2.1 定位原则的部署落地。

完整案例：背景→操作→结果→解读→变式

• 背景：团队把含客户名的查询也发去云端模型，触发合规告警。
• 操作：在配置加 query_tags 识别，敏感标签走 route 的本地分支。
• 结果：含敏感字段的查询全部本地处理，合规告警归零，公开部分仍用云端保质量。
• 解读：配置里的路由旋钮一次设置，永久规避一类合规事故。
• 变式：若完全离线环境，把云端分支也指向本地，配置退化成纯本地部署，无需改代码。

把配置版本化还有个隐性收益：事故可回溯。某次报告出错，翻配置历史发现是有人把 max_sources 从 30 改成 50 想"多抓点"，结果灌水降质（呼应 4.3 冗余）。一行配置改动，复盘时一目了然，责任与修复都快。反之口头调参，出错只能靠人回忆"那天改了啥"，往往查不清。配置即文档、即审计日志，这是工程成熟度的硬指标，不是锦上添花。

最后提醒：配置里最容易漏的是"失败默认"。比如 web_agent 关了，检索就只剩搜索接口，系统应默认降级而非报错。把降级路径也写进配置（如 fallback 搜-only），比在代码里散落 if 更稳。配置覆盖的行为越全，系统越可预期——这点和 5.5 的失败可预期同源。

配置还有"环境差异"要处理。同一份配置在开发机、预发、生产三处表现可能不同——生产检索后端慢、限流严，早停阈值就得放宽。所以配置应是"基础加环境覆盖"：基础定行为，环境层调阈值。我们见过团队把生产阈值直接抄开发，结果生产频繁早停、报告残缺。环境覆盖写进配置，比在部署脚本里硬编码 if 环境 更稳，也更易被审计（呼应 5.2 的版本化）。

再说"配置评审"。改配置影响研究质量，应像改代码一样走评审：提交、同事看、跑一组回归（用第四章综合分比对新旧），通过才合入。把质量门槛前置到配置合并，比事后发现报告变差再回滚省事。配置即代码（GitOps 思路），是团队规模化的必经路。

5.3 用真实场景把这份配置跑出结果，看它到底灵不灵。