【LangChain】langchain_community.llms.LlamaCpp 的使用方式

langchain_community.llms.LlamaCpp 是 LangChain 提供的本地 LLM（大型语言模型）包装器，基于 LLaMA.cpp 库，支持运行本地量化的 LLaMA 模型（GGUF 格式）。

本文基于 LangChain 0.3.x，详细介绍 langchain_community.llms.LlamaCpp 的初始化、配置和使用方式，包括核心功能、参数、方法和典型场景，并提供一个独立示例，展示如何使用 LlamaCpp 结合 langchain_core.prompts.PromptTemplate 构建一个简单的问答应用，示例使用本地 GGUF 模型，回答关于加密货币的问题。

---

LlamaCpp 简介

langchain_community.llms.LlamaCpp 是 LangChain 的 LLM 类，继承自 langchain_core.language_models.llms.BaseLLM，通过 LLaMA.cpp 库加载和运行本地 GGUF 格式的 LLaMA 模型。它适合隐私敏感场景或无需云服务的应用，常用于对话、问答、RAG 系统等。

核心功能：

• 本地生成文本，支持对话、问答等任务。
• 支持高效推理，兼容 CPU 和 GPU（通过 CUDA 或 Metal）。
• 集成 LangChain 链（如 LCEL），可与提示模板、向量存储结合。
• 支持同步、异步和流式生成。

适用场景：

• 本地问答或对话系统，无需云 API。
• 隐私敏感应用（如金融、医疗）。
• 开发测试或资源受限环境。

与云 LLM（如 OpenAI）对比：

• LlamaCpp：本地运行，免费，需硬件支持；性能依赖模型和设备。
• OpenAI：云服务，高性能，需 API 密钥和网络。

---

使用方式

以下是 langchain_community.llms.LlamaCpp 的使用方式，涵盖初始化、配置、调用方法和典型应用场景，基于源码（langchain_community/llms/llamacpp.py）和官方文档（LlamaCpp）。

1. 安装依赖

要使用 LlamaCpp，需安装 LangChain 和 LLaMA.cpp 的 Python 绑定：

pip install --upgrade langchain langchain-community llama-cpp-python

• GPU 支持（可选）：安装带 CUDA 的 llama-cpp-python：

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

• 示例依赖（提示模板）：

  pip install langchain-core
  

2. 准备 LLaMA 模型

• 下载模型：获取 GGUF 格式的 LLaMA 模型，如 llama-2-7b-chat.Q4_0.gguf。
  • 推荐：HuggingFace 的 TheBloke/Llama-2-7B-Chat-GGUF（约 4GB）。
  • 存储路径：如 /models/llama-2-7b-chat.Q4_0.gguf。
• 验证：确保模型文件存在且可读：

  import os
  assert os.path.exists("/models/llama-2-7b-chat.Q4_0.gguf")
  

3. 初始化 LlamaCpp

创建 LlamaCpp 实例，指定模型路径和其他配置参数。

常用初始化参数：

• model_path（str，必填）：GGUF 模型文件路径。
• n_gpu_layers（int，默认 0）：分配到 GPU 的层数，0 表示仅 CPU。-1表示所有GPU层数。
• n_batch（int，默认 512）：批处理大小，影响推理速度。
• temperature（float，默认 0.8）：控制生成随机性，0~1。
• max_tokens（int，默认 512）：最大输出 token 数。
• n_ctx（int，默认 512）：上下文窗口大小。
• top_p（float，默认 0.95）：Top-p 采样参数。
• top_k（int，默认 40）：Top-k 采样参数。
• stop（List[str]，默认 None）：停止词列表。
• verbose（bool，默认 False）：是否打印详细日志。

示例初始化：

from langchain_community.llms import LlamaCpp
llm = LlamaCpp(
    model_path="/models/llama-2-7b-chat.Q4_0.gguf",
    n_gpu_layers=0,  # 仅 CPU
    n_batch=512,
    temperature=0.7,
    max_tokens=512,
    n_ctx=2048,
    verbose=False
)

GPU 配置（若有 GPU）：

llm = LlamaCpp(
    model_path="/models/llama-2-7b-chat.Q4_0.gguf",
    n_gpu_layers=40,  # 分配 40 层到 GPU
    n_batch=1024,
    temperature=0.7,
    max_tokens=512,
    n_ctx=2048
)

4. 调用 LlamaCpp

LlamaCpp 提供多种调用方式，支持同步、异步和流式生成。

同步调用（invoke 或 __call__）

• 方法：invoke(input: str, stop: Optional[List[str]] = None, **kwargs) -> str
• 功能：输入提示，同步生成文本。
• 示例：

  response = llm.invoke("什么是加密货币？")
  print(response)  # 输出: 加密货币是...
  

流式生成（stream）

• 方法：stream(input: str, stop: Optional[List[str]] = None, **kwargs) -> Iterator[str]
• 功能：逐块返回生成结果，适合实时显示。
• 示例：

  for chunk in llm.stream("加密货币有哪些类型？"):
      print(chunk, end="", flush=True)
  

异步调用（ainvoke）

• 方法：ainvoke(input: str, stop: Optional[List[str]] = None, **kwargs) -> Awaitable[str]
• 功能：异步生成，适合高并发场景。
• 示例：

  import asyncio
  async def run():
      response = await llm.ainvoke("什么是区块链？")
      print(response)
  asyncio.run(run())
  

异步流式（astream）

• 方法：astream(input: str, stop: Optional[List[str]] = None, **kwargs) -> AsyncIterator[str]
• 功能：异步逐块生成，适合 Web 服务。
• 示例：

  async def run_stream():
      async for chunk in llm.astream("加密货币的优点是什么？"):
          print(chunk, end="", flush=True)
  asyncio.run(run_stream())
  

批量生成（generate）

• 方法：generate(prompts: List[str], **kwargs) -> LLMResult
• 功能：处理多个提示，批量生成。
• 示例：

  results = llm.generate(["什么是加密货币？", "它有哪些应用？"])
  for generation in results.generations:
      print(generation[0].text)
  

5. 结合 LangChain 链

LlamaCpp 常与 LCEL（LangChain Expression Language）结合，使用提示模板和输出解析器构建链。

常用组件：

• langchain_core.prompts.PromptTemplate：格式化提示。
• langchain_core.output_parsers.StrOutputParser：解析输出为字符串。
• langchain_core.runnables.RunnablePassthrough：传递输入。

示例链：

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough
prompt = PromptTemplate(
    template="问题：{question}\n回答：",
    input_variables=["question"]
)
chain = prompt | llm | StrOutputParser()
response = chain.invoke({"question": "什么是加密货币？"})

6. 典型使用场景

• 简单问答：直接调用 invoke 或 __call__。
• 实时对话：使用 stream 或 astream。
• RAG 系统：结合向量存储（如 Milvus），使用 LCEL 链。
• 对话历史：结合 RunnableWithMessageHistory。
• 批量处理：使用 generate 处理多提示。

---

使用 LlamaCpp 的问答示例

以下是一个独立示例，展示 LlamaCpp 的使用方式，结合 langchain_core.prompts.PromptTemplate 构建一个简单问答应用，回答关于加密货币的问题。示例使用 invoke 和 stream 方法，动态调整 temperature。

准备文件：

• LLaMA 模型：下载 GGUF 模型（如 llama-2-7b-chat.Q4_0.gguf），放置在本地路径（如 /models/llama-2-7b-chat.Q4_0.gguf）。
  • 推荐：TheBloke/Llama-2-7B-Chat-GGUF（约 4GB）。

代码：

import os
from langchain_community.llms import LlamaCpp
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough

# 初始化 LlamaCpp LLM
llm = LlamaCpp(
    model_path="/models/llama-2-7b-chat.Q4_0.gguf",
    n_gpu_layers=0,  # 仅 CPU
    n_batch=512,
    temperature=0.7,
    max_tokens=512,
    n_ctx=2048,
    stop=["\n"],
    verbose=False
)

# 检查配置
print("LlamaCpp 配置：")
print(f"Model Path: {llm.model_path}")
print(f"Temperature: {llm.temperature}")
print(f"Max Tokens: {llm.max_tokens}")

# 定义 PromptTemplate
prompt = PromptTemplate(
    template="""你是一个加密货币专家，回答以下问题：
问题：{question}
回答：""",
    input_variables=["question"]
)

# 创建问答链
qa_chain = (
    {"question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

# 使用 invoke 方法（同步）
print("\n使用 invoke 方法：")
response = qa_chain.invoke("什么是加密货币？")
print(response)

# 调整 temperature，测试不同风格
llm.temperature = 0.3  # 更确定性
print("\n使用 invoke 方法（低 temperature）：")
response = qa_chain.invoke("加密货币有哪些类型？")
print(response)

# 使用 stream 方法（流式）
print("\n使用 stream 方法：")
for chunk in qa_chain.stream("加密货币的优点是什么？"):
    print(chunk, end="", flush=True)
print()

输出示例（取决于模型和硬件，实际输出可能略有不同）：

LlamaCpp 配置：
Model Path: /models/llama-2-7b-chat.Q4_0.gguf
Temperature: 0.7
Max Tokens: 512

使用 invoke 方法：
加密货币是基于区块链的数字货币，使用加密技术确保安全。

使用 invoke 方法（低 temperature）：
加密货币的类型包括比特币、以太坊和稳定币。

使用 stream 方法：
加密货币的优点包括去中心化、透明性和低交易成本。

代码说明

1. 初始化：
   • 加载 GGUF 模型，运行于 CPU（n_gpu_layers=0）。
   • 配置 temperature=0.7、max_tokens=512、n_ctx=2048、stop=["\n"]。
2. 配置检查：
   • 打印 model_path、temperature、max_tokens，验证设置。
3. 提示模板：
   • 使用 langchain_core.prompts.PromptTemplate，格式化加密货币问题。
4. 问答链：
   • LCEL 链组合 prompt、llm 和 StrOutputParser。
   • 使用 invoke（同步）和 stream（流式）生成答案。
5. 动态调整：
   • 修改 temperature 到 0.3，展示更确定性的输出。
6. 主题：
   • 示例聚焦加密货币问答，简单且独立。

运行要求：

• LLaMA 模型文件（如 llama-2-7b-chat.Q4_0.gguf）存在且路径正确。
• 硬件支持：至少 8GB 内存（CPU 运行），推荐 GPU 加速。
• 安装依赖：

  pip install --upgrade langchain langchain-core langchain-community llama-cpp-python
  

---

注意事项

1. 模型准备：
   • 下载量化模型（如 Q4_0），减少内存需求。
   • 7B 模型需 8GB+ RAM，GPU 加速需 6GB+ 显存（n_gpu_layers=40）。
   • 验证路径：

     import os
     assert os.path.exists("/models/llama-2-7b-chat.Q4_0.gguf")
     

2. 依赖：
   • 安装：

     pip install --upgrade langchain langchain-core langchain-community llama-cpp-python
     

   • GPU 支持：

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

3. 性能优化：
   • 推理速度：
     • 启用 GPU：n_gpu_layers=40。
     • 增加 n_batch（如 1024）。
     • 使用更小模型（如 Q2_K）。
   • 上下文：
     • 增加 n_ctx（如 4096）支持长对话。
     • 确保提示简洁，避免超限。
   • 输出：
     • 降低 temperature（如 0.3）提高确定性。
     • 设置 stop=["\n", "###"] 控制终止。
4. 错误调试：
   • 模型加载失败：
     • 检查 model_path 和文件完整性。
     • 确保内存足够。
   • 输出截断：
     • 增加 max_tokens（如 1024）。
     • 检查 n_ctx 是否足够。
   • 慢速推理：
     • 启用 GPU 或优化 n_batch。
     • 验证模型量化级别。
5. 提示设计：
   • 确保提示清晰，避免歧义。
   • 测试不同 temperature 和 top_p 值。

---

常见问题

Q1：如何选择合适的 n_ctx 和 max_tokens？
A：

• n_ctx：根据输入提示和预期输出长度设置（如 2048 或 4096），需更多内存。
• max_tokens：控制输出长度（如 512），避免过长生成。

Q2：如何支持对话历史？
A：结合 RunnableWithMessageHistory：

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_community.chat_message_histories import ChatMessageHistory
prompt = ChatPromptTemplate.from_messages([
    MessagesPlaceholder(variable_name="chat_history"),
    ("human", "{question}")
])
chain = prompt | llm | StrOutputParser()
chain_with_history = RunnableWithMessageHistory(
    chain,
    lambda session_id: ChatMessageHistory(),
    input_messages_key="question",
    history_messages_key="chat_history"
)

Q3：如何结合 RAG？
A：使用向量存储（如 Milvus）：

from langchain_milvus import Milvus
from langchain_core.prompts import PromptTemplate
vectorstore = Milvus(...)
prompt = PromptTemplate(
    template="上下文：{context}\n问题：{question}\n回答：",
    input_variables=["context", "question"]
)
chain = (
    {"context": vectorstore.as_retriever() | lambda docs: "\n".join(d.page_content for d in docs), "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

Q4：如何处理慢速推理？
A：

• 启用 GPU（n_gpu_layers > 0）。
• 使用更高量化模型（如 Q2_K）。
• 优化 n_batch（如 1024）：

  llm = LlamaCpp(..., n_batch=1024, n_threads=8)
  

---

总结

langchain_community.llms.LlamaCpp 的使用方式包括：

• 初始化：指定 model_path、GPU 层数、上下文大小等。
• 调用：支持 invoke（同步）、stream（流式）、ainvoke/astream（异步）、generate（批量）。
• 链集成：结合 PromptTemplate 和 LCEL 构建问答或 RAG 系统。
• 优化：调整 temperature、max_tokens、n_ctx，启用 GPU。