本文档介绍了 llama.cpp 中的模型转换系统，该系统将模型从各种格式（主要为 HuggingFace）转换为优化的 GGUF 格式以进行推理。转换过程处理模型架构、张量转换、词汇处理和元数据提取。
有关 GGUF 文件格式本身的信息，请参阅 GGUF 文件格式。有关转换期间量化细节，请参阅 模型量化。
模型转换系统围绕 convert_hf_to_gguf.py 脚本，该脚本提供了一个统一的接口，用于将 HuggingFace 和其他格式的模型转换为 GGUF。该系统通过基于注册的方法支持数十种模型架构，并处理张量名称映射、词汇转换和元数据保留的复杂过程。
模型转换流程
转换过程涉及几个关键阶段：模型检测和加载、带有名称映射的张量处理、词汇提取和转换，以及带有正确元数据的最终 GGUF 输出生成。
来源：convert_hf_to_gguf.py87-267 gguf-py/gguf/gguf_writer.py64-110
转换系统使用基于注册的方法来支持不同的模型架构。每种架构都实现为 ModelBase 的子类，并使用与 HuggingFace 模型配置匹配的特定名称进行注册。
架构注册和模型创建
ModelBase 类提供了基础，其 _model_classes 注册表存储架构映射。@register 装饰器将模型类与 HuggingFace 配置中的架构名称相关联。
来源：convert_hf_to_gguf.py54-464 convert_hf_to_gguf.py440-449
张量转换包括加载模型权重、将张量名称映射到 GGUF 约定、应用量化以及写入输出文件。该过程根据模型大小和来源，支持即时加载和延迟加载。
张量处理和名称映射
系统使用 TensorNameMap 将 HuggingFace 张量名称转换为 GGUF 约定。例如，model.layers.{bid}.self_attn.q_proj 转换为 blk.{bid}.attn_q。量化根据张量类型和用户指定的格式应用。
来源：convert_hf_to_gguf.py256-366 gguf-py/gguf/tensor_mapping.py8-449
词汇转换从 HuggingFace 模型中提取分词器信息，并将其转换为 GGUF 格式。这包括词汇列表、分数、特殊词汇和预分词器配置。
词汇处理管道
系统通过编码标准测试字符串并对结果进行哈希处理来提取词汇数据并确定预分词器类型。这确保了 llama.cpp 在推理过程中使用正确的分词方法。
来源：convert_hf_to_gguf.py597-640 convert_hf_to_gguf.py646-749
转换系统包括复杂的预分词器检测，以确保 HuggingFace 模型和 llama.cpp 之间的分词器兼容性。这包括编码测试字符串并将哈希值与已知的预分词器类型进行匹配。
预分词器哈希检测
get_vocab_base_pre() 函数维护一个哈希值查找表，该表对应于不同的预分词器实现。这确保了 llama.cpp 应用与原始模型相同的分词规则。
来源：convert_hf_to_gguf.py646-749 convert_hf_to_gguf_update.py77-173
转换过程保留并增强了模型元数据，包括架构参数、训练细节和模型来源信息。这些元数据对于正确的模型加载和推理配置至关重要。
元数据处理和 GGUF 参数设置
系统从 HuggingFace 配置中提取模型参数，并将其转换为 GGUF 元数据键。模型卡片和覆盖文件中的其他元数据（如作者和许可信息）也会被保留。
来源：convert_hf_to_gguf.py519-564 convert_hf_to_gguf.py370-398
转换脚本提供了一个全面的命令行界面，支持各种输入格式、输出选项和转换参数。它处理本地和远程模型加载，并具有进度跟踪和错误处理功能。
| 参数 | 描述 | 默认 |
|---|---|---|
--outdir | GGUF 文件的输出目录 | 当前目录 |
--outtype | 输出量化类型 | f16 |
--vocab-only | 仅转换词汇 | 否 |
--split-max-size | 每个 GGUF 文件的最大大小 | 不分割 |
--dry-run | 显示转换计划而不写入 | 否 |
--model-name | 覆盖元数据中的模型名称 | 来自配置 |
--use-temp-file | 对大张量使用临时文件 | 否 |
该脚本从配置中自动检测模型架构，并选择合适的转换类。它支持本地模型目录和带有身份验证的远程 HuggingFace 模型标识符。