# PAN 2

PAN2 是一个基础世界模型，用于模拟场景在基于时间的动作和相机运动计划下如何演化。其 29B 生成式模拟器是一个双流多模态扩散 Transformer，已在此处集成；而负责编写其提示词的[推理主干](https://huggingface.co/IFM/PAN2#reasoning-backbone)则未集成。

PAN 2 仅以 [Modular Diffusers](../../modular_diffusers/overview) 块的形式集成。[PAN2Blocks](/docs/diffusers/v0.43.0/zh/api/pipelines/pan2#diffusers.PAN2Blocks) 支持两种工作流：

| 工作流 | 输入 |
|---|---|
| `t2v` | `prompt` |
| `i2v` | `prompt`, `image` |

```py
import torch
from diffusers import ModularPipeline
from diffusers.utils import export_to_video, load_image

pipe = ModularPipeline.from_pretrained("IFM/PAN2")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

prompt = "A red fox trots through fresh snow in a pine forest at dawn."

video = pipe(prompt=prompt, generator=torch.Generator().manual_seed(0), output="videos")[0]
export_to_video(video, "pan2_t2v.mp4", fps=24)

image = load_image("path/to/first_frame.png")
video = pipe(prompt=prompt, image=image, generator=torch.Generator().manual_seed(0), output="videos")[0]
export_to_video(video, "pan2_i2v.mp4", fps=24)
```

Classifier-free guidance 在 guider 上进行配置（默认值为 `guidance_scale=2.5`）：

```py
pipe.update_components(guider=pipe.guider.new(guidance_scale=5.0))
```

每次调用都接收单个提示词，且该提示词在编码时不进行填充。因此，Transformer 无需使用注意力掩码，并且所有 [注意力后端](../../optimization/attention_backends) 均可用：

```py
pipe.transformer.set_attention_backend("flash_hub")  # FlashAttention-2
```

## 安全检查器

PAN 2 会在生成前对提示词以及生成后的每个视频运行护栏检查，被拦截的提示词或视频会引发 `ValueError`。这些检查默认开启，`load_components()` 会加载护栏，这需要 [PAN 2 guardrail](https://github.com/ifm-ai/pan2-guardrail) 包：

```bash
pip install git+https://github.com/ifm-ai/pan2-guardrail
```

## 上下文并行

[PAN2Transformer3DModel](/docs/diffusers/v0.43.0/zh/api/models/pan2_transformer3d#diffusers.PAN2Transformer3DModel) 支持 [context parallelism](../../optimization/context_parallelism)。文本和视频的 token 数量通常不能被设备数量整除（文本 token 数量取决于提示词），因此推理时请使用 `ulysses_anything` 或 `ring_anything`。例如用于训练时，普通的 `ulysses_degree` / `ring_degree` 要求两种 token 数量都能被 context parallel size 整除。

```py
# torchrun --nproc_per_node=2 pan2_context_parallel.py
import torch
import torch.distributed as dist
from diffusers import ContextParallelConfig, ModularPipeline

dist.init_process_group("nccl")
rank = dist.get_rank()
torch.cuda.set_device(rank)

pipe = ModularPipeline.from_pretrained("IFM/PAN2")
pipe.load_components(dtype=torch.bfloat16)
pipe.to(f"cuda:{rank}")
pipe.transformer.enable_parallelism(config=ContextParallelConfig(ulysses_degree=2, ulysses_anything=True))

video = pipe(prompt="A red fox trots through fresh snow.", generator=torch.Generator().manual_seed(0), output="videos")[0]
dist.destroy_process_group()
```

## PAN2ModularPipeline[[diffusers.PAN2ModularPipeline]]

#### diffusers.PAN2ModularPipeline[[diffusers.PAN2ModularPipeline]]

```python
diffusers.PAN2ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/pan2/modular_pipeline.py#L42)

用于 PAN 2 的 ModularPipeline：文本生成视频，以及从首帧图像生成视频。

```py
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("IFM/PAN2")
pipe.load_components(dtype=torch.bfloat16)
```

#### check_safety_checker_loaded[[diffusers.PAN2ModularPipeline.check_safety_checker_loaded]]

```python
check_safety_checker_loaded()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/pan2/modular_pipeline.py#L103)

如果检查已启用但未加载 PAN 2 护栏，则引发异常。

#### disable_safety_checker[[diffusers.PAN2ModularPipeline.disable_safety_checker]]

```python
disable_safety_checker()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/pan2/modular_pipeline.py#L118)

关闭提示词和视频检查，风险自负。

#### enable_safety_checker[[diffusers.PAN2ModularPipeline.enable_safety_checker]]

```python
enable_safety_checker()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/pan2/modular_pipeline.py#L97)

使用 PAN 2 护栏检查提示词和生成的视频。

## PAN2Blocks[[diffusers.PAN2Blocks]]

#### diffusers.PAN2Blocks[[diffusers.PAN2Blocks]]

```python
diffusers.PAN2Blocks()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/pan2/modular_blocks_pan2.py#L251)

用于文本生成视频和图像生成视频的模块化流水线组件，基于 PAN 2。

支持的工作流：
- `t2v`：需要 `prompt`
- `i2v`：需要 `prompt`、`image`

组件：text_encoder (`Qwen3_5TextModel`) tokenizer (`Qwen2Tokenizer`) safety_checker (`PAN2SafetyChecker`) vae (`AutoencoderKLWan`) video_processor (`VideoProcessor`) scheduler (`FlowMatchEulerDiscreteScheduler`) transformer (`PAN2Transformer3DModel`) guider (`ClassifierFreeGuidance`)

配置：enable_safety_checker（默认值：True）

输入：prompt (`str`)：用于引导生成的提示词，单个字符串。negative_prompt (`str`，*可选*)：用于避免引导生成的提示词，单个字符串。当需要引导但未传入（或传入空值）时，将使用 PAN 2 的默认负面提示词，其时间范围设置为片段的时长。max_sequence_length (`int`，*可选*，默认为 1536)：提示词编码的最大序列长度。num_frames (`int`，*可选*，默认为 313)：要生成的视频帧数，形式为 `4 * n + 1`。fps (`float`，*可选*，默认为 24.0)：视频的帧率，用于在默认负面提示词中设置其时长。image (`Image`，*可选*)：第一帧，单张图像。height (`int`，*可选*)：生成视频的高度（像素），默认为 704。width (`int`，*可选*)：生成视频的宽度（像素），默认为 1248。num_videos_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的视频数量。image_latents (`Tensor`，*可选*)：归一化的首帧潜在变量。可由 vae_encoder 步骤生成。num_inference_steps (`int`)：去噪步骤数。sigmas (`list`，*可选*)：用于去噪过程的自定义 sigmas。latents (`Tensor`)：预生成的噪声潜在变量，用作视频生成的输入。generator (`Generator`，*可选*)：用于确定性生成的 Torch 生成器。attention_kwargs (`dict`，*可选*)：注意力处理器的额外 kwargs。output_type (`str`，*可选*，默认为 np)：输出格式：'pil'、'np'、'pt'。

输出：videos (`list`)：生成的视频。