llama-agentic-system

该仓库允许您运行Llama 3.1作为一个能够执行"主动"任务的系统，例如：

将任务分解并执行多步推理。
使用工具的能力
- 内置：模型内置了搜索或代码解释器等工具的知识
- 零样本：模型可以通过之前未见过的、上下文中的工具定义学习调用工具

此外，我们希望将安全评估从模型层面转移到整体系统层面。这使得底层模型能够保持广泛的可操控性，并适应需要不同安全保护级别的使用场景。

其中一项安全保护由Llama Guard提供。默认情况下，Llama Guard用于输入和输出过滤。然而，系统可以配置修改这个默认设置。例如，在经常观察到对良性提示的拒绝的情况下，建议使用Llama Guard进行输出过滤，只要满足您用例的安全要求。

[!注意] API仍在不断发展，可能会发生变化。欢迎构建和实验，但请暂时不要依赖其稳定性！

开始使用Llama Stack

一个主动型应用需要几个组件：

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

Llama Stack定义并标准化了这些组件以及构建生成式AI应用所需的许多其他组件。然后，通过Llama Stack Distribution方便地将这些API的各种实现组装在一起。

要开始使用Distributions，您需要：

安装任何先决条件
设置提供核心llama CLI的工具链
下载模型
安装distribution
启动distribution服务器

启动后，您可以将主动型应用指向此服务器的URL（例如http://localhost:5000），然后开始创造奇迹。

现在让我们详细介绍这些步骤：

安装先决条件

Python包

我们建议创建一个隔离的conda Python环境。

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

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

现在您应该能够运行llama --help：

usage: llama [-h] {download,distribution,model} ...

欢迎使用LLama cli

选项：
  -h, --help            显示此帮助消息并退出

子命令：
  {download,distribution,model}

bubblewrap

代码执行环境使用bubblewrap进行隔离。您的系统可能已经安装了它；如果没有，它很可能在您操作系统的软件包仓库中。

Ollama（可选）

如果您计划使用Ollama进行推理，您需要按照这些说明安装服务器。

下载检查点

从Meta下载

使用以下命令下载所需的检查点：

# 下载8B模型，可以在单个GPU上运行
llama download --source meta --model-id Meta-Llama3.1-8B-Instruct --meta-url META_URL

# 您也可以获取70B模型，但这需要8个GPU
llama download --source meta --model-id Meta-Llama3.1-70B-Instruct --meta-url META_URL

# llama-agents默认启用安全功能。为此，您需要
# 安全模型 -- Llama-Guard和Prompt-Guard
llama download --source meta --model-id Prompt-Guard-86M --meta-url META_URL
llama download --source meta --model-id Llama-Guard-3-8B --meta-url META_URL

对于以上所有操作，您需要提供一个URL（META_URL），该URL可以在签署协议后从https://llama.meta.com/llama-downloads/获取。

从Huggingface下载

基本上，上面的相同命令也适用，只需将--source meta替换为--source huggingface。

llama download --source huggingface --model-id  Meta-Llama3.1-8B-Instruct --hf-token <HF_TOKEN>

llama download --source huggingface --model-id Meta-Llama3.1-70B-Instruct --hf-token <HF_TOKEN>

llama download --source huggingface --model-id Llama-Guard-3-8B --ignore-patterns *original*
llama download --source huggingface --model-id Prompt-Guard-86M --ignore-patterns *original*

**重要：**设置环境变量HF_TOKEN或在命令中传入--hf-token以验证您的访问权限。您可以在https://huggingface.co/settings/tokens找到您的令牌。

提示：llama download的默认设置是使用--ignore-patterns *.safetensors运行，因为我们使用original文件夹中的.pth文件。然而，对于Llama Guard和Prompt Guard，我们需要safetensors。因此，请使用--ignore-patterns original运行，以便下载safetensors并忽略.pth文件。

通过ollama下载

如果您已经在使用ollama，我们也支持ollama-local分发版，您可以继续使用ollama来管理模型下载。

ollama pull llama3.1:8b-instruct-fp16
ollama pull llama3.1:70b-instruct-fp16

[!注意] 目前仅支持上述两个模型。

安装和配置分发版

[!注意] local分发版目前仅在Linux上进行了测试。对于其他平台(ubuntu, mac)，请尝试使用ollama-local分发版并安装特定平台的ollama。

让我们先列出可用的分发版

$ llama distribution list

+---------------+---------------------------------------------+----------------------------------------------------------------------+
| 规格ID         | 提供商规格                                   | 描述                                                                 |
+---------------+---------------------------------------------+----------------------------------------------------------------------+
| local         | {                                           | 使用`llama_toolchain`自身的代码来提供所有llama堆栈API                   |
|               |   "inference": "meta-reference",            |                                                                      |
|               |   "safety": "meta-reference",               |                                                                      |
|               |   "agentic_system": "meta-reference"        |                                                                      |
|               | }                                           |                                                                      |
+---------------+---------------------------------------------+----------------------------------------------------------------------+
| remote        | {                                           | 指向远程服务以获取所有llama堆栈API                                      |
|               |   "inference": "inference-remote",          |                                                                      |
|               |   "safety": "safety-remote",                |                                                                      |
|               |   "agentic_system": "agentic_system-remote" |                                                                      |
|               | }                                           |                                                                      |
+---------------+---------------------------------------------+----------------------------------------------------------------------+
| ollama-local  | {                                           | 类似于local-source，但使用ollama来运行LLM推理                           |
|               |   "inference": "meta-ollama",               |                                                                      |
|               |   "safety": "meta-reference",               |                                                                      |
|               |   "agentic_system": "meta-reference"        |                                                                      |
|               | }                                           |                                                                      |
+---------------+---------------------------------------------+----------------------------------------------------------------------+

如上所示，每个"规格"详细说明了构成该规格的"提供商"。例如，local使用"meta-reference"提供商进行推理，而ollama-local则依赖于不同的提供商(Ollama)进行推理。

目前，我们不建议使用remote分发版，因为还没有远程提供商支持Llama堆栈API。

要安装分发版，我们运行一个简单的命令，提供2个输入：

我们想要安装的分发版的规格ID（从list命令获得）
这个安装在本地将被称为的名称。

假设你正在使用8B-Instruct模型，所以我们将本地安装命名为local-llama-8b。以下命令将同时安装和配置分发版。作为配置的一部分，你将被要求输入一些信息（model_id, max_seq_len等）。

llama distribution install --spec local --name local-llama-8b

运行成功后，你应该会看到一些类似以下形式的输出：

$ llama distribution install --spec local --name local-llama-8b
....
....
成功安装 cfgv-3.4.0 distlib-0.3.8 identify-2.6.0 libcst-1.4.0 llama_toolchain-0.0.2 moreorless-0.4.0 nodeenv-1.9.1 pre-commit-3.8.0 stdlibs-2024.5.15 toml-0.10.2 tomlkit-0.13.0 trailrunner-1.4.0 ufmt-2.7.0 usort-1.0.8 virtualenv-20.26.3

分发版 `local-llama-8b`（规格为local）已成功安装！

你可以通过运行以下命令重新配置这个分发版：

llama distribution configure --name local-llama-8b

以下是CLI如何引导你填写配置的示例运行：

$ llama distribution configure --name local-llama-8b

配置API表面：inference
输入model的值（必填）：Meta-Llama3.1-8B-Instruct
输入quantization的值（可选）：
输入torch_seed的值（可选）：
输入max_seq_len的值（必填）：4096
输入max_batch_size的值（默认：1）：1
配置API表面：safety
你想配置llama_guard_shield吗？(y/n)：y
进入llama_guard_shield的子配置：
输入model的值（必填）：Llama-Guard-3-8B
输入excluded_categories的值（必填）：[]
输入disable_input_check的值（默认：False）：
输入disable_output_check的值（默认：False）：
你想配置prompt_guard_shield吗？(y/n)：y
进入prompt_guard_shield的子配置：
输入model的值（必填）：Prompt-Guard-86M
配置API表面：agentic_system
YAML配置已写入/home/ashwin/.llama/distributions/i0/config.yaml

如你所见，我们上面进行了基本配置，并配置了：

inference在模型Meta-Llama3.1-8B-Instruct上运行（从llama model list获得）
使用模型Llama-Guard-3-8B的Llama Guard安全屏障
使用模型Prompt-Guard-86M的Prompt Guard安全屏障

关于这些配置如何以yaml形式存储，请查看配置结束时打印的文件。

请注意，所有配置以及模型都存储在~/.llama中。

安装和配置`ollama-local`分发版

在一个终端中，使用以下命令启动ollama服务器：

ollama serve

[!注意] 在服务器日志中，你应该看到形如msg="llama runner started in xx seconds"的消息，表示模型已准备好进行推理。

你可以通过以下命令测试你的ollama设置：

ollama run llama3.1:8b-instruct-fp16

现在，安装llama堆栈分发版：

llama distribution install --spec local-ollama --name ollama

安装和配置`local`分发版

现在让我们使用命令行界面开始分发。您需要知道用于安装/配置的分发名称。

llama distribution start --name local-llama-8b --port 5000

您应该看到分发开始并打印出它支持的API，

$ llama distribution start --name local-llama-8b --port 5000

> initializing model parallel with size 1
> initializing ddp with size 1
> initializing pipeline with size 1
Loaded in 19.28 seconds
NCCL version 2.20.5+cuda12.4
Finished model load YES READY
Serving POST /inference/batch_chat_completion
Serving POST /inference/batch_completion
Serving POST /inference/chat_completion
Serving POST /inference/completion
Serving POST /safety/run_shields
Serving POST /agentic_system/memory_bank/attach
Serving POST /agentic_system/create
Serving POST /agentic_system/session/create
Serving POST /agentic_system/turn/create
Serving POST /agentic_system/delete
Serving POST /agentic_system/session/delete
Serving POST /agentic_system/memory_bank/detach
Serving POST /agentic_system/session/get
Serving POST /agentic_system/step/get
Serving POST /agentic_system/turn/get
Listening on :::5000
INFO:     Started server process [453333]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://[::]:5000 (Press CTRL+C to quit)

[!注意] 配置文件位于~/.llama/distributions/local-llama-8b/config.yaml。您可以随意增加max_seq_len。

[!重要] "local"分发推理服务器目前仅支持CUDA。它在Apple Silicon机器上无法运行。

这个服务器在本地运行Llama模型。

[!提示] 您可能需要使用--disable-ipv6标志来禁用IPv6支持

现在分发服务器已经设置好，接下来就是使用AgenticSystem API运行一个智能代理应用。

我们已经构建了示例脚本、笔记本和一个UI聊天界面（使用Mesop！）来帮助您入门。

为工具添加API密钥

如果您想使用工具，必须在仓库根目录创建一个.env文件并为工具添加API密钥。完成后，您需要重启分发服务器。

模型支持的工具以及需要API密钥的工具包括：

Brave用于网络搜索 (https://api.search.brave.com/register)
Wolfram用于数学运算 (https://developer.wolframalpha.com/)

提示如果您没有API密钥，仍然可以运行应用，但模型将无法访问这些工具。

启动应用并与服务器交互

通过运行以下命令启动应用（本地）并与之交互：

mesop app/main.py

这将启动一个mesop应用，您可以访问localhost:32123来使用聊天界面。

您也可以选择为自定义工具设置API密钥：

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

与这个主应用类似，您还可以尝试其他变体

PYTHONPATH=. mesop app/chat_with_custom_tools.py 展示如何集成自定义工具
PYTHONPATH=. mesop app/chat_moderation_with_llama_guard.py 展示如何修改应用以作为安全聊天审核员

创建智能代理系统并与分发服务器交互

注意：确保分发服务器仍在运行。

cd <path-to-llama-agentic-system>
conda activate $ENV
llama distribution start --name local-llama-8b --port 5000 # 如果尚未启动

PYTHONPATH=. python examples/scripts/vacation.py localhost 5000

您应该看到形如以下的标准输出：

Environment: ipython
Tools: brave_search, wolfram_alpha, photogen

Cutting Knowledge Date: December 2023
Today Date: 23 July 2024


User> 我正在计划去瑞士旅行，有哪三个最值得去的地方？
Final Llama Guard response shield_type=<BuiltinShield.llama_guard: 'llama_guard'> is_violation=False violation_type=None violation_return_message=None
Ran PromptGuardShield and got Scores: Embedded: 0.9999765157699585, Malicious: 1.1110752893728204e-05
StepType.shield_call> No Violation
role='user' content='我正在计划去瑞士旅行，有哪三个最值得去的地方？'
StepType.inference> 瑞士是一个美丽的国家，拥有丰富的历史、文化和自然美景。以下是三个必去的地方，可以添加到您的行程中：....

提示您可以选择在脚本中使用--disable-safety来避免每次都运行安全防护。

如果您有任何问题，随时与我们联系。

使用VirtualEnv替代Conda

[!注意] 虽然您可以使用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