llama-stack-apps

本仓库展示了基于 Llama Stack 构建的应用程序示例。自 Llama 3.1 起，您可以构建具备以下能力的智能代理应用：

• 将任务分解并执行多步推理。
• 使用工具执行某些操作：
  • 内置工具：模型内置了对搜索或代码解释器等工具的知识；
  • 零样本工具调用：模型能够通过先前未见过的上下文工具定义学会调用工具。
• 利用 Llama Guard 等模型提供系统级安全保护。

一个智能代理应用需要几个关键组件：

• 能够在底层 Llama 系列模型上运行推理；
• 能够使用 Llama Guard 系列模型进行安全检查；
• 能够执行工具，包括代码执行环境，并利用模型的多步推理流程进行循环。

所有这些组件如今都由单一的 Llama Stack 发行版提供。Llama Stack 定义并标准化了这些组件以及许多其他使生成式 AI 应用开发更加顺畅所需的组件。随后，这些 API 的各种实现会通过 Llama Stack 发行版 组合在一起。

开始使用 Llama Stack 应用

要开始使用 Llama Stack 应用，您需要：

1. 安装先决条件
2. 启动 Llama Stack 服务器
3. 将您的客户端智能代理应用连接到 Llama Stack 服务器

启动后，您只需将智能代理应用指向该服务器的 URL 即可（例如 http://localhost:8321）。

1. 安装先决条件

Python 包

我们建议创建一个独立的 conda Python 环境。

# 创建并激活虚拟环境
ENV=stack
conda create -n $ENV python=3.10
cd <path-to-llama-stack-apps-repo>
conda activate $ENV

# 安装依赖
pip install -r requirements.txt

这将安装所有必要的依赖，用于 (1) 构建并启动 Llama Stack 服务器；(2) 将您的客户端应用连接到 Llama Stack 服务器。

2. 启动 Llama Stack 服务器

请参阅我们的 llama-stack 仓库中的 入门指南，以设置 Llama Stack 发行版并运行服务器来提供 API 端点。您应该有一个可用于构建客户端应用的服务器端点。

一旦服务器启动，您应该会看到如下输出——

...
正在监听 :::8321
INFO:     已启动服务器进程 [587053]
INFO:     等待应用程序启动。
INFO:     应用程序启动完成。
INFO:     Uvicorn 正在 http://[::]:8321 上运行（按 CTRL+C 退出）

3. 测试智能代理演示脚本

我们已构建了与 Stack 服务器交互的示例演示脚本。

在服务器运行时，您可以运行一个简单的智能代理进行测试。

此示例需要 Tavily Search 的 API 密钥。您需要将其设置为环境变量 TAVILY_SEARCH_API_KEY。

Linux/Mac

export TAVILY_SEARCH_API_KEY=[KEY]

运行命令：

python -m examples.agents.hello localhost 8321

您将看到类似如下的输出——

> 创建了 agent_id=d050201b-0ca1-4abd-8eee-3cba2b8c0fbc 的智能代理
用户> 你好
shield_call> 无违规
inference> 今天有什么可以帮您的吗？
shield_call> 无违规
用户> 请告诉我2024年NBA西部半决赛获胜球队中有哪些球员，麻烦使用工具查询一下。
shield_call> 无违规
inference> brave_search.call(query="2024年NBA西部半决赛获胜球队球员")
tool_execution> 工具：brave_search 参数：{'query': '2024年NBA西部半决赛获胜球队球员'}
tool_execution> 工具：brave_search 响应：{"query": "2024年NBA西部半决赛获胜球队球员", "top_k": [{"title": "2024年NBA西部半决赛——独行侠对阵雷霆 | Basketball-Reference.com", "url": "https://www.basketball-reference.com/playoffs/2024-nba-western-conference-semifinals-mavericks-vs-thunder.html", "description": "关于<strong>2024</strong>年<strong>NBA</strong><strong>西部</strong><strong>半决赛</strong>——独行侠对阵雷霆的总结与统计数据", "type": "search_result"}, {"title": "2024年NBA季后赛——维基百科", "url": "https://en.wikipedia.org/wiki/2024_NBA_playoffs", "description": "年仅20岁96天的……成为<NBA>历史上最年轻的<strong>球员</strong>，在季后赛比赛中拿到10分以上、15个篮板以上的成绩，这一壮举发生在5月18日独行侠对阵雷霆的<strong>西部</strong><strong>半决赛</strong>第6场比赛中。森林狼队则在第七场比赛中逆转掘金队，成功晋级，这是<NBA>季后赛历史上最大的一次第七场大逆转。卫冕冠军掘金队不敌明尼苏达森林狼队，因此<strong>2024</strong>年的季后赛标志着……", "type": "search_result"}, {"title": "2024年NBA季后赛｜官方赛程、对阵表及系列赛安排", "url": "https://www.nba.com/playoffs/2024", "description": "官方的<strong>2024</strong>年<NBA>季后赛网站。最新新闻、赛程、对阵、精彩集锦、赛程表等信息。", "type": "search_result"}]}
shield_call> 无违规
inference> 根据提供的搜索结果，2024年NBA西部半决赛获胜球队的球员并未明确列出。不过，搜索结果表明独行侠队确实在西部半决赛中对阵雷霆队，并且最终赢得了系列赛。
shield_call> 无违规

启动应用并与服务器交互

现在 Stack 服务器已经搭建完毕，接下来就是使用 Agents API 运行一个智能代理应用。

我们已构建了示例脚本、笔记本以及一个 UI 聊天界面（使用 Gradio！），以帮助您快速上手。

启动一个本地应用并与之交互，运行以下命令：

PYTHONPATH=. python examples/agent_store/app.py localhost 8321

此外，您还可以为自定义工具设置 API 密钥：

• WolframAlpha：存储在 WOLFRAM_ALPHA_API_KEY 环境变量中
• Brave Search：存储在 BRAVE_SEARCH_API_KEY 环境变量中

您可以在 Agent Store README.md 中查看其他交互方式。

创建代理系统并与 Stack 服务器交互

注意：请确保 Stack 服务器仍在运行。

cd <llama-stack-apps-repo 的路径>
conda activate $ENV
llama stack run <名称> # 如果尚未启动
python -m examples.agents.rag_with_vector_db localhost 8321

您应该会在终端看到如下输出——

找到可用的防护盾：['meta-llama/Llama-Guard-3-8B']
正在使用模型：meta-llama/Llama-3.1-405B-Instruct
已为 Agent(0cfe05a8-cb97-430f-bec6-b1c7d42c712a) 创建 session_id=cdb8a978-0085-4f3d-a976-939ba2b19de9
shield_call> 无违规
memory_retrieval> 从向量数据库中检索到上下文：['test_vector_db']。
====
以下是检索到的相关文档：
=== 开始检索到的上下文 ===
 id:编号1；内容：_
Llama2 的模板，以更好地支持多轮对话。同样的文本在 Lla...
>
inference> 根据提供的文档，以下是解释的前 5 个主题：

* 使用聊天数据对 Llama3 进行微调
* 从 Llama2 到 Llama3 的模板变更
* 对提示模板和特殊标记进行分词
* 在自定义聊天数据集上进行微调
* 将提示模板用于特定任务
shield_call> 无违规

...

如有任何疑问，请随时联系我们。

Llama Stack 客户端 SDK

• 请查看我们的客户端 SDK，用于连接到 Llama Stack 服务器，您可以选择 Python、Node、Swift 和 Kotlin 等编程语言，快速构建您的应用程序。

使用 VirtualEnv 而非 Conda

[!NOTE] 虽然您可以使用 venv 运行这些应用，但安装发行版时仍需使用 conda。

在 Linux 上

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate

在 Windows 上

# 创建并激活虚拟环境
python -m venv venv
venv\Scripts\activate  # 对于命令提示符
# 或
.\venv\Scripts\Activate.ps1  # 对于 PowerShell
# 或
source venv/Scripts/activate  # 对于 Git Bash

此后步骤（包括运行 pip install -r requirements.txt 安装依赖）保持不变。

llama-stack-apps 快速上手指南

环境准备

系统要求

• 操作系统：Linux、macOS 或 Windows（推荐使用 Linux/macOS）
• Python 版本：3.10 或更高版本
• 依赖项：需安装 Conda 或 VirtualEnv（推荐使用 Conda）

前置依赖

确保已安装以下工具：

• Conda（推荐）或 VirtualEnv
• Git（用于克隆仓库）
• Python 3.10+

💡 提示：如需加速依赖包下载，可使用国内镜像源，例如：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

---

安装步骤

1. 克隆项目仓库

git clone https://github.com/meta-llama/llama-stack-apps.git
cd llama-stack-apps

2. 创建并激活虚拟环境（推荐使用 Conda）

ENV=stack
conda create -n $ENV python=3.10
conda activate $ENV

3. 安装依赖

pip install -r requirements.txt

4. 启动 Llama Stack 服务

请参考 Llama Stack 官方文档 设置并启动 Llama Stack 分发版。

启动成功后，您将看到如下输出：

...
Listening on :::8321
INFO:     Started server process [587053]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://[::]:8321 (Press CTRL+C to quit)

---

基本使用

示例一：运行 Agent 测试脚本

确保 Llama Stack 服务正在运行，并设置 TAVILY_SEARCH_API_KEY 环境变量（如需使用 Tavily Search 工具）：

export TAVILY_SEARCH_API_KEY=[你的API密钥]

然后运行测试脚本：

python -m examples.agents.hello localhost 8321

您将看到类似如下输出：

> created agents with agent_id=d050201b-0ca1-4abd-8eee-3cba2b8c0fbc
User> Hello
shield_call> No Violation
inference> How can I assist you today?
...

示例二：启动本地应用并与服务器交互

运行以下命令启动一个本地应用：

PYTHONPATH=. python examples/agent_store/app.py localhost 8321

您将看到一个基于 Gradio 的聊天界面，可以与模型进行交互。

示例三：使用 RAG 与向量数据库结合的 Agent

运行以下命令启动一个支持 RAG 的 Agent 示例：

python -m examples.agents.rag_with_vector_db localhost 8321

您将看到类似如下输出：

Available shields found: ['meta-llama/Llama-Guard-3-8B']
Using model: meta-llama/Llama-3.1-405B-Instruct
Created session_id=cdb8a978-0085-4f3d-a976-939ba2b19de9 for Agent(0cfe05a8-cb97-430f-bec6-b1c7d42c712a)
shield_call> No Violation
memory_retrieval> Retrieved context from vector dbs: ['test_vector_db'].
...

---

可选配置

您可以为自定义工具设置 API 密钥，例如：

• WolframAlpha：设置环境变量 WOLFRAM_ALPHA_API_KEY
• Brave Search：设置环境变量 BRAVE_SEARCH_API_KEY

更多交互方式请参考 Agent Store README.md

---

使用 VirtualEnv 替代 Conda（可选）

如果您选择使用 VirtualEnv 而非 Conda，请按以下步骤操作：

Linux

python3 -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate  # 在命令提示符中
# 或
.\venv\Scripts\Activate.ps1  # 在 PowerShell 中
# 或
source venv/Scripts/activate  # 在 Git Bash 中

之后的依赖安装步骤与 Conda 相同：

pip install -r requirements.txt