UCB 用户手册

本手册说明何时选择 UCB、如何配置参数，以及结果如何解读。

如果你还不熟悉 SFCT 表单与输出文件，建议先读主用户手册。

快速读法

UCB 可以先理解为“大库分批精筛”：系统不会一次性把全库都送入高精度评估，而是先抽一批、计算结果、训练一个临时预测模型，再用模型挑下一批。多数用户保持默认自适应预算和候选池加速即可；只有需要严格控制总采样量或排查迭代行为时，才需要看后面的术语和公式。

最常用的判断方式：

• 库越大，越适合 UCB；小库通常直接全量或随机更简单。
• 每轮都依赖 Boltz-2 结果做学习，所以 UCB 任务必须启用 Boltz-2。
• 候选池是加速用的工作子集，不是最终结果；最终结果仍来自每轮实际完成的 Boltz-2 评估。
• 命中太少时，优先放宽 Filter/GraphDTA/Boltz-2 阈值，再考虑扩大采样预算。

0. 开始前（UCB 的必要输入）

UCB 是“多轮迭代 + 主动学习”的采样策略。要跑起来，你必须准备好：

• 靶点序列（或上传结构/序列文件让系统提取序列）
• MSA（A3M）：必须提供（上传 A3M，或开启“自动获取 MSA”）
• 完整化合物库（Pool）：必须有一个“可被反复采样的候选池”
  • 上传/数据中心 CSV；或
  • 选择预置库（Preset Library）
  • 可选启用“分子生成”扩充 Pool（生成一次后与上述来源合并去重，再进入 UCB）
  • Pool CSV 必须包含可识别的 ID 列（如 ligand_id / origin_id / ID / compound_id / hit_id / molecule_id），用于跨轮去重与结果合并

注意：

• UCB 依赖每轮 Boltz-2 结果作为训练目标，因此 UCB 模式下 必须启用 Boltz-2；关闭会导致训练数据为空并使迭代失败。

1. 适用场景

当化合物库规模较大、无法全量跑完（或预算不允许全量精筛）时，UCB 用“每轮只精筛一小部分候选”的方式，把算力集中到更有希望的区域。

它特别适合：

• 库很大（例如 10 万到百万级），你希望在固定预算下尽可能提高最终命中质量
• 你希望通过多轮迭代逐步改进后续采样（系统会在一次提交内自动完成多轮）

2. UCB 是什么

UCB（Upper Confidence Bound）是一种在“高分子”和“高不确定性分子”之间取得平衡的采样方法：

• 均值 μ：模型预测的结合强度（越大越好）。
  
• 不确定性 σ：模型预测的不确定程度（越大越不确定，也越值得探索）。

系统按 UCB = μ + κ·σ 计算排序分数，κ 越大越鼓励探索；κ 越小越偏向已知高分。
因此，UCB 不是单纯选最高分，而是在“稳妥命中”和“潜在新结构”之间取得平衡。

在本系统里，这个 μ/σ 由（UCB 内置的）Chemprop 模型给出；它与“Collector 里的 QSAR（Chemprop）模块”是两件事，互不依赖。

2.1 术语对照（先看这个）

• Active Pool = 候选池：UCB 每轮实际预测与选点的工作子集，不等于全库。
• Pool / 全库（N）：上传/预置/生成合并后的完整候选集合。
• top_n = per_round = sampler_size = 每轮采样数（K）：同一概念，指每轮进入 SFCT 的候选数。
• warmup = sampler_warmup_size：Round0 冷启动采样数。自适应预算默认 warmup=2K；固定预算且开启 Active Pool 时沿用历史语义 warmup_eff=K。
• Round0：冷启动轮；Round1+：预测采样轮。
• source=auto|collector|random：候选池初始化来源。auto 在 N<=2M 时优先用 Collector bootstrap，N>2M 时默认回退随机初始化；管理员也可把超大库策略配置为 bounded Collector bootstrap。
• κ（kappa）：探索强度；越大越探索，越小越偏向当前高分头部。
• P（pool size）：候选池目标大小；手填优先，否则按库规模自动分档。
• E（inject）：每轮注入数量，E=ceil(P*refresh_ratio)。
• R（replace）：周期替换数量，R=ceil(P*replace_ratio)，按 replace_interval 轮执行。
• tau（注入温度）：指数抽样温度；越大越探索，越小越偏向排名靠前头部。
• Collector 初始化：用于构建候选池 master 的一次性前置打分排序；评分列会随 active pool 行保留，供后续 UCB 轮内精评前筛选复用。
• Collector 阶段：SFCT 的常规阶段之一；UCB 随机建池且手动 TopM/Hybrid 时才会在本轮 sampled batch 内补跑这条评分/筛选链。
• Tester 阶段：执行 Boltz-2 计算与结果整理的阶段。
• history 去重：按 ligand_id 记录已采样分子，防止跨轮重复进入 round_compound。

3. 操作步骤

1. 在 Sampler 采样策略 中选择 UCB
   
2. 确认已提供 MSA（A3M）（上传或开启自动获取）
   
3. 确认已提供 完整化合物库（Pool）（上传/数据中心 CSV 或选择预置库）
   
4. 预算保持默认 自适应；如需固定每轮采样数量和轮数，再切到 固定；Active Pool 大小可留空自动分档，也可手填覆盖
5. 设置 kappa、Active Pool 开关/来源（自适应预算下 Active Pool 大小自动分档）
6. 若关闭 Active Pool 且预算为固定，再设置冷启动样本数（warmup）
7. 如需精调，再展开“高级参数（注入/替换/退火）”
8. 点击提交，系统自动执行多轮迭代

4. 默认迭代流程

UCB 会在一次任务里自动跑多轮（Round 0..R-1），每一轮都会生成一个独立的子目录 ucb/round_<n>/，用于复核本轮候选、日志与产物。

在进入 UCB 轮次前，系统会先对全量化合物库做一次清洗（artifacts/compounds_clean.csv，并记录 artifacts/invalid_smiles.csv）。 每个 round 在执行 run_sfct_round 前，也会对当轮输入再清洗一次，确保进入各阶段的 SMILES 合法。

Round 0（冷启动 warmup）：

1. 若关闭 Active Pool：从全库随机抽取 冷启动样本数 个分子作为本轮候选。
   
2. 若启用 Active Pool：先建立 pool，再在 pool 内采样；自适应预算下 warmup_eff = 2 × 每轮采样数量(top_n)。
3. 对这批候选运行一轮标注流程（直到 Output）。其中：
   

• 默认 TopM 为空时：该轮“精评前筛选=不截断”，跳过 Filter/ADMET/GraphDTA/QSAR/Collector，Boltz-2 在 Tester 阶段直接执行真实计算
  
• 如果专家手动填写 TopM/Hybrid：只控制本轮 sampled batch 进入 Boltz-2 前的数量，不改变 UCB 选样和 Boltz-2 标注量预算
  
• source=collector，或 auto 解析为 Collector：初始化前置评分链仍会跑到 Collector 建池；轮内 TopM/Hybrid 复用 active pool 行上缓存的评分列，不再重跑预评分链
  
• source=random，或 auto 超大库回退 random：轮内 TopM 为空时直接进 Boltz-2；手动 TopM/Hybrid 时才对本轮 sampled batch 补跑评分链再控量
  

4. 用本轮的 Boltz-2 结果更新训练池（ucb/train/train.csv）。
   
5. 训练 UCB 内置的 Chemprop 模型（用于下一轮对候选池的 μ/σ 预测）。

Round 1..R-1（UCB 采样）：

1. 用上一轮模型对候选池做预测，得到每个分子的均值 μ 与不确定性 σ。
   • Active Pool 开启：预测对象是 active_pool_current.csv
     
   • Active Pool 关闭：预测对象是全库 CSV
     
2. 按 UCB = μ + κ·σ 从 Pool 中选出 每轮采样数量 个、且此前未采样过（按 ligand_id 去重）的分子作为本轮候选。
   
3. 重复：标注本轮 sampled batch -> 更新训练池 -> 训练模型。
   
4. Active Pool 开启且来源选择 collector，或 auto 解析为 Collector 时，初始化后 UCB 轮次（含 Round0）默认不重跑 Filter/ADMET/GraphDTA/QSAR/Collector；TopM 为空则不截断，手动 TopM/Hybrid 则复用缓存评分控量后进入 Boltz-2。
   
5. 轮末更新池子：移除已采样/历史分子，并按配置执行“每轮注入 + 周期替换（带 tau 退火）”。

收尾（合并输出）：

• 最后一轮结果会复制为 output/ucb_last_round*.csv。
  
• 多轮 final_full.csv 会先合并为 output/ucb_final_full.csv（按 ligand_id 去重，保留每个分子跨轮的最好 boltz2_score 记录；未进入 Boltz-2 精评的审计候选可能没有 boltz2_score/prob，报告会额外显示 scored 行数）。
  
• output/ucb_final_hits.csv 会基于这份 ucb_final_full.csv 再按当前最终保留策略（默认 A1）重建，而不是直接拼接各轮 final_hits.csv。
  
• 若启用了受体模板、模板重跑、统一受体坐标系或 binding-site 分组，这些结构复核不会在每个 round 内重复执行，而是会在 ucb_final_hits.csv / ucb_final_full.csv 生成后对最终合并命中执行一次；其中 final pocket_site/ 才是后续 FEP 默认使用的口袋分组依据。
• 若启用了 AiZynth，该模块不会在每个 round 内单独执行，而是会在 ucb_final_hits.csv / ucb_final_full.csv 生成后对最终合并命中执行一次。
• 报告（Report）只在所有轮次完成后生成一次（reports/），不会在每个 ucb/round_<n>/ 内生成。

跨轮去重：

• 去重粒度是 ligand_id；确保它唯一且稳定，否则会影响采样与合并结果。

5. Boltz-2 说明

在本流程中，Boltz-2 用于给候选分子打分（主要输出 boltz2_score 与 boltz2_prob），并驱动最终命中列表的筛选与排序。

6. Chemprop 训练在做什么

Chemprop 用于学习“结构 → 结合强度”的映射，训练目标来自每轮 SFCT 产生的 Boltz-2 结果：

• 训练数据：SMILES + boltz2_score（即 -ΔG，数值越大结合越强），每轮都会累积已有 Boltz-2 结果参与训练。
  
• 训练目的：得到预测均值 μ 与不确定性 σ，用于下一轮 UCB 采样。
  
• 输出：预测文件包含均值与不确定性列（例如 prediction/uncertainty 或 chemprop_mu/chemprop_sigma）。

因此，Chemprop 训练的核心是拟合 Boltz-2 评分趋势并提供不确定性， 随着训练池累积，模型通常会逐轮更稳定；UCB 选择依赖这一对“均值 + 不确定性”的打分完成采样， 但最终仍会在每轮候选上运行 Boltz-2，用于生成正式评分与结果输出，而不是用 Chemprop 直接替代 Boltz-2 本身。

Boltz-2 结果会累计写入训练池（ucb/train/train.csv），训练集会随轮次增长；即使某一轮命中较少， 历史 Boltz-2 结果仍会用于后续 Chemprop 训练。

当训练集较小导致验证集样本不足时，系统会自动降低 Chemprop 的 batch_size 并放宽早停条件， 避免因验证集为空导致训练失败；仍建议适当增加冷启动样本或放宽筛选阈值。

7. 参数说明

• 每轮采样数量（per_round）：每轮进入 SFCT 的候选数量（UCB/随机选点的 TopN）。
• 预算模式：默认 auto。自适应模式下用户无需填写每轮采样数量、轮数和 Active Pool 大小；页面会在上传 CSV 或选择预置库后，在普通候选采样摘要、运行方案提示、流程图 UCB Sampler 卡片和 Sampler 参数抽屉中给出提交前预估，其中普通摘要会同时显示 warmup + 后续轮次 × per_round = 总采样量。Runner 会在清洗/去重后按唯一候选数计算实际 per_round/rounds/warmup，并按库规模自动分档候选池大小，写入任务列表、status.json.ucb_budget 与 ucb/budget.json。固定模式下才使用手填的 sampler_size/sampler_rounds/sampler_warmup_size；启用 Active Pool 时，候选池大小可留空按库规模自动分档，也可手填覆盖。
• 冷启动样本数（warmup）：自适应预算下由 Runner 计算，默认 warmup=2K；固定预算且开启 Active Pool 时沿用历史语义 warmup_eff=K，前端仍隐藏该项。
• 轮数（rounds）：迭代轮次（Round 0..R-1）。每轮都会：选点 -> 跑 SFCT -> 累积训练池 -> 训练 Chemprop。
• kappa（κ）：探索权重。κ 越大越偏向“不确定但潜力高”的分子；κ 越小越偏向“当前预测高分”的分子。
• Active Pool 来源（source）：auto|collector|random。auto 在 N<=2M 时优先用 Collector bootstrap，N>2M 时默认回退随机初始化；管理员可配置 bounded Collector bootstrap，在超大库中先抽取有界子集再排序建池，实际抽样量会至少覆盖 Active Pool master 目标。Collector 只负责初始化或排序 active pool；UCB 轮内默认不截断 sampled batch，只有专家手动填写 TopM 时才截断；后续池外注入会优先沿用 Collector 输出里的 rrf_score。
• Active Pool 大小（P）：留空时自动分档：N<=150k -> 全量，<=2M -> 120k，>2M -> 300k；固定预算且启用 Active Pool 时，前端会显示预计 P，手填后覆盖自动值。
• 每轮注入比例：E=ceil(P*ratio)（默认 0.15）。
• 周期替换比例/间隔：R=ceil(P*ratio)，默认每 2 轮替换一次（默认 0.20）。
• 指数注入温度（tau）：默认 1.0 -> 0.35 线性退火，前期更探索，后期更收敛。

注意：

• 这里的“采样数量”指 进入 SFCT 的候选数，并不等于“进入 Boltz-2 的数量”。实际进入 Boltz-2 的数量会受到 Filter/GraphDTA 预筛/Collector 阈值影响。
• UCB 的训练池大小以 ucb/train/train.csv 为准；如果某轮追加数据很少或为 0，说明阈值过严或上游阶段产物为空，需要先放宽阈值/排障，再谈参数放大。
• 常规 UCB 断点续算会复用来源任务的候选池和预筛结果；如果原任务启用了分子生成，续算不会为了重建候选池而再次生成分子。
• 前端默认只展示常用参数；“每轮注入/周期替换/退火温度”位于“高级参数”折叠区，默认使用推荐值。

运行时长/费用直觉（仅用于估算）：

• Active Pool 开启（默认）时，自适应预算会按 warmup=2K、后续每轮 K 计算，进入 SFCT 的总采样量大致是 warmup + (轮数-1)*每轮采样数量。Runner 默认先按库规模分档计算 target_total（N<=2000 时取 N，<=10000 取 2000，<=100000 取 4000，<=1000000 取 8000，更大取 12000），再把总预算分到最多 9 轮；默认不设置显式单轮上限，因此超大库为 2400 + 8×1200 = 12000。例如清洗后 N_unique=1414 时实际预算为 warmup=282、后续 8×141（累计 1410）。
• Active Pool 关闭时，进入 SFCT 的总采样量大致是 冷启动样本数 + (轮数-1)*每轮采样数量。
• 轮数/每轮采样数量越大，通常越容易收敛，但耗时与费用也会更高；建议先小规模试跑，再逐步放大参数。

试跑参数（链路验证/排障建议）：

目标：尽快验证“UCB 能跑通、每轮都能追加训练数据、不会出现 selection empty/训练失败”。
若要做真正的生产筛选，请使用下方“总采样预算（生产建议）”。

总采样预算（生产建议）：

• 若 关闭 Active Pool，可把“UCB 采样总数”理解为：总采样预算 = 冷启动样本数 + (轮数-1)*每轮采样数量。
• 若采用 冷启动 = 2 * 每轮采样，且 轮数 = 9（仅适用于 Active Pool 关闭），则：
  • 总采样预算 = 10 * 每轮采样数量
    
  • 每轮采样数量 = 总采样预算 / 10
    
  • 冷启动样本数 = 总采样预算 / 5
    
• 若 开启 Active Pool（默认），可近似按 总采样预算 = 轮数 * 每轮采样数量 估算。

下面给一个“库大小 vs 总采样预算”的起步建议（按 Active Pool 关闭口径估算；范围二选一，先用小档试跑，效果不足再升档）：

注意：

• Pool 大小需大于“总采样预算”，且 ligand_id 需唯一稳定，否则后几轮可能出现 UCB selection empty。
• 自适应预算会避免一开始就请求超过唯一候选数的轮次预算；如果固定预算仍超过可用候选，Runner 会先告警，已完成至少一轮后可提前结束并生成已完成轮次结果。
• 实际进入 Boltz-2 的数量可能小于“每轮采样数量”（会受到过滤/阈值影响），从而影响训练池大小。
• Pool 极大（例如 1000 万级）时，每轮“对全库预测 + 选点”的开销会显著增大；建议先通过预筛/拆分把 Pool 控制在更可控的规模后再跑 UCB。

为什么推荐“warmup = 2 * per_round + rounds = 9”作为默认自适应配置：

• warmup 足够大时，首轮训练池更容易“有信号可学”，避免 Chemprop 训练/预测因样本过少而不稳定。
• rounds = 9 时，后续还有 8 轮可用于“按 UCB 逐步收敛”，在稳定性与总成本之间更容易取得平衡。
• 用这种固定比例配置，你只需要先确定一个“总采样预算”，就能快速换算出每轮参数（见上面的预算公式），方便在不同库规模下复用同一策略。

使用建议：

• 命中偏少时，先适当放宽 Filter/GraphDTA/Boltz-2 阈值，再考虑提高每轮采样数量（Active Pool 开启）或冷启动样本数（Active Pool 关闭）。
• 想更稳，kappa 取 0.5~1；想探索更多，kappa 取 2~3。

8. Boltz-2 结果与最终输出

每轮 UCB 采样后都会对候选分子运行 Boltz-2 计算，生成当轮 boltz2_score。
所有轮次的 Boltz-2 结果会持续累积，并在结束时合并为最终结果（去重汇总）。

9. 输出文件（标准文件名）

以下文件按 boltz2_score 降序排序（-ΔG，数值越大结合越强）：

• output/ucb_last_round.csv：最后一轮命中
• output/ucb_last_round_full.csv：最后一轮全量快照
• output/ucb_final_full.csv：多轮合并快照（按 ligand_id 去重并保留最好分数，包含更多过程列便于复核）
• output/ucb_final_hits.csv：基于 ucb_final_full.csv 再按最终保留策略重建的 UCB 最终命中
• output/ucb_final_hits_topN.csv：合并 Top N 命中（按 Boltz-2 分数排序）
• output/ucb_final_hits_recommend.csv：合并推荐集合（骨架聚类后每簇保留一定数量）

说明：

• ucb_final_hits_topN.csv 与 ucb_final_hits_recommend.csv 都是从 ucb_final_hits.csv 派生出来的子集文件，不会改变主结果的生成逻辑。

推荐查看顺序：

• 想要最终 shortlist：优先看 output/ucb_final_hits_recommend.csv（结构多样性更好）
• 想看 Top 命中：看 output/ucb_final_hits_topN.csv
• 想做全面复核/自己再筛：看 output/ucb_final_full.csv

10. 常见问题

11. 排障与目录结构

11.1 常见报错对照表

11.2 UCB 相关文件在哪里

如果你下载了结果包（或有权限查看 job_dir），UCB 相关产物主要在这些路径下：

• output/ucb_*.csv：UCB 的最终输出（最后一轮/多轮合并/TopN/推荐集合）。
• ucb/budget.json：运行时实际预算，包含预算模式、清洗后唯一候选数、实际每轮采样数/轮数、Active Pool 实际大小，以及 source_requested/source/source_resolution_reason（例如 auto -> collector 或 auto -> random）；任务 status.json 也会同步写入 ucb_budget。
• ucb/active_pool_bootstrap/artifacts/collector_bootstrap_manifest.json：Collector/auto 初始化时的前置评分链记录，说明 active pool master 如何构建。
• ucb/round_<n>/artifacts/ucb_scored_batch_manifest.json：UCB 轮内 TopM 为空时“精评前筛选=不截断”的记录，包含 direct batch 来源、可沿用评分列与跳过阶段；Collector 建池和 random 建池都会使用这类记录。
• ucb/round_<n>/artifacts/ucb_cached_filter_manifest.json：Collector 建池来源且轮内手动 TopM/Hybrid 时生成，记录复用缓存评分后的精评前筛选方式与选中行数。
• ucb/round_<n>/input/compound/round_<n>.csv：第 n 轮实际跑 SFCT 的候选（采样结果）。
• ucb/round_<n>/output/final_hits.csv、ucb/round_<n>/output/final_full.csv：第 n 轮的结果快照。
• ucb/round_<n>/boltz2/refined.csv：第 n 轮 Boltz-2 结果（用于训练池）。
• ucb/train/train.csv：训练池（SMILES,g），会按 SMILES 合并去重（同一 SMILES 多次出现时覆盖旧记录）。
• ucb/history_ids.csv：已采样 ligand_id 列表（跨轮去重依据）。
• ucb/preds_round_<n>.csv：第 n 轮 Chemprop 预测结果（用于采样；Active Pool 开启时对应 active_pool_current.csv，关闭时对应全库）。
• logs/run.log：总控日志（记录每轮进度、失败轮次等）。
• logs/chemprop.log：Chemprop 训练与预测日志（UCB 的训练/预测都写这里，不在 round 目录内）。
• ucb/round_<n>/logs/run.log：第 n 轮 SFCT 流程日志（Filter/GraphDTA/Boltz-2 等细节）。
• reports/：任务总报告（仅在任务结束后生成一次）。

结果包默认会排除大体积目录（不影响复核 CSV）：

• ucb/models/（每轮 Chemprop 模型目录）
• ucb/**/boltz2/workdir/（UCB 每轮的 Boltz-2 原始 workdir）