Llama.cpp Python 绑定与本地模型部署实战

GPU 加速配置

如果机器有 GPU（如 NVIDIA CUDA 或 Apple Silicon Metal），可以调整 n_gpu_layers 来加速推理。例如在 Apple Silicon 上设置 n_gpu_layers=1 即可启用 Metal 加速。

4. 文本生成功能

基础生成

可以直接调用对象或使用 create_completion 方法。后者允许更精细地控制生成参数：

output = llm.create_completion(
    prompt="What is AI?",
    max_tokens=100,
    temperature=0.7,
    top_p=0.9,
    stop=["\n", "Human:"]
)
print(output["choices"][0]["text"])

流式输出

对于长文本生成，流式输出体验更佳，避免长时间等待：

stream = llm.create_completion(
    prompt="Write a story about",
    max_tokens=200,
    stream=True
)
for output in stream:
    chunk = output["choices"][0]["text"]
    print(chunk, end="", flush=True)

采样策略调优

通过调整温度 (temperature) 和核采样 (top_p) 可以改变输出的创造性。低温度适合事实性问答，高温度适合创意写作。

5. 聊天对话 API

多轮对话管理

聊天模式需要维护消息历史列表。每次请求都应将之前的对话内容包含在内：

messages = [
    {"role": "system", "content": "你是一个友好的 AI 助手。"},
    {"role": "user", "content": "你好"}
]

response = llm.create_chat_completion(
    messages=messages,
    temperature=0.7,
    max_tokens=200
)
assistant_reply = response["choices"][0]["message"]["content"]
messages.append({"role": "assistant", "content": assistant_reply})

不同格式支持

Llama.cpp 支持 Alpaca、Vicuna 和 ChatML 等多种提示词格式，可根据模型微调时的格式进行适配。

6. 嵌入与相似度计算

除了生成文本，该库还能生成向量嵌入，常用于 RAG 系统：

import numpy as np
from numpy.linalg import norm

# 生成嵌入
emb1 = llm.embed("猫是一种动物")
emb2 = llm.embed("狗是一种宠物")

# 计算余弦相似度
def cosine_similarity(vec1, vec2):
    return np.dot(vec1, vec2) / (norm(vec1) * norm(vec2))

similarity = cosine_similarity(emb1, emb2)
print(f"相似度：{similarity:.4f}")

7. 高级控制与调试

语法约束

可以通过 Grammar 约束生成的输出格式，例如强制 JSON 结构，但这通常需要特定的模型支持。

错误处理

加载模型或生成时可能遇到内存不足等问题，建议包裹在 try-except 块中并监控日志：

try:
    response = llm.create_completion(prompt="test", max_tokens=100)
except RuntimeError as e:
    if "out of memory" in str(e).lower():
        print("内存不足，请减小上下文大小")

8. 服务器模式与集成

启动本地服务

可以将模型封装为 HTTP 服务，方便其他语言调用：

from llama_cpp.server.app import create_app
import uvicorn

app = create_app(model_path="./models/model.bin")
uvicorn.run(app, host="0.0.0.0", port=8000)

生态集成

• LangChain: 可直接作为 LLM 后端接入 LangChain 链。
• Gradio: 几行代码即可构建 Web 演示界面。

9. 性能优化建议

1. 量化选择：优先使用 q4_0 或 q5_0 量化模型，在精度和速度间取得平衡。
2. 批处理：合理设置 n_batch 参数以提高 CPU 利用率。
3. 内存映射：开启 use_mmap=True 可减少物理内存占用。
4. 线程数：设置为物理核心数通常能获得最佳性能。

通过上述配置，你可以在本地高效运行大语言模型，构建隐私安全且响应迅速的应用程序。