把ZIM镜像变成Hugging Face数据集：kage parquet无损往返导出Parquet实战-平芜编程栈

把ZIM镜像变成Hugging Face数据集：kage parquet无损往返导出Parquet实战

【免费下载链接】kageShadow any website for offline viewing, with the JavaScript stripped out项目地址: https://gitcode.com/gh_mirrors/kage6/kage

kage 是一款开源的网站离线镜像工具：它用真实无头浏览器渲染网页、剥离全部 JavaScript，再把整站打包成单文件 ZIM 归档。本文带你实战kage parquet子命令——只需两条命令，就能把 ZIM 镜像无损导出成 Parquet 列式数据表，这正是 Hugging Face 数据集期望的形状；再用一条命令反向导入，还能把 Parquet 完整还原回 ZIM，实现字节级的无损往返。

为什么要把 ZIM 镜像变成 Parquet 数据集？

ZIM 是单文件归档，适合分享和阅读；但如果你想用 SQL 查询镜像内容、把爬取结果作为网页语料数据集发布、或与其他爬虫数据集合并训练，列式格式会更顺手：

形状标准：Parquet 表是"一行一个条目"的扁平结构，url、title、text等列名与 open-index/open-markdown 等主流网页数据集对齐，导出文件可直接放进 Hugging Face 数据集仓库；
查询友好：DuckDB、pandas 可以原样读取，离线即可全文检索；
无损往返：这不是一次性的单向导出。Parquet 表里保留了原始字节和 ZIM 结构信息，ZIM → Parquet → ZIM 的往返能复现每一个条目、其元数据和主页面。

准备工作：先做一个 ZIM 镜像

如果你还没有现成的 ZIM 文件，三步即可得到（安装 kage 可参考 README.md）：

kage clone paulgraham.com # 克隆整站到 $HOME/data/kage/paulgraham.com kage pack paulgraham.com # 打包成单个 ZIM 归档 -> paulgraham.com.zim

打包是确定性的：同一个镜像两次打包产出字节完全相同的文件，可以放心做校验和缓存。

一键导出：kage parquet export

核心命令只有一行：

kage parquet export paulgraham.com.zim -o paulgraham.parquet

省略-o时默认输出同名的.parquet文件。运行后终端会打印导出统计：

exported paulgraham.parquet rows 142 redirects 1 content 4.2 MiB size 3.8 MiB

Parquet 文件本身也用 zstd 压缩，体积通常比 ZIM 更小巧。

表里到底有哪些列？

导出实现位于 dataset/dataset.go，每行一个归档条目，列分为两组：

列	说明
`doc_id`	页面 URL 派生的确定性 UUID v5，同一页面每次导出都是同一个 id
`url`/`host`	条目路径与镜像的站点主机名
`title`/`mime`	页面标题与 MIME 类型
`crawl_date`	抓取日期（来自 ZIM 元数据）
`text`/`text_length`	HTML 页面的可见文本（自动剔除 script/style）
`namespace`	单字母 ZIM 命名空间：C 页面资产、M 元数据、W 主页面指针
`is_redirect`/`redirect_target`	重定向条目及其目标，例如`C/index.html`
`content`	条目原始字节——正是这一列让导出可无损还原

其中text列的文本抽取逻辑见 dataset/dataset.go，它会把script、style、noscript之外的文本拼成一段干净纯文本，非常适合直接做全文检索。

无损验证：kage parquet import 还原 ZIM

真正的亮点是反向操作：

kage parquet import paulgraham.parquet -o paulgraham2.zim kage open paulgraham2.zim # 用还原出的 ZIM 离线浏览

导入端会重新写入每个条目的原始字节、元数据，并从W/mainPage重定向行恢复主页指针，见 cli/parquet.go。项目内置的往返测试 dataset/dataset_test.go 校验了：行数与重定向数一致、页面 HTML 逐字节相同、图片字节不变、元数据 Title 保留、主页面仍正确解析。

这意味着 Parquet 表双重身份：既是可查询的数据集，也是一份可逆的归档副本。

导出后的两个高频用法

1. 离线全文检索镜像内容。ZIM 本身不带 Xapian 全文索引，而 Parquet 表可以交给 DuckDB 直接查：

duckdb -c "SELECT url FROM 'paulgraham.parquet' WHERE text ILIKE '%schlep blindness%'"

完整思路见官方指南 docs/content/guides/packing-a-mirror.md。

2. 作为 Hugging Face 数据集发布。把.parquet文件放进数据集仓库即可——列名与主流网页爬取数据集对齐，doc_id稳定可去重，下游用 datasets 库或 pandas 加载零改造。

小结

步骤	命令	产物
克隆 + 打包	`kage clone`+`kage pack`	单文件 ZIM
导出	`kage parquet export a.zim`	Hugging Face 数据集形状的 Parquet
还原	`kage parquet import a.parquet`	逐字节还原的 ZIM