sequential_attention 项目版本演进与 CHANGELOG 发布流程指南

原创2026-10-10 12:01:211,629 阅读
文章标签:人工智能深度学习NLP计算机视觉强化学习

sequential_attention 项目版本演进与 CHANGELOG 发布流程指南

导读

本文以 sequential_attention/CHANGELOG.md 为骨架,系统讲解该特征选择项目的版本记录规范、两个正式版本(v0.1.0 与 v0.2.0)的实际演进内容,以及遵循 keepachangelog 标准发布新版本的具体操作步骤。读完本文,你将掌握如何解读该仓库的版本历史、如何把代码变更(如新增算法实验)正确登记到 CHANGELOG 中,并理解 CHANGELOG.md 与源码 __version__、打包配置之间的联动机制。

一、CHANGELOG 的定位与规范基础

sequential_attention/CHANGELOG.md 是该项目的版本变更记录文件,其头部注释明确了两个核心设计目标:

  1. 支持自动化发布:文件格式遵循 keepachangelog 标准(至少是标题格式),使得发布说明能够在 GitHub Actions 自动化发布流程中被自动解析,生成 release notes;
  2. 可点击的标题:按标准格式书写的 ## [版本号] - 日期 标题,在渲染后的 Markdown 中呈现为可点击的锚点,便于读者在多个版本说明之间快速跳转。

从仓库实际内容看,CHANGELOG.md 与打包系统是配套的:pyproject.toml 中通过 dynamic = <a href="https://link.gitcode.com/i/45de900c9610b8246cd854feede59eee" target="_blank">"version"] 声明版本号由 sequential_attention.__version__ 自动推导,而 [sequential_attention/init.py 中的注释明确写道:每次提升 __version__ 都会触发新的 PyPI 发布,同时必须同步更新 CHANGELOG.md。也就是说,CHANGELOG 不是可有可无的文档,而是发布流水线的一部分。

二、版本历史解读:两次发布背后的功能演进

当前 CHANGELOG.md 记录的版本历史非常精简,但每一条都对应着仓库中的实质性代码模块:

2.1 [0.1.0] - 2022-01-01:Initial release

这是项目的首次正式发布,对应的是论文《Sequential Attention for Feature Selection》(Yasuda 等人)的核心算法实现。本次发布包含的功能实体:

  • 核心模块 sequential_attention/sequential_attention.py:SequentialAttention 类,用注意力机制高效实现经典贪心前向选择算法。其构造参数包括 num_candidates(候选特征总数)、num_candidates_to_select(要选出的特征数)、num_candidates_to_select_per_step(每步选出数量,默认 1)、start_percentage(默认 0.1)、stop_percentage(默认 1.0)与 reset_weights(默认 True)。前向调用接收 training_percentage(0~1 之间单调递增的训练进度),返回一个和为 1 的注意力权重向量,并用 selected_features 变量累加记录已选特征;
  • 实验框架 sequential_attention/experiments/run.py:基于 absl flags 的完整实验入口,支持 sa / lly / seql / gl / omp 五种特征选择算法在 mnist / fashion / isolet / mice / coil / activity 六个数据集上运行;
  • 对比基线 sequential_attention/sequential_attention/benchmarks/:收录了 Orthogonal Matching Pursuit(orthogonal_matching_pursuit.py)、Sequential Lasso(sequential_lasso.py)以及 Liao-Latty-Yang 注意力掩码(liao_latty_yang.py)等对照算法。

从源码结构可以推断,v0.1.0 发布时点对应论文复现实验的完整交付,即"Simple Sequential Attention"形态。

2.2 [0.2.0] - 2023-08-03:Added Ensembled Sequential Attention experiments

第二次发布只记录了一条变更,却对应着一个全新的独立功能目录 ensembled_sequential_attention/,其中包括:

  • 对比研究 Notebook SequentialAttentionTimeTracking.ipynb:在低数据量(20%/40%/60% 随机子样本)与低特征量两种实验设置下,对 Simple Sequential Attention 与 Intermediate(Ensembled)Sequential Attention 进行对比研究,目标是降低所需数据量并产出更好、更稳定的结果;
  • 算法扩展说明:Notebook 中新增了 IntermediateSA 方法——由 K 个 worker 组成的集成,每个 worker 各自给出下一批最优特征(示例中为 20 个),在每个检查点由集成投票选出共同掩码,随后所有 worker 以该共同先验继续推进,直到覆盖全部目标特征集大小(如 [20, 30, 40, 50])。核心实现见 get_masks_fn_intermediate_sa(),其投票逻辑基于 model.sa.selected_features 的 top-k 索引统计;
  • 实验结果图片:目录下的三张结果图(见下文第四节)展示了该方法在特征质量与稳定性上的改进。

这一版本的演进脉络清晰:从"单个模型顺序挑选特征"升级到"多个模型投票集成挑选特征",即 Ensembled Sequential Attention。

三、发布新版本的标准操作流程

CHANGELOG.md 头部注释给出了严格的发布步骤,这是 keepachangelog 规范在项目中的落地实践。假设当前版本为 1.0.0,需要发布 2.0.0:

3.1 第一步:新增版本标题并迁移变更

在文件顶部([Unreleased] 之下)创建新的标题行,并把当前 [Unreleased] 中积累的变更说明移入新版本:

## [Unreleased]

## [2.0.0] - YYYY-MM-DD

* <此处填写自 1.0.0 以来的全部用户可见变更>

日期格式为 YYYY-MM-DD,与 keepachangelog 标准保持一致。

3.2 第二步:更新文件末尾的版本链接

在文件末尾需要完成两项链接维护:

  1. 定义新版本的比较链接,用于查看从旧版本到新版本的完整代码差异:
[2.0.0]: https://github.com/google-research/sequential_attention/compare/v1.0.0...v2.0.0
  1. 更新 [Unreleased] 的链接基线,把 v1.0.0...HEAD 改为 v2.0.0...HEAD:
[Unreleased]: https://github.com/google-research/sequential_attention/compare/v2.0.0...HEAD

3.3 第三步:同步提升源码版本号

根据 sequential_attention/init.py 中的约定,发布动作与 __version__ 直接挂钩:修改该文件中的 __version__ = '0.1.0' 为新的版本号(如 0.2.0),flit 构建后端会据此自动生成包版本(见 pyproject.toml 的 dynamic = ["version"]),PyPI 发布流程随之触发。因此,发布新版本 = 更新 CHANGELOG + 更新 __version__,两步缺一不可。

四、0.2.0 新增内容的实证:Ensembled Sequential Attention 关键结果

CHANGELOG.md 对 0.2.0 的条目虽然只有一句话,但其背后的实验结论在 ensembled_sequential_attention/README.md 中有明确数据支撑,可以作为理解该版本价值的实证材料:

  • 在部分数据集上,即使进一步削减特征数量,仍能保持同等质量;
  • Intermediate(Ensembled)Sequential Attention 比 Simple Sequential Attention 更稳定(多次随机初始化下精度波动更小);
  • 在论文的同一实验设置下(50 个特征、Activity 数据集),Intermediate Sequential Attention 的测试集准确率为 93.22%,比 Simple SA 的 92.54% 高出 0.7%,而用全部 561 个特征训练的全量模型为 94.47%——即仅用约 9% 的特征就逼近全量模型的精度。

Sequential Attention 与随机特征选择的对比结果

上图为特征选择质量对比:在多种特征集大小下,Sequential Attention 明显优于随机特征选择基线,这也是 v0.1.0 核心算法有效性的直观证据。

Intermediate Sequential Attention 相较 Simple Sequential Attention 的稳定性提升

上图展示的是 v0.2.0 的核心增量——集成式(Intermediate)注意力在多次随机初始化下的精度分布更集中、方差更小,即"更稳定"这一结论的实验来源。两张图分别对应 CHANGELOG.md 中两次发布的核心内容,可作为阅读版本记录时的可视化参考。

五、版本记录与仓库结构的对照速查

为了便于检索和引用,这里将 CHANGELOG 条目与仓库文件建立一一对应关系:

CHANGELOG 条目 对应功能 仓库位置
0.1.0] Initial release SequentialAttention 核心模块 [sequential_attention/sequential_attention.py
0.1.0] Initial release 实验入口与超参数配置 [sequential_attention/experiments/run.py、hyperparams_sa.py
[0.1.0] Initial release OMP / Sequential Lasso / LLY 对比基线 sequential_attention/sequential_attention/benchmarks/
[0.2.0] Ensembled 实验 集成式注意力对比研究 Notebook SequentialAttentionTimeTracking.ipynb
[0.2.0] Ensembled 实验 实验结果说明与图表 ensembled_sequential_attention/README.md

此外,仓库根目录的 run.sh 提供了一条完整的本地复现链路:创建 virtualenv → pip install --editable . 安装包 → 运行 get_all_data.sh 下载活动、COIL、ISOLet、Mice 数据集 → 执行 python -m sequential_attention.experiments.run --num_epochs=3 --data_name=mice 快速验证;完整实验套件则可通过 python -m sequential_attention.experiments.experiments 运行,其内部会依次调度 run.py 并在 /tmp/model_dir 下按 数据集/experiment_seed_{1..5} 组织 5 个随机种子的结果,最终由 read_results.py 汇总各次实验的验证/测试准确率。

结语

sequential_attention/CHANGELOG.md 虽然篇幅简短,却是理解整个项目演进史与发布机制的入口:v0.1.0 承载了核心的 Sequential Attention 特征选择算法与完整实验框架,v0.2.0 则引入了 Ensembled Sequential Attention 这一集成扩展。遵循 keepachangelog 标准的标题格式、版本链接维护方式,以及与 __version__ 和 flit 打包的联动约定,共同构成了该项目"代码变更 → 版本记录 → 自动发布"的完整闭环。当你在该仓库中提交新功能时,按第三节的流程同步维护 CHANGELOG 与版本号,即可保证发布说明的准确与可追溯。

登录后查看全文
google-research