乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > 分子对接辅助工具:批量下载PubChem上的sdf文件

分子对接辅助工具:批量下载PubChem上的sdf文件

当前时间： 2026-04-21 12:02:58 更新时间： 2026-04-21 分类：软件教程 评论(0)

分子对接辅助工具:批量下载PubChem上的sdf文件

写在前面

分子对接是用计算方法模拟“小分子配体”和“生物大分子受体”如何结合的过程，我们公众号也曾推出过分子对接的详细教程（看过来！最全AutoDock分子对接教程（一）：软件介绍及环境配置）。而PubChem 在分子对接中的意义主要是“提供化合物标准化信息”，保护名称、CID、SMILES、InChI、2D/3D 结构、SDF。

PubChem（直译：公共化学数据库）是一个化学分子及其生物测定活性的数据库。该系统由美国国家生物技术信息中心（NCBI）维护。用户可以通过网络用户界面免费访问PubChem。数百万种化合物结构和描述数据集可以通过文件传输协议（FTP）免费下载PubChem包含多种物质描述以及原子数少于100个、键数少于1,000个的小分子。超过80家数据库供应商为内容不断增长的PubChem数据库做出了贡献（来自维基百科）。

虽然，用户可以通过网络界面免费访问PubChem并下载如sdf文件用于对接，但通常，分子对接需要在极大的小分子库里进行检索匹配，而通过用户界面逐个下载，对动辄成百上千的化合物库来说，确实是一个巨大的工程。而我们开发的 PubChem SDF Downloader则会解决这一问题。

PubChem SDF Downloader是一个基于 PubChem PUG REST API的批量结构下载小项目。

当前核心脚本 download_sdf.py用于从 PubChem 批量下载化合物的 SDF结构文件，支持两种输入方式：

  • • 按化合物名称查询 CID 后再下载 SDF
  • • 直接按 PubChem CID 下载 SDF

项目默认优先下载 3D结构，若 3D不存在，则自动回退到 2D结构；同时输出结果表和错误日志，便于续跑和排查。

此外，我们还增强了下载过程中的网络异常处理：

  • • 对 429/5xx、超时、连接中断、代理异常、DNS 解析失败进行更稳的重试
  • • 重试采用指数退避，并带少量随机抖动，减少短时间连续请求失败
  • • 错误日志会给出更明确的提示，便于区分是 PubChem 临时不可用，还是本地网络 / 代理配置问题

1. 环境要求

  • • Python 3.9 及以上
  • • 依赖包：requests

安装依赖：

pip install requests

2. 输入文件格式

2.1 文本文件（TXT）

每行一个输入值，可以是化合物名称，也可以是 CID。

名称示例：

Pro-alaEchinulinPseudoephedrine

CID 示例：

63475781152527028

2.2 CSV 文件

如果输入是 CSV，需要通过 --input-column指定读取哪一列。

示例：

compound_name,cidPro-ala,6347578Echinulin,115252Pseudoephedrine,7028

如果要按名称下载，可以指定：

--input-column compound_name

如果要按 CID 下载，可以指定：

--input-column cid

3. 输入模式

脚本通过 --input-mode控制当前输入值如何解释：

  • • name
    • • 按化合物名称查询 PubChem CID，再下载 SDF
    • • 这是默认模式，兼容你现在已有的用法
  • • cid
    • • 将输入内容直接当作 CID 使用，不再走名称查询
  • • auto
    • • 自动识别
    • • 纯数字内容按 CID 处理
    • • 非纯数字内容按名称处理

4. 基本用法

4.1 按化合物名称下载

默认就是名称模式：

python download_sdf.py -i high.txt -o high_structures --result-csv high_cid_sdf_results.csv --error-csv high_download_errors.csv

等价写法：

python download_sdf.py -i high.txt --input-mode name

4.2 按 CID 下载

假设 cid_list.txt中每行都是一个 CID：

python download_sdf.py -i cid_list.txt --input-mode cid -o cid_structures --result-csv cid_results.csv --error-csv cid_errors.csv

4.3 自动识别名称和 CID

如果一个文件里混合了名称和 CID，可以用：

python download_sdf.py -i mixed_input.txt --input-mode auto -o mixed_structures

例如：

Pro-ala115252Pseudoephedrine7028

5. 读取 CSV 的示例

5.1 CSV 按名称下载

python download_sdf.py -i compounds.csv --input-column compound_name --input-mode name -o structures_from_names

5.2 CSV 按 CID 下载

python download_sdf.py -i compounds.csv --input-column cid --input-mode cid -o structures_from_cids

5.3 CSV 自动识别

python download_sdf.py -i compounds.csv --input-column cid --input-mode auto -o auto_structures

6. 批量模式

可以一次处理多个输入文件：

python download_sdf.py \  --inputs high.txt low.txt \  --labels high low \  --input-mode name \  --output-root .

会自动生成：

  • • high_structures/
  • • high_cid_sdf_results.csv
  • • high_download_errors.csv
  • • low_structures/
  • • low_cid_sdf_results.csv
  • • low_download_errors.csv

如果不提供 --labels，默认使用输入文件名去掉扩展名后的部分。

7. 常用参数

-i, --input                  单个输入文件，默认 metabolites.txt--inputs                     批量输入多个文件--labels                     批量模式下的输出标签--output-root                批量模式输出根目录-o, --output-dir             SDF 输出目录--result-csv                 结果汇总 CSV--error-csv                  错误日志 CSV--input-column               CSV 输入时读取的列名--input-mode                 输入模式：name / cid / auto--timeout                    单次请求超时秒数--max-retries                最大重试次数--request-interval           普通请求间隔--retry-wait                 重试等待基数--cooldown-on-temp-fail      临时错误后的额外冷却时间--overwrite                  覆盖已存在的 SDF--resume                     结果 CSV 已存在时跳过已处理输入--append                     向已有结果文件末尾追加

8. 输出文件说明

8.1 结果文件

结果 CSV 默认包含以下字段：

  • • original_name
    • • 原始输入值
    • • 名称模式下通常是原始化合物名称
    • • CID 模式下这里保存原始 CID 字符串，便于续跑和追踪
  • • query_name
    • • 实际用于查 CID 的名称
    • • CID 模式下这里通常也是 CID 字符串
  • • cid
    • • 最终使用的 PubChem CID
  • • cid_status
    • • success、failed、temp_failed
  • • sdf_status
    • • success、failed、temp_failed、not_started
  • • record_type
    • • 3d、2d或 existing
  • • sdf_file
    • • 下载好的 SDF 文件路径
  • • message
    • • 详细说明
    • • 网络异常时会尽量指出是超时、代理失败、DNS 解析失败还是连接中断

8.2 错误日志

错误 CSV 会记录：

  • • 原始名称
  • • 查询名称
  • • CID
  • • 出错阶段
  • • 错误说明

常见阶段包括：

  • • cid_query
  • • cid_parse
  • • sdf_download

9. 断点续跑

如果下载过程中中断，可以使用：

python download_sdf.py -i high.txt --resume --append

说明：

  • • --resume会根据结果 CSV 跳过已经处理过的输入值
  • • --append会继续往现有结果文件末尾写入，而不是重写

建议这两个参数一起使用。

10. 注意事项

  • • 名称模式依赖 PubChem 名称匹配结果，个别化合物可能查不到 CID
  • • 脚本内已经包含一部分名称清洗和别名扩展逻辑，但仍不能保证所有名称都能命中
  • • CID 模式更直接，也更稳定；如果你已经有可靠 CID，建议优先使用 CID 模式
  • • 如果 SDF 已存在且未指定 --overwrite，脚本会直接跳过下载
  • • auto模式适合混合输入，但如果某些本应是名称的内容恰好是纯数字，会被当作 CID 处理

11. 网络异常说明

如果结果文件中的 message出现以下提示，可以按对应方向排查：

  • • 网络解析失败
    • • 说明当前环境无法解析 pubchem.ncbi.nlm.nih.gov
    • • 常见原因是 DNS 配置异常、无外网权限，或沙箱环境限制联网
  • • 代理连接失败
    • • 说明当前 Python 请求走了代理，但代理不可达或被远端关闭
    • • 可检查 HTTP_PROXY、HTTPS_PROXY、系统代理设置
  • • 请求超时
    • • 说明 PubChem 响应较慢，或当前网络波动较大
    • • 可以适当增大 --timeout
  • • 网络连接中断
    • • 说明连接建立后被中途关闭
    • • 通常属于临时网络问题或代理链路不稳定

脚本会对这几类问题自动重试；如果多次重试后仍失败，会在结果中写出 临时不可用（重试耗尽）。

12. 推荐用法

场景 1：你手里是代谢物名称列表

python download_sdf.py -i high.txt --input-mode name -o high_structures

场景 2：你手里已经有 CID 列表

python download_sdf.py -i high_cids.txt --input-mode cid -o high_structures

场景 3：你有一个 CSV，同时包含名称和 CID

按名称列下载：

python download_sdf.py -i compounds.csv --input-column compound_name --input-mode name

按 CID 列下载：

python download_sdf.py -i compounds.csv --input-column cid --input-mode cid

13. 项目获取

PubChem SDF Downloader项目可在下面的GitHub仓库中直接获取：

https://github.com/nongxinshengxin/PubChem-SDF-Downloader