代码收藏家技术教程 2025-02-09

使用 Llama.cpp 和 llama-cpp-python 快速部署本地 LLM 模型

在这篇技术文章中，我们将探讨如何使用 llama-cpp-python （llama.cpp 的 Python 绑定）在本地运行大语言模型（LLMs）。你将学到如何安装依赖、加载模型、调整参数以获得最佳性能，以及如何结合 LangChain 处理推理任务。

一、技术背景介绍

llama-cpp-python 是 llama.cpp 的 Python 绑定，旨在简化本地运行大语言模型的过程。它支持多种 LLM 模型，包括可以从 Hugging Face 获取的模型。

新版本提示

最新版本的 llama-cpp-python 已改用 GGUF 模型文件格式并不再兼容旧版 GGML 文件格式。如果你需要转换模型文件，可使用以下命令：

python ./convert-llama-ggmlv3-to-gguf.py --eps 1e-5 \
--input models/openorca-platypus2-13b.ggmlv3.q4_0.bin \
--output models/openorca-platypus2-13b.gguf.q4_0.bin

二、安装 llama-cpp-python

1. CPU 安装

最简单的安装方式:

pip install --upgrade --quiet llama-cpp-python

2. 使用 OpenBLAS/cuBLAS/CLBlast 加速

要启用更高性能的 BLAS 后端，可设置环境变量 FORCE_CMAKE=1 并使用以下命令：

CMAKE_ARGS="-DLLAMA_CUBLAS=on" FORCE_CMAKE=1 \
pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir

3. Metal (适用于 Apple Silicon)

Mac 用户可以通过 Metal GPU 获得性能优化：

CMAKE_ARGS="-DLLAMA_METAL=on" FORCE_CMAKE=1 \
pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir

4. Windows 安装

Windows 用户需从源码编译：

git clone --recursive -j8 https://github.com/abetlen/llama-cpp-python.git
cd llama-cpp-python
python -m pip install -e . --force-reinstall --no-cache-dir

三、使用 llama-cpp-python 运行 LangChain 推理任务

1. 基础代码实现

以下示例使用一个本地 LLaMA 2 7B 模型进行推理：

from langchain_community.llms import LlamaCpp
from langchain_core.callbacks import CallbackManager, StreamingStdOutCallbackHandler
from langchain_core.prompts import PromptTemplate

# 设置模型路径，请根据实际情况调整
model_path = "/path/to/your/model/openorca-platypus2-13b.gguf.q4_0.bin"

template = """Question: {question}

Answer: Let's work this out in a step by step way to be sure we have the right answer."""
prompt = PromptTemplate.from_template(template)

callback_manager = CallbackManager([StreamingStdOutCallbackHandler()])

llm = LlamaCpp(
    model_path=model_path,
    temperature=0.75,
    max_tokens=2000,
    top_p=1,
    callback_manager=callback_manager,
    verbose=True,
)

# 示例问题
question = "What NFL team won the Super Bowl in the year Justin Bieber was born?"
result = llm.invoke({"question": question})
print(result)

2. 参数详解

temperature: 控制模型生成的随机性，值越高输出越多样化。

max_tokens: 限制生成的最大 token 数量。

top_p: 用于控制采样中概率分布的截断程度。

四、优化性能的 GPU 参数设置

如果你使用 GPU，加载模型时可以调整以下参数来提高性能：

llm = LlamaCpp(
    model_path=model_path,
    n_gpu_layers=20,  # 指定加载到 GPU 的网络层数
    n_batch=512,      # 每次处理的 token 批量大小
    callback_manager=callback_manager,
    verbose=True,
)

Metal 优化（Apple Silicon 专属）

Metal 支持需开启 f16_kv 参数以避免兼容性问题：

llm = LlamaCpp(
    model_path=model_path,
    n_gpu_layers=1,
    n_batch=512,
    f16_kv=True,
    callback_manager=callback_manager,
    verbose=True,
)

五、约束模型输出 (Grammar)

llama-cpp-python 支持基于语法规则生成模型输出。以下是一个使用 .gbnf 文件生成 JSON 输出的示例：

llm = LlamaCpp(
    model_path=model_path,
    grammar_path="/path/to/json.gbnf",  # 指定语法规则文件路径
    n_gpu_layers=1,
    n_batch=512,
    f16_kv=True,
    callback_manager=callback_manager,
    verbose=True,
)

result = llm.invoke("Describe a person in JSON format:")
print(result)