【LangChain】langchain_community.llms.LlamaCpp 类的常用方法和属性

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

本文基于 LangChain 0.3.x，详细介绍 langchain_community.llms.LlamaCpp 的核心方法和属性，包括功能、参数和使用场景，并提供一个独立示例，展示如何使用 LlamaCpp 的方法构建一个简单的问答应用，示例使用本地 GGUF 模型和 langchain_core.prompts.PromptTemplate。

---

LlamaCpp 简介

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

功能：

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

初始化参数（常用属性）：

• model_path（str，必填）：GGUF 模型文件路径，如 /path/to/llama-2-7b-chat.Q4_0.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）：是否打印详细日志。

适用场景：

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

---

常用方法和属性

以下是 langchain_community.llms.LlamaCpp 的常用方法和属性，基于源码（langchain_community/llms/llamacpp.py）和官方文档（LlamaCpp）。列出方法签名、参数、返回值、功能描述及使用场景。

1. 方法

__call__(prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str

• 功能：直接调用模型，输入提示生成文本（同步）。
• 参数：
  • prompt：输入提示字符串。
  • stop：可选停止词列表，覆盖初始化时的 stop。
  • **kwargs：附加参数，如 max_tokens。
• 返回值：str，生成的文本。
• 使用场景：
  • 快速测试模型输出。
  • 简单问答或文本生成。
• 示例：

  from langchain_community.llms import LlamaCpp
  llm = LlamaCpp(model_path="/models/llama-2-7b-chat.Q4_0.gguf")
  response = llm("什么是人工智能？")
  print(response)  # 输出: 人工智能是...
  

invoke(input: str, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs) -> str

• 功能：同步调用模型，生成文本（LCEL 标准方法）。
• 参数：
  • input：输入提示字符串。
  • config：运行时配置，如 max_tokens。
  • stop：停止词列表。
  • **kwargs：附加参数。
• 返回值：str，生成的文本。
• 使用场景：
  • 在 LCEL 链中使用。
  • 替代 __call__，更符合现代 LangChain API。
• 示例：

  response = llm.invoke("什么是人工智能？", stop=["\n"])
  print(response)
  

stream(input: str, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs) -> Iterator[str]

• 功能：流式生成文本，逐块返回结果。
• 参数：
  • input：输入提示字符串。
  • config：运行时配置。
  • stop：停止词列表。
  • **kwargs：附加参数。
• 返回值：Iterator[str]，生成文本的迭代器。
• 使用场景：
  • 实时显示生成结果（如聊天界面）。
  • 处理长输出，节省内存。
• 示例：

  for chunk in llm.stream("人工智能有哪些应用？"):
      print(chunk, end="", flush=True)
  

ainvoke(input: str, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs) -> Awaitable[str]

• 功能：异步调用模型，生成文本。
• 参数：同 invoke。
• 返回值：Awaitable[str]，异步返回生成的文本。
• 使用场景：
  • 异步应用（如 Web 服务）。
  • 高并发场景。
• 示例：

  import asyncio
  async def run():
      response = await llm.ainvoke("什么是人工智能？")
      print(response)
  asyncio.run(run())
  

astream(input: str, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs) -> AsyncIterator[str]

• 功能：异步流式生成文本，逐块返回。
• 参数：同 stream。
• 返回值：AsyncIterator[str]，异步生成文本的迭代器。
• 使用场景：
  • 异步实时输出（如 WebSocket 聊天）。
  • 高并发流式处理。
• 示例：

  async def run_stream():
      async for chunk in llm.astream("人工智能有哪些应用？"):
          print(chunk, end="", flush=True)
  asyncio.run(run_stream())
  

generate(prompts: List[str], **kwargs) -> LLMResult

• 功能：批量生成文本，处理多个提示。
• 参数：
  • prompts：提示字符串列表。
  • **kwargs：附加参数，如 stop。
• 返回值：LLMResult，包含生成结果和元数据。
• 使用场景：
  • 批量处理多个输入。
  • 测试模型在不同提示下的表现。
• 示例：

  results = llm.generate(["什么是人工智能？", "它有哪些应用？"])
  for generation in results.generations:
      print(generation[0].text)
  

2. 属性

model_path: str

• 功能：GGUF 模型文件的路径。
• 类型：str
• 使用场景：
  • 验证模型加载路径。
  • 调试模型初始化问题。
• 示例：

  print(llm.model_path)  # 输出: /models/llama-2-7b-chat.Q4_0.gguf
  

temperature: float

• 功能：控制生成随机性，值越低越确定性（0~1）。
• 类型：float
• 使用场景：
  • 调整输出风格（低 temperature 更严谨，高更创意）。
  • 动态修改：

    llm.temperature = 0.5
    

• 示例：

  print(llm.temperature)  # 输出: 0.7
  

max_tokens: int

• 功能：最大输出 token 数。
• 类型：int
• 使用场景：
  • 控制输出长度。
  • 避免过长生成。
• 示例：

  llm.max_tokens = 1024
  print(llm.max_tokens)  # 输出: 1024
  

n_ctx: int

• 功能：上下文窗口大小，决定模型能处理的输入长度。
• 类型：int
• 使用场景：
  • 处理长对话或复杂提示（需更多内存）。
  • 调试上下文截断问题。
• 示例：

  print(llm.n_ctx)  # 输出: 2048
  

n_gpu_layers: int

• 功能：分配到 GPU 的层数，0 表示仅 CPU。
• 类型：int
• 使用场景：
  • 优化推理性能（需 GPU 支持）。
  • 调试 GPU 配置。
• 示例：

  print(llm.n_gpu_layers)  # 输出: 0
  

stop: Optional[List[str]]

• 功能：停止词列表，生成到这些词时停止。
• 类型：Optional[List[str]]
• 使用场景：
  • 控制输出终止（如避免多余换行）。
  • 动态设置：

    llm.stop = ["\n", "###"]
    

• 示例：

  print(llm.stop)  # 输出: None 或 ["\n"]
  

方法和属性总结

类型	名称	功能	典型场景
方法	__call__	同步生成文本	快速测试
方法	invoke	同步生成（LCEL）	LCEL 链
方法	stream	流式生成	实时输出
方法	ainvoke	异步生成	异步应用
方法	astream	异步流式生成	实时 Web 服务
方法	generate	批量生成	批量处理
属性	model_path	模型路径	调试加载
属性	temperature	随机性控制	输出风格
属性	max_tokens	输出长度	控制生成
属性	n_ctx	上下文窗口	长对话
属性	n_gpu_layers	GPU 层数	性能优化
属性	stop	停止词	终止控制

推荐方法：

• invoke：标准同步调用，适合 LCEL 链。
• stream：实时输出，适合交互应用。
• astream：异步流式，适合 Web 服务。

推荐属性：

• temperature：调整输出风格。
• max_tokens：控制输出长度。
• n_ctx：支持长上下文。

---

使用 LlamaCpp 的问答示例

以下是一个独立示例，展示 LlamaCpp 的常用方法（invoke, stream）和属性（temperature, max_tokens），结合 langchain_core.prompts.PromptTemplate 构建一个简单问答应用，回答关于区块链的问题。

准备文件：

• 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,  # 0 表示仅 CPU
    n_batch=512,
    temperature=0.7,
    max_tokens=512,
    n_ctx=2048,
    verbose=False
)

# 检查属性
print("模型属性：")
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)

# 使用 stream 方法
print("\n使用 stream 方法：")
for chunk in qa_chain.stream("区块链有哪些应用？"):
    print(chunk, end="", flush=True)
print()

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

模型属性：
Model Path: /models/llama-2-7b-chat.Q4_0.gguf
Temperature: 0.7
Max Tokens: 512

使用 invoke 方法：
区块链是分布式账本技术，通过加密保证数据安全和透明。

使用 stream 方法：
区块链的应用包括加密货币、金融结算和供应链管理。

代码说明

1. LlamaCpp 初始化：
   • 加载 GGUF 模型，运行于 CPU（n_gpu_layers=0）。
   • 设置 temperature=0.7、max_tokens=512、n_ctx=2048。
2. 属性检查：
   • 打印 model_path、temperature、max_tokens，验证配置。
3. 方法使用：
   • invoke：同步生成答案，回答 “什么是区块链？”。
   • stream：流式生成，实时输出 “区块链有哪些应用？”。
4. 提示模板：
   • 使用 langchain_core.prompts.PromptTemplate，格式化问题。
5. 问答链：
   • LCEL 链组合 prompt、llm 和 StrOutputParser。
6. 主题：
   • 示例聚焦区块链问答，简单且独立。

运行要求：

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

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

---

注意事项

1. LLaMA 模型：
   • 下载 GGUF 模型，推荐量化版本（如 Q4_0，约 4GB）。
   • 验证路径：

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

   • GPU 加速：设 n_gpu_layers=40（需 6GB+ 显存）。
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. 性能优化：
   • LLM：
     • 增加 n_ctx（如 4096）支持长上下文。
     • 调整 n_batch（如 1024）提高吞吐量。
     • 启用 GPU：n_gpu_layers=40。
   • 生成：
     • 降低 temperature（如 0.5）提高确定性。
     • 设置 stop=["\n"] 控制输出终止。
4. 错误调试：
   • 模型加载失败：
     • 检查 model_path 和文件完整性。
     • 确保内存足够（7B 模型需 8GB+ RAM）。
   • 输出截断：
     • 增加 max_tokens（如 1024）。
     • 检查 n_ctx 是否足够。
   • 慢速推理：
     • 启用 GPU 或优化 n_batch。
     • 使用更小模型（如 Q2_K）。
5. 流式输出：
   • stream 和 astream 适合交互应用，但需确保终端或 UI 支持实时显示。

---

常见问题

Q1：invoke 和 __call__ 的区别？
A：invoke 是 LCEL 标准方法，支持配置（如 stop）和链集成；__call__ 是快捷调用，功能类似但更简单。

Q2：如何加速 LlamaCpp 推理？
A：启用 GPU（n_gpu_layers > 0），使用量化模型（如 Q4_0），优化 n_batch 和 n_threads：

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

Q3：如何处理长对话？
A：增加 n_ctx（如 4096），结合 RunnableWithMessageHistory：

from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_community.chat_message_histories import ChatMessageHistory
chain_with_history = RunnableWithMessageHistory(
    runnable=qa_chain,
    get_session_history=lambda session_id: ChatMessageHistory()
)

Q4：可以结合 RAG 吗？
A：可以，使用向量存储（如 Milvus）：

from langchain_milvus import Milvus
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()
)

---

总结

langchain_community.llms.LlamaCpp 的常用方法包括：

• invoke：同步生成，适合 LCEL 链。
• stream：流式生成，实时输出。
• ainvoke/astream：异步调用，适合 Web 服务。
• generate：批量处理。

常用属性包括：

• model_path：模型路径。
• temperature：随机性控制。
• max_tokens：输出长度。
• n_ctx：上下文窗口。