Files
hm 2936b4a888 feat(corpus): W12 首批真实语料导入与 B1/B2/B5/B6 真实 KPI 基线
真实语料 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。
2026-11-19 23:06:19 +08:00
..

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)

  1. 来源登记:在 corpus/real_manifest.json 填写 id/path/source/source_path/ source_repos/license/license_basis/redistributable/sanitized。source 为空 → 禁止入库。
  2. 法务初筛:许可证必须明确允许内部测试;再分发另需许可。 不明确的先放 corpus/real/../pending/(不入库、不进 manifest), 完成复核后再移动;排除件登记在 real_provenance.md §5。参考:qcad__flange.dxf 即因许可待复核、license_review_required=true 而暂不建议对外分发。
  3. 脱敏:删除标题栏客户名/图号/个人信息(同长度占位符替换,登记 original_sha256); 按 4.1 规则重命名。
  4. 校验:python corpus/gen_manifest.py(逐项复核 size/sha256)+ python corpus/verify_manifest.py --strict。
  5. 入库: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)在真实语料上的实测对照。