# RuntimeError: torch.compile：函数 'forward' 发生图断裂，回退到 eager 模式。请考虑重写函数以避免动态控制流。

- **ID:** `pytorch/torch-compile-graph-break`
- **领域:** pytorch
- **类别:** runtime_error
- **验证级别:** ai_generated
- **修复率:** 70%

## 根因

torch.compile 遇到图断裂（例如动态控制流、不支持的操作或 Python 端副作用），导致无法捕获整个计算图，被迫回退到 eager 模式，并可能降低性能。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| torch>=2.1 | active | — | — |
| torch>=2.3 | active | — | — |
| Python 3.11 | active | — | — |

## 解决方案

1. ```
   Refactor the forward method to remove dynamic control flow. Replace if statements with torch.where or masked operations:

# Before (causes graph break):
if x.sum() > 0:
    y = x * 2
else:
    y = x + 1

# After (no graph break):
mask = (x.sum() > 0).float()
y = mask * (x * 2) + (1 - mask) * (x + 1)
   ```
2. ```
   Use torch.compiler.disable() decorator on specific submodules that cause graph breaks, while keeping the rest compiled:

@torch.compiler.disable
def custom_op(x):
    return my_python_function(x)

model = torch.compile(model)
   ```
3. ```
   Enable torch._dynamo.config.verbose=True and torch._dynamo.config.suppress_errors=True to get detailed logs on where the graph break occurs:

import torch._dynamo
torch._dynamo.config.verbose = True
torch._dynamo.config.suppress_errors = True
   ```

## 无效尝试

- **Disabling torch.compile entirely with torch.compiler.reset()** — This removes the performance benefits of compilation and does not address the underlying code pattern that causes graph breaks. (95% 失败率)
- **Adding @torch.jit.script decorator on top of torch.compile** — torch.jit.script and torch.compile are different systems; mixing them can cause conflicts and unexpected behavior, not fixing the graph break. (90% 失败率)
- **Using torch.inference_mode() to disable autograd entirely** — While inference mode reduces overhead, it does not resolve graph breaks caused by dynamic control flow in the model's forward method. (85% 失败率)