在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

meta-llama/llama-models

菜单

工具实用程序

相关源文件

本文档介绍了用于解析和验证Llama模型输出中工具调用的工具实用程序。这些实用程序处理模型生成的各种格式的函数调用的提取和验证。有关提示格式和工具集成模式的信息，请参阅提示格式。

工具实用程序概述

工具实用程序提供用于从Llama模型输出中解析、验证和提取结构化工具调用的函数。模型可以生成多种格式的工具调用，这些实用程序负责将原始文本输出转换为应用程序可执行的结构化数据。

工具实用程序系统包括

  1. 用于不同工具调用格式的解析函数
  2. 验证函数，以确保正确的语法和结构
  3. 用于将文本转换为结构化工具调用的提取实用程序
  4. 支持多种工具调用格式（JSON、函数标签、Python列表）

工具实用程序处理流程

来源: models/llama3/tests/api/test_tool_utils.py9-13 models/llama3/tests/api/test_tool_utils.py16-22

核心数据类型

工具集成系统基于datatypes.py中定义的几种基本数据类型构建

角色枚举

Role枚举包括tool作为其值之一，用于标识包含工具结果的消息

内置工具枚举

BuiltinTool枚举定义了Llama模型中可用的内置工具

ToolCall 类

ToolCall类表示一个工具调用，包含唯一ID、工具名称和参数

来源: models/datatypes.py21-26 models/datatypes.py28-33 models/datatypes.py39-59 models/datatypes.py93-113

工具调用格式和解析

工具实用程序处理Llama模型生成的三种主要工具调用格式

函数标签格式

函数标签格式使用类似XML的语法，通过ToolUtils.maybe_extract_custom_tool_call()方法进行处理

组件语法示例
起始标签<function=name><function=getWeather>
参数JSON 对象{"location":"New York","date":"2023-08-05"}
完整调用<function=name>{args}<function=getWeather>{"location":"New York","date":"2023-08-05"}

Python 列表格式

Python列表格式将函数调用表示为Python表达式，通过is_valid_python_list()进行验证，并通过parse_python_list_for_function_calls()进行解析

格式描述示例
单次调用[function_name(param=value)][get_boiling_point(liquid_name="water", celcius=True)]
多次调用[func1(...), func2(...)][get_boiling_point(liquid_name="water"), get_melting_point(substance="ice")]
混合类型支持字符串、数字、布尔值[process_data(name="sample", value=42, active=True)]

JSON 格式

JSON格式遵循OpenAI函数调用规范

核心实用函数

ToolUtils.maybe_extract_custom_tool_call()

从函数标签格式字符串中提取工具名称和参数

is_valid_python_list()

验证字符串是否表示有效的Python函数调用列表

有效示例无效示例
[get_weather(city="NYC")][]（空列表）
[func1(), func2()][func("positional")]（位置参数）
[calc(x=5.2, y=10)]get_weather(city="NYC")（不在列表中）

parse_python_list_for_function_calls()

将有效的Python列表字符串解析为结构化的函数调用数据

来源: models/llama3/tests/api/test_tool_utils.py16-22 models/llama3/tests/api/test_tool_utils.py25-76 models/llama3/tests/api/test_tool_utils.py77-130

Python 列表验证规则

is_valid_python_list()函数强制执行有效函数调用列表的特定规则

有效模式

模式示例描述
单个函数[get_weather(city="NYC")]一个带有关键字参数的函数
多个函数[func1(a=1), func2(b=2)]列表中有多个函数
混合数据类型[calc(x=5.2, flag=True, name="test")]字符串、数字、布尔值
空参数[initialize()]无参数函数
复杂参数[func(data={"key": "value"})]嵌套字典和列表

无效模式

模式示例原因
空列表[]必须至少包含一个函数调用
位置参数[func("arg1", "arg2")]只允许关键字参数
非函数项[func(), "string", 42]列表必须只包含函数调用
嵌套列表[[func()]]无嵌套列表结构
裸函数func()必须用列表方括号括起来
语法错误<FileRef file-url="https://github.com/meta-llama/llama-models/blob/01dc8ce4/func(a=1缺少闭合括号或引号

解析复杂参数

parse_python_list_for_function_calls()函数处理复杂的参数类型

支持的数据类型

复杂解析示例

输入格式解析输出
[analyze_text(content="Hello, world!", language="en")][("analyze_text", {"content": "Hello, world!", "language": "en"})]
[calculate_volume(radius=5.2, height=10)][("calculate_volume", {"radius": 5.2, "height": 10})]
[process_data(name="sample", value=42, active=True, ratio=3.14)][("process_data", {"name": "sample", "value": 42, "active": True, "ratio": 3.14})]
[get_info(data={"name": "water"}, values=[100, 101])][("get_info", {"data": {"name": "water"}, "values": [100, 101]})]

来源: models/llama3/tests/api/test_tool_utils.py93-130

实用函数集成

工具实用程序与核心数据结构集成，以处理模型输出

来源: models/llama3/tests/api/test_tool_utils.py9-13 models/llama3/tests/api/test_tool_utils.py16-22

错误处理和边缘情况

工具实用程序处理各种边缘情况和错误条件

常见验证失败

错误类型输入示例验证结果
空列表[]is_valid_python_list()返回False
位置参数[func("arg1", "arg2")]is_valid_python_list()返回False
混合内容[func(), "string", 42]is_valid_python_list()返回False
语法错误[func(a=1is_valid_python_list()返回False
嵌套结构[[func()]]is_valid_python_list()返回False

解析边缘情况

解析实用程序正确处理了多种边缘情况

  • 空参数：[initialize()]解析为[("initialize", {})]
  • 带空格的字符串：[analyze_text(content="Hello, world!")]保留字符串值中的空格
  • 复杂的嵌套数据：[func(data={"key": [1, 2, 3]})]处理嵌套的字典和列表
  • 多个函数：[func1(a=1), func2(b=2)]返回每个函数的元组列表

来源: models/llama3/tests/api/test_tool_utils.py36-76 models/llama3/tests/api/test_tool_utils.py108-130

在应用程序中使用工具实用程序

要使用工具实用程序处理模型输出

基本使用模式

集成工作流程

  1. 接收模型输出：获取包含潜在工具调用的文本
  2. 检测格式：识别输出是包含函数标签还是Python列表
  3. 验证：使用is_valid_python_list()进行Python列表格式验证
  4. 解析：使用适当的解析函数提取结构化数据
  5. 处理：将解析的数据转换为ToolCall对象以执行

来源: models/llama3/tests/api/test_tool_utils.py9-13 models/llama3/tests/api/test_tool_utils.py16-22

工具实用程序的最佳实践

  1. 优先验证：在解析Python列表格式之前，始终使用is_valid_python_list()验证输入
  2. 错误处理：使用实用函数周围的try-catch块优雅地处理解析失败
  3. 格式检测：实现格式检测逻辑以选择正确的解析实用程序
  4. 数据类型处理：实用程序在解析过程中保留数据类型（字符串、数字、布尔值）
  5. 复杂参数：利用实用程序对函数参数中嵌套字典和列表的支持

格式选择指南

用例推荐格式实用函数
简单工具调用函数标签maybe_extract_custom_tool_call()
类代码表达式Python 列表parse_python_list_for_function_calls()
多个同步调用Python 列表parse_python_list_for_function_calls()
复杂的嵌套参数Python 列表parse_python_list_for_function_calls()

来源: models/llama3/tests/api/test_tool_utils.py25-76 models/llama3/tests/api/test_tool_utils.py77-130

结论

工具集成扩展了Llama模型的能力，使其超越了训练数据，允许它们通过定义的工具和函数访问外部信息并执行操作。工具集成系统的模块化设计提供了定义、调用和处理工具的灵活性，使开发人员能够构建将Llama模型的语言能力与外部系统的实际实用性相结合的复杂AI应用程序。