Llama.cpp Python 绑定与 API 使用详解

3.2 完整初始化参数

3.3 GPU 支持配置

# 使用 GPU（如果支持）
llm = Llama(
    model_path="./models/llama-2-7b-chat.ggmlv3.q4_0.bin",
    n_gpu_layers=35,   # 将 35 层放在 GPU 上
    n_threads=4,       # CPU 线程数
    n_ctx=2048,
    verbose=True
)

# Apple Silicon GPU 支持（Metal）
llm = Llama(
    model_path="./models/llama-2-7b-chat.ggmlv3.q4_0.bin",
    n_gpu_layers=1,    # 使用 Metal GPU
    n_threads=8,
    n_ctx=2048,
    verbose=True
)

4. 文本生成 API

4.1 基础文本生成

# 基本生成
output = llm("Once upon a time")
print(output["choices"][0]["text"])

# 使用 create_completion 方法
output = llm.create_completion(
    prompt="What is AI?",
    max_tokens=100,
    temperature=0.7,
    top_p=0.9,
    stop=["\n","Human:","AI:"]
)

4.2 生成参数详解

4.3 流式生成

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

4.4 带参数的生成示例

response = llm.create_completion(
    prompt="解释量子计算的基本原理：",
    max_tokens=300,
    temperature=0.7,        # 中等创造性
    top_p=0.9,              # 核采样
    top_k=40,               # 仅考虑前 40 个候选
    frequency_penalty=0.5,  # 减少重复词汇
    presence_penalty=0.3,   # 鼓励新话题
    repeat_penalty=1.1,     # 惩罚重复
    stop=["\n\n","###"],   # 停止符
    echo=False              # 不包含输入
)
print(response["choices"][0]["text"])

5. 聊天对话 API

5.1 基础聊天

messages = [
    {"role":"system","content":"你是一个有用的助手。"},
    {"role":"user","content":"你好，请介绍一下你自己。"}
]
response = llm.create_chat_completion(
    messages=messages,
    temperature=0.7,
    max_tokens=200
)
print(response["choices"][0]["message"]["content"])

5.2 多轮对话

def chat_with_llama(llm, messages):
    """多轮对话函数"""
    while True:
        user_input = input("\n用户：")
        if user_input.lower() == 'quit':
            break
        messages.append({"role":"user","content": user_input})
        response = llm.create_chat_completion(
            messages=messages,
            max_tokens=150,
            temperature=0.7
        )
        assistant_reply = response["choices"][0]["message"]["content"]
        print(f"助手：{assistant_reply}")
        messages.append({"role":"assistant","content": assistant_reply})
    return messages

# 初始消息
messages = [{"role":"system","content":"你是一个友好的 AI 助手，用中文回答。"}]
# 开始对话
chat_with_llama(llm, messages)

5.3 不同聊天格式

# Alpaca 格式
alpaca_prompt = """Below is an instruction that describes a task. Write a response that appropriately completes the request.
### Instruction: {instruction}
### Response:"""

# Vicuna 格式
vicuna_prompt = """A chat between a curious user and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the user's questions.
USER: {prompt}
ASSISTANT:"""

# ChatML 格式
chatml_prompt = """<|im_start|>system {system_message}<|im_end|>
<|im_start|>user {user_message}<|im_end|>
<|im_start|>assistant """

6. 嵌入生成 API

6.1 生成文本嵌入

# 生成单个文本嵌入
embedding = llm.embed("This is a sample text.")
print(f"嵌入维度：{len(embedding)}")
print(f"嵌入向量：{embedding[:5]}...")  # 显示前 5 个维度

# 批量生成嵌入
texts = ["人工智能是计算机科学的一个分支","机器学习是 AI 的子领域","深度学习使用神经网络"]
embeddings = []
for text in texts:
    emb = llm.embed(text)
    embeddings.append(emb)
print(f"生成了 {len(embeddings)} 个嵌入向量")

6.2 计算相似度

import numpy as np
from numpy.linalg import norm

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

# 生成嵌入
emb1 = llm.embed("猫是一种动物")
emb2 = llm.embed("狗是一种宠物")
emb3 = llm.embed("Python 是一种编程语言")

# 计算相似度
sim_cat_dog = cosine_similarity(emb1, emb2)
sim_cat_python = cosine_similarity(emb1, emb3)
print(f"猫 - 狗相似度：{sim_cat_dog:.4f}")
print(f"猫-Python 相似度：{sim_cat_python:.4f}")

7. 高级生成控制

7.1 采样策略

# 使用不同采样策略
response = llm.create_completion(
    prompt="写一首关于春天的诗：",
    max_tokens=100,
    temperature=0.8,          # 高温度 = 更多随机性
    # temperature=0.2,       # 低温度 = 更确定
    top_p=0.9,                # 核采样
    top_k=50,                 # top-k 采样
    repeat_penalty=1.2,       # 重复惩罚
    frequency_penalty=0.5,    # 频率惩罚
    presence_penalty=0.5,     # 存在惩罚
    mirostat_mode=2,          # Mirostat 采样（0=禁用，1=Mirostat，2=Mirostat 2.0）
    mirostat_tau=5.0,         # Mirostat 目标困惑度
    mirostat_eta=0.1          # Mirostat 学习率
)

7.2 语法约束生成

# 使用 grammar 约束生成
grammar = """ root ::= (statement ". ")*
statement ::= "I" verb object
verb ::= " love" | " hate"
object ::= " cats" | " dogs"
"""
# 注意：当前版本可能需要通过不同方式应用 grammar
# 通常通过 GGML 格式的 grammar 文件

7.3 对数概率获取

# 获取生成的对数概率
response = llm.create_completion(
    prompt="The weather is",
    max_tokens=10,
    logprobs=10,              # 返回前 10 个候选的 logprobs
    echo=True                 # 包含输入文本
)
if "logprobs" in response["choices"][0]:
    logprobs = response["choices"][0]["logprobs"]
    print("Top token probabilities:")
    for token, logprob in zip(logprobs["tokens"], logprobs["token_logprobs"]):
        prob = np.exp(logprob)
        print(f" {token}: {prob:.4f}")

8. 模型信息和管理

8.1 获取模型信息

# 获取模型上下文大小
print(f"模型上下文大小：{llm.n_ctx()}")
# 获取词表大小
print(f"词表大小：{llm.n_vocab()}")
# 获取模型参数
print(f"模型参数：{llm.model.params}")

# 获取所有 token
vocab = llm.tokenize(b"test")
print(f"Token IDs: {vocab}")

# 解码 token
token_id = 1234
token_text = llm.detokenize([token_id])
print(f"Token {token_id} 对应文本：{token_text}")

8.2 Token 处理

# 编码文本
text = "Hello, world!"
tokens = llm.tokenize(text.encode())
print(f"文本 '{text}' 的 tokens: {tokens}")

# 解码 tokens
decoded_text = llm.detokenize(tokens)
print(f"解码后的文本：{decoded_text}")

# 计算 token 数
def count_tokens(text):
    tokens = llm.tokenize(text.encode())
    return len(tokens)

text = "这是一个测试句子。"
token_count = count_tokens(text)
print(f"文本 token 数：{token_count}")

9. 服务器模式 API

9.1 启动服务器

# 启动服务器（使用命令行）
# python -m llama_cpp.server --model models/7B/ggml-model.bin

# 或者从 Python 启动
from llama_cpp.server.app import create_app
import uvicorn

app = create_app(
    model_path="./models/llama-2-7b-chat.ggmlv3.q4_0.bin",
    n_ctx=2048,
    n_threads=8
)

# 运行服务器
uvicorn.run(app, host="0.0.0.0", port=8000)

9.2 API 端点

9.3 客户端调用

import requests

# 调用本地服务器
response = requests.post(
    "http://localhost:8000/v1/chat/completions",
    json={"messages":[{"role":"user","content":"你好"}],"temperature":0.7,"max_tokens":100}
)
result = response.json()
print(result["choices"][0]["message"]["content"])

10. 性能优化 API

10.1 批处理优化

# 批处理生成
prompts = ["解释 AI 的含义：","什么是机器学习？","深度学习有哪些应用？"]
for prompt in prompts:
    response = llm.create_completion(
        prompt=prompt,
        max_tokens=100,
        temperature=0.7,
        n_batch=512       # 批处理大小
    )
    print(f"Q: {prompt}")
    print(f"A: {response['choices'][0]['text']}\n")

10.2 内存优化

# 内存优化配置
llm = Llama(
    model_path="./models/llama-2-7b-chat.ggmlv3.q4_0.bin",
    n_ctx=2048,
    n_threads=8,
    n_batch=512,
    use_mlock=True,       # 锁定内存，防止交换
    use_mmap=True,        # 使用内存映射文件
    verbose=True
)

# 释放内存
del llm
import gc
gc.collect()

10.3 量化模型使用

# 不同量化级别的模型
quantizations = {
    "q4_0": "4-bit 整数量化（最快）",
    "q4_1": "4-bit 带尺度量化",
    "q5_0": "5-bit 整数量化",
    "q5_1": "5-bit 带尺度量化",
    "q8_0": "8-bit 整数量化",
    "f16": "半精度浮点数",
    "f32": "全精度浮点数"
}

# 加载量化模型
model_path = "./models/llama-2-7b-chat.ggmlv3.q4_0.bin"
llm = Llama(model_path=model_path, n_ctx=2048)
print(f"加载模型：{model_path}")
print(f"量化类型：{model_path.split('.')[-2]}")

11. 实际应用示例

11.1 文档问答系统

class DocumentQA:
    def __init__(self, model_path):
        self.llm = Llama(
            model_path=model_path,
            n_ctx=4096,
            n_threads=8,
            verbose=False
        )

    def answer_question(self, context, question):
        prompt = f"""基于以下文本回答问题。
文本内容：{context}
问题：{question}
答案："""
        response = self.llm.create_completion(
            prompt=prompt,
            max_tokens=200,
            temperature=0.3,      # 低温度确保准确性
            stop=["\n\n"]
        )
        return response["choices"][0]["text"].strip()

# 使用示例
qa_system = DocumentQA("./models/llama-2-7b-chat.ggmlv3.q4_0.bin")
context = "Llama.cpp 是一个用 C++ 编写的 LLaMA 模型推理实现，支持 CPU 上的高效推理..."
question = "Llama.cpp 是什么？"
answer = qa_system.answer_question(context, question)
print(f"问题：{question}")
print(f"答案：{answer}")

11.2 代码生成助手

class CodeGenerator:
    def __init__(self, model_path):
        self.llm = Llama(
            model_path=model_path,
            n_ctx=2048,
            n_threads=8,
            verbose=False
        )

    def generate_code(self, description, language="python"):
        prompt = f"""# {language.capitalize()}代码生成
# 要求：{description}
# 代码："""
        response = self.llm.create_completion(
            prompt=prompt,
            max_tokens=300,
            temperature=0.5,
            stop=["# ","\n\n"]
        )
        return response["choices"][0]["text"]

# 使用示例
coder = CodeGenerator("./models/codellama-7b.ggmlv3.q4_0.bin")
description = "写一个函数计算斐波那契数列"
code = coder.generate_code(description,"python")
print(code)

12. 错误处理和调试

12.1 常见错误处理

import traceback

try:
    # 尝试加载模型
    llm = Llama(
        model_path="./models/nonexistent.bin",
        n_ctx=2048
    )
except FileNotFoundError as e:
    print(f"模型文件不存在：{e}")
    # 尝试备用模型
    llm = Llama(
        model_path="./models/backup.bin",
        n_ctx=2048
    )
except Exception as e:
    print(f"加载模型时出错：{e}")
    traceback.print_exc()

# 生成时的错误处理
try:
    response = llm.create_completion(
        prompt="test",
        max_tokens=100
    )
except RuntimeError as e:
    if "out of memory" in str(e).lower():
        print("内存不足，尝试减小上下文大小")
        llm = Llama(
            model_path="./models/model.bin",
            n_ctx=1024       # 减小上下文
        )

12.2 性能监控

import time

def benchmark_generation(llm, prompt, iterations=5):
    """性能基准测试"""
    times = []
    for i in range(iterations):
        start_time = time.time()
        response = llm.create_completion(
            prompt=prompt,
            max_tokens=100,
            temperature=0.7
        )
        end_time = time.time()
        generation_time = end_time - start_time
        times.append(generation_time)
        tokens_per_second = 100 / generation_time
        print(f"迭代 {i+1}: {generation_time:.2f}秒，{tokens_per_second:.2f} tokens/秒")
    
    avg_time = sum(times) / len(times)
    print(f"\n平均生成时间：{avg_time:.2f}秒")
    print(f"平均速度：{100/avg_time:.2f} tokens/秒")

# 运行基准测试
benchmark_generation(llm, "Once upon a time")

13. 与其他库集成

13.1 与 LangChain 集成

from langchain.llms import LlamaCpp
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 创建 LlamaCpp 实例
llm = LlamaCpp(
    model_path="./models/llama-2-7b-chat.ggmlv3.q4_0.bin",
    n_ctx=2048,
    n_threads=8,
    temperature=0.7,
    max_tokens=200,
    verbose=True
)

# 创建提示模板
template = """问题：{question}
回答："""
prompt = PromptTemplate(template=template, input_variables=["question"])

# 创建链
llm_chain = LLMChain(prompt=prompt, llm=llm)

# 运行
question = "什么是人工智能？"
response = llm_chain.run(question)
print(response)

13.2 与 Gradio 集成创建 Web 界面

import gradio as gr

def generate_text(prompt, temperature, max_tokens):
    response = llm.create_completion(
        prompt=prompt,
        temperature=temperature,
        max_tokens=max_tokens
    )
    return response["choices"][0]["text"]

# 创建界面
iface = gr.Interface(
    fn=generate_text,
    inputs=[
        gr.Textbox(label="输入提示", lines=3),
        gr.Slider(0, 1, value=0.7, label="温度"),
        gr.Slider(1, 500, value=100, label="最大 Token 数")
    ],
    outputs=gr.Textbox(label="生成结果", lines=10),
    title="Llama.cpp 文本生成器",
    description="使用 Llama.cpp 模型生成文本"
)

iface.launch(share=True)

14. 最佳实践总结