📚 课程目录第4章配置文件基础

4、配置文件基础：Vina 配置文件的格式、常用参数说明

配置文件，说白了就是告诉 Vina“你要拿什么蛋白、对接什么配体、搜索范围多大、搜多仔细”。我最早用 Vina 的时候，连配置文件都不会写，全在命令行敲参数，后来发现用配置文件才是正经做法——改参数不用翻历史命令，还能分享给别人。这一节咱们就把配置文件的结构和关键参数吃透。

4.1 配置文件长什么样？

Vina 的配置文件是纯文本格式，每行一个参数，参数名和值用空格或等号隔开。注释用 # 开头。我习惯把参数名写小写，虽然 Vina 不区分大小写，但保持统一看着舒服。

下面是我常用的一个模板：

# Vina 配置文件模板
receptor = receptor.pdbqt
ligand = ligand.pdbqt

center_x = 15.0
center_y = 20.0
center_z = -5.0

size_x = 22.5
size_y = 22.5
size_z = 22.5

exhaustiveness = 8
num_modes = 9
energy_range = 3.0

seed = 0
cpu = 4

out = output.pdbqt

这个文件看起来简单，但每个参数都直接影响对接结果。咱们一个一个来看。

  核心原则：Vina 读取配置文件时，遇到不认识的行会直接忽略，不会报错。所以拼写错误是最常见的踩坑点。

4.2 文件路径参数：receptor 和 ligand

参数	含义	必填	常见错误
`receptor`	受体PDBQT文件路径	是	路径含空格、文件名写错
`ligand`	配体PDBQT文件路径	是	配体没有加氢或电荷

我个人习惯：把受体和配体文件放在配置文件同一个目录下，用相对路径。如果文件在其他目录，一定要用绝对路径或用 ../ 引用。我曾经把受体文件放在 ~/data/receptors/，配体放在 ~/data/ligands/，写配置文件时偷懒只写了文件名，Vina 报错说找不到文件，查了半天才发现路径没写全。

小技巧：如果你用 Windows，路径里的反斜杠 \ 要写成双反斜杠 \\ 或者用正斜杠 /。Vina 对系统路径的处理还算友好，但正斜杠最安全。

4.3 对接盒子的定义：center 和 size

这是配置文件里最关键的参数组。Vina 只在盒子内部搜索配体可能的结合位置。盒子定歪了，结果就完全没有意义。

盒子的位置由 center_x、center_y、center_z 定义中心坐标，大小由 size_x、size_y、size_z 定义边长（单位是埃）。

举个例子，假设你的受体活性口袋中心大约在 (15, 20, -5)，你想要一个 22.5 埃见方的盒子，那就写成：

center_x = 15.0
center_y = 20.0
center_z = -5.0
size_x = 22.5
size_y = 22.5
size_z = 22.5

为什么 size 设成 22.5？这是因为 Vina 的盒子划分网格时，边长最好是 0.375 的整数倍。22.5 / 0.375 = 60，恰好是整数，网格点均匀分布。如果你设成 22.6，网格点数就不是整数了，Vina 会自己取整，但精度会有微小偏差。

注意：盒子不能小于配体。如果盒子太小，配体放不进去，Vina 会直接终止。我遇到过一个人，他把 size_x 设成了 5，结果对接了 10 分钟还没出结果，一看日志全是“out of box”警告。

那怎么确定盒子位置和大小呢？ 我个人推荐两种方法：

看文献或晶体结构：如果受体有共晶配体（co-crystallized ligand），直接以那个配体的质心作为盒子中心，盒子稍微扩大一点（比如每个方向加 5-10 埃）。
用 PyMOL 或 Chimera 测量：打开受体结构，手动测量活性口袋的坐标范围。记住要测的是蛋白上的原子坐标，不是空腔。

避坑指南：我曾经做一个对接，盒子中心定在了蛋白表面原子坐标的几何中心，结果盒子有一半在蛋白外面，另一半包含了整个活性口袋以外的区域。最后对接出来的姿态全飘在溶剂区。嗯，后来我才意识到，应该以活性口袋内的原子为参考，而不是整个蛋白。

4.4 搜索精度参数：exhaustiveness

exhaustiveness 是 Vina 里最影响计算时间的参数，没有之一。它控制了蒙特卡洛搜索的随机程度，值越大，搜索越充分，结果越可能找到全局最优，但时间也直线上升。

exhaustiveness	典型适用场景	耗时（相对值）
1 – 4	快速筛选（几千个配体时）	1x
8 – 16	常规对接（大部分研究）	2-4x
32 – 64	追求精度（发文章、验证结合模式）	8-16x

我个人经验：exhaustiveness=8 是绝大多数字段的黄金值。低于 8 时，结果重复性不够好——你跑两次可能会得到不同的 top 1 姿态。高于 16 时，时间成本翻倍，但改善效果很有限。我做一个大规模虚拟筛选时，先用 exhaustiveness=1 过滤掉明显不结合的配体，对候选分子再用 exhaustiveness=16 精细对接，这样效率高很多。

4.5 输出控制参数

Vina 默认只输出一个结合模式（pose），但通常我们想看多个可能的结合姿态。下面这几个参数最常用：

参数	默认值	说明
`num_modes`	9	输出最多多少个结合模式
`energy_range`	3.0	只保留能量在最优模式 ± 该范围内的模式（单位 kcal/mol）
`out`	无（默认输出到终端）	指定输出文件名（通常是 .pdbqt）
`log`	无	将日志信息写入文件，而不是终端

避坑：我曾经把 energy_range 设成 0.5，结果只输出了 2 个模式，大多数有效姿态被丢弃了。后来我改成 3.0，模式数量才正常。为什么设成 0.5？我当时觉得“只要最好的那一个不就够了”？但后来发现，能量差 0.5 以内的姿态在结合模式上可能差异很大，不能只看能量排序。

4.6 其他常用参数

还有一些参数，不一定每个项目都用，但知道了关键时刻能救命。

seed：随机数种子。设为任意整数，结果可复现。不设置时每次结果不同（因为系统时间是种子）。我调试时总设成 seed = 0，这样前后两次结果完全一致，方便排查问题。
cpu：使用的 CPU 核心数。默认是用满所有核心。如果你在服务器上跑，建议留一个核心给其他任务，比如 cpu = 3（四核机器留一个）。
weight_*：调整打分函数的权重（如 weight_gauss1、weight_repulsion 等）。极少数情况下才需要改，默认值经过大量验证，不要轻易动。

4.7 配置文件的结构关系

下面这张图把配置文件的各参数按功能分组，帮你理清它们的关联：

4.8 常见问题与排查

我用配置文件对接过上万次，整理几个高频踩坑点，你遇到了可以直接翻这里。

现象	原因	解决
“Cannot open file” 错误	文件路径写错或文件不存在	检查路径、文件名大小写、扩展名是否为 .pdbqt
“Atom type … not supported”	配体或受体 pdbqt 转换时原子类型命名异常	用 obabel 或 meeko 重新转换，确保所有原子都有 standard Vina types
对接结果全是乱摆	盒子中心没对准活性口袋	在 PyMOL 里测口袋坐标，重新设置 center
每次跑结果都不一样	没有设置 seed	在配置文件中加一行 `seed = 12345`
跑得特别慢（几天级别）	exhaustiveness 设太大，或配体太大	降低 exhaustiveness，或缩小盒子，或减小配体可旋转键数

最后一个提醒：配置文件最后一行一定要有一个换行。有些编辑器（比如 Windows 记事本）保存时不自动加尾行换行，Vina 读最后一行时可能会出奇怪的错误。我习惯在写完配置后用 cat -A config.txt 检查，确保每行结尾都有 $（Linux 换行符）。

好了，配置文件的基本结构就是这些。你只要把 receptor、ligand、盒子定义和 exhaustiveness 这四个模块写对了，剩下的参数按需添加即可。下一组参数（柔性残基、格点参数等）我们会在后面章节展开——别急，先把这组安身立命的参数用熟。