预处理
common/data/prepare_*.py，产出一个本地的 parquet 或 jsonl 目录。
推一个版本
v2。
在控制台中使用
- 打开 数据 → 数据集，上传文件并发布版本，或打开已有数据集。
- 在作业中使用 区域直接展示可复制的版本引用。展开 使用指南，选择版本、 训练输入 或 验证输入，再选择该版本中的文件。
- 将生成的参数追加到已有的
tp submit命令，保留实验名、模型、硬件配置等其他必需参数。 - 如果使用自己的预处理脚本，复制 Python 路径示例。数据集准备完成后，作业内才会有对应的环境变量。
@版本 的引用。
导入选定的 Hugging Face 分片
在 数据 → 数据集 → 从 Hub 导入 中选择 Hugging Face，打开 选择配置与数据划分， 填写仓库数据卡中声明的配置名称和数据划分。导入器会先固定仓库 commit，再复制所选 Parquet 或 JSONL 文件，保留文件名、已有分片边界和内嵌图片。 记录文件模式 可以缩小已声明划分的文件范围，例如data/train-*.parquet。
数据卡没有声明 configs 时，这一项必填。此时会记录你指定的文件范围及标签，
不会自动推断仓库的数据划分。每个模式都必须匹配到文件。
记录引用外部图片时，还需填写 关联图片模式，例如 images/**/*.png。
路径相对于仓库根目录，导入后也相对于数据集根目录。内嵌图片不需要额外文件。
导入器只复制文件，不解码图片，也不执行数据集脚本。
此模式目前支持公开仓库、Parquet/JSONL 记录文件及显式选择的关联图片，单文件上限为
8 GiB。其他格式需要先预处理再上传。私有 Hub 凭据、自动格式转换和物理重分片尚未开放。
关闭选择开关可沿用整个仓库导入方式。
导入列表和数据集来源区域会显示所选配置、划分及固定 commit。新建的数据集默认私有；
导入成功不代表扫描通过，也不授予训练准入。仍需对新版本执行所需的数据治理检查。
图片治理的 CPU OCR
图片治理默认使用 CPU 引擎governance_ocr_engine=rapidocr-v6。worker 需要安装
服务端 ocr-v6 可选依赖，并包含已校验的 PP-OCRv6 small 模型包。可在源码目录运行
docker build --build-arg BUILD_NATIVE=1 --build-arg BUILD_GOVERNANCE_OCR=1 -t governance-worker .
构建包含模型的 worker 镜像，再将仓库中的镜像摘要配置为 governance_worker_image。
普通控制平面镜像不包含 OCR 模型。已有显式配置仍然生效：rapidocr 使用旧引擎，
空值关闭 OCR。启用新默认值前请先升级获准的 worker 镜像；模型缺失会导致作业失败，
不会自动选择其他引擎。也可以在可联网的构建机运行
scripts/prepare_governance_ocr.py --output <directory>，然后将整个目录放入
worker 镜像的 /opt/tuneplane/ocr-v6，保持只读且允许 worker 用户读取。
模型缺失或校验失败时，worker 会拒绝执行，不会临时下载。v6 引擎将 ONNX 和
OpenCV 限制为单线程，并检查推理会话只使用 CPU。
JPEG、PNG、静态 WebP 及支持范围内的 TIFF，其 OCR 输入会按 EXIF 方向转正。脱敏区域使用原始图片
坐标，派生图片会转正并移除元数据。无效或不完整的 OCR 输出不能计为完成检查。
TIFF 首版支持经典单页、无符号 8 位灰度、RGB 及非预乘透明度 RGBA，每张最多
4096 个条带或瓦片。多页、BigTIFF、金字塔、分平面、带透明度灰度及高位深图片
仍不支持，也不会计为完成检查；图片大小和解码预算仍然生效。
原生解码器将转正后的 RGBA 像素共享给 CPU OCR，省去再次解码。
启用生产策略前，应使用自己的文档验证中文识别及敏感区域
覆盖率；内置简繁体样本仅用于回归检查。
Parquet 治理会复用有界的 Arrow 批次投影，并在编码前合并输出块。
未修改字段的类型、原始行标识和内嵌图片校验均保留。精确去重的临时索引使用
紧凑二进制指纹，报告标识和保留记录顺序不变。这些优化不能代替实际部署的 TB 级验收。
对比治理前后的数据分布
发起检查时开启 采集分布对比，系统会自动统计长度。语言、任务和来源可分别指定 元数据字段路径，以及最多 64 个以逗号分隔的类别标签。例如，字段填/language，
标签填 en, zh, fr。未声明的取值归入 其他，缺失或为空、未配置的维度会单独显示。
处理完成后，分布对比 展示源数据和输出的记录数、占比及变化的百分点。
JSONL 和 Parquet 都在处理过程中采集统计。长度为每条记录中映射文本的 Unicode
字符数，不是 token 数，也不含 OCR 文本；分母为零时显示横线。
语言、任务和来源来自声明的元数据标签，不代表自动识别。该对比不含隔离区后来放行的
记录，也不代表下游模型质量评分或训练准入许可。旧任务会显示未采集分布；如需统计，
请启用采集后发起新的检查和处理。
源文件、输出文件和索引的临时磁盘空间
选定分片的 HF 导入和治理 Parquet 读取器会在下载前预留临时文件空间。 当 scratch 卷的预算已被占用或剩余空间不足时，会拒绝新的源文件；原有的校验和发布检查仍然执行。 处理结果、隔离结果和审核释放结果共用该预算池，在文件增长前申请额外容量。 管理员可以将TUNEPLANE_SCRATCH_DIR 设置为绝对路径的私有目录，并设置
TUNEPLANE_SCRATCH_MAX_BYTES（默认 64 GiB）及
TUNEPLANE_SCRATCH_MIN_FREE_BYTES（默认 1 GiB）。通过
TUNEPLANE_SCRATCH_OUTPUT_MAX_BYTES 设置单个输出文件上限（默认 8 GiB）。
空输出不会预占整个上限，而是在写入前按需申请。超限会导致操作失败，不会截断记录或发布不完整的数据集。
可以拆分输入，或调整限额后重试。共享目录的进程必须使用相同的预算池限额。
未配置时，导入使用 Hub 缓存目录，治理读取器和输出写入器使用进程临时目录，两者是独立预算池。
发现项、重复记录、图片资产和图片处理指令的临时索引也纳入该预算池。
通过 TUNEPLANE_SCRATCH_INDEX_MAX_BYTES 设置单个索引数据库的上限（默认 1 GiB）。
与输出不同，索引会在加载记录前预留整个上限；需要额外排序文件的查询会被拒绝。
请为同时存在的源文件、索引和输出预留足够容量，或降低并发数。
对于本地 Docker/Podman Fleet 上已授权的治理 worker，显式配置目录后，平台会自动传入共享挂载和数值限额。
目录必须由服务 UID 持有、仅服务用户可访问，并且只包含 scratch 状态文件。
Docker 主机上必须能通过同一路径访问该目录；容器化部署的控制台需要对应的主机绑定挂载。
worker 使用服务的 UID/GID 运行，并在领取工作前校验预算池身份。普通作业不能通过环境变量申请此可写挂载。
这不提供操作系统文件系统配额，也不代表启动前已预留整次任务的容量。
生产挂载和具有代表性的 TB 级负载仍需验证。导入因容量不足被拒绝后，可在空间可用时重新发起。
从作业里引用它
如果脚本支持配置中的平台字段，可以在experiments/<experiment>/config.yaml 中声明引用。
与已有的 data 段合并，不要重复添加 YAML 键。TRL SFTConfig 等严格的训练配置不接受此段，
请使用下方的命令行参数。部分配方仍需通过 --train-data 指定输入文件：
<NAME>_DATA_DIR。所以 --train-data 是
数据集内部的路径，不是你机器上的路径。
数据集清单（含预签名 URL）在提交时生成并写进作业包。作业侧不需要对象存储凭据，也不需要通往控制台
的路由。
如需同时使用同一版本中的验证文件，在命令中追加：
@v2 可以固定输入；省略版本则在提交时解析为最新版本。
在自己的脚本中，运行时读取平台注入的路径：
input_file 传给数据加载器。变量名取数据集名称的大写形式，将 - 和 . 换为 _，
再加 _DATA_DIR；不包含所有者和版本。这不是本机终端上的变量。
处理结果写入 $TUNEPLANE_OUT_DIR；作业声明输出数据集时，数据集文件写入 $TUNEPLANE_DATASET_OUT_DIR。
写一张数据卡
只有名字的数据集，对除了推它的人以外所有人都是黑盒，而挑错数据要花掉几百 GPU 小时。在目录里放一个README.md，tp dataset push 会连数据一起发布它：
管理
parquet 的预览为什么更好
parquet 的 footer 里带行数和声明的列类型，读它只花几 KB。所以一个 parquet 数据集显示的是精确行数和 真实类型 ——int64、string、timestamp[us] —— 而不是从前几行猜出来的类型。
jsonl 和 csv 要数行数就得全量扫描，所以它们显示 — 而不是一个猜测。
平台读 footer 和第一个 row group，有字节上限。用很大的 row group 写出来的文件（每组 64 到 128 MB
是常见设置）不会有样本行；列和行数照样显示，并在样本本该出现的位置留一句说明。
预览里的列长度是截断之前量的。样本单元格在送往浏览器的路上被切到 160 字符，所以从样本算出的
平均值永远等于那个截断上限 —— 一个你没法用来定 max_seq_len 的数。
推之前先抓污染
--fields 把范围收到题干上：同一个短语出现在答案里不算污染。
匹配用归一化的 13-gram，也就是 GPT-3 和 PaLM 的污染分析用的窗口。大小写、标点和全角形式不改变
判定。中文按字切 shingle，因为按空格切会把整句话变成一个 token，什么都找不到。
读质量报告
tp dataset push 会算同一份报告并随版本存下来，控制台在数据集页顶部显示它。手动跑这条命令是为了
在推之前先看一眼。
它只数机器能确定地数出来的东西。一个回答好不好是人或裁判的判断，那是
偏好标注。
近重复用一个小的 MinHash。模板生成的数据 —— 五十条只差一个数字 —— 会被报成重复，那不是误报。
那正是这份报告存在的意义。
不搬字节就能比较两个数据集
tp dataset push 会在算校验和的同时算一份 n-gram 指纹，随版本一起上传。push 本来就要把每个
文件读一遍，所以在那里切 shingle 几乎不花钱；事后再算就意味着从对象存储里把几个 GB 拉回来。
两边都有指纹时，比较两个数据集就是一次集合求交：
指纹比较是估计。抽样只会产生漏报，而一个很小的数据集可能完全没被抽到。小数据集用
tp dataset check，它点名具体行而不是给一个比例。指纹功能之前推的版本没有指纹，接口会明说这件
事，而不是报”没有污染”。敏感值扫描
一个版本发布之后，平台会扫它一次，结果出现在数据集页上。它产出一份报告，从不改写你上传的 东西。 这份报告说了三件多数扫描器不说的事：- 它读了多少行。 一个 100 GB 的数据集不可能在提交的路上读完，所以扫描读的是分散在每个文件里 的有界窗口。抽样的扫描永远说不出”干净”，只能说”我看过的部分里没有”。
- 每条发现的严重级别。 API key、私钥或校验位正确的身份号是
high。邮箱和电话是medium。 通用长 token 规则是low，因为它会命中一个代码语料里的每个 base64 块和 git SHA。 - 没跑过的时候什么都不说。 缺失的报告渲染成未扫描，从不渲染成干净。
TUNEPLANE_DATA_SCAN_POLICY=block）只在 high 上阻断。管理员可以用
TUNEPLANE_DATA_SCAN_DENY_TERMS 加本部署特有的词，用 TUNEPLANE_DATA_SCAN_ALLOW_TERMS 压掉已知
误报。那些是词，不是正则 —— 平台会转义并编译它们。
真要清洗一个数据集，跑一次 Processing Run：读它、用你自己的代码处理、
发布一个新版本。
Hub 数据集也可以
在配置里直接写一个 Hugging Face 或魔搭 id：确认成功
tp dataset ls alice/gsm8k-zh 会列出你推的版本，控制台的 Files 标签页显示文件数和校验和。在运行中
的作业里，echo $GSM8K_ZH_DATA_DIR 会打印缓存路径。