triaging-issues

PyTorch 问题分流技能

此技能可帮助分流 GitHub 问题，包括转交问题、应用标签和发送一线回复。

目录

• 可用的 MCP 工具
• 绝不能添加的标签
• 问题分流步骤
  • 步骤 0：已转交——跳过
  • 步骤 1：问题咨询还是 Bug／功能请求
  • 步骤 1.5：需要复现——外部文件
  • 步骤 2：转交
  • 步骤 2.5：PT2 问题——特殊处理
  • 步骤 3：转交给次级值班团队
  • 步骤 4：为问题添加标签
  • 步骤 5：升级——高优先级（人工审核），然后进行版本分流
  • 步骤 6：bot-triaged（自动）
  • 步骤 7：标记为已分流
• V1 限制

标签参考： 完整的适用于分流的标签目录，请参阅 labels.json。仅使用此文件中已有的标签。 不要编造或猜测标签名称。此文件不包含 CI 触发器、测试配置、发行说明、已弃用的标签以及需要人工决策的标签。

PT2 分流指南： 分流 PT2／torch.compile 问题时的详细标签指导，请参阅 pt2-triage-rubric.md。

回复模板： 标准回复消息请参阅 templates.json。

---

可用的 MCP 工具

使用以下 GitHub MCP 工具进行分流：

工具	用途
mcp__github__get_issue	获取问题详情和现有标签
mcp__github__get_issue_comments	获取现有的问题评论
mcp__github__update_issue	应用标签或关闭问题
mcp__github__add_issue_comment	添加评论（仅用于将问题咨询者引导至其他渠道）
mcp__github__search_issues	查找类似问题以供参考

---

绝不能添加的标签

前缀／类别	原因
labels.json 中不存在的标签	只能使用允许列表中已有的标签
ciflow/*	仅用于 PR 的 CI 任务触发器
test-config/*	仅用于 PR 的测试套件选择器
release notes: *	自动分配的发行说明标签
ci-*、ci:*	CI 基础设施控制项
sev*	严重程度标签需要人工决策
merge blocking	需要人工决策
actionable、needs design、needs reproduction、needs research	仅供人工审核者审核问题后使用
任何包含 "deprecated" 的标签	已过时
oncall: releng	不是分流转交目标。请改用 module: ci

如果无法继续： 如果钩子阻止添加标签，只添加 triage review，然后停止。后续由人工处理。

这些规则由 PreToolUse 钩子强制执行，该钩子会根据 labels.json 验证所有标签。

绝不覆盖人工添加的标签

如果人工已经添加了标签（尤其是 ci: sev、严重程度标签或优先级标签），不要移除或替换它们。你的工作是补充，而不是覆盖。

---

问题分流（逐个问题处理）

0）已转交——跳过

如果问题已有任何 oncall: 标签，则完全跳过。 不要：

• 添加任何标签
• 添加 triaged
• 留下评论
• 执行任何分流工作

该问题归次级值班团队所有，由他们负责处理。

1）问题咨询还是 Bug／功能请求

• 如果是问题咨询（不是 Bug 报告或功能请求）：关闭问题，并使用 templates.json 中的 redirect_to_forum 模板。
• 如果不确定这是 Bug／功能请求还是问题咨询：使用 request_more_info 模板请求补充信息，然后停止。

1.5) 外部文件

检查问题正文是否包含用户需要下载以复现问题的外部文件链接。

需要检测的模式：

• 文件附件：.zip、.pt、.pth、.pkl、.safetensors、.onnx、.bin 文件
• 外部存储：Google Drive、Dropbox、OneDrive、Mega、WeTransfer 链接
• 模型仓库：指向模型文件的 Hugging Face Hub 链接

操作：

1. 编辑问题正文，移除或隐藏下载链接
   • 替换为：[Link removed - external file downloads are not permitted for security reasons]
2. 使用 templates.json 中的 request_self_contained_reproduction 模板
3. 不要添加 triaged ——等待用户提供可复现示例

1.55) 缺少复现示例——其他情况

出现以下情况时，请求提供自包含复现示例，然后停止：

• 用户报告了特定硬件问题（例如，特定 GPU 型号），但没有提供自包含的复现脚本
• 用户提及了无法通过几行代码公开运行的特定模型、检查点或数据集
• 问题描述了升级版本后出现的问题，但只提供了高层描述，没有提供最小脚本
• 复现依赖特定训练设置、分布式环境或复杂基础设施

1.6) 边界情况与数值精度

如果问题涉及极端值或数值精度差异：

需要检测的模式：

• 接近 torch.finfo(dtype).max 或 torch.finfo(dtype).min 的值
• 使用有效（但极端）的输入时，输出中出现 NaN/Inf
• CPU 和 GPU 结果之间存在差异
• 不同 dtype 之间存在精度差异（例如，fp32 与 fp16）
• Fuzzer 生成的边界情况

重要——避免因关键词触发错误分类：

应根据根本原因添加标签，而不是根据错误或标题中出现的关键词。关键词只能告诉你哪里失败了，不能说明原因。

• 在 import torch 时出现 undefined symbol: ncclAlltoAll 错误属于打包问题（module: binaries），而非分布式训练错误——用户根本没有运行分布式代码。
• 参数名或容差检查中出现 nan，并不意味着应标记为 module: NaNs and Infs，除非问题确实与 NaN 传播有关。
• 堆栈跟踪中提到 autograd，并不意味着应标记为 module: autograd——请确认问题出在 autograd 本身，还是仅仅经过了相关调用路径。
• 带有容差阈值的测试失败属于 module: tests，而非 module: numerical-stability。

请问自己：“需要在哪里修复？”这决定了应使用什么标签。

操作：

1. 添加 module: edge cases 标签
2. 如果问题来自 Fuzzer，还要添加 topic: fuzzer
3. 使用 templates.json 中的 numerical_accuracy 模板链接到文档
4. 如果文档明确指出该问题属于预期行为，则使用模板评论关闭问题

2) 转交（领域库或 ExecuTorch）

如果问题属于其他仓库（vision/text/audio/RL/ExecuTorch 等），请转交该问题并停止。

2.5) PT2 问题——特殊处理

PT2 不是重定向。 oncall: pt2 与步骤 3 中其他 oncall 标签不同。PT2 问题仍需继续执行步骤 4–7，完成完整的分类处理——添加 oncall: pt2，然后继续添加 module: 标签、标记为 triaged 等。

每个带有 oncall: pt2 的问题都必须至少有一个 module: 标签。 如果没有模块标签，PT2 oncall 队列范围过于宽泛——团队需要知道受影响的组件（例如，module: dynamo、module: inductor、module: helion、module: dynamic shapes）。如果无法确定具体模块，则使用 module: compile ux 作为后备选项，但请始终先尝试确定具体模块。详细指导请参阅 pt2-triage-rubric.md。

3) 重定向至二级 Oncall

至关重要： 将问题重定向到非 PT2 oncall 队列时，恰好应用一个 oncall: ... 标签，然后停止。不要：

• 添加任何 module: 标签
• 将其标记为 triaged
• 继续进行任何分类处理

子 oncall 团队会自行处理分类。你的职责仅是将问题转交给他们。

值班重定向标签

标签	使用场景
oncall: jit	TorchScript 问题
oncall: distributed	分布式训练（DDP、FSDP、RPC、c10d、DTensor、DeviceMesh、对称内存、上下文并行、流水线）。**特别处理：**应用此标签后，在此问题上调用分布式分诊子技能（/distributed-triage），进行二级分诊——该技能会将问题分派给子值班人员、添加模块标签并标记为已分诊。
oncall: export	torch.export 问题
oncall: quantization	量化问题
oncall: mobile	移动端（iOS/Android），不包括 ExecuTorch
oncall: profiler	Profiler 问题（CPU、GPU、Kineto）
oncall: visualization	TensorBoard 集成

应避免的常见分派错误：

• MPS ≠ Mobile。 MPS（Metal Performance Shaders）是 macOS/Apple Silicon GPU 后端。请勿将 MPS 问题分派给 oncall: mobile。MPS 问题应留在常规队列中，并标记为 module: mps。
• DTensor → oncall: distributed。 DTensor 问题应始终分派给 oncall: distributed，即使问题未提及 DDP/FSDP。
• ONNX → module: onnx。 不存在 oncall: onnx。请使用 module: onnx，并将问题留在常规队列中。
• CI/releng → module: ci。 不要使用 oncall: releng。CI 基础设施问题请使用 module: ci。
• torch.compile + 分布式。 当 torch.compile 未能正确处理分布式操作（例如 dist.all_reduce）时，问题通常需要同时添加 oncall: pt2 和 oncall: distributed，因为修复可能涉及两个代码库。

注意： oncall: cpu inductor 是 PT2 的子队列。常规分诊只需使用 oncall: pt2。

4) 为问题添加标签（如果未转交／重定向）

仅当问题留在常规队列中时：

• 根据受影响的领域添加 1 个或更多 module: ... 标签
• 如果同时存在具体标签和通用标签，优先使用具体标签。查看 labels.json 中的说明，了解具体标签何时取代通用标签（例如，SDPA 问题使用 module: sdpa，而不是 module: nn；flex attention 问题使用 module: flex attention，而不是 module: nn）。
• feature——目前以任何形式都不存在的全新功能
• enhancement——对已有可用功能的改进（例如，为已通过回退／组合方式运行的算子添加原生后端内核、性能优化、提供更好的错误消息）。如果改进涉及性能，也添加 module: performance。
• function request——新函数，或为现有函数添加新参数／模式
• 如果问题描述说该操作“目前可以运行”或“会回退到”较慢的路径，则应标记为 enhancement，而不是 feature

容易漏掉的常见标签——务必检查：

条件	标签
段错误、非法内存访问、SIGSEGV	module: crash
性能问题：性能回退、变慢或优化请求	module: performance
Windows 上的问题	module: windows
之前正常工作的功能现在出现故障	module: regression
之前正常工作的文档／链接现已失效	module: docs + module: regression（不是 enhancement）
关于测试失败的问题（而非底层功能）	module: tests
反向传播／梯度计算错误	module: autograd（除算子模块标签外还需添加）
torch.linalg 算子或线性代数算子（solve、svd、eig、inv 等）	module: linear algebra
has workaround	仅当解决方法并非显而易见且并不简单时才添加。如果问题是“非连续张量无法使用 X”，调用 .contiguous() 只是该错误的反向操作，不能算作解决方法。真正的解决方法例如安装特定版本的包、添加同步点、插入 gc.collect()，或改用一个无法从错误描述中直接推知的 API。

根据实际错误而不是关键词添加标签。 阅读问题以了解实际出错之处。一个关于广播的问题即使恰好在参数名中提到“nan”，也属于前端问题，而不是 NaN／Inf 问题。

5) 升级处理——高优先级（需人工审核），然后进行版本发布分流

按以下顺序作出两个独立判断。先完成 5a，然后对每个问题完成 5b——5b 不仅适用于在 5a 中升级处理的问题，而且一个问题可以同时带有两个标签、其中一个标签，或都不带。

5a) 高优先级——必须人工审核

重要： 如果你认为某个问题属于高优先级，必须：

1. 添加 triage review 标签，且不要添加 triaged

未经人工确认，不要直接添加 high priority。

高优先级标准：

• 崩溃／段错误／非法内存访问
• 静默的正确性问题（结果错误但没有报错）
• 相较于之前版本出现回退
• 内部断言失败
• 影响大量用户
• 影响核心组件或热门模型

5b) 发布分诊 — 已在最新版本中确认

release triage 是一个适用范围狭窄的标记，并非包罗万象。它会将问题呈交给负责该版本发布的人；它不是挑选提交的请求，也不会作出任何决定。

你会获知当前版本，切勿猜测。 你的提示词中包含一个 RELEASE CONTEXT 区块，其中给出了最近发布的次版本。如果区块显示 unknown，就不要添加 release triage。

只有满足以下两个条件之一时，才添加该标记：

条件 1 — 已确认发生在最近发布的次版本中。 问题中注明了 PyTorch 版本，且该版本是 RELEASE CONTEXT 中提到的次版本，或其某个补丁版本。“注明版本”是指版本号写在问题中：环境转储中的 torch.__version__ 行、pip install 行，或报告者在文字说明中提及的版本。从问题中读取版本；切勿根据回溯、问题日期或你认为的当前版本推断。

条件 2 — 已有 high priority 标签。 你查看问题时，该标签已由人工在之前的处理过程中添加。这只指现有标签，不是你在 5a 中作出的判断。如果你认为问题优先级高，5a 会让你添加 triage review 并停止；仅凭这一点，不足以添加 release triage。

以下情况均不足以单独成为添加该标签的理由：

情况	不添加的原因
仅在 main、nightly 或 RC 上复现	未在正式发布版本中确认。如果问题严重，应按 5a 添加 triage review。
问题中没有注明任何版本	未经确认。不要猜测。
注明的版本早于 RELEASE CONTEXT 中的次版本	已经发布；不属于当前发布系列。
崩溃、静默的正确性问题、BC 破坏、打包或安装错误	严重程度不是判定条件。只有同时满足条件 1 或条件 2，才符合要求。
看起来像是发布时会带着问题上线	属于推测。
功能请求、增强请求或仅涉及文档的问题	无论满足哪个条件，都不要添加 release triage。

不确定时，就不要添加。 发布经理会将此标签视为一份简短清单并逐项人工处理，因此误报的代价高于漏报：清单里如果塞满了不确定项，就没人会继续查看，最终什么问题也发现不了。真正紧急的问题仍可通过 5a 中的 triage review 呈交给人工处理。

release triage 与 5a 的决定相互独立——一个问题可以同时带有这两个标签——它始终只是一个标记，而非裁决：是否挑选提交绝不是机器人可以决定的。

6) bot-triaged（自动）

每次修改问题后，post-hook 都会自动应用 bot-triaged 标签。你无需手动添加。

7) 标记为已分诊

如果问题未转交／重定向，也未标记为需要审核，则添加 triaged。

---

V1 约束

不要：

• 自动关闭错误报告或功能请求
• 除非属于步骤 1 中明确的使用问题，否则不要关闭问题
• 将问题指派给用户
• 未经人工确认，直接添加 high priority
• 将问题重定向给值班人员时添加模块标签
• 对错误报告或功能请求发表评论，但分类不明确时可单独请求一次补充信息

要：

• 关闭明确的使用问题，并指向 discuss.pytorch.org（根据步骤 1）
• 保持谨慎——有疑问时，添加 triage review 交由人工处理
• 仅当问题已在最近发布的次版本中确认，或已有 high priority 标签时，才添加 release triage（步骤 5b）；不确定时不要添加
• 有把握时添加类型标签（feature、enhancement、function request）
• 完成分类后添加 triaged 标签

注意： 每次修改问题后，post-hook 都会自动应用 bot-triaged 标签。