Thinker 离线翻译示例

功能说明

本示例在 ARCS AP Core 上运行 Thinker Transformer Encoder/Decoder，将固定的英文 句子离线翻译为中文。示例复用一块 PSRAM 模型缓冲区依次运行 Encoder 和 Decoder，并从外部 Flash 直接查询紧凑词表，不依赖网络或 Host 侧 Python 环境。

硬件连接

无需外部连接，Thinker、Luna、PSRAM 和外部 NOR Flash 均为开发板资源。示例支持 arcs_evb 和 arcs_mini，两种板型都搭载带 16 MiB PSRAM 的 LS2684。

示例步骤

  1. 从词表资源查找英文单词 ID，生成不超过 32 个词元的 Encoder 输入。

  2. 从 Flash 加载 arcs_encoder.bin 到 PSRAM，运行 Encoder 并保存 int8 [1, en_len, 256] memory tensor。

  3. 释放 Encoder 后复用模型缓冲区，加载 arcs_decoder.bin。

  4. Decoder 使用贪婪搜索逐个生成中文词元，遇到 EOS 或达到 32 个词元时结束。

  5. Decoder 每步同时传入 int8 [1, 8, de_len, de_len] 因果掩码，防止注意力读取未来词元。

  6. 将中文词元拼接后输出到日志。

资源布局

应用和三个运行资源需要分别烧录：

资源

Flash 偏移

默认 XIP 地址

大小

lnn_thinker_translation.bin

0x000000

0x30000000

不超过 1 MiB

arcs_encoder.bin

0x100000

0x30100000

0x6CC060

arcs_decoder.bin

0x800000

0x30800000

0x650160

translation_vocab.bin

0xE80000

0x30E80000

0x3BE61

编译

重要提示：编译前需要先确认当前示例支持的目标板型，然后将板型标识传给 -DBOARD。请按以下方式选择：

  1. 确认示例限制：查看当前示例 README 中的硬件连接和注意事项，确认是否限定板型。

  2. 参考示例配置：查看相关示例目录下的 sample.yaml，确认支持的板型。

  3. 填写板型标识：SDK 内置板型的标识为 boards/ 下的目录名。例如实际使用的板型目录为 boards/<板型名称>/，则编译参数填写为 -DBOARD=<板型名称>。

在 SDK 根目录执行编译，并将命令中的 <示例路径> 和 <板型名称> 替换为实际值。

Linux 使用 build.sh：

# 通用命令
./build.sh -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

Windows PowerShell 使用 build.ps1：

# 通用命令
.\build.ps1 -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
.\build.ps1 -C -S samples/<示例路径> -DBOARD=arcs_evb

Note

确保已安装对应平台的工具链和 ListenAI 开发工具包。Windows 环境请先执行 .\env.ps1 或直接使用 .\build.ps1 自动加载环境。

注意事项：-DBOARD 填写的是板型标识，不是芯片系列名称。如果示例有板型专用配置或额外编译参数，以示例 README 中的说明为准。

烧录

先烧录应用，再烧录 Encoder、Decoder 和词表资源：

cskburn -C arcs -s /dev/ttyACM0 -b 3000000 \
  0x0 build/lnn_thinker_translation.bin \
  0x100000 build/arcs_encoder.bin \
  0x800000 build/arcs_decoder.bin \
  0xE80000 build/translation_vocab.bin

构建时 CMake 会把三个 resources/ 文件复制到构建目录。烧录完成后设备自动 复位；日志串口波特率为 921600。

预期输出

[I][thinker_translation] translation input: May the Force be with you.
[I][translation_vocab] vocabulary ready: source=15080 target=4362 size=245345
[I][offline_translation] encoder forward cost: ... ms
[I][offline_translation] decoder forward total cost: ... ms steps=9
[I][thinker_translation] translation result: 愿力量与你同在。

模型使用与 ARCS Thinker 3.0.10 LayerNorm 实现一致的 Q10 归一化尺度。 Encoder 和 Decoder 在打包前已通过 Linger ONNXRunner/Thinker 逐层一致性验证， 默认句子的 x86 Thinker 与实板都应输出上述翻译。

配置说明

待翻译英文句子由 src/main.c 中的 s_translation_sentence 设置。板端预处理与 训练工程保持一致，会先转为小写、删除最后一个字符再按空白分词，因此句子必须以 标点结尾，且加上 BOS/EOS 后不能超过 32 个词元。

模型地址、大小和运行内存池由以下配置控制：

CONFIG_THINKER_TRANSLATION_ENCODER_MODEL_ADDR=0x30100000
CONFIG_THINKER_TRANSLATION_ENCODER_MODEL_SIZE=0x6CC060
CONFIG_THINKER_TRANSLATION_DECODER_MODEL_ADDR=0x30800000
CONFIG_THINKER_TRANSLATION_DECODER_MODEL_SIZE=0x650160
CONFIG_THINKER_TRANSLATION_VOCAB_ADDR=0x30E80000
CONFIG_THINKER_TRANSLATION_VOCAB_SIZE=0x3BE61
CONFIG_THINKER_TRANSLATION_PSRAM_POOL_SIZE=0x20000
CONFIG_THINKER_TRANSLATION_SHARE_POOL_SIZE=0x60000

核心 API

API

说明

tGetMemoryPlan()

获取当前 Encoder 或 Decoder 的运行内存计划。

tModelInit()

从 PSRAM 中的 Thinker 模型资源创建模型。

tCreateExecutor()

创建当前模型执行器。

tSetInput()

设置词元 ID、Encoder memory tensor 或 Decoder 因果掩码，并写入实际输入维度。

tUpdateShape()

设置全部输入后，根据输入 Tensor 推导动态 Shape。

tForward()

执行一次 Encoder 或 Decoder 推理。

tGetOutput()

读取 Encoder memory tensor 或 Decoder 概率张量。

词表重新生成

如果训练侧 vocab.json 发生变化，使用脚本重新生成紧凑词表：

labs/lnn/thinker_translation/scripts/generate_vocab.py \
  /path/to/vocab.json \
  labs/lnn/thinker_translation/resources/translation_vocab.bin

生成后必须同步更新 CONFIG_THINKER_TRANSLATION_VOCAB_SIZE，并确保模型的英文、 中文词表大小仍分别为 15080 和 4362。

注意事项

  1. 资源必须配套：两个 Thinker 模型和词表来自同一次训练/转换结果，不能单独替换。

  2. Flash 容量：默认布局占用约 14.8 MiB，只适用于至少 16 MiB NOR Flash 的板卡。

  3. PSRAM 复用：Encoder 和 Decoder 不能同时驻留；修改代码时要保留先释放再加载的顺序。

  4. 量化输出：Decoder 输出为 int8 [1, de_len, 4362]，每步直接对量化分数取最大值。

  5. 词表校验：板端启动时会检查词表头、尺寸、词表项数量和 payload CRC32。