访问官网
Github
Huggingface
文档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，您需要：
- 安装任何先决条件
- 设置提供核心
llamaCLI的工具链 - 下载模型
- 安装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
之后的指令（包括使用 pip install -r requirements.txt 安装依赖项）保持不变。
