Pyrefly 张量形状移植原则如何为 PyTorch 模型标注 Tensor Shape 类型【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly导读本文解读 pyrefly 仓库中面向 PyTorch 模型移植的张量形状类型系统Tensor[[B, C, H, W]]、Int[T]的核心移植原则——即 porting_principles.md 所定义的优先级顺序、忠实性约束与 Stub 哲学。你将学会在把模型改写为形状感知代码时如何保证运行行为不变、如何用assert_type证明形状被真正推断、以及何时应该修改形状感知 stub 而非绕过问题。读完本文你将掌握一套可复用的移植决策框架并理解底层三大形状追踪机制形状感知 stub、类型级形状函数、特殊处理器的工作原理。1. 为什么需要一套移植原则pyrefly 为 PyTorch 提供了形状感知的类型系统张量可以标注为Tensor[[B, C, H, W]]维度可以是字面量、类型变量或代数表达式如D // NHead、2 * H - 1。把现有模型改写成这种风格不是简单的机械替换——它要求移植者在一系列相互冲突的目标忠实于原模型、最大化形状覆盖、识别形状丢失的根因之间做权衡。porting_principles.md 正是这个权衡过程的决策宪法。它与技能套件的其他文档配合使用SKILL.md门控式gate-based的逐步移植方法论定义 Gate 0–2 与模块循环的 6 个步骤shape_tracking_capabilities.md形状追踪的三种底层机制与 API 面style_guide.md从已移植的开源模型语料中提炼的注解风格模式verify_port.sh移植质量启发式检查脚本。本文以移植原则文档为骨架结合其余文档与 pyrefly-torch-stubs 语料库 中的真实示例展开。2. 优先级顺序Faithfulness Shape coverage Identify blockers移植原则给出了明确的三级优先级这是所有后续决策的出发点2.1 第一优先忠实性FaithfulnessRestructuring must preserve runtime behavior: never drop constructor parameters, never remove conditional branches, never add or remove layers.重构必须保持运行时行为不变绝不删除构造函数参数、绝不移除条件分支、绝不增删层。功能等价的重构是允许的例如把列表中的模块提取为独立属性extracting modules from a list into individual attributes把nn.Sequential子类转换为组合composition形式。这条约束的深层原因是形状追踪是添加在运行行为之上的类型层类型层必须可随时剥离而不改变模型语义。从源码看shape_extensions包的设计正是如此——它导入后会给torch.Tensor、nn.Conv2d等打补丁以支持下标语法Tensor[[B, C, H, W]]提供IntVar的算术支持但这都是运行时兼容层不改变张量运算本身。Restructure 的粒度在 SKILL.md 的 Step 4 中被明确定义通常只是 2–3 行的改动——分离一次迭代、移除一次int()强转、增加一个Int类型参数。如果发现自己正在重写算法就已经越界了。2.2 第二优先形状覆盖Shape coveragetype with shapes as much as possible. Useassert_typeto verify inference, not just annotation fallback. Shapeless parts get bareTensorwith comments explaining why.在忠实性的前提下尽可能多地用形状注解。关键要求是用assert_type验证推断结果而不是依赖注解回退annotation fallback无法追踪形状的部分使用裸Tensor并必须用注释说明原因。2.3 第三优先识别阻塞点Identify blockersevery place where shapes are lost should trace back to a specific gap or genuinely># 错误示范没有 assert_type0 errors 说明不了任何事 h F.relu(self.fc1(x)) # 正确示范assert_type 证明推断出了具体形状 h F.relu(self.fc1(x)) assert_type(h, Tensor[[B, 512]]) # pyrefly 验证类型运行时零开销这也解释了为什么 SKILL.md 要求每个 forward 方法中的每个局部变量都要有一个assert_type无例外——即使在使用类型化接口typed interface的模块内部也一样类型化接口只说明边界是类型化的内部仍然需要assert_type检查点。3.1 注解层级Annotation hierarchy当检查器无法推断形状时按以下优先级决策来自 SKILL.md Step 5优先级手段适用场景1assert_type验证检查器的推断证明系统真正工作2注解回退x: Tensor[[B, C, H, W]] unrefined_op(...)操作返回 unrefined 但你知道形状需注释 WHY3type: ignore检查器算出了错误类型代数缺口 A1 或条件等式最后手段必须注释具体缺口4裸Tensor形状真正不可知数据依赖的 token 数、条件累积必须注释具体原因4. Stub 哲学修 Stub 还是绕过去移植原则文档的第二节是 Stub 哲学——是否修改 stub 由用户决定这必须在移植前Gate 0 之前确认用户不打算改 stub或不置可否不要动 stub。在现有 stub 允许的范围内尽量移植把无法追踪的操作记录为缺口gap在完成报告中建议为值得修复的缺口提交 upstream issue。这条路径完全被支持——一个不太完整的移植是预期结果不是失败。用户同意改 stub获得一次性许可可在移植过程中顺手改进 stub 签名无需每个算子都重新询问。但仍要先移植并用reveal_type确认缺口再动 stub。核心判断stub 缺口往往是值得修复的根因而非值得绕过的表象——一个改进后的签名能为每一个使用该算子的模型恢复形状而不仅是当前这一个。这就是为什么在范围内时贡献 stub 修复是更高杠杆的选择。修复 stub 时必须遵循通用性原则When you do change a stub or shape DSL function, make the fix general — capture the truth about the op, dont special-case it for your model.即修改要捕获算子本身的真实形状规律而不是为你的模型特判。4.1 stub 修改的具体形态从 shape_tracking_capabilities.md 和 torch-stubs 源码 看stub 的返回类型有四种追踪形态Self返回保形操作.float()、.contiguous()、.detach()Tensor[S] → Tensor[S]S: IntTuple整体保形F.relu、nn.LayerNorm对任意 batch 前缀后的尾部维度用Tensor[[*Elements[Bs], D]]泛型参数捕获构造参数并在forward中计算输出形状nn.Linear[In, Out]、nn.Conv2d[InC, OutC, K, S, P, D]Int[N]捕获把运行时 int 参数绑定到类型级维度。例如真实 stub 中nn.Linear的定义nn/init.pyiclass LinearIN: IntVar, OUT: IntVar: weight: Tensor[[OUT, IN]] bias: Tensor[[OUT]] | None def __init__( self, in_features: _Int[IN], out_features: _Int[OUT], bias: bool True, ...当调用nn.Linear(400, 10)时检查器绑定IN 400、OUT 10于是forward输出为Tensor[[..., 10]]。4.2 需要形状函数的操作当输出形状依赖参数计算而非简单泛型时stub 的返回注解会调用类型级形状函数例如 nn/init.pyi 中的adaptive_pool2d_shape、pixel_shuffle_shape、pool_shape等这些函数定义在 torch-stubs/_shapes.pyi 中用type_shape_dsl_function装饰从 stub 中以torch._shapes导入因为torch-stubs包为类型检查提供了torch包。Gate 1 的算子审计表就要求逐一确认stub 返回注解是否调用形状函数以及该函数是否真的存在于_shapes.pyi。5. 在忠实性约束下最大化形状覆盖真实案例优先级框架在实际移植中的运用可以从 finalmlp.pyFinalMLP 双流 MLP 模型中看到完整演绎。这个示例同时演示了忠实性不删除任何原参数、不改变结构与形状覆盖尽可能追踪如何共存。5.1 桥接维度Bridge dims忠实保留动态内部类型化边界MLP类内部用nn.Sequential(*block)动态构建层因为隐藏层数量来自list[int]这必然擦除模块类型。移植原则允许这种重构受限的情况存在——关键是把连接未追踪段与已追踪下游的桥接维度提升为类级类型参数class MLPInD: IntVar, OutD: IntVar: output_dim: Int[OutD] def __init__( self, input_dim: Int[InD], hidden_units: list[int], output_dim: Int[OutD], activation: str ReLU, dropout: float 0.0, batch_norm: bool False, ) - None: super().__init__() # ... nn.Sequential(*block) 动态构建内部形状是 bare self.layers nn.ModuleList(layer_blocks) self.output_dim output_dim def forwardB: IntVar - Tensor[[B, OutD]]: for layer in self.layers: x layer(x) # typed interface: Sequential(*list) ModuleList[nn.Module] 循环擦除形状 result: Tensor[[B, OutD]] x # type: ignore[pyrefly:bad-assignment] assert_type(result, Tensor[[B, OutD]]) return result注意这里__init__的每个参数都被保留忠实性forward 通过类型化接口返回Tensor[[B, OutD]]——下游的nn.Linear接受Tensor[[*Elements[Bs], OutD]]Bs: IntTuple绑定Bs (B,)后 batch 维继续传播。没有这个桥接维度注解回退只能恢复裸Tensor或仅 batch 的形状。5.2 注解回退与assert_type的配合同一个文件里InteractionAggregation.forward展示了注解回退 类型化元素列表的配合bilinear_terms: list[Tensor[[B]]] [] for i in range(self.num_heads): x_h x[:, i * head_x_dim : (i 1) * head_x_dim] interaction (x_h self.bilinear_W[i] * y_h).sum(dim-1) assert_type(interaction, Tensor[[B]]) bilinear_terms.append(interaction) # annotation fallback: stack from dynamic loop cant infer collection size bilinear_out: Tensor[[B, NH]] torch.stack(bilinear_terms, dim-1) assert_type(bilinear_out, Tensor[[B, NH]])动态循环的torch.stack无法从集合长度推断新维度DSL 无法统计动态循环的迭代次数于是用注解回退标注Tensor[[B, NH]]并用注释说明原因——这正是移植原则Shapeless parts get bareTensorwith comments explaining why的精确延伸即使无法完整追踪也要用断言固定每一个局部变量的类型。5.3 首次迭代分离避免分支汇合展宽FinalMLPBackbone.forward演示了分支汇合展宽branch join widening的解法——第一层把[B, F, D]变换为[B, K, D]后续层保持[B, K, D]。如果写成一个循环x会被展宽成联合类型。移植原则要求在这种情况下分离第一次迭代x self.first_layer(input_embs) assert_type(x, Tensor[[B, K, D]]) for layer in self.rest_layers: x layer(x) assert_type(x, Tensor[[B, K, D]])对照 SKILL.md Step 4 的重构清单这类 2–3 行改动正是Restructure的典型粒度。6. 何时可以停下来真正数据依赖的形状移植原则强调每一个形状丢失点都必须能追溯到具体缺口或真正数据依赖的形状。而 shape_tracking_capabilities.md 明确指出真正无法追踪的模式极少数据依赖的结果数量torch.nonzero、t[bool_mask]输出长度取决于掩码内容而非形状数据依赖的累积条件torch.cat中元素数量取决于运行时控制流A1 代数缺口N * (X // N) X对向下取整除法不成立注意反向(a * b) // b → a是可简化且健全的。其余一切理论上都应可追踪。如果结果回退到Tensor[IntTuple]应首先检查三大机制——stub、形状函数、特殊处理器位于 pyrefly/lib/alt/如nn_module_specials.rs中的nn.Sequential链式追踪。当形状丢失时追溯上游而非就地放弃trace upstream而非就地放弃输入本身就是裸Tensor吗没有算子能从裸Tensor恢复形状——找到形状真正丢失的位置才是修复点该用Int却用了int函数参数类型改为Int[X]该用tuple却用了listtorch.cat([a, b])会均质化元素类型改用torch.cat((a, b))分支汇合展宽在各分支独立计算输出或用 Optional 收窄内联表达式丢形状f(g(x))拆成y g(x); f(y)stub 返回裸类型检查返回注解是否计算形状否则修复.pyi签名或添加形状函数。7. 用 verify_port.sh 与检查器验证移植移植原则的验证手段在 verify_port.sh 和 SKILL.md 的 Verification 阶段中体现# 1. 启发式质量门不进行类型检查只做静态统计 tensor-shapes/skills/add-shape-types-to-torch-model/verify_port.sh path/to/your/port.py # 2. 真正的 Pyrefly 检查形状追踪在 stub 与 shape_extensions 位于搜索路径时自动开启 pyrefly check --config /dev/null --python-version 3.13 \ --search-path root containing torch-stubs \ --search-path root containing shape_extensions \ path/to/your/port.py两个搜索根是独立的tensor-shapes/pyrefly-torch-stubs提供torch-stubs包和tensor-shapes/pyrefly-shape-extensions提供shape_extensions包。没有--tensor-shapes之类的开关——形状追踪在形状感知 stub 和shape_extensions出现在搜索路径上时就自动启用。PEP 695/696 泛型语法需要--python-version 3.12或更高语料库运行在3.13。pyrefly dump-config可以报告解析后的搜索路径。verify_port.sh 的检查项直接对应移植原则的关切type: ignore[的数量——每一条都要审计是 A1 代数缺口还是可修的 stub 问题签名与局部变量中的裸Tensor——问形状是否真正不可知assert_type的 shaped/bare 比例——bare 比例就是移植质量指标是否存在def test_冒烟测试——且测试必须用assert_type验证类型化输出而不是assert out.shape (...)运行时形状断言不验证 pyrefly只证明模型能跑是否出现 excl/excluded/not ported 等排除标记——Gate 2 清单要求原文件的每个类、函数、方法都必须出现在移植中。完成报告Completion report模板把移植原则的三条优先级落成可填写的字段Gate 1 审计的算子数、Gate 2 清单勾选情况、type: ignore分类计数、assert_type的 shaped/bare 数量与比例、每个裸断言是否有注释 Step 4 收据追溯以及最后面向用户的缺口与改进建议块。8. 总结三条原则如何构成决策闭环移植原则文档的三条优先级构成一个自洽的决策闭环忠实性划定重构的边界——一切形状追踪都必须在保持运行行为不变的前提下进行形状覆盖规定目标与验收标准——assert_type是唯一凭证注解回退不能冒充推断裸Tensor必须附带原因注释识别阻塞点把剩余的缺口转化为路线图——每个裸形状要么追溯到具体 stub/DSL/代数缺口要么归于真正数据依赖的形状并以此决定下一步该修复哪个 stub、为哪个算子编写形状函数。而 Stub 哲学则回答了闭环中谁来修、修到多通用的问题是否修改 stub 由用户预先决定一旦决定修复就要捕获算子的真实规律而非针对单个模型特判。三者结合构成了 pyrefly 张量形状移植从决策、实施到验证的完整方法论——这也是 SKILL.md 中门控式流程Gate 0–2、模块循环、验证阶段得以成立的思想基础。【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pyrefly 张量形状移植原则：如何为 PyTorch 模型标注 Tensor Shape 类型
Pyrefly 张量形状移植原则如何为 PyTorch 模型标注 Tensor Shape 类型【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly导读本文解读 pyrefly 仓库中面向 PyTorch 模型移植的张量形状类型系统Tensor[[B, C, H, W]]、Int[T]的核心移植原则——即 porting_principles.md 所定义的优先级顺序、忠实性约束与 Stub 哲学。你将学会在把模型改写为形状感知代码时如何保证运行行为不变、如何用assert_type证明形状被真正推断、以及何时应该修改形状感知 stub 而非绕过问题。读完本文你将掌握一套可复用的移植决策框架并理解底层三大形状追踪机制形状感知 stub、类型级形状函数、特殊处理器的工作原理。1. 为什么需要一套移植原则pyrefly 为 PyTorch 提供了形状感知的类型系统张量可以标注为Tensor[[B, C, H, W]]维度可以是字面量、类型变量或代数表达式如D // NHead、2 * H - 1。把现有模型改写成这种风格不是简单的机械替换——它要求移植者在一系列相互冲突的目标忠实于原模型、最大化形状覆盖、识别形状丢失的根因之间做权衡。porting_principles.md 正是这个权衡过程的决策宪法。它与技能套件的其他文档配合使用SKILL.md门控式gate-based的逐步移植方法论定义 Gate 0–2 与模块循环的 6 个步骤shape_tracking_capabilities.md形状追踪的三种底层机制与 API 面style_guide.md从已移植的开源模型语料中提炼的注解风格模式verify_port.sh移植质量启发式检查脚本。本文以移植原则文档为骨架结合其余文档与 pyrefly-torch-stubs 语料库 中的真实示例展开。2. 优先级顺序Faithfulness Shape coverage Identify blockers移植原则给出了明确的三级优先级这是所有后续决策的出发点2.1 第一优先忠实性FaithfulnessRestructuring must preserve runtime behavior: never drop constructor parameters, never remove conditional branches, never add or remove layers.重构必须保持运行时行为不变绝不删除构造函数参数、绝不移除条件分支、绝不增删层。功能等价的重构是允许的例如把列表中的模块提取为独立属性extracting modules from a list into individual attributes把nn.Sequential子类转换为组合composition形式。这条约束的深层原因是形状追踪是添加在运行行为之上的类型层类型层必须可随时剥离而不改变模型语义。从源码看shape_extensions包的设计正是如此——它导入后会给torch.Tensor、nn.Conv2d等打补丁以支持下标语法Tensor[[B, C, H, W]]提供IntVar的算术支持但这都是运行时兼容层不改变张量运算本身。Restructure 的粒度在 SKILL.md 的 Step 4 中被明确定义通常只是 2–3 行的改动——分离一次迭代、移除一次int()强转、增加一个Int类型参数。如果发现自己正在重写算法就已经越界了。2.2 第二优先形状覆盖Shape coveragetype with shapes as much as possible. Useassert_typeto verify inference, not just annotation fallback. Shapeless parts get bareTensorwith comments explaining why.在忠实性的前提下尽可能多地用形状注解。关键要求是用assert_type验证推断结果而不是依赖注解回退annotation fallback无法追踪形状的部分使用裸Tensor并必须用注释说明原因。2.3 第三优先识别阻塞点Identify blockersevery place where shapes are lost should trace back to a specific gap or genuinely># 错误示范没有 assert_type0 errors 说明不了任何事 h F.relu(self.fc1(x)) # 正确示范assert_type 证明推断出了具体形状 h F.relu(self.fc1(x)) assert_type(h, Tensor[[B, 512]]) # pyrefly 验证类型运行时零开销这也解释了为什么 SKILL.md 要求每个 forward 方法中的每个局部变量都要有一个assert_type无例外——即使在使用类型化接口typed interface的模块内部也一样类型化接口只说明边界是类型化的内部仍然需要assert_type检查点。3.1 注解层级Annotation hierarchy当检查器无法推断形状时按以下优先级决策来自 SKILL.md Step 5优先级手段适用场景1assert_type验证检查器的推断证明系统真正工作2注解回退x: Tensor[[B, C, H, W]] unrefined_op(...)操作返回 unrefined 但你知道形状需注释 WHY3type: ignore检查器算出了错误类型代数缺口 A1 或条件等式最后手段必须注释具体缺口4裸Tensor形状真正不可知数据依赖的 token 数、条件累积必须注释具体原因4. Stub 哲学修 Stub 还是绕过去移植原则文档的第二节是 Stub 哲学——是否修改 stub 由用户决定这必须在移植前Gate 0 之前确认用户不打算改 stub或不置可否不要动 stub。在现有 stub 允许的范围内尽量移植把无法追踪的操作记录为缺口gap在完成报告中建议为值得修复的缺口提交 upstream issue。这条路径完全被支持——一个不太完整的移植是预期结果不是失败。用户同意改 stub获得一次性许可可在移植过程中顺手改进 stub 签名无需每个算子都重新询问。但仍要先移植并用reveal_type确认缺口再动 stub。核心判断stub 缺口往往是值得修复的根因而非值得绕过的表象——一个改进后的签名能为每一个使用该算子的模型恢复形状而不仅是当前这一个。这就是为什么在范围内时贡献 stub 修复是更高杠杆的选择。修复 stub 时必须遵循通用性原则When you do change a stub or shape DSL function, make the fix general — capture the truth about the op, dont special-case it for your model.即修改要捕获算子本身的真实形状规律而不是为你的模型特判。4.1 stub 修改的具体形态从 shape_tracking_capabilities.md 和 torch-stubs 源码 看stub 的返回类型有四种追踪形态Self返回保形操作.float()、.contiguous()、.detach()Tensor[S] → Tensor[S]S: IntTuple整体保形F.relu、nn.LayerNorm对任意 batch 前缀后的尾部维度用Tensor[[*Elements[Bs], D]]泛型参数捕获构造参数并在forward中计算输出形状nn.Linear[In, Out]、nn.Conv2d[InC, OutC, K, S, P, D]Int[N]捕获把运行时 int 参数绑定到类型级维度。例如真实 stub 中nn.Linear的定义nn/init.pyiclass LinearIN: IntVar, OUT: IntVar: weight: Tensor[[OUT, IN]] bias: Tensor[[OUT]] | None def __init__( self, in_features: _Int[IN], out_features: _Int[OUT], bias: bool True, ...当调用nn.Linear(400, 10)时检查器绑定IN 400、OUT 10于是forward输出为Tensor[[..., 10]]。4.2 需要形状函数的操作当输出形状依赖参数计算而非简单泛型时stub 的返回注解会调用类型级形状函数例如 nn/init.pyi 中的adaptive_pool2d_shape、pixel_shuffle_shape、pool_shape等这些函数定义在 torch-stubs/_shapes.pyi 中用type_shape_dsl_function装饰从 stub 中以torch._shapes导入因为torch-stubs包为类型检查提供了torch包。Gate 1 的算子审计表就要求逐一确认stub 返回注解是否调用形状函数以及该函数是否真的存在于_shapes.pyi。5. 在忠实性约束下最大化形状覆盖真实案例优先级框架在实际移植中的运用可以从 finalmlp.pyFinalMLP 双流 MLP 模型中看到完整演绎。这个示例同时演示了忠实性不删除任何原参数、不改变结构与形状覆盖尽可能追踪如何共存。5.1 桥接维度Bridge dims忠实保留动态内部类型化边界MLP类内部用nn.Sequential(*block)动态构建层因为隐藏层数量来自list[int]这必然擦除模块类型。移植原则允许这种重构受限的情况存在——关键是把连接未追踪段与已追踪下游的桥接维度提升为类级类型参数class MLPInD: IntVar, OutD: IntVar: output_dim: Int[OutD] def __init__( self, input_dim: Int[InD], hidden_units: list[int], output_dim: Int[OutD], activation: str ReLU, dropout: float 0.0, batch_norm: bool False, ) - None: super().__init__() # ... nn.Sequential(*block) 动态构建内部形状是 bare self.layers nn.ModuleList(layer_blocks) self.output_dim output_dim def forwardB: IntVar - Tensor[[B, OutD]]: for layer in self.layers: x layer(x) # typed interface: Sequential(*list) ModuleList[nn.Module] 循环擦除形状 result: Tensor[[B, OutD]] x # type: ignore[pyrefly:bad-assignment] assert_type(result, Tensor[[B, OutD]]) return result注意这里__init__的每个参数都被保留忠实性forward 通过类型化接口返回Tensor[[B, OutD]]——下游的nn.Linear接受Tensor[[*Elements[Bs], OutD]]Bs: IntTuple绑定Bs (B,)后 batch 维继续传播。没有这个桥接维度注解回退只能恢复裸Tensor或仅 batch 的形状。5.2 注解回退与assert_type的配合同一个文件里InteractionAggregation.forward展示了注解回退 类型化元素列表的配合bilinear_terms: list[Tensor[[B]]] [] for i in range(self.num_heads): x_h x[:, i * head_x_dim : (i 1) * head_x_dim] interaction (x_h self.bilinear_W[i] * y_h).sum(dim-1) assert_type(interaction, Tensor[[B]]) bilinear_terms.append(interaction) # annotation fallback: stack from dynamic loop cant infer collection size bilinear_out: Tensor[[B, NH]] torch.stack(bilinear_terms, dim-1) assert_type(bilinear_out, Tensor[[B, NH]])动态循环的torch.stack无法从集合长度推断新维度DSL 无法统计动态循环的迭代次数于是用注解回退标注Tensor[[B, NH]]并用注释说明原因——这正是移植原则Shapeless parts get bareTensorwith comments explaining why的精确延伸即使无法完整追踪也要用断言固定每一个局部变量的类型。5.3 首次迭代分离避免分支汇合展宽FinalMLPBackbone.forward演示了分支汇合展宽branch join widening的解法——第一层把[B, F, D]变换为[B, K, D]后续层保持[B, K, D]。如果写成一个循环x会被展宽成联合类型。移植原则要求在这种情况下分离第一次迭代x self.first_layer(input_embs) assert_type(x, Tensor[[B, K, D]]) for layer in self.rest_layers: x layer(x) assert_type(x, Tensor[[B, K, D]])对照 SKILL.md Step 4 的重构清单这类 2–3 行改动正是Restructure的典型粒度。6. 何时可以停下来真正数据依赖的形状移植原则强调每一个形状丢失点都必须能追溯到具体缺口或真正数据依赖的形状。而 shape_tracking_capabilities.md 明确指出真正无法追踪的模式极少数据依赖的结果数量torch.nonzero、t[bool_mask]输出长度取决于掩码内容而非形状数据依赖的累积条件torch.cat中元素数量取决于运行时控制流A1 代数缺口N * (X // N) X对向下取整除法不成立注意反向(a * b) // b → a是可简化且健全的。其余一切理论上都应可追踪。如果结果回退到Tensor[IntTuple]应首先检查三大机制——stub、形状函数、特殊处理器位于 pyrefly/lib/alt/如nn_module_specials.rs中的nn.Sequential链式追踪。当形状丢失时追溯上游而非就地放弃trace upstream而非就地放弃输入本身就是裸Tensor吗没有算子能从裸Tensor恢复形状——找到形状真正丢失的位置才是修复点该用Int却用了int函数参数类型改为Int[X]该用tuple却用了listtorch.cat([a, b])会均质化元素类型改用torch.cat((a, b))分支汇合展宽在各分支独立计算输出或用 Optional 收窄内联表达式丢形状f(g(x))拆成y g(x); f(y)stub 返回裸类型检查返回注解是否计算形状否则修复.pyi签名或添加形状函数。7. 用 verify_port.sh 与检查器验证移植移植原则的验证手段在 verify_port.sh 和 SKILL.md 的 Verification 阶段中体现# 1. 启发式质量门不进行类型检查只做静态统计 tensor-shapes/skills/add-shape-types-to-torch-model/verify_port.sh path/to/your/port.py # 2. 真正的 Pyrefly 检查形状追踪在 stub 与 shape_extensions 位于搜索路径时自动开启 pyrefly check --config /dev/null --python-version 3.13 \ --search-path root containing torch-stubs \ --search-path root containing shape_extensions \ path/to/your/port.py两个搜索根是独立的tensor-shapes/pyrefly-torch-stubs提供torch-stubs包和tensor-shapes/pyrefly-shape-extensions提供shape_extensions包。没有--tensor-shapes之类的开关——形状追踪在形状感知 stub 和shape_extensions出现在搜索路径上时就自动启用。PEP 695/696 泛型语法需要--python-version 3.12或更高语料库运行在3.13。pyrefly dump-config可以报告解析后的搜索路径。verify_port.sh 的检查项直接对应移植原则的关切type: ignore[的数量——每一条都要审计是 A1 代数缺口还是可修的 stub 问题签名与局部变量中的裸Tensor——问形状是否真正不可知assert_type的 shaped/bare 比例——bare 比例就是移植质量指标是否存在def test_冒烟测试——且测试必须用assert_type验证类型化输出而不是assert out.shape (...)运行时形状断言不验证 pyrefly只证明模型能跑是否出现 excl/excluded/not ported 等排除标记——Gate 2 清单要求原文件的每个类、函数、方法都必须出现在移植中。完成报告Completion report模板把移植原则的三条优先级落成可填写的字段Gate 1 审计的算子数、Gate 2 清单勾选情况、type: ignore分类计数、assert_type的 shaped/bare 数量与比例、每个裸断言是否有注释 Step 4 收据追溯以及最后面向用户的缺口与改进建议块。8. 总结三条原则如何构成决策闭环移植原则文档的三条优先级构成一个自洽的决策闭环忠实性划定重构的边界——一切形状追踪都必须在保持运行行为不变的前提下进行形状覆盖规定目标与验收标准——assert_type是唯一凭证注解回退不能冒充推断裸Tensor必须附带原因注释识别阻塞点把剩余的缺口转化为路线图——每个裸形状要么追溯到具体 stub/DSL/代数缺口要么归于真正数据依赖的形状并以此决定下一步该修复哪个 stub、为哪个算子编写形状函数。而 Stub 哲学则回答了闭环中谁来修、修到多通用的问题是否修改 stub 由用户预先决定一旦决定修复就要捕获算子的真实规律而非针对单个模型特判。三者结合构成了 pyrefly 张量形状移植从决策、实施到验证的完整方法论——这也是 SKILL.md 中门控式流程Gate 0–2、模块循环、验证阶段得以成立的思想基础。【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考