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/hybrid。passthrough表示本轮 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. 操作步骤
- 在
Sampler 采样策略中选择 UCB
- 确认已提供 MSA(A3M)(上传或开启自动获取)
- 确认已提供 完整化合物库(Pool)(上传/数据中心 CSV
或选择预置库)
- 预算保持默认 自适应;如需固定每轮采样数量和轮数,再切到 固定;Active Pool 大小可留空自动分档,也可手填覆盖
- 设置 kappa、Active Pool 开关/来源(自适应预算下 Active Pool 大小自动分档)
- 若关闭 Active Pool 且预算为固定,再设置冷启动样本数(warmup)
- 如需精调,再展开“高级参数(注入/替换/退火)”
- 点击提交,系统自动执行多轮迭代
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):
- 若关闭 Active Pool:从全库随机抽取
冷启动样本数个分子作为本轮候选。
- 若启用 Active Pool:先建立 pool,再在 pool 内采样;自适应预算下
warmup_eff = 2 × 每轮采样数量(top_n)。 - 对这批候选运行一轮标注流程(直到 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。
- 用本轮的 Boltz-2
结果更新训练池(
ucb/train/train.csv)。
- 训练 UCB 内置的 Chemprop 模型(用于下一轮对候选池的 μ/σ 预测)。
Round 1..R-1(UCB 采样):
- 用上一轮模型对候选池做预测,得到每个分子的均值 μ 与不确定性 σ。
- Active Pool 开启:预测对象是
active_pool_current.csv
- Active Pool 关闭:预测对象是全库 CSV
- Active Pool 开启:预测对象是
- 按
UCB = μ + κ·σ从 Pool 中选出每轮采样数量个、且此前未采样过(按ligand_id去重)的分子作为本轮候选。
- 重复:标注本轮 sampled batch -> 更新训练池 -> 训练模型。
- Active Pool 使用富集建池或全量 Collector bootstrap 时,初始化后 UCB
轮次(含 Round0)固定不重跑
Filter/ADMET/GraphDTA/QSAR/Collector,直接把本轮 sampled batch 送入
Boltz-2。
- 轮末更新池子:移除已采样/历史分子,并按配置执行“每轮注入 + 周期替换(带 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生成后对最终合并命中执行一次;其中 finalpocket_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,并按库规模自动分档候选池大小,未设置单轮上限时会把整除余量补到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 建池模式:普通 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.jsonmanifest 并按来源抽样,跳过任务内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_total(N<=2000时取N,<=10000取2000,<=100000取4000,<=1000000取8000,更大取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.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. 常见问题
| 问题 | 说明/建议 |
|---|---|
| 会重复采样吗? | 不会,系统按 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>.csv
与 preds_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_mode、ucb_round_filter_mode与fallback_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/hybrid且TopM<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.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)