llama-cpp-agent

已不再维护。请改用 ToolAgents 或其他 Python 代理框架。 []

简介

llama-cpp-agent 框架旨在简化与大型语言模型（LLMs）的交互。它提供了一个用于与 LLMs 聊天、执行函数调用、生成结构化输出、进行检索增强生成以及使用带有工具的代理链处理文本的接口。

该框架使用引导采样技术，将模型输出限制在用户定义的结构内。这样一来，即使未经微调以执行函数调用和 JSON 输出的模型也能做到这一点。

该框架兼容 llama.cpp 服务器、llama-cpp-python 及其服务器，以及 TGI 和 vllm 服务器。

主要特性

• 简单聊天界面：与 LLMs 进行无缝对话。
• 结构化输出：从 LLMs 生成结构化输出（对象）。
• 单次及并行函数调用：使用 LLMs 执行函数。
• RAG - 检索增强生成：结合 colbert 重排序进行检索增强生成。
• 代理链：使用带有工具的代理链处理文本，支持会话式、顺序式和映射式链。
• 引导采样：使大多数 7B 参数量的 LLMs 能够执行函数调用和结构化输出。这得益于语法和 JSON 模式的生成，用于引导采样。
• 多提供商支持：可作为提供商与 llama-cpp-python、llama.cpp 服务器、TGI 服务器和 vllm 服务器配合使用！
• 兼容性：兼容 Python 函数、Pydantic 工具、LlamaIndex 工具以及 OpenAI 工具模式。
• 灵活性：适用于各种应用场景，从日常聊天到特定功能的执行。

目录

• 简介
• 主要特性
• 安装
• 文档
• 快速入门
• Discord 社区
• 使用示例
  • 简单聊天
  • 并行函数调用代理示例
  • 结构化输出
  • RAG - 检索增强生成
  • LlamaIndex 工具示例
  • 顺序链示例
  • 映射链示例
  • 知识图谱创建示例
• 附加信息
  • 预定义消息格式器
  • 创建自定义消息格式器
• 贡献
• 许可证
• 常见问题解答

安装

使用 pip 安装 llama-cpp-agent 框架：

pip install llama-cpp-agent

文档

您可以在[这里]找到最新文档！(https://llama-cpp-agent.readthedocs.io/en/latest/)

快速入门

您可以在[这里]找到快速入门指南！(https://llama-cpp-agent.readthedocs.io/en/latest/get-started/)

Discord 社区

加入 Discord 社区这里

使用示例

llama-cpp-agent 框架提供了大量示例，展示了其功能。以下是一些关键示例：

使用 llama.cpp 服务器后端的简单聊天示例

此示例演示如何使用 llama.cpp 服务器后端与 LLM 模型开始聊天。

查看示例

并行函数调用代理示例

此示例展示了使用 FunctionCallingAgent 类进行并行函数调用。它演示了如何同时定义和执行多个函数。

查看示例

结构化输出

此示例说明如何使用 StructuredOutputAgent 类生成结构化输出对象。它展示了如何从非结构化数据中创建一本书的数据条目。

查看示例

RAG - 检索增强生成

此示例演示了带有 colbert 重排序的检索增强生成（RAG）。它需要安装可选的 rag 依赖项（ragatouille）。

查看示例

LlamaIndex 工具示例

此示例展示了如何使用 LlamaIndex 工具和查询引擎与 FunctionCallingAgent 类一起使用。

查看示例

顺序链示例

此示例演示了如何使用顺序链创建完整的产品发布活动。

查看示例

映射链示例

此示例说明了如何创建映射链，将多篇文章总结为一篇摘要。

查看示例

知识图谱创建示例

此示例基于 Instructor 库中关于 OpenAI 的一个例子，展示了如何使用 llama-cpp-agent 框架创建知识图谱。

查看示例

附加信息

预定义消息格式化器

llama-cpp-agent 框架提供了预定义的消息格式化器，用于为 LLM 模型格式化消息。MessagesFormatterType 枚举定义了可用的格式化器：

• MessagesFormatterType.MISTRAL：使用 MISTRAL 格式化消息。
• MessagesFormatterType.CHATML：使用 CHATML 格式化消息。
• MessagesFormatterType.VICUNA：使用 VICUNA 格式化消息。
• MessagesFormatterType.LLAMA_2：使用 LLAMA 2 格式化消息。
• MessagesFormatterType.SYNTHIA：使用 SYNTHIA 格式化消息。
• MessagesFormatterType.NEURAL_CHAT：使用 NEURAL CHAT 格式化消息。
• MessagesFormatterType.SOLAR：使用 SOLAR 格式化消息。
• MessagesFormatterType.OPEN_CHAT：使用 OPEN CHAT 格式化消息。
• MessagesFormatterType.ALPACA：使用 ALPACA 格式化消息。
• MessagesFormatterType.CODE_DS：使用 CODE DS 格式化消息。
• MessagesFormatterType.B22：使用 B22 格式化消息。
• MessagesFormatterType.LLAMA_3：使用 LLAMA 3 格式化消息。
• MessagesFormatterType.PHI_3：使用 PHI 3 格式化消息。
• MessagesFormatterType.AUTOCODER：使用 Autocoder 格式化消息。
• MessagesFormatterType.DEEP_SEEK_CODER_2：使用 DeepSeek Coder v2 格式化消息。

创建自定义消息格式化器

你可以通过使用所需参数实例化 MessagesFormatter 类来创建自己的自定义消息格式化器：

from llama_cpp_agent.messages_formatter import MessagesFormatter, PromptMarkers, Roles

custom_prompt_markers = {
    Roles.system: PromptMarkers("<|system|>", "<|endsystem|>"),
    Roles.user: PromptMarkers("<|user|>", "<|enduser|>"),
    Roles.assistant: PromptMarkers("<|assistant|>", "<|endassistant|>"),
    Roles.tool: PromptMarkers("<|tool|>", "<|endtool|>"),
}

custom_formatter = MessagesFormatter(
    pre_prompt="",
    prompt_markers=custom_prompt_markers,
    include_sys_prompt_in_first_user_message=False,
    default_stop_sequences=["<|endsystem|>", "<|enduser|>", "<|endassistant|>", "<|endtool|>"]
)

贡献

我们欢迎对 llama-cpp-agent 框架的贡献！如果您想参与贡献，请遵循以下指南：

1. 克隆仓库并基于 master 分支创建您的分支。
2. 确保您的代码符合项目的编码风格和规范。
3. 编写清晰、简洁的提交信息和拉取请求描述。
4. 在提交拉取请求之前，彻底测试您的更改。
5. 向 master 分支发起拉取请求。

如果您遇到任何问题或有改进建议，请在 GitHub 仓库 上提交问题。

许可证

llama-cpp-agent 框架采用 MIT 许可证 发布。

常见问题解答

问：如何安装 RAG 的可选依赖项？
答：要使用 RAGColbertReranker 类和 RAG 示例，您需要安装 RAG 的可选依赖项（ragatouille）。可以通过运行 pip install llama-cpp-agent[rag] 来完成安装。

问：我可以为 llama-cpp-agent 项目做出贡献吗？
答：当然可以！我们非常欢迎社区的贡献。请参阅“贡献”部分，了解如何参与贡献的指南。

问：llama-cpp-agent 是否与最新版本的 llama-cpp-python 兼容？
答：是的，llama-cpp-agent 旨在与最新版本的 llama-cpp-python 配合使用。不过，如果您遇到任何兼容性问题，请在 GitHub 仓库中提交问题。

llama-cpp-agent 快速上手指南

⚠️ 重要提示：本项目已停止维护（Not Longer Maintained）。作者建议迁移至 ToolAgents 或其他 Python 智能体框架。本指南仅用于参考或维护现有项目。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.8 或更高版本
• 前置依赖：
  • pip 包管理工具
  • （可选）后端服务：本项目支持多种后端，如 llama.cpp server, TGI, vllm 等。若使用本地模型，需确保已部署相应的推理服务或安装 llama-cpp-python。

安装步骤

使用 pip 直接安装核心库：

pip install llama-cpp-agent

可选依赖安装： 如果您需要使用检索增强生成（RAG）功能（包含 ColBERT 重排序），请安装额外依赖：

pip install llama-cpp-agent[rag]

💡 国内加速建议：若下载速度较慢，可使用国内镜像源安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple llama-cpp-agent

基本使用

llama-cpp-agent 的核心优势在于通过引导采样（Guided Sampling）让未微调的模型也能执行函数调用和结构化输出。以下是一个最简单的聊天示例，展示如何连接后端并发起对话。

简单聊天示例

此示例演示如何使用 llama.cpp 服务器后端与 LLM 进行对话。

from llama_cpp_agent import LlamaCppAgent
from llama_cpp_agent.messages_formatter import MessagesFormatterType

# 初始化代理
# 注意：请确保您的 llama.cpp server 正在运行，并替换为正确的地址
agent = LlamaCppAgent(
    host="localhost",
    port=8080,
    messages_formatter_type=MessagesFormatterType.LLAMA_3, # 根据模型选择对应的格式，如 LLAMA_3, MISTRAL 等
)

# 发送消息并获取回复
user_message = "你好，请介绍一下你自己。"
response = agent.chat(user_message)

print(response)

关键配置说明

• messages_formatter_type：必须根据您的模型类型选择合适的预定义格式器（如 LLAMA_3, MISTRAL, CHATML 等），否则模型可能无法正确理解指令。
• 后端兼容性：该框架不仅支持 llama-cpp-python，还兼容 TGI 和 vllm 服务器，只需调整连接参数即可。

更多高级用法（如并行函数调用、结构化输出、RAG 等）请参考官方文档：https://llama-cpp-agent.readthedocs.io