iderex/cudec

# cudec 针对标准格式的开源 GPU 解压缩。 **目标：在 NVIDIA GPU 上以内存带宽速度批量解码 LZ4、Snappy、GDeflate 和 Zstd —— 可审计、故障安全闭合且经过模糊测试。** ## 为什么重要 只要解码吞吐量成为瓶颈，GPU 解压缩就至关重要：资产流式加载、分析扫描、ML 数据加载、检查点恢复。该领域唯一达到生产级别的库 NVIDIA 的 nvCOMP 自 v2.3 起就一直是闭源的——目前没有一个维护良好的开源库能在 GPU 上解码标准格式。Meta 的 dietgpu 虽然开源，但使用的是其专有的 rANS 格式；GDeflate 的参考实现仅支持 CPU；学术原型也早已停止维护。 cudec 填补了这一空白。不是在价格上——nvCOMP 是免费使用的——而是在闭源二进制文件无法提供的特性上： - **可审计性。** 解压缩器是经典的攻击面。cudec 中的每一个边界检查都是可读的、经过测试的，并针对参考实现进行了模糊对比测试——目前是 liblz4，随着 DEFLATE 和 Zstd 格式的加入，zlib 和 libzstd 也将纳入其中。 - **可移植性。** 优先支持 CUDA；HIP 移植是一个计划中的里程碑。被厂商锁定的二进制文件永远无法做到这一点。 - **可修改性。** 格式的特殊性、调优的权衡以及 kernel 设计都在代码树中有文档记录，而不是隐藏在技术支持合同背后。 ## 范围 仅限解码，面向批处理。压缩工作留在它本该属于的 CPU 上；当成千上万个独立的 chunk 并行解码时，GPU 就能展现出优势。在冷启动的 PCIe 总线上处理单个小文件不是其应用场景——这种情况 CPU 更有优势，本 README 也永远不会宣称其他情况。 ## 状态 **M0 和 M1 已完成；M2 正在进行中。** cudec 目前已经可以在 NVIDIA GPU 上解码真实的 LZ4——包括批量 block 解码、`.lz4` 帧格式（block 独立子集）以及固定主机内存的流式传输路径——所有这些都做到了故障安全闭合，并针对 liblz4 进行了模糊对比测试。设计记录详见 [docs/MASTERPLAN.md](docs/MASTERPLAN.md)；包含完整测试方法的 LZ4 block 和流式传输实测基准详见 [docs/BENCHMARKS.md](docs/BENCHMARKS.md)。Snappy、GDeflate、Zstd 以及 HIP 移植已在计划中，但尚未实现。进度在 issues 和 milestones 中跟踪： | 里程碑 | 交付物 | 状态 | | ---------------- | --------------------------------------------------- | ----------- | | M0 — Foundation | 工具链、CMake+CUDA 骨架、CI、测试工具套件 | 已完成 | | M1 — LZ4 block | Warp 协同 LZ4 block 解码，模糊对比测试 | 已完成 | | M2 — LZ4 批处理 | 帧格式、批量 API、流式传输路径、基准测试 | 进行中 | | M3 — Snappy | 在同一 kernel 家族上实现 Snappy 解码 | 计划中 | | M4 — GDeflate | 首个开源的 GPU GDeflate 解码器 | 计划中 | | M5 — Zstd | Zstd 解码 (FSE/Huffman 序列) | 计划中 | | M6 — 可移植性 | HIP 移植 | 计划中 | ## 原则 - **故障安全闭合。** 格式错误或恶意的比特流会产生明确的错误，绝不会导致越界访问，也绝不进行猜测。每一个拒绝路径都有对应的负面测试。 - **确定性。** 相同的输入，相同的输出——在每条代码路径上都做到比特级精确。 - **真实数据。** 记录在案的基准：[docs/BENCHMARKS.md](docs/BENCHMARKS.md)（`bench/bench_lz4`；语料库通过 `bench/get-corpora.sh` 获取，哈希固定）。每一项性能声明都随附了 GPU 型号、驱动程序、CUDA 版本、语料库和 chunk 大小分布。 - **最小化。** 用最少的代码完成工作；结构规则由一致性测试锁定。 ## 构建 有两种构建方式。仅主机构建只需要一个 C 编译器，并编译 ABI 和版本接口——不包括解码器——这样即使没有 CUDA 工具链（CMake ≥ 3.24），CI 也能拥有一个真正的构建门控： ``` cmake -B build && cmake --build build ``` CUDA 构建包含解码器（CUDA 12.x 工具链；推荐的路径是使用固定的开发容器——仅在运行标记为 gpu 的测试时才需要 GPU，构建本身不需要：如果没有 GPU，请在 ctest 命令行中移除 `--gpus all` 并添加 `-LE gpu`，以构建所有内容并运行主机端测试子集）： ``` docker run --rm --gpus all -v "$PWD:/w" -w /w \ nvidia/cuda:12.6.2-devel-ubuntu24.04@sha256:738fba0fbdb225b7a2931c58a5c8f03a84d3cd2f6a84975826a157339ef750b8 \ sh -c "apt-get update -q && apt-get install -yq cmake >/dev/null && \ cmake -B build-cuda -DCUDEC_ENABLE_CUDA=ON && \ cmake --build build-cuda -j && \ ctest --test-dir build-cuda --no-tests=error --output-on-failure" ``` ## 🤝 AI 辅助，人类主导 这里的开发是由 AI 辅助的。Claude (Anthropic) 协助处理单个流程步骤——生成和分析代码、运行对抗性安全审查，以及将文档和注释翻译成英文。它绝不会直接提交未经审查的最终成果：每一个步骤仅仅是一项提议。人类维护者会审查、理解，并在需要时进行编辑，然后签署通过每一项更改——由 AI 提议，由人类决定，并且人类始终对发布的每一行代码负责。这种审查规范，在志愿者项目力所能及的范围内，参考了医疗保健等关键行业中对获得 TÜV/BSI 认证的软件所期望的变更控制标准——但并不宣称已获得实际认证。简而言之：任何内容的合并不是因为某个工具提出了建议，而是因为人类对其进行了验证。 ## 许可证 [Apache-2.0](LICENSE)

标签：Bash脚本, 请求拦截