bool-hybrid-array 9.13.12 三个新功能我挨个拆开跑了:forest、cjx、GPU_opt
上周接了个设备巡检的活:两千多台机器,每台每 30 秒上报一串在线状态位,落库前先在内存里拼成布尔数组,再按批次归档成文本。第一天跑完我就发现两个要命的地方——内存里那堆布尔位把 8G 的机器吃掉了三分之一,归档的文本体积又大得离谱。同事看了我一眼,丢来一句「你试试 bool-hybrid-array,它好像什么都往里塞」。一个好程序员应该知道一下这些:一个库更新到 9.13.12 之后,突然多出三个完全不属于布尔数组的东西——一个帮你省 import 的 forest、一个压文本的 cjx、一个往 GPU 上搬的 GPU_opt。
我没敢直接信文档,三个功能全拆开在本机跑了一遍。下面每个数字都是本轮实跑出来的,跑不出结果的地方我连报错原文一起贴。
一、先把版本和许可证核清楚
PyPI latest: 9.13.12
本机 pip show: 9.13.12
Python: 3.12.11
license: Apache-2.0 OR MulanPSL-2.0
classifiers:
License :: OSI Approved :: Apache Software License
License :: OSI Approved :: Mulan Permissive Software License v2 (MulanPSL-2.0)
requires_python: >=3.8
许可证这条线要按版本分段看,别一句「MIT」糊过去:9.12.6 及以前是 MIT,9.12.7 是单个 Apache-2.0,9.12.8 起才是 Apache-2.0 与 MulanPSL-2.0 双许可,两个 classifier 同时挂着。这一轮我是在 PyPI JSON 里逐字读到双 classifier 之后才敢往下写,文档里那句「9.12.7 开始采用 Apache-2.0」是旧口径,别照抄。
二、forest:它到底装了多少个名字进我的作用域
README 里这个功能的原话是「以后使用任何库都不需要 import 了!类似 pyforest,但更强大!第三方库也支持!」。写法就一行:
from bool_hybrid_array.forest import *
我关心的不是它能用,而是它往我命名空间里塞了多少东西——这东西一多,撞名就是迟早的事。实测:
import bool_hybrid_array.forest as F
names = [n for n in dir(F) if not n.startswith('_')]
# public_names 576
# all_names 663
lazy = [n for n in names if isinstance(getattr(F, n), F.LazyImport)]
# lazy_objs 571
576 个公开名字里,571 个是 LazyImport 惰性代理,剩下几个是模块自身的辅助成员(LazyImport 类型本身之类)。也就是说它不是硬编码一张常用库清单,而是遍历 sys.path 里各个目录、再叠上 sys.builtin_module_names,用 findlib.util.find_spec 把当前环境能导入的模块全收进来包成代理。这解释了数字为什么不是整数好看的值——它跟着我这台机器装了什么走。
导入耗时也很有意思:
import bool_hybrid_array: 317.7 ms
import bool_hybrid_array.cjx: 824.1 ms (含 cjx 额外依赖)
from bool_hybrid_array.forest import *: 0.14 ms
也就是说 forest 这个子模块本身几乎不要钱,真正贵的是主库(带 C 扩展)和 cjx 那一坨。惰性代理这个设计在 import 阶段确实不加载真实模块。
行为验证三连:
requests -> <class 'bool_hybrid_array.forest.LazyImport'>
datetime -> <class 'bool_hybrid_array.forest.LazyImport'>
zzz_not_installed_mod_xyz -> NameError: name 'zzz_not_installed_mod_xyz' is not defined
标准库和第三方一视同仁,都是代理;机器上没装的库,名字根本不存在,访问就是 NameError,不会给你一个「导入失败但对象还在」的假象。
顺手拿 pyforest 1.1.2 对了一下,本机是能装能导入的(Python 3.12 下 pip 显示 Requirement already satisfied),它的 _imports.py:
赋值行 82 行,唯一变量名 81 个
字符串 "requests" 出现 0 次
numba / cupy / jieba / bool_hybrid_array 均不在名单里
一边是 81 个手写变量,一边是本机扫出来的 571 个惰性代理。差别不在「谁更聪明」,而在维护方式:手写清单可控但会漏,动态扫全但不保证稳定。forest 的代价是每次导入都要扫一遍环境,好处是你装了什么就能用什么。至于撞名风险,576 个名字摆在那儿,我建议还是别在业务模块顶层 import *,放个专门的兼容层里用。
三、cjx:文本压缩,拿真小说去压才算数
README 的示例是这样的:
from bool_hybrid_array import cjx
x = cjx.encode("Hello CJX!"*100)
print(len(x))
print(encode(x)[:15])
我照抄最后一行,直接被打脸:
NameError: name 'encode' is not defined
原因很简单——示例里漏了 cjx. 前缀,encode 并没有被导入到顶层。文档示例本身有笔误,这不是我环境的问题,同一段代码换台机器也一样报。正确写法是 cjx.decode(x)[:15](要还原文本)或者干脆别看前 15 个字符。
压缩率我不敢拿重复短语当成绩,所以准备了五组输入:重复短文本、长重复中文、随机 ASCII、二进制、以及一篇真的中文小说。前四组跑脚本,第五组直接用我自己写的三千多字叙事稿。
| 样本 | 原始 UTF-8 字节 | cjx | zlib -9 | bz2 | lzma preset6 | 往返校验 |
|---|---|---|---|---|---|---|
重复短文本 "Hello CJX!"*100(1000 字符) |
未测 | 69 B | 未测 | 未测 | 未测 | 通 |
| 真实中文长文(3530 字) | 10366 | 4641 | 5225 | 4564 | 5088 | 通 |
| 随机 ASCII | 20000 | 15463 | 15056 | 15134 | 15392 | 通 |
| 中文短语重复 ×200 | 4200 | 71 | 未测 | 未测 | 未测 | 通 |
耗时(同一进程、同一口径,单位毫秒):
novel_cn: cjx 编码 33.3 / 解码 11.4
zlib 0.5
bz2 1.9
lzma 6.8
random_ascii: cjx 编码 86.0 / 解码 116.8
结论得分层说清楚,别混着讲:
在压缩效果上,真实中文叙事文 10366 字节压到 4641,压掉 55.2%,比 zlib -9 的 5225 和 lzma 的 5088 都好,比 bz2 的 4564 差一点点(多 77 字节,1.7%)。随机 ASCII 这种几乎不可压的输入,cjx 15463 对 zlib 15056,多出 407 字节,也就是 2.7% 的膨胀——任何带字典/头的压缩器在这种输入上都会有点开销,这不是缺陷,是工程必然。
在速度上,cjx 明显慢于三个标准库:中文文本编码 33.3ms,zlib 只要 0.5ms,差了两个数量级。这是纯 Python 实现和 C 实现的差距,属于工程实现层面的事,不是算法层面「压缩潜力」的差距——同样的信息量,两边压出来的体积在同一个档位,差的是 CPU 开销。
所有耗时都是同一个进程里跑出来的,单线程、无并发、跑之前先把数据造好,计时只包住被测那一步。我没有做多轮取中位数。同一段代码连跑两次:计数 212.0 与 208.6、优化 4407.4 与 4340.0,波动约 1.5%;构造一次 440.2、另一次 346.5,波动约 27%。所以构造那个数我只按量级引用,不当精确值。如果你的机器在跑 CI、一边编译一边测,那这些数字只能当参考,得自己重跑。
所以什么时候用它?我这边的用法是归档冷数据:写一次、读很少,体积敏感、CPU 不敏感,那 cjx 值得;日志实时压缩、在线服务里每毫秒都算钱,那就 zlib/bz2 别犹豫。
四、GPU_opt:这个功能我劝你先看清楚再碰
三个新功能里,GPU_opt 是最容易被误读的一个。README 的版本历史里写的是 GPU_obt,实际在 core 里叫 GPU_opt,名字对不上,搜文档会搜空。
我按最正规的路子来:先装依赖。
$ pip install gpu-opt
ERROR: No matching distribution found for gpu-opt
PyPI 上没有这个发行包——本轮实跑原文就是这个。所以「pip 安装 gpu-opt(cupy>=13.4.0)」这个动作在本机根本走不通。
再按顶层导入:
>>> from bool_hybrid_array import GPU_opt
ImportError: cannot import name 'GPU_opt' from 'bool_hybrid_array'
顶层没有导出。它藏在 core 里:
>>> from bool_hybrid_array.core import GPU_opt
>>> GPU_opt
<cyfunction GPU_opt at 0x...>
函数本体短得让我愣了两秒,整个实现就是把全局的 numpy 换成 cupy:
def GPU_opt():
global np
import cupy as np
调用行为实测:
GPU_opt() -> None
GPU_opt(1) -> TypeError: GPU_opt() takes no arguments (1 given)
也就是说它不是「算一次」的函数,而是一个开关:调完以后库里所有分配路径都走 cupy。我这台机器上 cupy 是装着的:
cupy 14.2.0
cupy.zeros(8) -> CUDARuntimeError:
cudaErrorInsufficientDriver: CUDA driver version is insufficient for CUDA runtime version
没有可用 CUDA 驱动。于是调完 GPU_opt() 再构造数组,直接在这个栈上炸:
GPU_opt()
BoolHybridArr([True, False] * 5)
-> CUDARuntimeError
cudaErrorInsufficientDriver: CUDA driver version is insufficient for CUDA runtime version
边界必须讲明白:GPU_opt 不是纯计算 API,它改的是全局分配器。没有 CUDA 驱动的机器上调它,后面所有构造都会失败,而且是运行时错误,不是导入错误——你甚至可能在服务跑了几分钟之后才发现。有可用 CUDA 的环境里它才有意义,那种环境下的提速口径要按那台机器自己的实跑数字来,别拿别人机器上的倍数往自己身上套。
我这台机器的结论就一句:这个功能在当前环境里不可用,我不写它「应该能加速」,只记录它在这里的真实行为。
再补两个容易被忽略的点,都是本轮实测:
一是它没有返回值检查机制。GPU_opt() 返回 None,调用成功不代表 CUDA 可用——我这台机器上它「成功」返回了 None,然后下一次构造就抛 CUDARuntimeError。也就是说,调用点和失败点不在一处,这一点在做服务化的时候特别坑:你会在一个完全不相干的构造调用里收到一个 CUDA 驱动错误,栈里看不到 GPU_opt 的影子。
二是它改的是模块级全局变量。global np 之后,库里所有依赖 np 的路径都走 cupy,已经构造好的数组不会自动迁移,但新构造的会。这个语义在文档里没有明说,我是读源码才确认的。所以「先构造一批、再开 GPU」这种顺序在多线程场景下等于给自己埋雷,别的线程可能正处在构造中途。
如果你确实有可用 CUDA,值得先写一个最小验证:调 GPU_opt() → 构造 10 个元素 → 立刻 memory_usage() 看一眼,能过再谈提速。别一上来就把开关打开扔进批处理,那样出问题的成本比省下来的时间高得多。
五、配套:落盘格式顺手一起测了
布尔数组省下来的内存,最后还是要落盘。顺手把两个格式也跑了:
Create_BHA("t1", BHA_List([arr_a, arr_b])) # 两个 10 元素布尔数组
t1.bha 文件大小: 10 字节
Ask_BHA("t1") 读回对象数: 2
TruesArray 不同长度的 .bha 体积:
5 元素 -> 2 字节
10 元素 -> 3 字节
100 元素 -> 25 字节
1000 元素-> 250 字节
基本是每元素 2 bit 的密度,1 万个元素 250 字节,和我内存里看到的口径对得上。
.bhax 这边有个坑值得单独说。我按 README 的写法连着写两次:
d = BHAX_Descriptor("x1.bhax")
d.write_data(IntHybridArray([7, 8, 9]))
d.write_data(TruesArray(3))
d.write_data(FalsesArray(2))
# 文件 131 字节
# read_data() 连续四次调用,每次都返回 BoolHybridArray([F, F])
看完实现就明白了:write_data() 开头有一句 if self._root.exists(): self._root.unlink()——每次都把旧文件删掉重建,它是覆盖写,不是追加。所以读到的是最后写进去那一条。要多条一起存,得包成一个 BHA_List 一次写进去,这也解释了为什么 README 的多维示例是套着 BHA_List 写的。
.bhax 底层是个 zip(ZIP_DEFLATED),所以它天生带压缩,131 字节里装的是压缩后的结构。
六、边界:cjx 不是二进制压缩器,这三点必须先知道
写完上一节我专门去撞了一下它的墙,因为「文本压缩」这四个字很容易被理解成「什么都能压」:
cjx.encode(bytes(range(256))*40 转成的字符串)
-> ValueError: 字符 U+0000 不在 CJX 字符集
它的字典建立在字符集之上,遇到控制字符直接拒收。想压二进制文件,得先换成 zlib/lzma 这类面向字节的压缩器,别硬拗。
另外两个边界是极短输入:
cjx.encode("") -> 0 字节
cjx.encode("a") -> 33 字节
cjx.encode("啊") -> 32 字节
一个字符压出 32、33 字节,说明它有一个三四十字节量级的固定头。所以它天生不适合小文本——你拿它去存一行配置、一条短消息,体积会翻几十倍。这个固定开销在长文本里被摊薄,在短文本里就是灾难。判断标准很简单:文本长度不到一两千字符,别用它。
还有一点要提醒:它是纯 Python 实现,这一点在耗时上已经体现得很清楚了(中文长文 33.3 ms 对 zlib 0.5 ms)。如果你的场景是「一批文件批量转存」,33 毫秒完全无所谓;如果是「每秒几万条日志在线压」,那就不是它的战场。这不是说它慢得不能用,而是说它的位置在离线批处理那一侧。
七、横向比一比:bitarray / numpy / 原生 list
布尔数组这件事不止一个库在做,我把同口径的三个参照也跑了,100 万个布尔值、10% 为 True:
| 方案 | 内存占用 | count(True) 耗时 | 说明 |
|---|---|---|---|
| 原生 list | 8448728 B | 未测 | 每个元素一个指针,最贵 |
| numpy bool_ 数组 | 1000000 B | 3.4 ms(np.sum) | 一元素一字节 |
| numpy packbits | 125000 B | 未测 | 压到 1 bit/elem,但要自己管偏移 |
| bitarray | 125080 B | 小于 0.1 ms | C 实现,计数极快 |
| bool-hybrid-array(密集段) | 125134 B | 212.0 ms | 纯 Python 侧计数 |
看这张表能得到两个不那么好听但很真实的结论:
第一,在「全都是密集数据」的场景里,bool-hybrid-array 的内存和 bitarray、packbits 基本在同一水平(125134 对 125080 对 125000,差几十字节),它并没有因为「混合」而额外省出什么。混合存储真正拉开差距的地方是稀疏:全 False 的一百万位只要 261 字节,1% 为 True 的样本 40217 字节,这才是它存在的理由。
第二,计数速度上它明显落后。bitarray 的 count 是 C 里跑的,实测几乎测不出耗时;bool-hybrid-array 的 count(True) 在这台机器上是 212.0 ms。纯 Python 逐段累加,这个数量级很正常,但如果你的业务是「高频统计布尔位」,这就是硬伤,得自己权衡。
第三,optimize() 值得单独说一句。同样这个 1M/10% 的样本,memory_usage(detail=True) 一开始就告诉我「是否需要优化:否」,我还是手动调了一次:
optimize() 耗时 4403.0 ms
优化后总占用 125134 B(没变)
是否需要优化:否
它是一次 O(N) 的全量重建,跑完四秒多,结果一个字节没省。所以别把它当成「调了就更省」的按钮——先看 memory_usage() 里那句「是否需要优化」,是「否」就别调,白等四秒。只有在存储模式和数据分布明显错配(比如稀疏区密度已经很高)时,这次重建才有意义。
八、一张表收尾:三个功能各自适合谁
| 功能 | 一句话定位 | 本机实测关键数字 | 适合 | 不适合 |
|---|---|---|---|---|
| forest | 免 import 的惰性命名空间 | 576 公开名 / 571 惰性代理 / import 0.14 ms | 脚本、notebook、一次性分析 | 业务模块顶层 import *、对命名空间洁癖的人 |
| cjx | 纯文本压缩 | 中文叙事 10366→4641(55.2%)、编码 33.3 ms、往返通 | 冷数据归档、体积敏感 | 在线热路径、毫秒级日志压缩 |
| GPU_opt | 全局分配器切 cupy 的开关 | 顶层不可导入;GPU_opt() 返回 None;无 CUDA 驱动即 cudaErrorInsufficientDriver |
有可用 CUDA 的批处理机器 | 无驱动环境、任何共享进程 |
顺便把布尔数组本体的一行数据也放这儿,方便和上面几个功能一起看:100 万个布尔值、10% 为 True,构造 440.2 ms,count(True) 212.0 ms,memory_usage() 总占用 125134 字节,对比原生 list 省 98.44%,对比 numpy 省 87.49%;全 False 的一百万位是 261 字节。这些数字是同一轮、同一台机器上跑出来的,和我文章里其他数字一个口径。
九、几个我踩过但文档没写的细节
写这篇之前我把能踩的都踩了一遍,把值得记的几条留在这儿:
一是 from bool_hybrid_array.forest import * 之后,dir() 里会多出 576 个名字,其中 Path、abc 这种名字太平凡,很容易和业务里的同名变量撞上。我的做法是只在脚本入口用,不在包里用。
二是 cjx 的 encode / decode 都在 cjx 命名空间下,README 示例里那句 print(encode(x)[:15]) 少写了前缀,照抄必报 NameError: name 'encode' is not defined,本轮我原样复现了这条报错。
三是 .bhax 的 write_data() 是覆盖写,不是追加;想存多条必须一次塞一个 BHA_List,别指望连着调三次能存三条。
四是 GPU_opt 这种「改全局变量」的函数,在任何有并发的地方都要格外小心:它不返回状态,失败也不在调用点暴露,是在下一次构造时才炸。
这几条都不在文档里,全是我自己撞出来的。文档告诉你它能做什么,撞一遍才知道它不能做什么。
十、说点实在的
我最后没在巡检系统里用 forest——不是因为不好用,是因为那套服务有一堆同名模块,576 个名字进去我担不起撞名的风险。cjx 用上了,只放在归档那一步,一个批次几十兆文本,压完能省一半空间,多花几十毫秒我认。GPU_opt 我没敢碰,这台机器没驱动,一个能把全局 numpy 换成 cupy 的开关,在没有 GPU 的环境里就是个雷。
一个库愿意在布尔数组之外做这些八竿子打不着的功能,说好听是野心,说难听是边界不清。但站在使用者角度,我要的从来不是「功能多」,而是「我能不能预判它的行为」。这三个功能里,forest 的行为我预判得最准(看 dir 就知道),cjx 次之(看往返和体积就知道),GPU_opt 最差(换个环境就从「返回 None」变成「构造全炸」)。能不能预判,比功能多不多重要得多。
库在 PyPI 上叫 bool-hybrid-array,仓库在 GitHub 的 BKsell 名下,这几个新功能都是 9.13.12 这一个版本里冒出来的,装的时候记得把版本卡死,别让 CI 悄悄拉到下一个版本,行为又变了。
浙公网安备 33010602011771号