AutoDrug Docs UCB_USER
返回主站

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)
    • 可选同时选择多个上传/预置来源;UCB Active Pool 会按来源抽样,不需要先把大库复制合并到任务目录
    • 可选启用“分子生成”扩充 Pool(生成一次后与上述来源合并去重,再进入 UCB;这一类仍需要任务内物化,不走多来源 manifest)
    • 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):上传/预置/生成合并后的完整候选集合。多来源 UCB Active Pool 会用 sampler/compound_sources.json 记录来源和合计行数,不一定存在一个合并后的 sampler/pool.csv
  • top_n = per_round = sampler_size = 每轮采样数(K):同一概念,指每轮进入 SFCT 的候选数。
  • warmup = sampler_warmup_size:Round0 冷启动采样数。自适应预算默认从 warmup=2K 起步,不能整除的余量会补到 warmup;固定预算且开启 Active Pool 时沿用历史语义 warmup_eff=K
  • Round0:冷启动轮;Round1+:预测采样轮。
  • Active Pool 建池模式:普通 UI 提供“自动建池(推荐)/PharmacoNet PrePool Collector 建池/多样性 PrePool Collector 建池/全量 Collector 建池/快速随机建池”。自动建池小库或可全量处理时走全量 Collector;大库且 PharmacoNet 条件满足时走 PharmacoNet PrePool + Collector;大库但 PharmacoNet 条件不足时走 fingerprint diversity PrePool + Collector。
  • PrePool 建池:PharmacoNet PrePool Collector 会先对 full library/source manifest 做 PharmacoNet 预评分取 top-L PrePool,再在 hits 内做 fingerprint 多样性抽样并交给 Collector 建 Active Pool;多样性 PrePool Collector 则直接按 fingerprint 近似聚类覆盖化学空间,再交给 Collector。
  • UCB 轮内筛选模式passthrough/topm/hybridpassthrough 表示本轮 sampled batch 直接进 Boltz-2;topm/hybrid 只有 TopM 有效且小于本轮 batch K 时,才补跑本轮评分链后截断。
  • κ(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 轮次前,普通 CSV 来源会先对全量化合物库做一次清洗(artifacts/compounds_clean.csv,并记录 artifacts/invalid_smiles.csv)。如果是共享大预置库直通或多来源 manifest 的 UCB Active Pool 路径,Runner 会跳过任务内全量归档/清洗/预筛,只在抽出的 PrePool、Active Pool 或每轮输入上做有界处理,避免把 1000 万级候选复制成任务内大 CSV。 每个 round 在执行 run_sfct_round 前,也会对当轮输入再清洗一次,确保进入各阶段的 SMILES 合法。

Round 0(冷启动 warmup):

  1. 若关闭 Active Pool:从全库随机抽取 冷启动样本数 个分子作为本轮候选。
  2. 若启用 Active Pool:先建立 pool,再在 pool 内采样;自适应预算下 warmup_eff = 2 × 每轮采样数量(top_n)
  3. 对这批候选运行一轮标注流程(直到 Output)。其中:
  • ucb_round_filter_mode=passthrough:该轮跳过 Filter/ADMET/GraphDTA/QSAR/Collector,Boltz-2 在 Tester 阶段直接执行真实计算
  • ucb_round_filter_mode=topm/hybrid:只有 TopM 有效且小于本轮 batch K 时,才对本轮 sampled batch 补跑评分链后控量。
  • Active Pool 使用富集建池或全量 Collector bootstrap 时,轮内筛选模式会锁定为“不截断”,不再做二次 TopM/Hybrid。
  1. 用本轮的 Boltz-2 结果更新训练池(ucb/train/train.csv)。
  2. 训练 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 bootstrap 时,初始化后 UCB 轮次(含 Round0)固定不重跑 Filter/ADMET/GraphDTA/QSAR/Collector,直接把本轮 sampled batch 送入 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_scoreboltz2_prob),并驱动最终命中列表的筛选与排序。

6. Chemprop 训练在做什么

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

  • 训练数据:SMILES + boltz2_score(即 -ΔG,数值越大结合越强),每轮都会累积已有 Boltz-2 结果参与训练。
  • 训练目的:得到预测均值 μ 与不确定性 σ,用于下一轮 UCB 采样。
  • 输出:预测文件包含均值与不确定性列(例如 prediction/uncertaintychemprop_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,并按库规模自动分档候选池大小,未设置单轮上限时会把整除余量补到 warmup 以覆盖目标总预算,写入任务列表、status.json.ucb_budgetucb/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 建池模式:普通 UI 提供 5 个模式。推荐默认是自动建池:小库走全量 Collector,大库优先 PharmacoNet PrePool Collector,条件不足时多样性 PrePool Collector。显式选择 PharmacoNet 或多样性 PrePool 时,会固定对应 PrePool 方法;显式全量 Collector 适合小库,超大库会被物化阈值保护;快速随机建池适合调试。
  • 参考配体与口袋:基础面板可上传参考配体或填写口袋中心。Runner 优先用上传参考配体坐标算 centroid;未上传参考配体时,优先从上传的复合物结构自动抽取 ligand 并使用 ligand centroid;仍没有 ligand 时才使用手填口袋中心;只有 apo receptor 且 fpocket 可用时,才输出多个 top pocket candidates 并用于 PharmacoNet 多口袋筛选。没有可信 ligand、用户中心或口袋检测结果时会在 manifest 写 pocket_source=not_available,自动建池降级到 fingerprint diversity PrePool + Collector 或全量 Collector,不会用蛋白整体 centroid 伪装口袋。参考配体用于口袋/药效团建模,不要求它本身一定是药物;后续相似度、分子对接等模块可默认复用,模块参数中的显式输入优先。
  • UCB 轮内筛选模式:默认“不截断”。只有在快速随机建池或关闭 Active Pool 的场景下显式选择 topm/hybrid,且 TopM 小于本轮 batch K,才补跑本轮评分链后截断。自动建池、全量 Collector 和 PrePool Collector 建池会锁定为“不截断”。
  • Active Pool 大小(P):留空时自动分档:N<=150k -> 全量<=2M -> 120k>2M -> 300k;固定预算且启用 Active Pool 时,前端会显示预计 P,手填后覆盖自动值。若开启大库物化保护,自动 P 会收敛到阈值以内;手填超过阈值会失败。
  • 大库流转:UCB 单独选择远端预置库且开启 Active Pool 时,Runner 直接引用共享 CSV;多个上传/预置来源在 UCB Active Pool 且未启用分子生成器时,会写 sampler/compound_sources.json manifest 并按来源抽样,跳过任务内 sampler/pool.csv 合并、全量归档、全量清洗和预筛。Active Pool 的当前池 P、master 目标 M 和富集建池 PrePool 子集也受同一阈值约束。分子生成器底池、关闭 Active Pool 的全库 UCB、普通流程、显式全量 Collector 建池或 Collector 直通需要全量处理时,默认超过 50 万行会被拦截,避免把 1000 万级大库写入单个任务。
  • 每轮注入比例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_totalN<=2000 时取 N<=100002000<=1000004000<=10000008000,更大取 12000),再把总预算分到最多 9 轮;默认不设置显式单轮上限,因此超大库为 2400 + 8×1200 = 12000。若整除后有余量,余量会补到 warmup。例如清洗后 N_unique=1414 时实际预算为 warmup=286、后续 8×141(累计 1414)。
  • Active Pool 关闭时,进入 SFCT 的总采样量大致是 冷启动样本数 + (轮数-1)*每轮采样数量
  • 轮数/每轮采样数量越大,通常越容易收敛,但耗时与费用也会更高;建议先小规模试跑,再逐步放大参数。

试跑参数(链路验证/排障建议):

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

场景 冷启动样本数 每轮采样数量 轮数 kappa
链路试跑(尽快跑完) 200 100 3 1
小规模试跑(看趋势) 400 200 5 1

总采样预算(生产建议):

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

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

Pool 规模(量级) 总采样预算(所有轮次累计) 冷启动样本数(约 = 预算/5) 每轮采样数量(约 = 预算/10) 轮数
1 万 1000-2000 200-400 100-200 9
10 万 2000-4000 400-800 200-400 9
100 万 4000-8000 800-1600 400-800 9
1000 万 8000-16000 1600-3200 800-1600 9

注意:

  • Pool 大小需大于“总采样预算”,且 ligand_id 需唯一稳定,否则后几轮可能出现 UCB selection empty
  • 自适应预算会避免一开始就请求超过唯一候选数的轮次预算;如果固定预算仍超过可用候选,Runner 会先告警,已完成至少一轮后可提前结束并生成已完成轮次结果。
  • 实际进入 Boltz-2 的数量可能小于“每轮采样数量”(会受到过滤/阈值影响),从而影响训练池大小。
  • Pool 极大(例如 1000 万级)时,不建议关闭 Active Pool;关闭后每轮“对全库预测 + 选点”会生成大 CSV 并被保护阈值拦截。需要组合多个大库时,保持 UCB Active Pool 开启,让 Runner 使用多来源 manifest + PrePool/随机建池。

为什么推荐“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.csvucb_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. 常见问题

问题 说明/建议
会重复采样吗? 不会,系统按 ligand_id 跨轮去重。
UCB 跑得太慢怎么办? 可适当降低采样数量或减少轮数;Active Pool 关闭时也可先用较小 warmup 试跑后再放大参数。
某一轮命中为 0 会怎样? 若该轮 Boltz-2 结果为空且训练池为空(常见于首轮),UCB 会提前终止并标记失败;若已有训练池,则仍会继续后续轮次。
后几轮提示 UCB selection empty / UCB active pool 候选耗尽 是什么原因? 通常表示“可用于采样的候选已被耗尽”,常见原因是化合物池太小(轮数 × 每轮采样数量 接近或超过可用候选),或 ligand_id 重复导致去重过强。若已经完成至少一轮,系统会提前结束 UCB 并用已完成轮次生成最终结果,同时在 warnings 中记录原因;若首轮前就候选不足,仍会失败。
处理方式:减少轮数/每轮采样数量,或扩大 Pool,并确保 ligand_id 唯一且稳定。
命中偏少怎么调整? 优先放宽 Filter/GraphDTA/Boltz-2 阈值;仍偏少时,再提高冷启动样本数或每轮采样数量。

11. 排障与目录结构

11.1 常见报错对照表

报错/现象(日志中可见) 常见原因 建议处理
UCB 需要完整化合物库 CSV 未提供化合物来源(上传/数据中心 CSV/预置库均为空),或上传未完成导致文件不可读 至少提供一种化合物来源;大文件建议用数据中心 CSV;确认提交前无报错
UCB selection empty Pool 太小,或 ligand_id 重复导致跨轮去重过强,使候选提前耗尽 减少轮数/每轮采样数量;扩大 Pool;确保 ligand_id 唯一且稳定
UCB active pool 候选耗尽 Active Pool 更新后剩余可用候选不足以下一轮采样(rows < top_n 若已有完成轮次,系统会提前结束并生成已完成轮次的 UCB 最终结果;后续任务应降低每轮采样数量/轮数,或扩大 Pool,并检查 ligand_id 去重是否过强
UCB predictions count mismatch 断点续算/复用预测缓存时,predict_input_round_<n>.csvpreds_round_<n>.csv 的行数/输入哈希不一致(输入池变化或缓存陈旧) 优先重新提交一次(不续算);如必须续算,删除该轮预测缓存后重试
Train boltz missing / Train boltz empty 某轮 boltz2/refined.csv 不存在或为空(Boltz-2 失败、阈值过严、或输入不足) 确认 Boltz-2 启用且 MSA 有效;适当放宽阈值并增加 warmup/per_round;查看该轮 ucb/round_<n>/logs/run.log
UCB 未完成轮次(完成 X/Y) 迭代中途失败或训练池为空导致提前终止 先在 logs/run.log 找到失败轮次与阶段,再按对应原因处理后重跑
Chemprop 训练失败 / Chemprop 预测失败 环境/依赖问题,或训练集太小导致训练不稳定 查看 logs/chemprop.log;若样本太少,增加 warmup/per_round 或放宽阈值;若可执行文件缺失,联系管理员
MSA 文件缺失,无法继续运行 Boltz-2 / E_MSA_LEN_MISMATCH 未提供 A3M,或 A3M 与靶点序列不一致 重新生成与页面“靶点序列”一致的 A3M,或启用自动获取 MSA

11.2 UCB 相关文件在哪里

如果你下载了结果包(或有权限查看 job_dir),UCB 相关产物主要在这些路径下:

  • output/ucb_*.csv:UCB 的最终输出(最后一轮/多轮合并/TopN/推荐集合)。
  • ucb/budget.json:运行时实际预算,包含预算模式、清洗后唯一候选数、实际每轮采样数/轮数、Active Pool 实际大小、active_pool_build_modeucb_round_filter_modefallback_reason;Active Pool 还会记录 PrePool、Collector master、初始候选池行数和补抽次数,帮助判断候选池是否缩水;任务 status.json 也会同步写入 ucb_budget
  • ucb/active_pool_bootstrap/artifacts/collector_bootstrap_manifest.json:富集建池或全量 Collector bootstrap 时的前置评分链记录,说明 active pool master 如何构建。
  • ucb/round_<n>/artifacts/ucb_scored_batch_manifest.json:UCB 轮内不截断时的记录,包含 direct batch 来源、可沿用评分列与跳过阶段;富集建池和快速随机建池都会使用这类记录。
  • UCB 轮内显式 topm/hybridTopM<K 时,Runner 会对本轮 sampled batch 补跑常规 Filter/ADMET/GraphDTA/QSAR/Collector,产物沿用该轮常规阶段目录。
  • ucb/round_<n>/input/compound/round_<n>.csv:第 n 轮实际跑 SFCT 的候选(采样结果)。
  • ucb/round_<n>/output/final_hits.csvucb/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)