Propel与Python生态互通:npy格式检查点让JS科学计算无缝衔接NumPy
Propel与Python生态互通:npy格式检查点让JS科学计算无缝衔接NumPy
在JavaScript里做科学计算时,绕不开与Python生态的数据互通。Propel 作为一套面向 JS 的深度学习与科学计算库,把 npy 格式作为与 NumPy 无缝衔接的官方桥梁:既能用一行代码把 Python 存下的 .npy 数组读进 JS 的 Tensor,也能把训练好的模型参数以 npy 检查点(checkpoint)写回磁盘,供 Python 直接加载。本文带你快速搞懂 Propel 的 Python 互操作能力。
为什么选 npy 作为 JS 与 Python 的桥梁 🌉
npy 是 NumPy 的原生数组存储格式,二进制、带自描述头、跨语言读取成本极低。Propel 在 npy.ts 中明确注释了设计意图:
This module saves and loads from the numpy format. Propel uses this for storing checkpoints.
也就是说,npy 在 Propel 里身兼两职:
- 数据入口:把 Python 侧准备好的数据集、特征矩阵直接喂给 JS 模型;
- 检查点载体:训练参数(Params)按 npy 逐张落盘,实现断点续训与跨语言共享。
其解析器严格按照 npy 官方规范实现:校验魔数 0x93 与 NUMPY 标识、版本号 1.0,再把头部信息转成 JSON 解析 shape 与 dtype(见 npy.ts 中的 parse 函数)。
| npy dtype | 含义 | Propel 读取支持 |
|---|---|---|
<f4 |
float32 | ✅ |
<f8 |
float64(读取后转为 float32) | ✅ |
<i8 |
int64 | ✅ |
| ` | u1` | uint8 |
<i4 |
int32 | ✅ 写/读 |
三步上手:加载与序列化 npy
1. 用 load 一行读入 NumPy 数组
load 已作为库的公共 API 从 api.ts 导出:
import * as pr from "propel";
const t = await pr.load("src/testdata/2.npy");
// t.shape => [2, 2],t.dtype => "float32"
这个示例文件正是由 Python 生成的:np.save('2.npy', <a href="https://link.gitcode.com/i/9ae3fdde4a4c9b1b4bacc50b4516db8e" target="_blank">[1.5, 43], [13, 2.5]]),加载后 shape、数值、dtype 与 Python 侧完全一致。仓库 [src/testdata/ 目录下提供了 1.npy、2.npy、3.npy、4.npy、uint8.npy 等一组标准测试样本,覆盖一维、二维、三维及多种 dtype,可直接用于验证你的互操作管线。
2. 用 serialize 把 Tensor 写回 npy
import * as npy from "propel/src/npy";
const t = pr.tensor([1.5, 2.5]);
const ab = await npy.serialize(t); // 得到 ArrayBuffer,写入文件即可
serialize(npy.ts)会自动计算 16 字节对齐的头部、写入魔数与版本,并逐元素写入小端序数据——这正是 NumPy 可识别的标准布局。
3. 从网络拉取并缓存 npy 数据集
在 dataset.ts 中,CIFAR-10 的图片与标签就是以远程 .npy 文件形式分发的:
const load = async(url) => npy.parse(await cache.fetchWithCache(url));
配合 cache.ts 提供的本地缓存机制,大尺寸 npy 数据集只需下载一次,之后重复实验秒级加载。
npy 检查点:DiskExperiment 的自动存盘机制 💾
Propel 的亮点在于:npy 不只是数据格式,更是训练管线的"存档点"。
在 Node 环境下调用 experiment("my_exp")(experiment.ts)会创建 DiskExperiment,其磁盘策略由 disk_experiment.ts 实现:
- 目录结构:每个检查点是一个以 step 编号的目录(如
00000007),每个参数张量按名字存成独立 npy 文件,例如00000007/hello/world.npy(测试用例见 disk_experiment_test.ts); - 自动存盘:默认每 60 秒(
saveSecs: 60)在训练 step 后落盘一次,进程正常退出时再补存一次; - 滚动清理:默认只保留最近 3 个检查点(
checkpointsToKeep: 3),旧目录自动删除; - 断点恢复:下次启动时
createOrRestore自动找到最新检查点,遍历其中所有*.npy恢复参数(disk_experiment.ts)。
这套结构对 Python 极其友好——Python 侧用 np.load 即可逐张读取检查点里的权重,无需任何转换脚本,天然构成"JS 训练、Python 分析"的工作流。
跨语言一致性:测试用例替你把关 ✅
Propel 为 npy 互操作配备了专门的回归测试 npy_test.ts,其中值得留意两点:
- 加载测试逐文件断言了
shape、dtype与数值(npy_test.ts),确保与np.save的产物逐位一致; - Python 往返测试(
npy_pythonInterop,npy_test.ts)会把serialize的产物通过管道喂给 Python,再用np.load解析,校验输出字符串完全相同——这是最严格的跨语言验证方式。
使用建议与常见坑 ⚠️
- 写入侧目前支持 float32 与 int32:
serialize的 dtype 映射表只包含这两种(npy.ts),uint8/bool 已列入 TODO,导出前先确认 dtype; - 仅支持 npy 1.0 版本且
fortran_order必须为 False:新版 NumPy 可能写出 2.0 格式,Python 侧可用np.save(file, arr, allow_pickle=False)前先确认;解析失败会抛出Unsupported version.之类的明确错误; - float64 读取会降为 float32:这是 JS 侧数值模型的统一精度选择,介意的场景请在 Python 侧先转成
float32再保存。
总结
Propel 用轻量但严格的 npy 读写实现(src/npy.ts)+ 磁盘检查点机制(src/disk_experiment.ts),让 JavaScript 科学计算与 NumPy 生态之间做到了真正的双向互通:Python 存的数据 JS 直接读,JS 训的参数 Python 直接拿。如果你的项目正计划引入浏览器或 Node 端的数值计算能力,这条 npy 通道值得作为与 Python 团队对接的第一选择。