Pix2Struct-base NPU 适配与性能调优

模型信息

模型名称: google/pix2struct-base
模型类型: 图文理解 (Vision-Language)
硬件平台: 华为昇腾 800I A2 (Ascend 910B4)
适配状态: 已完成 NPU 推理适配与性能调优

一、性能调优计划

1.1 目标

NPU 推理跑通
与 GPU/CPU 误差 < 1%
达到指定性能基线
AtomGit 一键上传 + SKILL.md 提交

1.2 调优步骤

阶段	内容
Phase 1	基础适配与 Baseline 建立：下载模型、编写推理脚本、运行 baseline 性能测试
Phase 2	性能优化：亲和算子替换（npu_rms_norm）、运行时流水优化（TASK_QUEUE_ENABLE=2）、内存布局优化
Phase 3	精度与性能验证：同输入同精度对比 baseline vs optimized，确认误差 < 1% 且性能提升
Phase 4	交付件生成：完善推理脚本、部署文档、评测材料、Agent Skill
Phase 5	上传与提交：AtomGit 模型卡片上传、model-agent PR 提交

二、环境要求

CANN Toolkit >= 8.5.1
torch >= 2.9.0
torch_npu >= 2.9.0.post1
transformers >= 4.57.6
Python >= 3.9

三、快速开始

3.1 环境准备

# 确认 NPU 可用
npu-smi info

# 安装依赖
pip install torch torch_npu transformers pillow numpy

3.2 模型下载

export HF_ENDPOINT=https://hf-mirror.com
python3 -c "
from transformers import Pix2StructForConditionalGeneration, Pix2StructProcessor
processor = Pix2StructProcessor.from_pretrained('google/pix2struct-base')
model = Pix2StructForConditionalGeneration.from_pretrained('google/pix2struct-base')
"

3.3 推理运行

python3 inference_optimized.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --input image.png \
  --question "What does the image describe?"

3.4 性能评测

# Baseline (无优化)
python3 inference.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --benchmark \
  --iterations 5 \
  --warmup 2

# 优化版本
export TASK_QUEUE_ENABLE=2
python3 inference_optimized.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --benchmark \
  --iterations 5 \
  --warmup 2

3.5 精度验证

python3 accuracy_run.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --device-compare cpu \
  --input image.png

# 优化后精度验证
export TASK_QUEUE_ENABLE=2
python3 accuracy_run_perf.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --device-compare cpu \
  --input image.png

四、性能数据（核心交付件）

测试环境: Ascend 910B4, CANN 8.5.1, torch_npu 2.9.0.post1, transformers 4.57.6

4.1 优化前性能数据（Baseline）

指标	数值
Avg Latency	3876.93 ms
Throughput	0.26 iters/s
测试迭代数	5
Warmup	2

4.2 优化后性能数据（Optimized）

指标	数值
Avg Latency	2657.25 ms
Throughput	0.38 iters/s
测试迭代数	5
Warmup	2

4.3 性能提升汇总

指标	Baseline (未优化)	优化后	提升幅度
Avg Latency	3876.93 ms	2657.25 ms	31.5%
Throughput	0.26 iters/s	0.38 iters/s	46.2%

五、精度验证

对比项	相对误差	结果
NPU vs CPU (baseline)	0.000051%	通过
NPU vs CPU (优化后)	0.000051%	通过

结论: 优化前后 NPU 与 CPU 输出相对误差均远小于 1%，满足精度要求。

六、优化手段详解

6.1 亲和算子替换

将 Pix2StructLayerNorm（T5-style RMSNorm）替换为 torch_npu.npu_rms_norm 融合算子，减少 host 侧计算开销。

import torch_npu
from transformers.models.pix2struct.modeling_pix2struct import Pix2StructLayerNorm

_orig_forward = Pix2StructLayerNorm.forward

def _optimized_forward(self, hidden_states):
    if str(hidden_states.device).startswith("npu"):
        return torch_npu.npu_rms_norm(hidden_states, self.weight, epsilon=self.variance_epsilon)[0]
    return _orig_forward(self, hidden_states)

Pix2StructLayerNorm.forward = _optimized_forward

6.2 运行时流水优化

启用 TASK_QUEUE_ENABLE=2，将 host 侧任务下发与 NPU 执行流水线化，显著降低 host-bound 延迟。

export TASK_QUEUE_ENABLE=2

6.3 内存布局优化

确保 transpose/permute 后调用 contiguous()，避免非连续张量导致额外拷贝。

七、交付件清单

交付件	说明
`inference.py`	基础推理脚本（无优化，用于 baseline）
`inference_optimized.py`	优化后推理脚本（含 npu_rms_norm 替换）
`accuracy_run.py`	精度验证脚本（baseline）
`accuracy_run_perf.py`	精度验证脚本（优化后）
`readme.md`	部署文档与性能数据陈述
`SKILL.md`	Agent Skill 文档

八、提交记录

8.1 AtomGit 一键上传

模型卡片仓库: weixin_62994174/pix2struct-base-ascend
标签: #model-agent-tagged #transformers #pytorch #safetensors #pix2struct #image-text-to-text #image-to-text #npu #ascend #800I-A2

8.2 Agent Skill 提交

PR 地址: Ascend/model-agent !98
提交内容: skills/optimization/pix2struct-ascend-optimization/SKILL.md
状态: 已提交，等待合并

Pix2Struct-base NPU 适配与性能调优

模型信息

模型名称: google/pix2struct-base
模型类型: 图文理解 (Vision-Language)
硬件平台: 华为昇腾 800I A2 (Ascend 910B4)
适配状态: 已完成 NPU 推理适配与性能调优

一、性能调优计划

1.1 目标

NPU 推理跑通
与 GPU/CPU 误差 < 1%
达到指定性能基线
AtomGit 一键上传 + SKILL.md 提交

1.2 调优步骤

阶段	内容
Phase 1	基础适配与 Baseline 建立：下载模型、编写推理脚本、运行 baseline 性能测试
Phase 2	性能优化：亲和算子替换（npu_rms_norm）、运行时流水优化（TASK_QUEUE_ENABLE=2）、内存布局优化
Phase 3	精度与性能验证：同输入同精度对比 baseline vs optimized，确认误差 < 1% 且性能提升
Phase 4	交付件生成：完善推理脚本、部署文档、评测材料、Agent Skill
Phase 5	上传与提交：AtomGit 模型卡片上传、model-agent PR 提交

二、环境要求

CANN Toolkit >= 8.5.1
torch >= 2.9.0
torch_npu >= 2.9.0.post1
transformers >= 4.57.6
Python >= 3.9

三、快速开始

3.1 环境准备

# 确认 NPU 可用
npu-smi info

# 安装依赖
pip install torch torch_npu transformers pillow numpy

3.2 模型下载

export HF_ENDPOINT=https://hf-mirror.com
python3 -c "
from transformers import Pix2StructForConditionalGeneration, Pix2StructProcessor
processor = Pix2StructProcessor.from_pretrained('google/pix2struct-base')
model = Pix2StructForConditionalGeneration.from_pretrained('google/pix2struct-base')
"

3.3 推理运行

python3 inference_optimized.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --input image.png \
  --question "What does the image describe?"

3.4 性能评测

# Baseline (无优化)
python3 inference.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --benchmark \
  --iterations 5 \
  --warmup 2

# 优化版本
export TASK_QUEUE_ENABLE=2
python3 inference_optimized.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --benchmark \
  --iterations 5 \
  --warmup 2

3.5 精度验证

python3 accuracy_run.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --device-compare cpu \
  --input image.png

# 优化后精度验证
export TASK_QUEUE_ENABLE=2
python3 accuracy_run_perf.py \
  --model-path /path/to/pix2struct-base \
  --device npu \
  --device-compare cpu \
  --input image.png

四、性能数据（核心交付件）

测试环境: Ascend 910B4, CANN 8.5.1, torch_npu 2.9.0.post1, transformers 4.57.6

4.1 优化前性能数据（Baseline）

指标	数值
Avg Latency	3876.93 ms
Throughput	0.26 iters/s
测试迭代数	5
Warmup	2

4.2 优化后性能数据（Optimized）

指标	数值
Avg Latency	2657.25 ms
Throughput	0.38 iters/s
测试迭代数	5
Warmup	2

4.3 性能提升汇总

指标	Baseline (未优化)	优化后	提升幅度
Avg Latency	3876.93 ms	2657.25 ms	31.5%
Throughput	0.26 iters/s	0.38 iters/s	46.2%

五、精度验证

对比项	相对误差	结果
NPU vs CPU (baseline)	0.000051%	通过
NPU vs CPU (优化后)	0.000051%	通过

结论: 优化前后 NPU 与 CPU 输出相对误差均远小于 1%，满足精度要求。

六、优化手段详解

6.1 亲和算子替换

将 Pix2StructLayerNorm（T5-style RMSNorm）替换为 torch_npu.npu_rms_norm 融合算子，减少 host 侧计算开销。

import torch_npu
from transformers.models.pix2struct.modeling_pix2struct import Pix2StructLayerNorm

_orig_forward = Pix2StructLayerNorm.forward

def _optimized_forward(self, hidden_states):
    if str(hidden_states.device).startswith("npu"):
        return torch_npu.npu_rms_norm(hidden_states, self.weight, epsilon=self.variance_epsilon)[0]
    return _orig_forward(self, hidden_states)

Pix2StructLayerNorm.forward = _optimized_forward

6.2 运行时流水优化

启用 TASK_QUEUE_ENABLE=2，将 host 侧任务下发与 NPU 执行流水线化，显著降低 host-bound 延迟。

export TASK_QUEUE_ENABLE=2

6.3 内存布局优化

确保 transpose/permute 后调用 contiguous()，避免非连续张量导致额外拷贝。

七、交付件清单

交付件	说明
`inference.py`	基础推理脚本（无优化，用于 baseline）
`inference_optimized.py`	优化后推理脚本（含 npu_rms_norm 替换）
`accuracy_run.py`	精度验证脚本（baseline）
`accuracy_run_perf.py`	精度验证脚本（优化后）
`readme.md`	部署文档与性能数据陈述
`SKILL.md`	Agent Skill 文档

八、提交记录

8.1 AtomGit 一键上传

模型卡片仓库: weixin_62994174/pix2struct-base-ascend
标签: #model-agent-tagged #transformers #pytorch #safetensors #pix2struct #image-text-to-text #image-to-text #npu #ascend #800I-A2

8.2 Agent Skill 提交

PR 地址: Ascend/model-agent !98
提交内容: skills/optimization/pix2struct-ascend-optimization/SKILL.md
状态: 已提交，等待合并

Pix2Struct-base NPU 适配与性能调优

模型信息

一、性能调优计划

1.1 目标

1.2 调优步骤

二、环境要求

三、快速开始

3.1 环境准备

3.2 模型下载

3.3 推理运行

3.4 性能评测

3.5 精度验证

四、性能数据（核心交付件）

4.1 优化前性能数据（Baseline）

4.2 优化后性能数据（Optimized）

4.3 性能提升汇总

五、精度验证

六、优化手段详解

6.1 亲和算子替换

6.2 运行时流水优化

6.3 内存布局优化

七、交付件清单

八、提交记录

8.1 AtomGit 一键上传

8.2 Agent Skill 提交

标签

Pix2Struct-base NPU 适配与性能调优

模型信息

一、性能调优计划

1.1 目标

1.2 调优步骤

二、环境要求

三、快速开始

3.1 环境准备

3.2 模型下载

3.3 推理运行

3.4 性能评测

3.5 精度验证

四、性能数据（核心交付件）

4.1 优化前性能数据（Baseline）

4.2 优化后性能数据（Optimized）

4.3 性能提升汇总

五、精度验证

六、优化手段详解

6.1 亲和算子替换

6.2 运行时流水优化

6.3 内存布局优化

七、交付件清单

八、提交记录

8.1 AtomGit 一键上传

8.2 Agent Skill 提交

标签