要将 `.safetensors` 格式的模型转换为 Ollama 可加载的 GGUF 格式，核心是使用 `llama.cpp` 项目提供的转换工具。以下是一个完整的 Python 程序示例，它集成了下载、转换、量化及生成 Ollama Modelfile 的流程。 ### **1. 环境准备与依赖安装** 首先，确保你的 Python 环境已安装必要的依赖。我们推荐使用虚拟环境。 ```bash # 创建并激活虚拟环境（以 conda 为例） conda create -n model-convert python=3.10 conda activate model-convert # 安装核心依赖 pip install torch transformers accelerate huggingface-hub ``` ### **2. 核心转换程序** 以下 Python 脚本 (`convert_safetensors_to_gguf.py`) 实现了从 `.safetensors` 到 GGUF 的转换，并支持量化 [ref_2]。 ```python import os import subprocess import sys from pathlib import Path def setup_llama_cpp(): """ 克隆并编译 llama.cpp 仓库，这是转换的核心工具 [ref_2][ref_4]。 """ if not os.path.exists("llama.cpp"): print("正在克隆 llama.cpp 仓库...") subprocess.run(["git", "clone", "https://github.com/ggerganov/llama.cpp.git"], check=True) os.chdir("llama.cpp") print("正在编译 llama.cpp...") # 根据你的平台选择编译命令 if sys.platform == "linux": subprocess.run(["make"], check=True) elif sys.platform == "win32": # Windows 用户可能需要使用 CMake subprocess.run(["cmake", "-B", "build", "-G", "Ninja"], check=True) subprocess.run(["cmake", "--build", "build", "--config", "Release"], check=True) else: subprocess.run(["make"], check=True) os.chdir("..") print("llama.cpp 编译完成。") def convert_safetensors_to_gguf(model_path, output_dir="ollama_models"): """ 将 .safetensors 模型转换为 GGUF 格式 [ref_3][ref_4]。 参数: model_path: .safetensors 模型文件所在目录的路径。 output_dir: 输出 GGUF 文件的目录。 """ # 确保输出目录存在 Path(output_dir).mkdir(parents=True, exist_ok=True) # 构建转换命令 [ref_4] # 假设 model_path 是包含 .safetensors 文件和 tokenizer 的 Hugging Face 模型目录 convert_cmd = [ "python", "llama.cpp/convert.py", model_path, "--outtype", "f16", # 输出为 float16 精度 "--outfile", f"{output_dir}/converted_model.gguf" ] print(f"开始转换模型: {model_path}") try: subprocess.run(convert_cmd, check=True) print(f"转换成功！GGUF 文件已保存至: {output_dir}/converted_model.gguf") return f"{output_dir}/converted_model.gguf" except subprocess.CalledProcessError as e: print(f"转换失败: {e}") return None def quantize_gguf_model(gguf_path, quant_type="q4_0"): """ 对 GGUF 模型进行量化，以减小模型体积并提升推理速度 [ref_5]。 参数: gguf_path: 输入的 GGUF 文件路径。 quant_type: 量化类型，如 q4_0 (4位整数)、q8_0 (8位整数) 等。 """ quantized_path = gguf_path.replace(".gguf", f"_{quant_type}.gguf") # 使用 llama.cpp 的量化工具 [ref_5] quantize_cmd = [ "./llama.cpp/quantize", gguf_path, quantized_path, quant_type ] print(f"开始量化模型，类型: {quant_type}") try: subprocess.run(quantize_cmd, check=True, cwd=".") print(f"量化成功！文件已保存至: {quantized_path}") return quantized_path except subprocess.CalledProcessError as e: print(f"量化失败: {e}") return None def create_ollama_modelfile(gguf_path, model_name="my-custom-model"): """ 为转换后的 GGUF 模型创建 Ollama Modelfile，用于本地加载 [ref_6]。 参数: gguf_path: 量化后的 GGUF 文件路径。 model_name: 在 Ollama 中注册的模型名称。 """ modelfile_content = f"""FROM {gguf_path} # 设置模型参数 PARAMETER temperature 0.7 PARAMETER top_p 0.9 PARAMETER num_ctx 4096 # 可选的系统提示词 SYSTEM \"\"\"You are a helpful AI assistant.\"\"\" """ modelfile_path = f"ollama_models/Modelfile" with open(modelfile_path, "w", encoding="utf-8") as f: f.write(modelfile_content) print(f"Modelfile 已生成: {modelfile_path}") # 创建使用指南 guide_content = f""" # Ollama 模型加载指南 ## 1. 将模型导入 Ollama 在终端中执行以下命令，使用生成的 Modelfile 创建模型： ```bash ollama create {model_name} -f {modelfile_path} ``` ## 2. 运行模型 创建成功后，使用以下命令与模型交互： ```bash ollama run {model_name} ``` ## 3. 通过 API 调用 Ollama 提供 REST API，您可以使用 curl 或 Postman 进行调用： ```bash curl -X POST http://localhost:11434/api/generate -d '{{ "model": "{model_name}", "prompt": "Hello, how are you?", "stream": false }}' ``` """ guide_path = "ollama_models/ollama_usage_guide.md" with open(guide_path, "w", encoding="utf-8") as f: f.write(guide_content) print(f"使用指南已生成: {guide_path}") def main(): """ 主函数：协调整个转换流程。 """ # 步骤 1: 设置 llama.cpp setup_llama_cpp() # 步骤 2: 指定你的 .safetensors 模型路径 # 示例：本地路径或 Hugging Face 模型ID model_path = "E:\\姚华军\\人工智能\\_saves" # 请替换为你的实际路径 # 或者从 Hugging Face 下载: model_path = "NousResearch/Hermes-2-Pro-Llama-3-8B" # 步骤 3: 转换为 GGUF 格式 gguf_path = convert_safetensors_to_gguf(model_path) if not gguf_path: print("转换失败，程序退出。") return # 步骤 4: 量化模型（可选，但强烈推荐以减少体积） quantized_path = quantize_gguf_model(gguf_path, quant_type="q4_0") # 步骤 5: 创建 Ollama Modelfile 和使用指南 final_model_path = quantized_path if quantized_path else gguf_path create_ollama_modelfile(final_model_path, model_name="my-custom-llama") if __name__ == "__main__": main() ``` ### **3. 关键步骤说明与参数调整** #### **3.1 模型路径 (`model_path`)** - **本地目录**：如 `E:\\姚华军\\人工智能\\_saves`，该目录应包含 `.safetensors` 文件和 `tokenizer.json` 等配置文件 [ref_1]。 - **Hugging Face 模型ID**：如 `NousResearch/Hermes-2-Pro-Llama-3-8B`，脚本会自动从 Hugging Face 下载 [ref_3]。 #### **3.2 量化类型选择** 量化可大幅减少模型体积和内存占用。以下是常见量化类型及其特点 [ref_5]： | 量化类型 | 精度 | 典型体积减少 | 适用场景 | |----------|------|--------------|----------| | `q4_0` | 4位整数 | ~75% | 内存受限，追求速度 | | `q8_0` | 8位整数 | ~50% | 平衡精度与速度 | | `f16` | 16位浮点 | ~50% | 保留较高精度 | | `f32` | 32位浮点 | 0% | 最高精度，研究用途 | 在 `quantize_gguf_model` 函数中，可通过 `quant_type` 参数指定。 #### **3.3 生成 Modelfile 与使用指南** 程序会自动创建 `ollama_models` 目录，并生成： - **`Modelfile`**：Ollama 加载模型所需的配置文件，定义了模型路径和基本参数 [ref_6]。 - **`ollama_usage_guide.md`**：详细的使用说明，包含加载模型、运行交互和 API 调用的命令示例 [ref_1]。 ### **4. 完整工作流程示例** 假设你有一个通过 LLaMA-Factory 微调并导出为 `.safetensors` 的模型，存放在 `E:\my_model` 目录下。以下是完整的操作流程： 1. **运行转换脚本**： ```bash python convert_safetensors_to_gguf.py ``` 程序将自动完成克隆 `llama.cpp`、编译、转换和量化。 2. **导入模型到 Ollama**： ```bash # 进入生成的目录 cd ollama_models # 创建 Ollama 模型 ollama create my-model -f ./Modelfile ``` 3. **验证模型**： ```bash # 运行模型进行测试 ollama run my-model >>> Hello, how are you? >>> I'm doing well, thank you for asking! ``` 4. **通过 API 调用**（如使用 Postman）： ```bash curl -X POST http://localhost:11434/api/generate -d '{ "model": "my-model", "prompt": "Explain quantum computing in simple terms.", "stream": false }' ``` ### **5. 常见问题与解决方案** | 问题 | 可能原因 | 解决方案 | |------|----------|----------| | 转换时提示“找不到 tokenizer” | 模型目录缺少配置文件 | 确保目录包含 `tokenizer.json` 或从 Hugging Face 重新下载完整模型 [ref_3]。 | | 量化过程内存不足 | 模型过大或可用内存不足 | 尝试使用更低精度的量化（如 `q4_0`），或增加虚拟内存 [ref_5]。 | | Ollama 加载失败 | Modelfile 中路径错误 | 检查 `Modelfile` 中的 `FROM` 路径是否为绝对路径或相对路径正确 [ref_6]。 | | 转换速度慢 | 未使用 GPU 加速 | 确保已安装 CUDA 并在编译 `llama.cpp` 时启用 GPU 支持（`make LLAMA_CUDA=1`）[ref_4]。 | 此程序提供了一个端到端的自动化解决方案，涵盖了从格式转换到部署的全过程。通过调整量化参数和模型路径，你可以灵活地适配不同的模型和硬件环境。