数据形状与按设计血缘切分

data:
  quality:
    group_key: design            # 一行属于什么
    max_group_leak_ratio: 0.0    # 留出集里最多多少可以和训练集共用一个

这里的数据集就是一堆 JSON 对象，仅此而已：平台存它、剖析它、扫描它、把它交给框架，一行里是什么 是框架的事。这是正确的默认，而它只在一个地方不再正确 —— 有人为一份数据挑了 recipe，然后在训练跑到第四十分钟时才发现行是偏好对、而 recipe 要的是对话。这一页讲平台后来学会对语料内部说的两件事：它的行声称是什么形状，以及一行属于什么，好让切分能整个留出一个设计，而不是留出它的一个随机样本。

九种形状

形状是声明的，不是猜的，检查器只验证这个声明。另一条路是推断，而它在要紧的那一点上更糟：读三行去猜的启发式几乎总是对的，而那个「几乎」意味着一次无声的错训，而不是一次拒绝。这里没有 generic，也没有 custom。什么都不意味着的格式无法被检查，只会变成一个要填的字段；形状不在这份名单上的语料，干脆什么都不声明，其余一切照旧。 messages —— 对话 SFT。非空列表，每一项都带非空的 role 和 content。

{"messages": [{"role": "user", "content": "Explain clock domain crossing"}, {"role": "assistant", "content": "A CDC is ..."}]}

prompt_completion —— 普通的有监督文本。两个键都是非空字符串。

{"prompt": "Write a 4-bit counter", "completion": "module counter(...);\n..."}

preference —— DPO 及其同类。

{"prompt": "Review this always block", "chosen": "The sensitivity list ...", "rejected": "Looks fine."}

fim —— 中间填充，代码模型学会在文件内部补全而不是在末尾续写靠的就是它。只有 middle 必须非空：prefix 和 suffix 是上下文，在文件边缘任一侧为空都合理。

{"prefix": "always @(posedge clk) begin\n", "middle": "  q <= d;\n", "suffix": "end\n"}

repo_context —— 前面摆着仓库其余部分的一次补全。files 是非空的 {path, content} 列表， 路径不许重复，外加一个非空的 target。RTL-Repo 和每个仓库级代码评测集用的都是这个形状，也是那个一旦压平成 prompt 字符串就会丢掉「哪个文件是哪个」的形状。

{"files": [{"path": "rtl/uart.v", "content": "module uart(...);"}, {"path": "rtl/pkg.vh", "content": "`define W 8"}], "target": "  assign tx = ...;"}

spec_rtl —— 一段自然语言规格，和实现它的模块。

{"spec": "An 8-bit synchronous FIFO with full and empty flags", "rtl": "module fifo(...);\n..."}

testbench —— 一个设计，和验证它的 bench。方向是要紧的，而且和 spec_rtl 不对称：这里模型写的是 bench，那是验证工程师的活。

{"dut": "module alu(...);\n...", "testbench": "module tb_alu;\n  initial begin ..."}

log_root_cause —— 一段工具或回归日志，和出了什么问题。它既是设计侧的形状，也是制造侧的。

{"log": "ERROR: [Synth 8-3352] multi-driven net ...", "root_cause": "The reset is driven from two always blocks"}

script —— 一个 EDA 脚本任务：Tcl、Makefile、约束文件。之所以和 prompt_completion 分开，是因为让它正确的是脚本跑得起来，而不是文本读着顺。

{"request": "Constrain the 100 MHz input clock", "script": "create_clock -period 10.000 [get_ports clk]"}

repo_context 里重复的路径是拒绝而不是容忍：框架留下哪一份，决定了模型看到什么，所以那两项会在同一个样本里对同一个文件各说各话。

检查器可以看什么

形状，仅此而已。哪些键在、它们装的是字符串而不是嵌套结构、成对的两半都在。关于内容、质量、语言和长度的一概不看 —— 那些属于质量报告，而一个开始评判内容的格式检查，就是对你自己的数据发表第二种意见。

一致性是比例，不是门禁

from tuneplane.data.formats import DataFormat, conformance, parse

report = conformance(rows, DataFormat.SPEC_RTL)
print(report.rows, report.conforming, report.ratio)
for row_number, problem in report.examples:
    print(row_number, problem)

conformance 接受任何可迭代的行，所以读多少由调用方决定。它报告看了多少行、多少行合规、比例，以及最多十条带行号的问题 —— 一份有一百万行坏数据的语料只有一个问题，不是一百万个。两处刻意的拒绝：

它从不变成判决。 见到任何一条就触发的门禁，是一周之内就会被人关掉的门禁，而真实语料里就是有一些没人想为之争论的坏行。平台欠你的是那个数字和头几个例子。
空文件没有比例。 零行时 ratio 是 None，而不是 1.0。什么都没检查，「完美」是错的说法。

对没有声明的格式，parse 返回 None —— 这是常态，不是错误 —— 对不认识的名字则抛错并附上已知名字的排序列表。

随机切分一份工程语料会泄漏

平台已有的每一项污染检查比的都是文本。tp dataset check 匹配归一化后的 13-gram；指纹比对取的是采样 n-gram 哈希的交集。两者都回答了各自被造出来要回答的问题，而都看不见那个会让工程团队的评测报废的失败。工程语料里满是同一个产物的近似变体：一个 UART 的八个修订、一个模块和实例化它的 wrapper、同一个 testbench 参数化出的四份。一个模块的两个修订之间确实几乎没有共同的 n-gram，而就「衡量模型学到了什么」而言，它们是同一道题。随机切分它们，评测集里装的就是训练集的兄弟。每一行都不同。重复率不会响。shingle 重叠读起来是干净的。于是留出分数量的是模型早已见过的东西的记忆，数字涨了，模型没变好。所以这项检查比的是身份而不是文本：group_key 点名的任何东西 —— 一个设计、一个仓库、一个工单号 —— 答案是评测组里有多大比例也出现在训练集中。

from tuneplane.data.contamination import group_leak

leak = group_leak(train_groups=["uart", "spi"], eval_groups=["uart", "pcie"])
leak.ratio     # 0.5 —— 留出的设计有一半被训过
leak.clean     # False
leak.examples  # ("uart",)

三个值得知道的性质：

它按不同的组计数，不按行。 一个设计出现在一千条评测行里是一次泄漏。数一千次，就等于让语料的行分布来决定它的泄漏看起来有多严重。
什么都没留出时 ratio 是 None，不是 0.0，和空的一致性报告没有比例是同一个理由。
它完全不需要文本。 两个集合求交集，所以在两边都还没被读之前，它就能在元数据上跑。

对一个留出集来说，零是唯一值得瞄准的值。高于零就意味着分数里有一部分是记忆。

声明分组键

spec.data.quality 是 JobSpec 里承载训练数据上限的那一块 —— 评测门禁的对偶：那些判出来的模型够不够好，这些判进去的数据够不够干净。其中两个字段关于血缘：

字段	含义
`group_key`	点名一行属于什么的元数据字段。留空就是行级，也就是此前的行为，对由独立样本组成的语料这是正确的默认
`max_group_leak_ratio`	切分两侧共同出现的组所占比例的上限，`0`–`1`

data:
  quality:
    max_duplicate_ratio: 0.1
    group_key: design
    max_group_leak_ratio: 0.0

契约会直接拒绝两种自相矛盾的 spec：

比例不在 0–1 之间。
有 max_group_leak_ratio 却没有 group_key —— 没有它，每一行都是自己一组，上限永远不可能被突破，那就是一条永远不会被判的线。同一条规则早就把 max_overlap_ratio 绑在了 overlap_with 上。

随附的四个方案都声明了切分字段：两个 RTL 的用 design，脚本助手用 repo，日志定责用 case —— 同一个故障被报了两次，是一件事实。tp solution show 把它打印成 split by；见工程方案。

哪些通了，哪些没通

把这件事说准，比这个功能本身更要紧。

部件	状态
九种形状及其校验器	在 SDK 里，`tuneplane.data.formats`，有测试
`group_leak`	在 SDK 里，`tuneplane.data.contamination`，有测试
`group_key`、`max_group_leak_ratio`	JobSpec 契约会解析并校验
方案的 `data_format`	加载清单时会对着九种校验
`max_duplicate_ratio`、`max_overlap_ratio`	提交时对着已存的质量报告与指纹强制执行
提交时的组泄漏检查	没有实现。没有任何代码去算这个比例，所以声明的上限拒绝不了任何东西
数据集版本上声明的格式	没有实现。 `tp dataset push` 没有格式参数，也没有数据集字段承载它
实验配置里的 `data.quality` 块	`tp submit` 不带它。 CLI 从数据集与路径参数构造 JobSpec 的 data 段，`quality` 保持默认值，所以这一块只能通过直接对 API 构造的 JobSpec 到达平台

所以今天，这九个名字是工程方案会声明的一套词汇，外加一个你可以在自己的行上跑的库函数 —— 在预处理脚本里，或者在推送前的 CI 里。group_key 同理：声明它记录了意图、并会拒掉自相矛盾的 spec；算泄漏是 group_leak 的活，调用它是你的活。这个说法比「平台会拦住一次泄漏的切分」小，而它是真的那一个。

下一步

数据集 · 工程方案 · RTL 评测

开始

核心概念

训练模型

评测与服务

Agent 环境

扩展平台

协作

集成

参考

帮助

数据形状与按设计血缘切分

九种形状

检查器可以看什么

一致性是比例，不是门禁

随机切分一份工程语料会泄漏

声明分组键

哪些通了，哪些没通

下一步

​九种形状

​检查器可以看什么

​一致性是比例，不是门禁

​随机切分一份工程语料会泄漏

​声明分组键

​哪些通了，哪些没通

​下一步

九种形状

检查器可以看什么

一致性是比例，不是门禁

随机切分一份工程语料会泄漏

声明分组键

哪些通了，哪些没通

下一步