模块接口参考
本页只列出当前仓库的公开调用面。`样板` 标记表示命令已实现解析和返回格式，但不执行模型推理。
本页只列出当前仓库的公开调用面。样板 标记表示命令已实现解析和返回格式，但不执行模型推理。
1. Python 命令行接口
| 入口 | 必填参数 | 产物 | 功能 |
|---|---|---|---|
scripts/export_gguf_tokenizer_assets.py | --manifest、--out-dir | tokenizer 导出目录 | 从 GGUF metadata 写出词表、merge、token type、chat template 和 manifest。可重复传入 --smoke。 |
scripts/export_gguf_tensor_payloads.py | --inspect-json、--out-dir | tensor BIN 与 manifest | 按 inspect JSON 中的偏移复制每个 tensor 的原始 payload。 |
scripts/prepare_ps_tokenizer_bundle.py | --tokenizer-dir、--out-dir | PS bundle | 写入 token index/bytes 和 merge table。 |
scripts/pack_ps_tokenizer_runtime_image.py | 可选 --out-root、--model-key | Q25TOKRT image | 从默认或指定模型资产目录读取 bundle/index，封装成 6-section image。 |
scripts/run_qwen25_full_quant_token_step_logits_golden.py | 可选 --export-manifest、--tokenizer-dir、--smoke-en、--smoke-zh、--layer0-attention-reference、--layer0-mlp-reference、--out、--max-layers、--top-k、--force | Qwen logits golden | 运行 Qwen2.5 量化 forward。 |
scripts/run_smollm2_full_quant_logits_golden.py | 可选 --export-manifest、--smoke-report、--tokenizer-dir、--out、--max-layers、--top-k 与 layer 诊断开关 | SmolLM2 logits golden | 运行 SmolLM2 量化 forward。 |
ZCU106/scripts/validate_nl_uart_transcript.py | transcript、--mode | 可选 validation JSON | 检查 token/text/both 模式必需的协议标记。 |
ZCU106/scripts/run_q25_nl_board_acceptance.ps1 | report/bundle/SD/transcript 参数 | acceptance manifest 和归档 | 运行 preflight、可选串口采集、归档与 archive 验证。 |
2. UART 文本协议
协议文件：ZCU106/protocol/NL_UART_PROTOCOL.md。每条命令是一行 ASCII 命令头；TEXT_* 后面是 UTF-8 文本。
| 命令 | 参数 | 应用的处理模块 | 主要响应 |
|---|---|---|---|
HELP | 无 | print_help | NL_HELP 与可用命令列表。 |
INFO | 无 | handle_info | 板型、模型名、tokenizer profile、runtime image 状态。 |
LOAD_MODEL | <smollm2_135m|qwen2p5_0p5b> | handle_load_model | 记录字符串模型选择，返回 NL_MODEL_LOADED。 |
NL_PROMPT_IDS | 空格分隔 token ids | handle_prompt_ids | 保存最多 128 个 token，返回数量。 |
NL_GENERATE | 最大 token 数 | handle_generate | 返回最多 16 个演示 token 与 NL_RESULT_IDS。 |
TEXT_PROMPT | UTF-8 文本 | handle_text_prompt | BPE 或 byte fallback 编码，返回 TEXT_PROMPT_IDS。 |
TEXT_GENERATE | 最大 token 数 | handle_text_generate | 拼接最多 16 个固定后缀 token 并返回 TEXT_RESULT。 |
STATUS | 无 | dispatch | 模型名、tokenizer、文本 token 数和 image 状态。 |
PING | 无 | dispatch | PONG。 |
MODEL_LOAD | model=... 或模型名 | P4 样板 | 返回 MODEL_LOAD_RESULT status=loaded ... tokenizer=stub tensors=stub。 |
TOKEN_STEP | token_id、position、context | P4 样板 | 返回输入 token 加一的 TOKEN_STEP_RESULT status=stub。 |
TEXT_STEP | UTF-8 文本或 utf8_hex= | P4 样板 | 返回 TEXT_STEP_RESULT status=stub ... text=ok。 |
3. PS tokenizer C API
头文件：ZCU106/ps_app/nl_uart_app/src/q25_nl_tokenizer_bundle.h。
| API | 参数 | 返回/写入 | 用途 |
|---|---|---|---|
q25_nl_tokenizer_bundle_vocab_size(view) | bundle view | size_t | 返回词表条目数。 |
q25_nl_tokenizer_bundle_merge_count(view) | bundle view | size_t | 返回 merge 记录数。 |
q25_nl_tokenizer_bundle_get_token(view,id,out) | bundle、token id | q25_nl_token_span | 查询 token 的 bytes 偏移、长度和类型。 |
q25_nl_tokenizer_bundle_get_merge(view,index,out) | bundle、merge 下标 | q25_nl_merge_record | 查询左右 token、合并 token 和 rank。 |
q25_nl_tokenizer_bundle_inspect(view,out) | bundle | q25_nl_tokenizer_bundle_stats | 汇总词表/merge 统计。 |
q25_nl_tokenizer_bundle_detokenize(view,ids,count,flags,out,cap,need) | token ids | UTF-8 bytes | 支持跳过特殊 token、追加 NUL。 |
q25_nl_tokenizer_bundle_encode_bpe_bounded(view,input,...,out,...) | UTF-8 bytes、scratch、容量 | token ids、encode stats | 执行有界 BPE 编码。 |
q25_nl_tokenizer_runtime_image_open(image,size,bundle,encode,info) | Q25TOKRT 内存地址 | 三个只读 view | 打开 image 并验证 section 边界。 |
返回码：0 表示成功；-1 空指针；-2 布局；-3 越界；-4 token id；-5 merge。
4. HLS kernel 接口
所有列出的 kernel 使用 AXI4 m_axi 访问输入/输出数组，使用 AXI4-Lite s_axilite 传递标量控制参数和启动/完成控制。数组由调用者放入 DDR；kernel 不读取 UART，也不解析 GGUF 文件。
| Kernel | DDR 输入 | AXI-Lite 参数 | DDR 输出 | 功能 |
|---|---|---|---|---|
layer0_q6k_down_projection | Q6_K rows、4864 维 F32 input | row_count、row_bytes | 最多 4 个 F32 dot | 对 Qwen layer0 ffn_down 的选定行做 Q6_K 解码和 dot。 |
smollm2_attention_core | masked score 矩阵、V 矩阵 | seq_len | probabilities、attention output、checksum | 在最多 8 个 token、64 维 head 上做 softmax 和 value mix。 |
smollm2_qkv_rope_projection | hidden、RMSNorm weight、Q/K/V rows | position、qtype、row bytes、epsilon、RoPE base | Q/K RoPE、V | RMSNorm 后解码 Q5_0/Q5_1 投影，再给 Q/K 应用 RoPE。 |
smollm2_mlp_full_layer | residual、norm、gate/up/down rows | output rows、qtype、row bytes、epsilon | residual output | RMSNorm，Q5_0 gate/up，SiLU 逐元素相乘，Q5_K down，再加 residual。 |
smollm2_lm_head_streaming_topk | hidden、Q8_0 lm_head rows | row limit、row bytes、tile rows、K | token id、row index、score | 分块扫描词表，保留最多 5 个最高分。 |
q25rt_i8_matvec_tile | int8 weights、int8 activation | tile rows、input dim、strides | int32 dot tile | 最多 16 行、4096 维的 int8 矩阵向量乘。 |
q25rt_i8_lm_head_paged | int8 page weights、activation、page base token | page count、weight/output stride | 每行 dot、top-4 token/dot、status | 每页 16 行，扫描最多 16 页。 |
smollm2_quant_matvec_common_h0_rowblock | weight/activation buffers | qtype、shape、tile 描述 | zeroed partial output、状态 | 共用 row-block ABI 的接口/fixture 模块；当前不消费输入数据。 |
5. P4 runtime 样板 C API
头文件：q25_p4_runtime_cmd_stub.h。
| API | 输入 | 输出 | 作用 |
|---|---|---|---|
q25_p4_runtime_stub_init(state) | state 指针 | 清零 state | 初始化 model_loaded、token/text step 计数。 |
q25_p4_runtime_command_is_legacy(line) | UART 行 | 0/1 | 判断现有协议命令，避免由 P4 接管。 |
q25_p4_runtime_dispatch(state,line,response,cap) | UART 行 | 格式化响应、handled 状态 | 分发 MODEL_LOAD、TOKEN_STEP、TEXT_STEP。 |