45-EFT.WP.Data.Pipeline v1.0 | 第7章 转换与预处理

目录 ／ 文档-技术白皮书 ／ 45-EFT.WP.Data.Pipeline v1.0

第7章 转换与预处理

I. 章节目的与范围

II. 术语与依赖

• 术语：transform.*、preprocess.*、idempotent、resample、window/stride、stats_from:"train-only"、feature_space。
• 依赖：契约与导出（《Core.DataSpec v1.0》）；单位与量纲校核（《Core.Metrology v1.0》）；训练数据与切分（《DatasetCards v1.0》）；特征与 I/O 假设（《ModelCards v1.0》第6、9章）。
• 数学与符号：内联符号一律用反引号（如 x、z、μ、σ、f_samp、T_arr）；含除号/积分/复合算符必须加括号并（如涉路径量）声明 gamma(ell) 与 d ell；公式/符号/定义禁用中文。

III. 字段与结构（规范性）

stage:

name: "<normalize|standardize|resample|impute|encode|tokenize|stft|specaugment|feature_map|aggregate|pca|custom>"

type: "transform.<op>|preprocess.<op>"

impl: "I16-3.<impl_id>"

inputs: ["<Σ_in>"]

outputs: ["<Σ_out>"]

params:

method: "<zscore|minmax|robust|unit-norm|...>"

stats_from: "train-only|all" # 统计量来源

window: "<samples|ms>?"

stride: "<samples|ms>?"

f_samp: "<Hz>?" # 重采样目标频率

anti_alias: {enabled:true, cutoff:"<Hz>", order:5}?

encode: {vocab_ref:"<path>", unk:"<token>", pad:"<token>"}?

impute: {strategy:"mean|median|knn|model", value: null}?

pca: {n_components:"<int|ratio>", whiten:false}?

idempotent: true

retries: {max: 2, backoff: "expo"}

timeout_s: 1800

on_fail: "quarantine|skip|block"

schema_ref: "<contracts/after_transform@vX.Y>" # 与输出契约绑定

feature_space:

type: "<dense|sparse|sequence|image|audio_spec|tabular|embedding>"

shape: "<(…)>"

dtype: "<float32|int32|...>"

normalization: "<zscore|minmax|robust|unit-norm|none>"

IV. 常见算子与口径

1. 标准化/归一化（normalize|standardize）
   • zscore：( x - μ ) / σ；μ/σ 仅由训练集计算（stats_from:"train-only"）并固化到锁定文件。
   • minmax/robust/unit-norm：显式区间与范数；对异常值采用截断或稳健统计并记录策略。
2. 缺失值处理（impute）
   均值/中位数/KNN/模型推断；需记录对不确定度的影响并在相关章合成。
3. 时间/频率处理与重采样（resample|stft|specaugment）
   声明 f_samp、抗混叠滤波（anti_alias）、插值方法；STFT 的 window/stride 与窗型（如 hann）必须给出。
4. 编码/分词（encode|tokenize）
   vocab_ref、unk/pad、最大长度、截断/滑窗规则；分词/子词版本与哈希入库。
5. 特征构建与降维（feature_map|aggregate|pca）
   特征函数/核与超参；PCA 需保存载荷矩阵与解释方差比；聚合对齐时间窗并声明缺失策略。
6. 自定义算子（custom）
   提供容器/脚本引用与参数哈希；输入/输出契约显式化，失败回滚策略必须声明。

V. 幂等、可重放与异常处置

• 幂等：相同输入与参数哈希应产生字节级一致的输出；对非确定性算子需固定 seed 并记录库版本。
• 可重放：产出参数锁定与执行日志（config.lock.yaml、logs/*.jsonl）；需要时支持旁路回放。
• 处置：on_fail:"quarantine|skip|block"；隔离样本导出并记录不合格规则/阈值与输入片段哈希。

VI. 与特征空间/任务 I-O 的对齐

• feature_space 的 type/shape/dtype/normalization 必须与模型卡第6/9章一致；
• 多模态/多任务时为各模式提供独立 feature_space 子树，并在下游导出分路工件。

VII. 计量与单位（SI）

1. 重采样频率 f_samp（Hz）、窗口/步长（ms 或样本）、时延 T_inf（ms）、吞吐 QPS（1/s）等一律使用 SI，配 metrology:{units:"SI", check_dim:true}。
2. 若转换涉及路径量（如 T_arr），需登记：delta_form、path="gamma(ell)"、measure="d ell"，并采用等价式之一：
   • T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • T_arr = ( ∫ ( n_eff / c_ref ) d ell )；并通过 check_dim 校核。

VIII. 机器可读片段（可直接嵌入）

layers:

- name: "transform"

stages:

- name: "standardize.rgb"

type: "transform.normalize"

impl: "I16-3.standardize"

inputs: ["raw_image"]

outputs: ["img_std"]

params: {method:"zscore", stats_from:"train-only"}

idempotent: true

schema_ref: "contracts/img_std@v1.0"

feature_space: {type:"image", shape:"(H,W,3)", dtype:"float32", normalization:"zscore"}

- name: "resample.audio"

type: "transform.resample"

impl: "I16-3.resample"

inputs: ["waveform_48k"]

outputs: ["waveform_16k"]

params:

f_samp: 16000

anti_alias: {enabled:true, cutoff: 7600, order: 5}

idempotent: true

schema_ref: "contracts/waveform_16k@v1.0"

- name: "stft.spec"

type: "transform.stft"

impl: "I16-3.stft"

inputs: ["waveform_16k"]

outputs: ["spec"]

params: {window:512, stride:160, window_fn:"hann"}

feature_space: {type:"audio_spec", shape:"(F,T)", dtype:"float32", normalization:"zscore"}

idempotent: true

IX. Lint 规则（节选，规范性）

lint_rules:

- id: TF.IDEMPOTENT_REQUIRED

when: "$.layers[*].stages[?(@.type^='transform.')]"

assert: "idempotent == true"

level: error

- id: TF.STATS_FROM_TRAIN_ONLY

when: "$.layers[*].stages[?(@.params.stats_from)]"

assert: "value == 'train-only'"

level: error

- id: TF.FS_DECLARED

when: "$.layers[*].stages[*].feature_space"

assert: "has_keys(type,shape,dtype,normalization)"

level: error

- id: TF.RESAMPLE_SI

when: "$.layers[*].stages[?(@.type=='transform.resample')]"

assert: "is_number($.params.f_samp) and $.params.f_samp > 0"

level: error

- id: TF.UNITS_CHECKDIM

when: "$.pipeline.metrology"

assert: "units == 'SI' and check_dim == true"

level: error

- id: TF.PATH_TARR_FIELDS

when: "$.layers[*].stages[*].params[?(@.delta_form)]"

assert: "has_keys(delta_form) and has_keys(path) and has_keys(measure)"

level: error

X. 导出清单与审计

export_manifest:

version: "v1.0"

artifacts:

- {path:"transform/config.lock.yaml", sha256:"..."}

- {path:"transform/logs/step-*.jsonl", sha256:"..."}

- {path:"features/spec.yaml", sha256:"..."}

references:

- "EFT.WP.Core.DataSpec v1.0:EXPORT"

- "EFT.WP.Core.Metrology v1.0:check_dim"

- "EFT.WP.Data.ModelCards v1.0:Ch.9"

XI. 本章合规自检

• 算子 type/impl/params 完整；idempotent=true，重试/超时与失败处置明确；日志与锁定文件齐备。
• feature_space 与模型卡一致；统计量来源为训练集；编码/字典/降维载荷等工件已入库并哈希。
• 重采样/时间频率处理明确 f_samp/window/stride/anti_alias；单位为 SI 且 check_dim=true。
• 涉及 T_arr 等路径量时，delta_form/path/measure 登记完备并通过校核。
• export_manifest 列出变换相关工件与引用锚点，满足发布门槛。