模型下载与转换

更新: 2026/9/2 字数: 0 字时长: 0 分钟

在使用 $ai 模块之前，您需要获取一个 GGUF 格式的模型文件。获取方式主要有两种：

直接下载：从 Hugging Face 或 ModelScope 等平台下载已转换好的 GGUF 模型（最简便）。
自行转换：如果您有原始模型（PyTorch .bin/.pt 或 SafeTensors .safetensors），可使用 llama.cpp 提供的工具进行转换。

什么是 GGUF？

GGUF（GPT-Generated Unified Format）是一种专为 llama.cpp 设计的二进制文件格式，用于高效存储和加载大语言模型。它将模型权重、分词器数据、架构元数据和量化信息打包到一个可携带文件中。

GGUF 的核心优势：

单文件部署：无需管理多个配置文件
支持内存映射：实现快速加载
可扩展的元数据：带类型的键值对存储
多种量化类型：从低比特到全精度灵活选择

建议

GGUF 于 2023 年作为 llama.cpp 生态的一部分引入，取代了较早的 GGML 格式，现已成为 Hugging Face 上分发量化 LLM 的主流格式。

直接下载 GGUF 模型

直接下载预转换好的 GGUF 模型是最简单的方式，您无需处理转换细节。目前主流的模型社区（如 Hugging Face 和 ModelScope）都已大量支持 GGUF 格式，您可以根据网络情况选择合适的平台。

Hugging Face

Hugging Face 上已有大量预转换的 GGUF 模型，您可以直接下载使用。

注意

Hugging Face 为海外平台，国内网络环境可能无法直接访问。您可以使用国内镜像站 hf-mirror.com 获得同样的访问体验。

📥 下载步骤：

选择站点
- 国内用户访问：https://hf-mirror.com
- 海外用户访问：https://huggingface.co
搜索模型
在搜索框中输入模型名称，例如 Qwen2.5-1.5B-Instruct GGUF，找到对应的仓库（如 bartowski/Qwen2.5-1.5B-Instruct-GGUF）。
下载文件
进入仓库的 文件列表（页面通常显示为“文件”或“Files”），在列表中找到您需要的 .gguf 文件。
文件名中通常包含量化版本信息，例如 Qwen2.5-1.5B-Instruct-Q4_K_M.gguf 中的 Q4_K_M 表示量化类型。点击文件即可直接下载。
说明
如果您在 huggingface.co 上获取到模型的下载链接，可以通过替换域名来实现国内加速：将链接中的 https://huggingface.co 替换为 https://hf-mirror.com 即可。
示例：
- 原始链接：
  https://huggingface.co/bartowski/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/Qwen2.5-1.5B-Instruct-Q4_K_M.gguf
- 替换后（国内可用）：
  https://hf-mirror.com/bartowski/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/Qwen2.5-1.5B-Instruct-Q4_K_M.gguf

推荐 Hugging Face 仓库（含国内镜像地址）：

仓库	国外地址 (huggingface.co)	国内镜像 (hf-mirror.com)
ggml-org	https://huggingface.co/ggml-org	https://hf-mirror.com/ggml-org
bartowski	https://huggingface.co/bartowski	https://hf-mirror.com/bartowski
TheBloke	https://huggingface.co/TheBloke	https://hf-mirror.com/TheBloke

浏览更多 GGUF 模型：

海外用户：Hugging Face GGUF 模型页面
国内用户：hf-mirror.com GGUF 模型页面

ModelScope

ModelScope（魔搭社区） 是国内模型平台，访问流畅，同样提供了大量 GGUF 格式模型。

📥 下载步骤：

访问 ModelScope 官网
在搜索框中输入模型名称并加上 GGUF 关键词，例如 Qwen2.5-1.5B-Instruct GGUF
进入模型仓库，在文件列表中找到需要的 .gguf 文件，点击即可下载

自行转换模型

如果您已有源模型，或者在开源模型基础上进行了微调训练，可以使用 llama.cpp 提供的转换工具将其转为 GGUF 格式，以便在应用中加载使用。

转换工具支持的源模型格式包括：

PyTorch 格式：.pt、.pth
SafeTensors 格式：.safetensors 好的，根据你的要求，我将源码和模型分开两个独立路径，只保留一个模型（Qwen2.5-1.5B-Instruct）作为示例，展示不同量化类型的转换命令。

以下步骤均在 Windows 系统下演示，您需要先准备 llama.cpp 的编译环境。

环境准备

在进行模型转换前，请确保以下开发环境已就绪。

安装 Anaconda

Anaconda 是 Python 环境管理的最佳方式。如果尚未安装，请参考以下文档完成安装与配置：

📖 安装 Anaconda 详细步骤

安装 PyCharm（可选）

PyCharm 是 JetBrains 提供的专业 Python IDE，可以方便地编辑代码、调试脚本和切换 Conda 环境。如需使用，请参考：

📖 安装 PyCharm 详细步骤

源码下载（b10752）

版本说明

b10752 是 llama.cpp 的一个特定发行版本。Bot.js Pro 基于此版本构建，因此转换工具需保持版本一致，否则可能导致转换后的模型在应用中无法加载或出现闪退。

GitHub 官方下载地址：
https://github.com/ggml-org/llama.cpp/archive/refs/tags/b10752.zip
国内备用下载地址：
https://1823071502.cdn.123clouddisk.com/1823071502/public/ai/llama.cpp-b10752.zip

下载完成后解压源码到本地目录，例如：

G:\llama.cpp-b10752

⚠️ 请确保解压路径中不包含中文字符或空格，否则可能导致依赖安装或转换报错。

创建 Conda 虚拟环境

⚠️ 请先打开 Anaconda Prompt 终端（不要使用普通 CMD）。

推荐使用 Python 3.10：

bash

conda create -n gguf_env python=3.10

激活环境：

bash

conda activate gguf_env

安装项目依赖

进入 llama.cpp 项目目录

bash

pushd G:\llama.cpp-b10752

安装 Python 依赖

bash

pip install -r requirements.txt

此命令会安装转换脚本所需的全部 Python 依赖包。

使用 PyCharm 打开项目（可选）

使用 PyCharm 打开 G:\llama.cpp-b10752 项目目录，并将 Python 解释器切换为之前创建的 gguf_env Conda 环境。

配置成功后，PyCharm 右下角会显示当前环境名称：gguf_env。

转换步骤

目录结构说明

转换前，请先将待转换的源模型下载到 models 目录下。源码与模型分开放置，目录结构如下：

G:\llama.cpp-b10752                 # 源码目录
├─ convert_hf_to_gguf.py            # 转换脚本
├─ requirements.txt                 # Python 依赖
└─ ...

G:\models                           # 模型目录（独立于源码）
├─ Qwen2.5-1.5B-Instruct\           # 源模型（Hugging Face 格式）
│  ├─ config.json
│  ├─ model.safetensors
│  └─ ...
└─ output\                          # 转换后的 GGUF 文件输出目录
   ├─ Qwen2.5-1.5B-Instruct_f16.gguf
   ├─ Qwen2.5-1.5B-Instruct_q8_0.gguf
   ├─ Qwen2.5-1.5B-Instruct_tq1_0.gguf
   └─ Qwen2.5-1.5B-Instruct_tq2_0.gguf

📥 下载源模型：从 Hugging Face 或 ModelScope 下载源模型到 G:\models\Qwen2.5-1.5B-Instruct\ 目录。

格式转换工具

convert_hf_to_gguf.py：将 Hugging Face 格式的模型权重（PyTorch 或 SafeTensors）转换为 GGUF 格式。

--outtype 可选值：

类型	说明	适用场景
`f32`	32 位浮点（完整精度，文件最大）	对精度要求极高，且存储空间充足
`f16`	16 位浮点（默认）	通用推荐，精度与大小平衡
`bf16`	bfloat16 格式	部分模型推荐使用
`q8_0`	8 位量化	兼顾大小与精度，推荐
`tq1_0`	1 位量化（极小）	低资源设备，极端压缩
`tq2_0`	2 位量化（极小）	低资源设备，极端压缩
`auto`	自动选择	由脚本自动判断

转换命令示例

以下示例以 Qwen2.5-1.5B-Instruct 模型为例，展示不同量化类型的转换命令：

bash

# 进入源码目录
pushd G:\llama.cpp-b10752

# 1. 转换为 f16 格式（默认，推荐）
python convert_hf_to_gguf.py G:\models\Qwen2.5-1.5B-Instruct --outfile G:\models\output\Qwen2.5-1.5B-Instruct_f16.gguf

# 2. 转换为 bf16 格式
python convert_hf_to_gguf.py G:\models\Qwen2.5-1.5B-Instruct --outtype bf16 --outfile G:\models\output\Qwen2.5-1.5B-Instruct_bf16.gguf

# 3. 转换为 q8_0 格式（8 位量化，推荐）
python convert_hf_to_gguf.py G:\models\Qwen2.5-1.5B-Instruct --outtype q8_0 --outfile G:\models\output\Qwen2.5-1.5B-Instruct_q8_0.gguf

# 4. 转换为 tq2_0 格式（2 位量化，极端压缩）
python convert_hf_to_gguf.py G:\models\Qwen2.5-1.5B-Instruct --outtype tq2_0 --outfile G:\models\output\Qwen2.5-1.5B-Instruct_tq2_0.gguf

# 5. 转换为 tq1_0 格式（1 位量化，最小体积）
python convert_hf_to_gguf.py G:\models\Qwen2.5-1.5B-Instruct --outtype tq1_0 --outfile G:\models\output\Qwen2.5-1.5B-Instruct_tq1_0.gguf

模型量化（可选）

转换后得到的通常是 F16 精度的 GGUF 文件，您还可以进一步量化为更小的尺寸，以降低内存占用：

常用量化级别说明：

量化类型	文件大小	质量	推荐场景
`Q2_K`	最小	最低	内存极度受限
`Q3_K`	小	较低	低内存设备
`Q4_K_M`	中等	良好	通用推荐
`Q5_K_M`	较大	较好	追求更好质量
`Q6_K`	大	好	高质量需求
`Q8_0`	大	接近全精度	最佳质量
`F16`	最大	全精度	有足够内存和算力

7B 模型的 FP16 约 14 GB，而 Q4_K_M 量化后仅约 4-5 GB。

验证 GGUF 模型

特别说明

如果你是通过 convert-hf-to-gguf.py 等脚本自行转换的模型（而非直接下载官方或社区已发布的预转换版本），由于转换过程高度依赖 llama.cpp 的版本、源模型格式（如 Safetensors / PTH）以及是否包含自定义算子，强烈建议转换后务必进行推理验证。这可以及早发现因张量名映射错误、量化溢出或架构不兼容导致的“静默损坏”问题。

使用 llama.cpp 提供的 llama-cli 工具进行快速推理验证，确保模型文件可正常加载和生成文本。以下步骤均基于 Windows 系统，使用预编译的二进制文件。

获取 llama.cpp 预编译工具

从官方仓库下载适用于 Windows 的预编译包（以 b10752 版本为例）：

GitHub 官方下载地址：
https://github.com/ggml-org/llama.cpp/releases/download/b10752/llama-b10752-bin-win-cpu-x64.zip
国内备用下载地址：
https://1823071502.cdn.123clouddisk.com/1823071502/public/ai/llama-b10752-bin-win-cpu-x64.zip
查看更多平台的预编译包（Linux / macOS / Android / 不同硬件指令集）：
https://github.com/ggml-org/llama.cpp/releases/tag/b10752

下载后解压到本地，例如 G:\llama-b10752-bin-win-cpu-x64。解压后的目录结构如下：

G:\llama-b10752-bin-win-cpu-x64
├─ llama-cli.exe                 # 命令行推理工具
├─ llama-server.exe              # 启动兼容 OpenAI API 的服务
├─ llama-gguf-split.exe          # GGUF 分割/合并工具
├─ llama-common.dll              # 公共依赖库
├─ ...                           # 其他辅助工具和动态链接库

验证普通文本模型

使用 llama-cli.exe 加载 GGUF 模型并执行简单的文本生成测试。

命令格式：

cmd

llama-cli.exe -m <模型路径> -p "提示词" -n <生成token数>

示例（基于之前转换的 Qwen2.5-1.5B-Instruct 模型）：

cmd

# 进入工具目录
pushd G:\llama-b10752-bin-win-cpu-x64

# 验证 bf16 模型
.\llama-cli.exe -m "G:\models\output\Qwen2.5-1.5B-Instruct_bf16.gguf" -p "Hello, how are you?" -n 20

# 验证 q8_0 模型
.\llama-cli.exe -m "G:\models\output\Qwen2.5-1.5B-Instruct_q8_0.gguf" -p "What is the capital of France?" -n 30

# 若模型为对话式指令微调模型，建议使用 -p 配合固定指令模板（具体模板需查阅模型文档）

预期输出：模型能正常生成连贯的文本回复，无报错或崩溃。

⚠️ 注意：部分极端量化（如 tq1_0、tq2_0）可能导致生成质量严重下降甚至无法正常推理，此属正常现象，请根据实际需求选用。

验证多模态模型（含视觉编码器）

对于支持多模态（如图像理解）的模型（如 Qwen-VL、LLaVA 等），需要同时加载 主模型 和对应的 mmproj 视觉投影文件。

使用 llama-server.exe 启动兼容 OpenAI API 的服务，或直接使用 llama-cli 进行交互。以下以 llama-server 为例，启动服务后可通过 API 请求测试。

命令格式：

cmd

llama-server.exe -m <主模型路径> -mm <mmproj路径> -ngl <GPU层数> -c <上下文长度>

示例（假设您已下载 Qwen3-VL-2B 的多模态模型及 mmproj 文件）：

主模型：Qwen3VL-2B-Instruct-Q4_K_M.gguf
mmproj：mmproj-Qwen3VL-2B-Instruct-F16.gguf

cmd

pushd G:\llama-b10752-bin-win-cpu-x64


llama-server.exe ^
-m "E:\ollama_models\Qwen3VL-2B-Instruct-Q4_K_M.gguf" ^
-mm "E:\ollama_models\mmproj-Qwen3VL-2B-Instruct-F16.gguf" ^
-ngl 30 ^
-c 5000

-m：主模型文件路径
-mm：多模态投影文件（通常名为 mmproj-xxx.gguf）
-ngl：将多少层加载到 GPU（0 表示纯 CPU 推理，数值越大显存占用越高）
-c：上下文长度（可根据模型支持范围调整）

启动成功后，可通过 http://localhost:8080 的 OpenAI 兼容 API 进行验证（例如使用 curl 或 Postman 发送对话请求）。

若使用 llama-cli 直接测试多模态（仅支持某些版本），可参考官方文档，但通常推荐使用 llama-server 便于交互。

GGUF 文件分割与合并

当模型文件过大（例如超过 4GB）时，可能面临文件系统限制或传输不便。llama.cpp 提供了 llama-gguf-split 工具，用于将单个 GGUF 文件拆分为多个分片，以及将分片合并回完整文件。

以下操作基于 Windows，工具位于 llama-b10752-bin-win-cpu-x64 目录中。

示例模型与目录

我们以转换好的 Qwen2.5-1.5B-Instruct_bf16.gguf（位于 G:\models\output\）为例，演示分割与合并流程。

约定：

工作目录：G:\llama-b10752-bin-win-cpu-x64
原始模型：G:\models\output\Qwen2.5-1.5B-Instruct_bf16.gguf
分片输出目录：G:\models\split\Qwen2.5-1.5B-Instruct_split\（注意此处可自定义）

创建分割输出文件夹

cmd

mkdir G:\models\split\Qwen2.5-1.5B-Instruct_split 2>nul

分割 GGUF 文件（分片大小 500MB）

使用 llama-gguf-split.exe 的 --split 模式。

cmd

pushd G:\llama-b10752-bin-win-cpu-x64

.\llama-gguf-split.exe --split --split-max-size 500M G:\models\output\Qwen2.5-1.5B-Instruct_bf16.gguf G:\models\split\Qwen2.5-1.5B-Instruct_split\part

执行后，会在输出目录生成类似 part-00001-of-00002.gguf、part-00002-of-00002.gguf 的文件。

查看生成的分片文件名

cmd

dir G:\models\split\Qwen2.5-1.5B-Instruct_split\part-*.gguf

记录实际的分片数量和文件名（如 part-00001-of-00002.gguf）。

验证分片是否可读（可选）

可以直接加载第一个分片，llama-cli 会自动加载其余分片（前提是分片命名连续且在相同目录）。

cmd

.\llama-cli.exe -m G:\models\split\Qwen2.5-1.5B-Instruct_split\part-00001-of-00002.gguf -p "hi" -n 20

将 00002 替换为实际总分片数。

合并分片为完整 GGUF 文件

使用 --merge 模式，指定任意一个分片文件和最终输出路径。

cmd

.\llama-gguf-split.exe --merge G:\models\split\Qwen2.5-1.5B-Instruct_split\part-00001-of-00002.gguf G:\models\split\Qwen2.5-1.5B-Instruct_split\merged.gguf

工具会自动读取所有分片并合并。

验证合并后的文件

cmd

.\llama-cli.exe -m G:\models\split\Qwen2.5-1.5B-Instruct_split\merged.gguf -p "Hello" -n 20

若正常输出回复，则表示合并成功，可正常使用。

提示

分割后的模型分片可以直接被 llama-cli 或 llama-server 加载（只需指定第一个分片路径），但建议在分发前合并为单文件以简化部署。

常见问题

Q：为什么需要转换？

llama.cpp 要求模型为 GGUF 格式。如果您有 PyTorch 或 SafeTensors 格式的模型，必须先转换为 GGUF 才能使用。

Q：转换后文件放在哪里？

建议将 GGUF 模型文件放在手机存储的 models/ 目录下，便于 Bot.js Pro 脚本引用。

Q：如何选择量化级别？

内存有限（4-6GB）：选择 Q4_K_M，平衡大小与质量
内存充足（8GB+）：可选择 Q5_K_M 或 Q6_K 获得更好质量
追求极致质量：使用 F16，但需确保有足够内存

Q：不同版本的 llama.cpp 转换的模型是否兼容？

不保证完全兼容。 Bot.js Pro 集成的 llama.cpp 版本为 b10752，建议使用相同版本的转换工具，以避免因格式变化导致的兼容性问题。

Q：微调后的模型如何转换？

如果您在开源模型基础上进行了微调（LoRA/QLoRA 等），得到的通常是 PyTorch 格式的 checkpoint。您只需先将微调后的权重合并到基础模型，然后按照上述“模型转换”步骤操作即可。

模型下载与转换 ​

什么是 GGUF？ ​

直接下载 GGUF 模型 ​

Hugging Face ​

ModelScope ​

自行转换模型 ​

环境准备 ​

安装 Anaconda ​

安装 PyCharm（可选） ​

源码下载（b10752） ​

创建 Conda 虚拟环境 ​

安装项目依赖 ​

进入 llama.cpp 项目目录 ​

安装 Python 依赖 ​

使用 PyCharm 打开项目（可选） ​

转换步骤 ​

目录结构说明 ​

格式转换工具 ​

转换命令示例 ​

模型量化（可选） ​

验证 GGUF 模型 ​

获取 llama.cpp 预编译工具 ​

验证普通文本模型 ​

验证多模态模型（含视觉编码器） ​

GGUF 文件分割与合并 ​

示例模型与目录 ​

创建分割输出文件夹 ​

分割 GGUF 文件（分片大小 500MB） ​

查看生成的分片文件名 ​

验证分片是否可读（可选） ​

合并分片为完整 GGUF 文件 ​

验证合并后的文件 ​

常见问题 ​

Q：为什么需要转换？ ​

Q：转换后文件放在哪里？ ​

Q：如何选择量化级别？ ​

Q：不同版本的 llama.cpp 转换的模型是否兼容？ ​

Q：微调后的模型如何转换？ ​

模型下载与转换

什么是 GGUF？

直接下载 GGUF 模型

Hugging Face

ModelScope

自行转换模型

环境准备

安装 Anaconda

安装 PyCharm（可选）

源码下载（b10752）

创建 Conda 虚拟环境

安装项目依赖

进入 llama.cpp 项目目录

安装 Python 依赖

使用 PyCharm 打开项目（可选）

转换步骤

目录结构说明

格式转换工具

转换命令示例

模型量化（可选）

验证 GGUF 模型

获取 llama.cpp 预编译工具

验证普通文本模型

验证多模态模型（含视觉编码器）

GGUF 文件分割与合并

示例模型与目录

创建分割输出文件夹

分割 GGUF 文件（分片大小 500MB）

查看生成的分片文件名

验证分片是否可读（可选）

合并分片为完整 GGUF 文件

验证合并后的文件

常见问题

Q：为什么需要转换？

Q：转换后文件放在哪里？

Q：如何选择量化级别？

Q：不同版本的 llama.cpp 转换的模型是否兼容？

Q：微调后的模型如何转换？