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 悄悄拉到下一个版本,行为又变了。

posted @ 2026-11-19 14:17  贝壳bkshell  阅读(4)  评论(0)    收藏  举报