参阅上一篇：llama.cpp 如何下载、编译

mkdir ggml
cd ggml
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
如果仅使用 CPU，不用显卡 GPU
cmake -B build -DGGML_CURL=OFF
cmake --build build --config Release -j 8

编译成功后， llama.cpp 就已经准备就绪了。它就像一个本地的“AI引擎”，可以加载模型来回答你的问题。入门使用主要分三步：下载模型、运行对话、（可选）启动服务。

下面是具体的操作指南，我们直接从你上次编译好的 build 文件夹开始。

🚀 入门三步走

1. 下载模型

llama.cpp 需要特定格式的模型文件（后缀为 .gguf）。你不需要自己动手转换，直接从 Hugging Face 下载别人转换好的就行。

• 新手推荐：从 TheBloke 的模型仓库找，比如 Llama-2-7B-Chat-GGUF。这是对新手最友好的7B参数指令模型。
• 文件命名规则：像 llama-2-7b-chat.Q4_K_M.gguf 这种文件名里，Q4_K_M 代表4-bit量化。它在模型大小和智能程度之间取得了很好的平衡，是一个很好的起点。

2. 运行对话（CLI模式）

这是最直接的用法。将下载好的 .gguf 模型文件放到 llama.cpp 目录下的 models 文件夹中，然后打开终端，执行以下命令：

# 进入你之前编译的 build 文件夹
cd build

# 运行交互式对话
./bin/main -m ../models/你的模型文件.gguf -n 512 --color -i -r "User:" -p "You are a helpful assistant.\nUser: Hello!\nAssistant:"

参数解释：

• -m：指定模型文件的路径。
• -i：启动交互式对话模式。
• -p：设置系统提示词（prompt），告诉AI它的身份和对话格式。
• -r "User:"：设置一个停止词，当AI生成到“User:”时，会停下等待你的输入。
• -n 512：控制生成回复的最大长度（token数）。

3. 启动服务（Server模式）

如果你想通过编程调用，或者使用更友好的前端界面，可以把它变成一个API服务：

# 在 build 文件夹下执行
./bin/server -m ../models/你的模型文件.gguf --host 127.0.0.1 --port 8080

启动后，你就可以在 http://127.0.0.1:8080 访问它。它不仅提供了一个简单的Web聊天界面，还提供了一个与OpenAI API兼容的接口，方便你用代码调用。

⚙️ 常用参数调优

你可以通过调整参数来改变AI的“性格”和回复效果，建议在运行时添加：

• -t <数字>：设置使用的CPU线程数，一般设为你电脑的CPU核心数可以最大化性能。
• --temp <数字>：控制回复的创造性（0-2之间）。值越低（如0.3）回复越确定、保守；值越高（如0.9）回复越有创意和随机性。
• --repeat_penalty <数字>：防止AI重复同样的词句，建议设为 1.05 到 1.15 之间。

📊 量化模型参考

当你下载不同模型时，文件名里的“量化类型”决定了它的运行速度和智能程度。这里有个简单的对照表供你参考：

量化类型	内存占用（相对FP16）	相对速度	适用场景
Q4_K_M	约 30%	很快	首选推荐，平衡质量和速度。
Q5_K_M	约 40%	较快	如果你内存充足，想要更好质量。
Q2_K	约 15%	最快	内存极度紧张时的选择，质量有损。
Q8_0	约 50%	基准线	质量损失极小，但内存占用高，速度快不了多少。

简单来说：内存有限选Q4_K_M，追求质量选Q5_K_M，纯粹测试选Q2_K。

💡 下一步与问题排查

• 用Python调用：如果你想在Python项目里使用，可以安装 llama-cpp-python 库。它的用法和OpenAI的API非常像，会更方便。
• 遇到"illegal instruction"错误：这通常是因为你的CPU不支持某些高级指令集（如AVX2）。你需要重新编译，但这次要禁用它们：

  # 在 build 文件夹下重新配置并编译
  cmake .. -DLLAMA_AVX=OFF -DLLAMA_AVX2=OFF
  cmake --build . --config Release -j 8
  

---

python: llama-cpp-python 入门教程

相比于直接使用命令行，llama-cpp-python 能让你用熟悉的 Python 代码来驱动本地大模型。它的核心优势在于提供了一个和 OpenAI API 高度兼容的接口，让你既能保护数据隐私，又能轻松集成到现有项目里。

入门可以遵循以下四个步骤，从安装到运行一个带界面的服务。

第一步：安装

安装的核心是选择适合你硬件的版本，这能极大提升运行效率。对于 NVIDIA 显卡用户，强烈建议安装带 CUDA 支持的版本以启用 GPU 加速。

• 基础 CPU 版本 (最通用)

  pip install llama-cpp-python
  

  如果下载很慢或失败，可以尝试使用清华等国内镜像源。

• NVIDIA GPU (CUDA) 加速版 (推荐)

  pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
  

  这行命令会安装预编译的、支持 CUDA 12.4 的版本。如果你的 CUDA 版本不同，可以把链接中的 cu124 换成 cu121、cu122 等。

第二步：下载模型

你需要一个 .gguf 格式的模型文件。一个简单的方法是直接从 Hugging Face Hub 下载：

pip install huggingface-hub
huggingface-cli download TheBloke/Llama-2-7B-Chat-GGUF llama-2-7b-chat.Q4_K_M.gguf --local-dir ./models

这个命令会把一个 4-bit 量化的 Llama 2 模型下载到你本地的 models 文件夹。你也可以换成其他你喜欢的模型，比如 Qwen2-0.5B-Instruct-GGUF。

第三步：使用 Python 运行

安装好后，就可以用几行代码来加载模型并让它生成回答了。

这是一个最简单的例子：

from llama_cpp import Llama

# 1. 加载模型
# n_gpu_layers=-1 表示尽可能将层放到GPU上，如果是CPU版本可以注释掉这行
llm = Llama(
    model_path="./models/llama-2-7b-chat.Q4_K_M.gguf",
    n_ctx=2048,      # 上下文窗口大小
    n_gpu_layers=-1  # 使用GPU加速
)

# 2. 创建对话
output = llm(
    "Q: 太阳系有哪些行星？ A: ",  # 提示词
    max_tokens=64,                # 最多生成的token数
    stop=["Q:", "\n"],            # 遇到这些词就停止
    echo=False                    # 是否在输出中包含输入的提示词
)

# 3. 打印结果
print(output["choices"][0]["text"])

代码执行后，你会看到模型输出的行星列表。llm 函数返回的是一个字典，包含了生成的文本和使用情况统计。

第四步：使用对话模板 (Chat Completion)

对于指令微调模型，使用 create_chat_completion 方法和正确的 chat_format 能得到更好的效果。大多数现代模型能自动从文件中识别格式。

from llama_cpp import Llama

llm = Llama(
    model_path="./models/llama-2-7b-chat.Q4_K_M.gguf",
    # chat_format="llama-2" # 如果模型无法自动识别，可以手动指定
)

response = llm.create_chat_completion(
    messages=[
        {"role": "system", "content": "你是一个有用的AI助手。"},
        {"role": "user", "content": "能介绍一下你自己吗？"}
    ]
)

print(response["choices"][0]["message"]["content"])

这种方式模仿了 OpenAI API 的格式，处理多轮对话时会更加方便。

💡 补充：快速启动一个Web服务

除了写代码，你还可以一步启动一个本地的 API 服务器，它自带一个简易的聊天界面和 OpenAI 兼容的 API。

# 在命令行中运行
python -m llama_cpp.server --model ./models/llama-2-7b-chat.Q4_K_M.gguf --n_gpu_layers -1

启动成功后，在浏览器打开 http://localhost:8000 就能看到界面了。

📊 常用参数速查

参数	作用	示例
model_path	指定 .gguf 模型文件的路径	"./models/my_model.gguf"
n_ctx	上下文窗口大小，越大能记忆的对话越多，但也更消耗内存	2048, 4096
n_gpu_layers	将多少层模型放到 GPU 运行，设为 -1 代表全部	-1 (全部), 20 (部分)
temperature	控制随机性，值越高回答越有创意，越低越保守	0.7, 0.1
max_tokens	生成回答的最大长度	512, 2048

❓ 常见问题

• ModuleNotFoundError: No module named 'llama_cpp'
  这说明没有安装成功。检查一下你是否在正确的 Python 虚拟环境中，并确认 pip 安装命令没有报错。

• 安装时提示找不到 nmake 或编译失败
  这通常发生在 Windows 上。可以尝试安装预编译的 wheel 包，或者安装 Visual Studio 生成工具并确保在“开发者命令提示符”下进行安装。

• 模型回复乱码或无意义
  可能是在用基础模型做对话，或者 chat_format 设置不正确。建议下载带 “Instruct” 或 “Chat” 字样的模型，并尝试在 Llama 初始化时手动指定 chat_format 参数（如 chat_format="llama-2"）。