45-EFT.WP.Data.Pipeline v1.0 | 第8章 特征流水线与重用

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

第8章 特征流水线与重用

I. 章节目的与范围

II. 术语与依赖

• 术语：feature_space、dict_ref、embedding_store、materialize、cache、ttl、point-in-time（PIT 对齐）、surrogate_key。
• 依赖：契约与导出（《Core.DataSpec v1.0》）；单位/量纲校核（《Core.Metrology v1.0》）；训练数据与切分（《DatasetCards v1.0》）；特征与 I/O 假设（《ModelCards v1.0》第6、9章）。
• 数学与符号：内联符号用反引号（如 x_t、μ、σ、Δt、T_arr）；含除号/积分/复合算符必须加括号并（如涉路径量）声明 gamma(ell) 与 d ell；公式/符号/定义禁用中文。

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

stage:

name: "<feat.map|feat.aggregate|feat.join|feat.encode|feat.embed|feat.materialize>"

type: "feature.<op>"

impl: "I16-4.<impl_id>"

inputs: ["<Σ_in>"]

outputs: ["<Σ_out>"]

params:

key: ["<entity_id>", "<ts?>"] # 实体键/时间键

point_in_time:

enabled: true

lookback: "PT7D|P30D|N/A" # 回看窗口

tolerance: "PT5M" # 对齐容差

dict_ref: "dicts/<name>@vX.Y" # 字典/子词/类别映射

embed:

store: "faiss|annoy|milvus|custom"

dim: 768

metric: "cosine|l2"

index_ref: "embeddings/<name>@vX.Y"

aggregate:

window: "PT1H|P1D"

funcs: ["mean","max","count","std"]

fillna: {"method":"pad|zero|drop"}

join:

on: ["<entity_id>","<ts?>"]

how: "left|inner|asof"

materialize:

mode: "none|cache|persist"

cache: {ttl: "P7D", max_gb: 128}

idempotent: true

schema_ref: "contracts/feat_<name>@vX.Y"

feature_space:

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

shape: "<(…)>"

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

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

IV. 特征算子与口径

• 映射/构造（feat.map）：声明特征函数/核与超参；产出 feature_space 与单位/量纲。
• 聚合（feat.aggregate）：滑动/翻转窗口、边界包含性、缺失策略（fillna）；多窗口需列出各窗口参数。
• 连接（feat.join|feat.asof）：键与时间对齐策略；asof 需提供 tolerance 与方向（backward|forward）。
• 编码（feat.encode）：dict_ref 版本哈希、unk/pad 策略、OOV 处理与稀疏/稠密表示。
• 嵌入（feat.embed）：向量维度/度量、索引构建参数与 index_ref；推理路径的延迟与吞吐纳入计量。
• 物化（feat.materialize）：mode:"cache|persist" 时需声明存储位置、ttl、淘汰与一致性（全量/增量/旁路更新）。

V. 重用与依赖映射

• 跨任务重用：以 feature_view 抽象复用集合，记录 consumers[] 与版本约束；compat_mode:"forward|backward|both|break"。
• 多模态重用：为各模态维护独立 feature_view 与 feature_space，在导出物中分别登记工件。
• 变更影响：破坏性变更需影子对比与双写窗口，结果超阈触发回滚或向后兼容层。

VI. 一致性与时态对齐（PIT）

• PIT：历史回放与在线推理使用相同对齐规则；lookback/tolerance 一致并落入锁定文件。
• 切分一致：涉训练/评测输出的特征，splits 与数据卡冻结切分一致；泄漏审计（对象/时间窗）为阻断项。

VII. 字典与嵌入管理

• 字典：dict_ref 必带版本与哈希；新增类目接纳策略 unknown|reject|map-to-other；频繁变更的字典需提供稳定别名键。
• 嵌入：index_ref 版本化并记录训练数据时间范围；向量单位/量纲（若有）在 feature_space 声明并 check_dim。

VIII. 计量与单位（SI）

1. 性能：QPS（1/s）、T_inf（ms {p50,p95,p99}）、ρ（—）；带宽 net_mbps；存储/索引体量 size_bytes。
2. metrology:{units:"SI", check_dim:true} 为强制；合成/聚合前先做单位归一。
3. 涉路径量（如 T_arr）的特征需登记：delta_form、path="gamma(ell)"、measure="d ell"，并采用以下等价式之一并通过 check_dim：
   • T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • T_arr = ( ∫ ( n_eff / c_ref ) d ell )。

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

layers:

- name: "feature"

stages:

- name: "feat.map.stats"

type: "feature.map"

impl: "I16-4.feature_map"

inputs: ["std_rows"]

outputs: ["feat_rows"]

params:

key: ["entity_id","ts"]

point_in_time: {enabled:true, lookback:"P30D", tolerance:"PT5M"}

aggregate: {window:"P1D", funcs:["mean","std","count"], fillna:{method:"pad"}}

idempotent: true

schema_ref: "contracts/feat_stats@v1.1"

feature_space: {type:"tabular", shape:"(N,D)", dtype:"float32", normalization:"zscore"}

- name: "feat.encode.cat"

type: "feature.encode"

impl: "I16-4.encode"

inputs: ["feat_rows"]

outputs: ["feat_enc"]

params:

dict_ref: "dicts/category_voc@v2.0"

encode: {vocab_ref:"dicts/category_voc@v2.0", unk:"<UNK>", pad:"<PAD>"}

idempotent: true

schema_ref: "contracts/feat_enc@v1.0"

- name: "feat.materialize"

type: "feature.materialize"

impl: "I16-4.materialize"

inputs: ["feat_enc"]

outputs: ["feat_pkg"]

params:

materialize: {mode:"cache", cache:{ttl:"P7D", max_gb:256}}

idempotent: true

schema_ref: "contracts/feat_pkg@v1.0"

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

lint_rules:

- id: FEAT.FS_REQUIRED

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

assert: "has_key('feature_space')"

level: error

- id: FEAT.DICT_VERSIONED

when: "$.layers[*].stages[?(@.type=='feature.encode')].params.dict_ref"

assert: "matches('^dicts/[a-z0-9_\\-]+@v\\d+\\.\\d+$')"

level: error

- id: FEAT.PIT_PARAMS

when: "$.layers[*].stages[*].params.point_in_time"

assert: "value.enabled == true -> (has_key('lookback') and has_key('tolerance'))"

level: error

- id: FEAT.MATERIALIZE_POLICY

when: "$.layers[*].stages[?(@.type=='feature.materialize')].params.materialize"

assert: "value.mode in ['none','cache','persist']"

level: error

- id: FEAT.UNITS_CHECKDIM

when: "$.pipeline.metrology"

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

level: error

- id: FEAT.LEAKAGE_GUARDS_FOR_TRAIN_EXPORT

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

assert: "produces_train_eval(outputs) -> has_leakage_guards()"

level: error

XI. 导出清单与审计

export_manifest:

version: "v1.0"

artifacts:

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

- {path:"features/dict_category_v2.hash", sha256:"..."}

- {path:"features/feat_pkg.manifest.json", sha256:"..."}

references:

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

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

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

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

XII. 本章合规自检

• 特征算子 type/impl/params 完整，feature_space 已声明并与模型卡一致；PIT 对齐参数可复现。
• dict_ref/index_ref 版本化并具哈希；OOV/新增类目接纳策略明确；物化缓存含 ttl 与容量上限。
• 涉训练/评测产物的 splits 与数据卡冻结切分一致，泄漏护栏生效。
• 性能与单位采用 SI 且 check_dim=true；如涉路径量 T_arr，delta_form/path/measure 登记并校核通过。
• export_manifest 列出特征视图/字典/物化包等工件及引用锚点并具 sha256，满足发布门槛。