1. 快速开始

1 LLM模型快速转换¶

IPU_Toolchain的转换指令建议都在Docker环境下执行，详情请参考LLM环境搭建。

⚠️ 使用本工具前，请确保您的系统满足以下条件：

Python 环境：Python 3.11 或更高版本（务必确保使用 docker v1.11.1 及以上的 SDK 环境）
版本兼容：必须基于 transformers==4.57.3
IPU 工具链：已安装并配置对应版本的 IPU SDK 或驱动
运行环境：可访问 IPU 硬件设备或 IPU 模拟运行环境
存储空间：具备充足的磁盘空间，用于存放模型文件及转换中间数据

转换工具版本要求
核心依赖：transformers 4.57.3

验证方法：

import transformers
print(transformers.__version__)

须知

❌ 禁止使用其他 transformer 版本的模型

❌ 禁止混用不同版本的 transformers 库

查看IPU Toolchain具体适配的CHIP及版本信息可以执行

python3 SGS_IPU_Toolchain/DumpDebug/show_sdk_info.py

下载HuggingFace预训练模型

https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-AWQ

1.1 模型转换与运行¶

1.1.1 原生AWQ模型转换¶

运行如下命令转换

python3 SGS_IPU_Toolchain/Scripts/LLM_Converter/convert_hf_to_sim.py \
-d Qwen2.5-1.5B-Instruct-AWQ \
--soc_version CHIP

输出结果：在输入目录下自动创建 output_models 子目录，保存生成的IPU优化模型文件及模型转换所需的配置文件。

转换完成后，输出目录包含：

output_models/
├── model_sim.img           # 可在板端部署的IPU格式模型文件
├── *.ini,*.json,*.npy      # 输入配置
└── tokenize_template.py    # 分词器模板

更详细的输出文件内容说明请参考<模型转换>章节。

1.1.2 SGS量化模型转换¶

除原生AWQ模型外，IPU Toolchain也支持使用SGS量化库量化后的模型进行转换。以下以 Qwen3-0.6B 为例。

构造量化校准数据

量化过程需要准备校准数据集，格式为 JSON 数组，每个元素包含一个 prompt 字段。建议提供 10-20 条涵盖不同主题的高质量文本，数据越多样，量化精度越高。

⚠️ 由于量化算法要求，每条 prompt 的句子长度应尽可能长，建议每条 100 字以上。过短的文本会导致量化统计信息不足，影响模型精度。

示例 inputs_text.json：

[
    {"prompt": "在当前人工智能迅猛发展的背景下，大型语言模型如Qwen2.5在推理能力、多语言支持和上下文理解方面取得了显著进步，但其在处理模糊指代、常识推理和实时信息更新时仍存在局限性，请问如何通过结合符号逻辑与神经网络架构来提升模型的可解释性与事实一致性？"},
    {"prompt": "面对全球气候变暖加剧、极端天气频发的严峻现实，各国政府虽已签署《巴黎协定》并承诺碳中和目标，但在实际执行中仍面临经济增长依赖化石能源、绿色技术成本高昂及国际合作信任缺失等多重障碍，请问应如何构建一个兼顾公平性、可行性和强制力的全球气候治理新机制？"},
    {"prompt": "随着基因编辑技术如CRISPR-Cas9日趋成熟，人类已具备修改胚胎基因以预防遗传病的能力，但这同时也打开了定制婴儿和基因增强的伦理潘多拉魔盒，请问在尊重科学探索自由与防范优生学滥用之间，国际社会应建立怎样的伦理审查框架与法律边界？"},
    {"prompt": "在社交媒体高度渗透的现代社会，青少年群体普遍面临信息过载、外貌焦虑和社交比较压力，抑郁症与焦虑症发病率持续攀升，而心理服务资源却严重不足且存在污名化问题，请问如何通过学校、家庭与数字平台协同构建早期干预与支持生态系统？"},
    {"prompt": "近年来逆全球化思潮抬头，贸易保护主义、供应链本地化和地缘政治冲突导致全球价值链重构，跨国企业面临合规成本上升与市场分割风险，请问未来十年全球经济体系将走向区域化集团竞争还是新型多边合作？中小企业又该如何适应这一结构性转变？"}
]

执行模型转换

python3 ../Tool/Scripts/LLM_Converter/convert_hf_to_sim.py \
    -d /SSARTIFACTS/SYNC_IPU/SGS_LLM_Models/Qwen/Qwen3-0.6B/ \
    -o /path/to/output_model/ \
    --inputs inputs_text.json \
    --soc_version CHIP

参数	说明
`-d`	输入模型目录，指向 SGS 量化后的模型路径
`-o`	输出目录，保存转换后的 IPU 模型文件
`--inputs`	量化校准数据 JSON 文件，格式为 `[{"prompt": "文本"}, ...]`
`--soc_version`	目标芯片型号

转换完成后，输出目录结构与 1.1.1 节一致，包含 model_sim.img 及配套配置文件。

1.1.3 PC端仿真运行离线模型¶

python3 run_llm.py \
-d Qwen2.5-1.5B-Instruct-AWQ/output_models \
--prompt "Give me a short introduction to large language model." \
--soc_version CHIP

1.1.4 开发板运行离线模型¶

Linux SDK-alkaid已提供sdk/verify/release_feature/source/dla/ipu_server的app。

编译板端ipu_server示例。

cd sdk/verify/release_feature
make clean && make source/dla/ipu_server -j8

最终生成的可执行文件地址

sdk/verify/release_feature/out/${AARCH}/app/prog_dla_ipu_server

板端运行ipu_server开启RPC服务（PORT为设定的port号）

./prog_dla_ipu_server -p PORT

板端已运行prog_dla_ipu_server app 开启了RPC服务，PC端使用run_llm.py运行AI离线模型。

python3 run_llm.py \
-d Qwen2.5-1.5B-Instruct-AWQ/output_models \
--prompt "Give me a short introduction to large language model." \
--soc_version CHIP \
--host 板端ip地址 \
--port PORT \
--model_onboard_dir /path/to/model/on/borad/

1.2 级联模型转换与运行¶

1.2.1 模型转换¶

级联模型转换命令与非级联模型基本一致，只需额外增加 --num_soc 2 参数，表示使用两块 SOC 芯片级联推理。目前仅支持两块 SOC 芯片级联。

以 Qwen2.5-1.5B-Instruct-AWQ 为例：

python3 SGS_IPU_Toolchain/Scripts/LLM_Converter/convert_hf_to_sim.py \
    -d Qwen2.5-1.5B-Instruct-AWQ \
    --num_soc 2 \
    --soc_version CHIP

参数	说明
`-d`	输入模型目录
`--num_soc`	SOC 芯片数量，级联模式须设为 2
`--soc_version`	目标芯片型号

输出结果与非级联模型一致，在输入目录下生成 output_models/，包含 model_sim.img 及配套配置文件。

1.2.2 PC端仿真运行离线模型¶

级联模型的 PC 端仿真运行命令与非级联模型一致，无需额外参数：

python3 run_llm.py \
    -d Qwen2.5-1.5B-Instruct-AWQ/output_models \
    --prompt "Give me a short introduction to large language model." \
    --soc_version CHIP

1.2.3 开发板运行离线模型¶

级联模式使用两块 SOC 芯片协同推理，一块作为 rc 端，另一块作为 ep 端。两块板端需分别运行对应的服务程序。

1. 编译板端程序

Linux SDK-alkaid 已提供所需源码，分别编译 ipu_server（rc 端）和 cascade_service（ep 端）：

cd sdk/verify/release_feature

# 编译 rc 端 — ipu_server
make clean && make source/dla/ipu_server -j8

# 编译 ep 端 — cascade_service
make clean && make source/ipu/cascade_service -j8

编译产物路径：

sdk/verify/release_feature/out/${AARCH}/app/prog_dla_ipu_server（rc 端）
sdk/verify/release_feature/out/${AARCH}/app/prog_ipu_cascade_service（ep 端）

2. 启动板端服务

先在 ep 端启动 cascade_service，再在 rc 端启动 ipu_server：

# ep 端：启动级联服务（直接运行，无需额外参数）
./prog_ipu_cascade_service

# rc 端：启动 ipu_server 并指定 RPC 端口号
./prog_dla_ipu_server -p PORT

两块板端服务均已启动后，PC 端通过 rc 端的 ipu_server 与级联系统通信。

3. PC 端运行推理

python3 run_llm.py \
    -d Qwen2.5-1.5B-Instruct-AWQ/output_models \
    --prompt "Give me a short introduction to large language model." \
    --soc_version CHIP \
    --host <rc端IP地址> \
    --port PORT \
    --model_onboard_dir /path/to/model/on/board/