NOTES

模块 002：Host 参考计算与 golden

Host 模块在 PC 上读取 GGUF 和其导出的原始 tensor，生成模型结构信息、量化解码结果、层级中间值和指定 prompt 的 logits/top-k。HLS fixture 与 PS 运行时需要用这些文件确定输入字节、尺寸和期望输出。

Qwen2.5/modules/002_host_reference_pipeline.md 2026-07-13 约 3 分钟阅读

职责

主要脚本组

脚本组	输入	输出	具体功能
`run_ollama_smoke.py`	本地 Ollama model、prompt	smoke JSON	记录模型可用性、prompt context ids 和生成文本。
`inspect_ollama_gguf.py`	manifest、GGUF	inspect JSON	提取 tensor 名称、维度、GGML type、相对/绝对偏移。
`inventory_gguf_quant_tensors.py`	inspect JSON	inventory JSON	按 Q8_0、Q5_0、Q5_1、Q5_K、Q4_K、Q6_K 分类 tensor。
`run_gguf_dequant_check.py`	原始 quant payload	检查 JSON	校验单个 GGML block 的反量化结果。
`run_qwen25_full_quant_token_step_logits_golden.py`	Qwen tensor、token ids	full quant logits JSON	运行 24 层 Qwen2.5 量化 forward，写出 logits 和 top1。
`run_smollm2_full_quant_logits_golden.py`	SmolLM2 tensor、token ids	logits JSON	运行 SmolLM2 完整量化 forward。
`prepare_*_hls_fixture.py`	tensor 子集、host JSON	fixture BIN/头文件/manifest	生成 kernel 的最小输入与期望值。

数据接口

数据对象	格式	下游消费者
GGUF inspect	JSON：tensor 名、维度、类型、偏移	tensor 导出、量化 inventory、host compute
raw tensor payload	BIN：原始 GGML quant block	反量化、HLS fixture、HLS kernel
prompt context ids	JSON 数组	tokenizer parity、host forward
golden	JSON，内含输入描述、数值、hash、容差	HLS testbench、回归脚本
HLS fixture	BIN、C header、manifest	CSim/cosim kernel

量化格式的处理范围

项目使用 GGML 的块量化布局。常用的布局为：Q8_0 每 32 个元素 34 字节，Q5_0 每 32 个元素 22 字节，Q5_1 每 32 个元素 24 字节，Q4_K/Q5_K/Q6_K 每 256 个元素分别为 144/176/210 字节。脚本和 HLS kernel 依据 tensor 的 GGML type 选择对应解码。

结果流

flowchart LR
    A[GGUF inspect JSON] --> B[raw payload]
    B --> C[量化 block 解码]
    C --> D[投影 / attention / MLP / lm_head]
    D --> E[golden JSON]
    E --> F[HLS fixture]
    E --> G[host 回归]

流程或关系图。