NOTES

项目总览

项目把语言模型从本地 GGUF 文件拆成可验证的工程链路，并以 ZCU106 为目标板。链路包含：

Qwen2.5/01_Project_Overview_CN.md 2026-07-13 约 3 分钟阅读

项目目标

项目把语言模型从本地 GGUF 文件拆成可验证的工程链路，并以 ZCU106 为目标板。链路包含：

GGUF 模型和 tokenizer
  -> host 解析、量化计算和 golden
  -> HLS 独立算子和 fixture
  -> PS/A53 tokenizer、UART 命令应用
  -> ZCU106 构建、启动、串口采集和归档

项目同时维护两个模型对象。

工作线	模型	覆盖范围
M0	SmolLM2-135M	host 端 token 化 smoke
M1	SmolLM2-135M-Instruct	完整模型 token-to-token 的工程主线
M2	tokenizer 运行时	PS bare-metal BPE 编解码与 UART 文本 I/O
M3	Qwen2.5-0.5B-Instruct	中文和英文 token-to-token 主目标

SmolLM2 用作较小的先行对象；Qwen2.5 是目标模型。两条线使用同一套资产导出、HLS fixture、PS/UART 和板级脚本方法，但模型权重、tokenizer 和结果文件彼此独立。

顶层目录的用途

目录	内容	对外输入	对外输出
`models/`	GGUF 检查结果、tokenizer 资产、量化 tensor、fixture、golden	Ollama/GGUF blob、脚本参数	JSON、BIN、文本表、runtime image
`scripts/`	资产导出、host 计算、golden、HLS gate 的 Python 入口	模型 manifest、GGUF、fixture	结果 JSON、fixture、运行日志
`ZCU106/hls/`	可综合的 C/C++ kernel、testbench、HLS 配置	fixture 二进制、kernel 参数	CSim/cosim/csynth 结果、RTL/IP
`ZCU106/ps_app/`	A53 bare-metal UART 应用和 tokenizer C 库	UART 文本、可选 tokenizer runtime image	UART 响应、ELF
`ZCU106/scripts/`	XSA/ELF/SD 准备、串口采集、transcript 验证和归档	构建产物、串口、板卡端口	board 报告目录、manifest、archive
`project_management/`	任务、状态、接口合约和机器可读 manifest	脚本和人工流程	工作项与运行记录
`docs/`	设计约束、复用映射和集成接口定义	项目代码	项目内技术说明

实际运行边界

以下内容属于当前可直接调用的软件模块：GGUF tokenizer 导出、原始 tensor 导出、host 端量化计算脚本、多个 HLS C++ kernel、PS UART 命令解析器、Q25TOKRT tokenizer image 的打开/编码/解码、UART transcript 验证器。

当前 PS UART 应用可处理 token-id 和文本命令。TEXT_PROMPT 在 runtime image 已打开时调用受限 BPE 编码器；TEXT_GENERATE 只把固定后缀 " ok" 拼接到已有文本；NL_GENERATE 生成由最后一个输入 token 推导的递增 token。它们不是模型推理调用。

MODEL_LOAD、TOKEN_STEP、TEXT_STEP 由 q25_p4_runtime_cmd_stub.c 处理。它们保留未来运行时的命令外形，当前返回 status=stub 或 source=ps_hls_runtime_cmd_stub。