NOTES

模块 001：模型资产与 tokenizer

这个模块把本地 Ollama 使用的 GGUF blob 拆成可被 Python、HLS fixture 和 A53 C 程序读取的文件。它不改写模型数值：量化 tensor 保持 GGUF 的原始字节格式。

Qwen2.5/modules/001_model_assets_and_tokenizer.md 2026-07-13 约 4 分钟阅读

职责

这个模块把本地 Ollama 使用的 GGUF blob 拆成可被 Python、HLS fixture 和 A53 C 程序读取的文件。它不改写模型数值：量化 tensor 保持 GGUF 的原始字节格式。

输入和输出

阶段	输入	输出	入口
GGUF 检查	Ollama manifest、blob	模型/metadata/tensor 目录 JSON	`inspect_ollama_gguf.py`
tokenizer 导出	GGUF `tokenizer.*` metadata	`tokens.jsonl`、`merges.txt`、`token_types.bin`、`chat_template.txt`	`export_gguf_tokenizer_assets.py`
tensor 导出	tensor 目录、GGUF blob	`tensors/*.bin`、`tensor_payload_export_manifest.json`	`export_gguf_tensor_payloads.py`
PS bundle	词表、merge	`token_index.bin`、`token_bytes.bin`、`merge_table_u32.bin`	`prepare_ps_tokenizer_bundle.py`
runtime image	bundle、编码索引	`Q25TOKRT` 二进制与 manifest	`pack_ps_tokenizer_runtime_image.py`

tokenizer 数据布局

prepare_ps_tokenizer_bundle.py 把文本资产转换成三类二进制记录。

文件	单位记录	含义
`token_index.bin`	`{uint32 byte_offset; uint16 byte_length; uint16 token_type;}`，小端	token id 到 token bytes 的索引。
`token_bytes.bin`	连续字节	所有 token 的 ByteLevel 解码后字节。
`merge_table_u32.bin`	`{uint32 left_id; uint32 right_id; uint32 out_id; uint32 rank;}`，小端	BPE 合并对与优先级。

Q25TOKRT 是上述表及编码索引的单个内存映像。q25_nl_tokenizer_runtime_image_open() 读取其中的六个 section：token index、token bytes、merge table、byte-token map、merge-pair index 和 special-token index。

C 接口

函数	输入	输出	功能
`q25_nl_tokenizer_runtime_image_open`	image 地址、image 大小	bundle view、encode view、image info	检查 image 布局并暴露各 section 的只读视图。
`q25_nl_tokenizer_bundle_encode_bpe_bounded`	UTF-8 bytes、scratch、输出容量	token ids、统计	在给定上限内执行 BPE 编码。
`q25_nl_tokenizer_bundle_detokenize`	token ids、flags、输出缓冲区	UTF-8 bytes	将 token 序列拼回字节文本。
`q25_tokenize_utf8_bytes`	C 字符串	byte token ids	无 runtime image 时的逐字节 fallback。
`q25_detokenize_utf8_bytes`	byte token ids	C 字符串	fallback token 序列转回文本。

与下游的接口

flowchart LR
    A[GGUF tokenizer metadata] --> B[导出文本资产]
    B --> C[PS bundle]
    C --> D[Q25TOKRT image]
    D --> E[q25_nl_tokenizer_runtime_image_open]
    E --> F[TEXT_PROMPT 编码]
    E --> G[TEXT_GENERATE 解码]
    A --> H[Host tokenizer parity]

流程或关系图。