文档示例

## 任务目标

请为本次指定的 Python 接口或模块编写或修正可运行示例。

在现有授权范围内完成实际改动和验证；缺少外部条件时先完成可独立实现的部分，不能只停留在计划。

## 输入信息（选填）

两项均可留空，也可直接用一句话说明目标并附上已有资料。无需自行整理版本、配置或完整需求表；能读取的内容由执行者补齐。

示例目标：优先修正对话中提到的不可运行示例；未指定时从模块主要公开入口选择现有最小用例，补齐输入、调用和可核对输出。
模块或示例资料：读取接口源码、docstring、已有示例、资源引用和检查脚本，从项目依赖与测试矩阵识别实际运行条件。

## 信息不完整时

先使用本次对话中已经说明的信息；用户留空、写“暂无／不清楚”或未替换输入标记，都按缺失处理，不当作真实路径、参数或业务值。已能从资料确定的内容不重复询问，不编造文件、日志、接口、业务值或执行结果。在用户已授权的范围内读取相关工程和材料，不为补齐输入擅自扩大操作范围。

### 优先确认

- 查清示例的必要导入、初始化、参数和结果含义，排查前序示例遗留的隐式状态。
- 追踪数据文件、下载地址、许可及设备选择，判断能否用合法的小样本替代大资源。
- 核对解释器、依赖、随机源及现有示例检查流程；Paddle 专属条件仅在相应项目中采用。

### 可采用的默认处理

- 默认编写能说明既有接口用途的最小完整示例，不附加训练、部署或无关框架。
- 优先合法可构造的小数据和现有设备，明显标记示例数据；不把本地私有路径写成交付条件。
- 正文内给代码与说明，未被要求时不新建独立文档；预期输出和实测输出分开记录。

### 必须有依据的事项

- 接口用途或输出含义无定义，无法判断哪种样例能代表正确业务行为。
- 必要数据许可或访问资格不明且无法构造等价小样本时，不擅自下载或分发该资源。

只有缺口会改变业务结果、权限边界或关键实现，且无法从现有资料确认时，才集中提出最多 3 个关键问题；说明影响，并继续完成不依赖答案的部分。一般命名、排版和可逆实现细节按现有约定决定，不逐项等待确认。

### 资料仍不足时的交付

- 无执行设备时提供完整示例、资源准备及运行命令，列出结果核对点和待执行项。
- 无法取得真实资源时交付明确标注的小样本示例，并说明其不覆盖的真实数据或设备条件。

## 执行要求

示例应能复现并核对结果，运行条件须与目标项目一致。编写 Paddle 示例时，单独说明飞桨专用检查指令、执行时限与设备要求；普通 Python 项目不直接套用这些条件。

1. 选取能够解释接口主要用途的最小业务场景，明确输入、调用和输出。补齐必要导入与初始化，去掉与理解本接口无关的大段训练、部署或数据下载代码，确保读者复制后知道从哪里开始运行。
2. 使用小而有代表性的数据，列出每个输入字段、单位或形状。需要外部文件时说明取得方式与许可条件，不能引用本机私有路径；无法取得资源时提供合法可构造的小样本，不伪装成真实生产数据。
3. 明确展示用户需要核对的结果，区分实际输出与解释性注释。随机场景设置相关随机源并说明仍可能存在的环境差异；不承诺只设置一个种子就能让所有设备和版本得到逐位一致结果。
4. 写清解释器、依赖、CPU 或加速设备要求及运行步骤。需要特定硬件时不要隐含依赖默认设备；需要联网时列出资源用途和可替代方式，避免基础使用示例因大型下载长期没有反馈。
5. 用项目支持的方式执行示例或加入已有示例检查流程，核对输出的关键属性。优先修复可检查性问题，确实需要跳过时标明原因与缺失验证，不能通过跳过全部断言声称示例可靠。
6. 从空目录或干净环境复跑关键示例，检查上下文是否依赖前一个例子留下的变量、文件或全局状态。为最常见的非法输入增加短小的错误说明，使读者知道问题来自输入、环境还是接口限制。

## 交付与验收

输出：可复制示例、必要环境与资源说明、预期输出、实际运行记录及已知限制。只在用户要求时生成独立文档，其余直接给代码和说明。没有执行环境时明确标注示例尚未实跑，不能伪造输出或把手工推导写成实测结果。

### 本条完成检查

- 示例具备完整导入、初始化、输入及调用，外部文件可取得且没有私有路径依赖。
- 给出关键预期结果、字段单位或形状，以及常见非法输入的解释，不只展示函数调用。
- 从干净环境核对关键示例的独立运行，说明随机及硬件差异；没有运行记录不写实测通过。

按本条要求组织结果，使用简洁中文和一致的编号、术语、缩进及空行；已有项目格式优先。只说明实际完成的内容，将采用的假设、未完成项和缺少的条件写在相关位置，不额外生成无关文档。未执行、无法复现或缺少证据的检查如实标注，不宣称已通过或已有性能收益。

## 参考资料与适用边界

官方来源（2026-09-08 核验）：
- [百度飞桨《Python 文档示例代码书写规范》](https://www.paddlepaddle.org.cn/documentation/docs/zh/dev_guides/style_guide_and_references/code_example_writing_specification_cn.html)