3. 分子数据表示与输入输出规范

在高通量分子计算流水线中，数据格式不是无关紧要的细节，而是决定流水线能否稳定运行的基础设施。一个分子在 SMILES 字符串、SDF 文件、PDB 结构、XYZ 坐标和 FASTA 序列中的表示方式截然不同，每种格式携带的信息维度、精度和语义约束也各不相同。如果输入输出规范设计不当，后续的特征计算、对接、动力学模拟或机器学习推理都会在数据层面埋下隐患。本节从常见分子文件格式的语义差异出发，讨论元数据管理、数据校验和流水线接口设计的关键工程问题。

常见分子文件格式的语义与适用边界

SMILES 是一种用 ASCII 字符串线性表示分子二维拓扑的格式，例如乙醇写作 CCO，苯环写作 c1ccccc1。它的优势是紧凑、易于数据库存储和快速比对，但缺点也很明显：不包含三维坐标、不显式表达立体化学（除非使用 @ 和 / 等标记）、对同一分子的写法不唯一。在流水线中，SMILES 通常作为分子身份标识和二维拓扑输入，适合用于指纹计算、子结构搜索和分子生成模型的输出。

SDF 是 MDL 公司定义的分子文件格式，由多个 molfile 块组成，每个块包含原子块、键块和属性块。SDF 可以携带三维坐标、电荷、手性标记以及自定义属性字段，是化学信息学中最常用的交换格式之一。它的局限在于对超大分子的支持较弱，且不同软件对属性字段的解析行为可能不一致。在流水线中，SDF 常作为分子库的标准输入，配合 RDKit 或 Open Babel 进行读写。

PDB 格式面向生物大分子结构，以 ATOM 和 HETATM 记录描述原子坐标、残基名称、链标识和占据率等信息。它适合蛋白质、核酸及其复合物，但对小分子的化学键和拓扑描述不完整，需要借助 CONECT 记录或外部化学感知工具补全。XYZ 格式则只包含原子种类和三维坐标，结构最简单，但完全丢失键级和电荷信息，通常用于量子化学计算或分子动力学轨迹的中间表示。FASTA 格式用于表示生物序列，以 > 开头的描述行和后续的碱基或氨基酸序列组成，是序列比对和蛋白质语言模型的标准输入。

元数据管理：让每个分子可追溯

分子数据在流水线中流动时，除了分子本身的结构信息，还需要携带一组元数据来保证可追溯性和可复现性。元数据至少应包含：数据来源（数据库名称、下载日期、原始文件哈希）、格式版本（如 SDF V2000 或 V3000）、处理历史（每一步操作的参数和软件版本）、校验信息（原子数、分子量、InChIKey）以及时间戳。这些信息不应散落在日志文件中，而应作为结构化字段与分子对象绑定存储。

一个实用的做法是在流水线内部定义统一的分子记录结构，例如使用 JSON 或 MessagePack 序列化，字段包括 mol_id、smiles、inchi_key、coordinates、properties 和 provenance。其中 provenance 是一个嵌套字典，记录每一步转换的输入输出哈希和参数。这样即使原始文件被删除或覆盖，也能通过哈希追溯到具体版本。

数据校验：在错误传播之前拦截

高通量流水线最怕的不是单个分子出错，而是错误数据静默地流入下游模块，导致批量计算结果不可信。数据校验应分层进行。第一层是格式校验：检查文件头、行数、字段分隔符是否符合预期，例如 SDF 文件应以 $$$$ 分隔分子块，PDB 文件应包含 ATOM 或 HETATM 记录。第二层是化学校验：使用 RDKit 的 SanitizeMol 检查价态、芳香性、手性标记是否合法，对于 PDB 结构还需检查原子间距离是否合理、是否有缺失残基。第三层是业务校验：根据流水线目标检查分子量范围、元素组成、是否包含特定官能团等。

校验失败时，不应直接丢弃数据，而应记录失败原因和原始记录，写入隔离区供人工复查。对于可恢复的错误（如坐标缺失但拓扑完整），可以尝试自动修复；对于不可恢复的错误（如 SMILES 语法错误），则标记为无效并跳过。校验结果应汇总为统计报告，包括通过率、失败类型分布和典型失败样例。

流水线接口设计：统一输入输出契约

流水线接口设计的核心是定义清晰的输入输出契约。输入侧，每个模块应接受统一的分子记录流，而不是直接读取原始文件。这意味着需要一个独立的解析层，将 SMILES、SDF、PDB、XYZ、FASTA 等格式转换为内部统一表示。解析层应支持批量处理，能够处理单个文件、文件列表或目录，并自动识别格式。输出侧，每个模块应输出统一格式的分子记录，附带处理日志和校验信息，便于下游模块消费和问题定位。

接口设计还需要考虑错误处理和重试机制。对于网络请求或外部工具调用，应设置超时和重试次数，并保证操作的幂等性。对于大规模数据，应采用分块处理和流式读写，避免一次性加载全部数据导致内存溢出。日志应采用结构化格式（如 JSON Lines），包含时间戳、模块名、分子 ID、操作类型和结果状态，便于后续聚合分析。

格式转换中的常见陷阱

不同格式之间的转换并非总是无损的。SMILES 转 SDF 时，需要生成三维坐标，这通常通过距离几何或力场优化实现，但生成的构象可能不是全局最优。SDF 转 PDB 时，小分子的残基名称和链标识需要重新分配，否则下游工具可能无法正确识别。XYZ 转 SDF 时，必须通过化学感知推断键级和电荷，这一步骤对过渡金属配合物和自由基容易出错。FASTA 转 PDB 时，需要借助同源建模或折叠预测工具生成三维结构，序列比对的质量直接影响最终结构的可靠性。

因此，在流水线中应尽量保持原始格式的完整性，只在必要时进行转换，并记录转换工具和参数。对于关键转换步骤，应设置校验点，比较转换前后的分子量、原子数和 InChIKey 是否一致。如果出现不一致，应暂停流水线并输出差异报告。

可参考的输入输出规范示例

以下是一个简化的分子记录 JSON 结构示例，用于说明流水线内部统一表示应包含的字段。该示例为教学用途构造，实际字段可根据项目需求扩展。

{
  "mol_id": "MOL-2024-000123",
  "smiles": "CC(=O)Oc1ccccc1C(=O)O",
  "inchi_key": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
  "format_origin": "SDF",
  "coordinates": [[0.0, 0.0, 0.0], ...],
  "properties": {
    "molecular_weight": 180.16,
    "logp": 1.19,
    "hbd": 1,
    "hba": 4
  },
  "provenance": {
    "source": "ZINC20",
    "download_date": "2024-01-15",
    "file_hash": "sha256:abc123...",
    "processing_steps": [
      {"tool": "RDKit", "version": "2023.09", "action": "sanitize"},
      {"tool": "Open Babel", "version": "3.1.1", "action": "convert_3d"}
    ]
  },
  "validation": {
    "status": "passed",
    "checks": ["valence", "aromaticity", "coordinate_sanity"]
  }
}

这个结构将分子结构、属性、来源和校验信息集中在一个对象中，便于序列化、传输和持久化。在实际工程中，可以根据数据量选择 JSON、MessagePack 或 Parquet 等格式，但字段语义应保持一致。通过这样的规范，流水线的每个模块都能以统一方式消费和产出数据，降低耦合度，提高可维护性和可复现性。