真实语料 11 个 / 10,697,067 B(STEP 6、DXF 3、DWG 1、3MF 1),来源 ViewDesign-deepseek/corpus(与 kimi、Assembly 仓交叉校验),按 sha256 前 12 位命名;3 个文件做同长度 PII 脱敏(几何零改动),逐资产来源/哈希/许可判定见 corpus/real_manifest.json 与 real_provenance.md。 manifest 工具扩展:gen_manifest.py 扫描 corpus/real 并做登记表双向复核(未登记文件/哈希不符 exit 1),verify_manifest.py --strict 覆盖 tests/data + corpus/real;实测 gen --check 与 verify --strict 均 exit 0(63 合成 + 11 真实)。 driver 增加真实语料识别(real_corpus_present/real_step_files),修复 Get-StepFileCount 扩展名过滤 bug(首跑误记 11 STEP → 6 STEP)。 真实语料实测(run-20261119-225558):B1 import 6/6、clean 0/12=0%、perturbed 0/24=0%(381→372s);B2 3/19(与合成一致,无真实脏模型);B5 单线程 3 轮 bit-identical 通过、2/4/8 线程 digest 不一致且 8 线程拓扑不同(282v/434e),8 线程加速比 0.94x;B6 4/4 bounded_pass(4×30s≈180s)。KPI 表与门限建议见 docs/planning/benchmarks-kcp-wave1.md §7.1 与 docs/planning/wave2/corpus-notes.md。
corpus/ —— 语料规范与清单(KCP-1.0 Wave 1 / W4)
本目录是 VDE 内核追赶计划 KCP-1.0 Wave 1 W4「语料与基准」的语料资产登记与 规范入口。目标是让“引擎能力评测用了什么语料、来自哪里、许可如何、现状缺什么” 成为可机器校验、不可自欺的事实,而不是口头承诺。
诚实性声明(最重要)
- 真实语料首批已入库(W12,2026-11-19):
corpus/real/共 11 个资产 / 10,697,067 B(STEP 6、DXF 3、DWG 1、3MF 1),来源为项目内部仓库本地corpus/(gitignored);逐资产来源/许可/脱敏记录见real_manifest.json与real_provenance.md,manifest.json.real_corpus.status = "present"。corpus/realfile/仍不存在(不可再分发的更敏感原生文件尚未入库);manifest.json.missing显式登记,verify_manifest.py双向校验。tests/data/现有 63 个测试资产,其中 61 个是合成夹具, 仅 2 个是“真实参照”:OCCT 官方回归模型occ__xr1-tu-plt.stp与 QCad 示例图纸qcad__flange.dxf(后者的许可证仍需法务复核)。- 本目录不生成、不伪造任何“真实模型”;真实语料 KPI 实测结果见
docs/planning/benchmarks-kcp-wave1.md§7。合成夹具通过率不得表述为 真实模型通过率。
1. 文件说明
| 文件 | 作用 |
|---|---|
manifest.json |
权威清单:逐个登记仓库内语料资产的 path/format/category/size/sha256/source/license/synthetic;含 missing 段、real_corpus 段(真实语料现状/计数/逐资产条目)与真实语料规范 |
manifest.csv |
同一清单的表格视图(code review / 法务 review 用;含 redistributable 列) |
gen_manifest.py |
扫描 tests/data/ 与 corpus/real/(后者与 real_manifest.json 逐项复核)生成上述两份清单;分类规则集中在 classify(),新增合成资产需补规则 |
verify_manifest.py |
校验清单与磁盘一致(存在性/size/sha256)、missing 段反向校验、未登记文件检查(含 corpus/real/ 与登记表一致性) |
real_manifest.json |
真实语料来源/许可权威登记表:逐资产 source/source_path/source_repos/license/license_basis/redistributable/sanitized/original_sha256 |
real_provenance.md |
真实语料来源与许可判定说明、脱敏记录、排除清单(R01–R11 对照) |
real-corpus-layout.txt |
真实语料目录布局与命名规范 |
real_manifest.example.json |
真实语料清单条目 schema 示例(明确标记 example_only_not_a_real_asset) |
常用命令(在仓库根目录执行):
python corpus/gen_manifest.py # 重新生成清单(review diff 后提交)
python corpus/verify_manifest.py # 校验
python corpus/verify_manifest.py --strict --json
python corpus/gen_manifest.py --check # 只检查清单是否最新(CI 友好)
注:
.gitignore第 27 行忽略corpus/(语料目录默认不入库的数据策略)。 本目录内的规范、清单与 W12 首批真实语料(corpus/real/)是交付物,提交时使用git add -f corpus/README.md corpus/manifest.json corpus/real_manifest.json corpus/real ...强制加入版本管理。W12 首批真实语料判为redistributable=false(项目内部资产), 默认不随对外发行包分发;后续批次如含不可再分发文件,仍应放corpus/realfile/或外部对象存储,不入库。
注:
manifest.json.generated_from_git记录的是生成清单时的 HEAD(当前为计划 基线d2d50012);本清单与规范文件在随后的交付 commit 中入库,因此该 SHA 是 父提交而非包含它的提交,属预期。重新生成后如无资产变化,仅该字段会随 HEAD 变化。
2. 现有语料盘点(manifest 生成结果,2026-11-19)
tests/data/ 共 63 个文件 / 513,004 字节(约 501 KB):
| 类别 | 文件数 | 合成? | 来源/许可 |
|---|---|---|---|
STEP 合成夹具(fixtures/step/) |
3 | 是 | 自产(B-Rep 导出器) |
STEP 真实参照(fixtures/real/step/occ__xr1-tu-plt.stp) |
1 | 否 | OCCT 官方回归模型,LGPL-2.1 with OCCT exception |
| DXF 合成图纸(R12/R2000/R2010/R2018 变体) | 48 | 是 | 自产 |
DXF 真实参照(qcad__flange.dxf) |
1 | 否 | QCad 示例图纸,许可待法务复核 |
| DWG 合成图纸(AC1015/AC1032 等变体) | 4 | 是 | 自产 |
| 3MF 合成网格 | 3 | 是 | 自产 |
手工脏模型 w0_body87_open_5dangling.vde |
1 | 是(手工构造) | 开放体 + 5 悬挂边,heal/failure 语义测试 |
说明文本 native_corpus_*.txt |
2 | 是 | 元数据文本,非几何 |
分类计数以 manifest.json.by_category / by_format 为准,本表为摘要。
合成夹具不能替代真实语料:合成 STEP 只有 box/plate 类简单拓扑,无法覆盖
真实模型的自由曲面、长装配链、脏数据分布,因此 B1/B2 的真实语料 KPI 仍为未达标。
3. 真实语料现状(manifest.json.real_corpus / missing)
W12(2026-11-19)首批真实语料已入库,real_corpus.status = "present":
| 项 | 值 |
|---|---|
| 资产数 / 总字节 | 11 / 10,697,067 B(约 10.2 MiB,单文件最大 6.5 MiB,均在 20 MB 限内) |
| 格式分布 | STEP 6(含 1 个装配)、DXF 3、DWG 1、3MF 1 |
| 许可判定 | 全部项目内部资产(自研/内部导出),redistributable=false、license_review_required=false |
| 脱敏 | 3 个资产替换 Windows 用户名(同长度占位符),其余 PII 扫描无命中 |
| 来源登记 | corpus/real_manifest.json(R01–R11);判定依据/排除清单见 corpus/real_provenance.md |
missing 段仅剩 corpus/realfile/(不可再分发原生文件,仍未入库):
| 资产 | 状态 | 影响 |
|---|---|---|
corpus/real/ |
present(已入库 11 个资产) | B1 真实 STEP 语料、KC-Q06 corpus gate 真实语料部分可评测 |
corpus/realfile/ |
missing(已复核) | RealFile/CorpusProbe 类测试(审计中 79 skip 的语料缺失项)无法恢复 |
目录状态不会被悄悄改变:入库时须同步更新 real_manifest.json 与 manifest.json.real_corpus;
verify_manifest.py 会捕获“清单说缺失、实际已存在”或“磁盘有文件、清单未登记”的漂移。
4. 真实语料目录与获取/校验流程
4.0 已入库批次(W12 首批,2026-11-19)
| 类别 | 入库路径 | 数量 |
|---|---|---|
| 真实装配 | corpus/real/assembly/ |
1(CATIA V5 AP203 多体装配) |
| 真实零件 STEP | corpus/real/step/ |
5(SolidWorks AP203/AP214) |
| 真实图纸 | corpus/real/drawing/ |
4(DXF 3 + DWG 1) |
| 真实网格 | corpus/real/mesh/ |
1(3MF) |
与 §4.1 的有意偏离:本批资产判定为
redistributable=false,按 §4.1 本应放corpus/realfile/;W12 任务指示放corpus/real/以便 B1--fixtures-root直接指向。 本仓库为内部仓库且corpus/默认被.gitignore排除(不随发行包分发),该偏离 已记录在real_provenance.md§2;对外发布前必须迁移到 realfile 或重获再分发许可。
4.1 目录布局
corpus/real/{step,iges,mesh,drawing,assembly}/<vendor>__<part>__<sha256前12位>.<ext>
corpus/realfile/<vendor>__<file>__<sha256前12位>.<ext> # 不可再分发,本地/CI 缓存
详见 real-corpus-layout.txt。命名禁止包含真实客户名称/图号/个人信息。
4.2 获取流程(入库 checklist)
- 来源登记:在
corpus/real_manifest.json填写 id/path/source/source_path/ source_repos/license/license_basis/redistributable/sanitized。source为空 → 禁止入库。 - 法务初筛:许可证必须明确允许内部测试;再分发另需许可。
不明确的先放
corpus/real/../pending/(不入库、不进 manifest), 完成复核后再移动;排除件登记在real_provenance.md§5。参考:qcad__flange.dxf即因许可待复核、license_review_required=true而暂不建议对外分发。 - 脱敏:删除标题栏客户名/图号/个人信息(同长度占位符替换,登记
original_sha256); 按 4.1 规则重命名。 - 校验:
python corpus/gen_manifest.py(逐项复核 size/sha256)+python corpus/verify_manifest.py --strict。 - 入库:
manifest.json.real_corpus.status自动为"present",提交 PR, PR 描述必须粘贴来源与许可证依据。
4.3 校验流程
python corpus/gen_manifest.py # tests/data 部分重新生成(diff 仅预期变更)
python corpus/verify_manifest.py --strict
python tools/vde_corpus_gate.py --json # 语料门禁(真实语料缺失时按 --allow-empty 策略)
W1 nightly 的真实语料阶段接入方式见 docs/planning/benchmarks-nightly-integration.md:
设置 VDE_REAL_CORPUS_DIR / VDE_REALFILE_DIR 环境变量后跑 ctest -R "Corpus|RealCorpus|RealFile",
再用 tools/bench_kcp/run_kcp_bench.ps1 -CorpusRoot $env:VDE_REAL_CORPUS_DIR 跑 B1 真实语料集。
在目录仍是 missing 时,nightly 必须报告 skip(而非伪造通过)。
5. 基准如何使用语料
| 基准 | 语料来源 | 当前状态 |
|---|---|---|
| B1 STEP 布尔通过率 | `tests/data/fixtures/**/*.step | stp(合成 3 + OCCT 1);真实语料:corpus/real/**/*.step |
| B2 healing 恢复曲线 | 合成脏模型(逐面撕开 + gap 严重度)+ w0_body87_open_5dangling.vde |
真实脏模型 0(真实 STEP 能否作为 B2 脏源由 bench 决定) |
| B5 bit-identical/加速比 | 纯合成工作负载(box/cylinder/sphere 布尔),不依赖外部语料 | 可复现 |
| B6 fuzz 长跑 | 无外部语料(gtest fuzz targets) | 可复现 |
B1/B2 harness 见 tests/benchmark/bench_kcp.cpp,用法:
build\tests\benchmark\bench_kcp.exe --suite b1 --fixtures-root tests/data/fixtures --json-out out.json
build\tests\benchmark\bench_kcp.exe --suite b2 --test-data-root tests/data --json-out out2.json
6. Licensing 与来源
| 资产 | 许可证 | 义务/备注 |
|---|---|---|
| 合成夹具(STEP/DXF/DWG/3MF/VDE) | 自产,随仓库许可 | 无第三方再分发限制 |
真实语料 R01–R11(corpus/real/) |
项目内部资产(自研/内部导出;宿主仓库 AGPL-3.0/商业双许可) | redistributable=false;仅内部测试/基准;逐资产依据见 real_manifest.json 与 real_provenance.md |
occ__xr1-tu-plt.stp |
OCCT LGPL-2.1 with OCCT exception | 再分发保留版权与许可声明;来源登记 docs/reference/220、docs/reference/267 |
qcad__flange.dxf |
待复核(QCad CE 为 GPLv2) | license_review_required=true;复核前不对外分发 |
| 未来真实语料 | 逐资产登记 | 不明确 → 禁止入库;不可再分发者只进 corpus/realfile/ |
红线:不得把无许可证第三方模型放进本仓库;不得把合成夹具标注为真实语料; 不得在基准报告/审计文档中把“合成通过率”表述为“真实模型通过率”。
7. 覆盖的 KC(计划 §3 / §5)与当前缺口
W4 覆盖:KC-A19/A20(语料规范/真实语料获取与校验)、KC-B12(STEP 布尔 通过率基准)、KC-C10(healing 恢复曲线)、KC-I12(bit-identical/多线程 加速比)、KC-K06(fuzz 长跑)、KC-Q06(corpus gate/语料回归基线)。
已完成:规范+清单+可校验工具链、B1/B2/B5 harness、B6 driver、nightly 脚本、
真实语料首批入库(11 个/10.7 MB,来源/许可/脱敏可审计)。
未完成(时间盒内如实记录):corpus/realfile/ 语料(不可再分发原生文件)、
真实脏模型 B2 曲线扩展(当前 B2 脏源仍为合成 detach)、healing 目标值
(40/52→50/52)在真实语料上的实测对照。