Transformers 文档

智能体 & 工具

Transformers

加入 Hugging Face 社区

并获得增强的文档体验

在模型、数据集和 Spaces 上进行协作

通过加速推理获得更快的示例

切换文档主题

开始使用

智能体 & 工具

Transformers Agents 是一个实验性的 API，随时可能更改。智能体返回的结果可能会因 API 或底层模型容易更改而有所不同。

要了解有关智能体和工具的更多信息，请务必阅读入门指南。此页面包含底层类的 API 文档。

智能体

我们提供两种类型的智能体，基于主要的 Agent 类

CodeAgent 一次性执行操作，生成代码来解决任务，然后立即执行。
ReactAgent 逐步执行操作，每个步骤包括一个思考，然后调用一个工具并执行。它有两个类
- ReactJsonAgent 以 JSON 格式编写其工具调用。
- ReactCodeAgent 以 Python 代码编写其工具调用。

Agent

class transformers.Agent

( tools: typing.Union[typing.List[transformers.agents.tools.Tool], transformers.agents.agents.Toolbox] llm_engine: typing.Callable = None system_prompt: typing.Optional[str] = None tool_description_template: typing.Optional[str] = None additional_args: typing.Dict = {} max_iterations: int = 6 tool_parser: typing.Optional[typing.Callable] = None add_base_tools: bool = False verbose: int = 0 grammar: typing.Optional[typing.Dict[str, str]] = None managed_agents: typing.Optional[typing.List] = None step_callbacks: typing.Optional[typing.List[typing.Callable]] = None monitor_metrics: bool = True )

execute_tool_call

( tool_name: str arguments: typing.Dict[str, str] )

参数

tool_name (str) — 要执行的工具的名称（应为 self.toolbox 中的一个）。
arguments (Dict[str, str]) — 传递给工具的参数。

使用提供的输入执行工具并返回结果。如果参数引用状态变量，则此方法会将参数替换为来自状态的实际值。

extract_action

( llm_output: str split_token: str )

参数

llm_output (str) — LLM 的输出
split_token (str) — 操作的分隔符。应与系统提示中的示例匹配。

从 LLM 输出中解析操作

run

( **kwargs )

将在子类中实现

write_inner_memory_from_logs

( summary_mode: typing.Optional[bool] = False )

从日志中读取过去的 llm_outputs、actions 和 observations 或 errors，放入一系列可以用作 LLM 输入的消息中。

CodeAgent

class transformers.CodeAgent

( tools: typing.List[transformers.agents.tools.Tool] llm_engine: typing.Optional[typing.Callable] = None system_prompt: typing.Optional[str] = None tool_description_template: typing.Optional[str] = None grammar: typing.Optional[typing.Dict[str, str]] = None additional_authorized_imports: typing.Optional[typing.List[str]] = None **kwargs )

一个类，用于智能体使用单个代码块解决给定任务。它计划所有操作，然后一次性执行所有操作。

parse_code_blob

( result: str )

如果您想更改在 run 方法中清理代码的方式，请覆盖此方法。

run

( task: str return_generated_code: bool = False **kwargs )

参数

task (str) — 要执行的任务
return_generated_code (bool, 可选, 默认为 False) — 是否返回生成的代码而不是运行它
kwargs (附加关键字参数，可选) — 在评估代码时发送给智能体的任何关键字参数。

为给定任务运行智能体。

示例

from transformers.agents import CodeAgent

agent = CodeAgent(tools=[])
agent.run("What is the result of 2 power 3.7384?")

React 智能体

class transformers.ReactAgent

( tools: typing.List[transformers.agents.tools.Tool] llm_engine: typing.Optional[typing.Callable] = None system_prompt: typing.Optional[str] = None tool_description_template: typing.Optional[str] = None grammar: typing.Optional[typing.Dict[str, str]] = None plan_type: typing.Optional[str] = None planning_interval: typing.Optional[int] = None **kwargs )

这个 Agent 使用 ReAct 框架逐步解决给定的任务：当目标未达成时，agent 将执行思考和行动的循环。行动将从 LLM 输出中解析：它包括调用工具箱中的工具，以及由 LLM 引擎选择的参数。

direct_run

( task: str )

以直接模式运行 agent，仅在最后返回输出：应仅在 run 方法中启动。

planning_step

( task is_first_step: bool = False iteration: int = None )

参数

task (str) — 要执行的任务
is_first_step (bool) — 如果此步骤不是第一步，则计划应该是对先前计划的更新。
iteration (int) — 当前步骤的编号，用作 LLM 的指示。

Agent 定期使用它来计划实现目标的后续步骤。

provide_final_answer

( task )

此方法根据 agent 交互的日志，为任务提供最终答案。

run

( task: str stream: bool = False reset: bool = True **kwargs )

参数

task (str) — 要执行的任务

为给定任务运行智能体。

示例

from transformers.agents import ReactCodeAgent
agent = ReactCodeAgent(tools=[])
agent.run("What is the result of 2 power 3.7384?")

stream_run

( task: str )

以流式模式运行 agent，在执行步骤时产生步骤：应仅在 run 方法中启动。

class transformers.ReactJsonAgent

( tools: typing.List[transformers.agents.tools.Tool] llm_engine: typing.Optional[typing.Callable] = None system_prompt: typing.Optional[str] = None tool_description_template: typing.Optional[str] = None grammar: typing.Optional[typing.Dict[str, str]] = None planning_interval: typing.Optional[int] = None **kwargs )

这个 Agent 使用 ReAct 框架逐步解决给定的任务：当目标未达成时，agent 将执行思考和行动的循环。工具调用将由 LLM 以 JSON 格式制定，然后进行解析和执行。

step

( log_entry: typing.Dict[str, typing.Any] )

在 ReAct 框架中执行一个步骤：agent 思考、行动并观察结果。错误在此处引发，它们在 run() 方法中被捕获并记录。

class transformers.ReactCodeAgent

( tools: typing.List[transformers.agents.tools.Tool] llm_engine: typing.Optional[typing.Callable] = None system_prompt: typing.Optional[str] = None tool_description_template: typing.Optional[str] = None grammar: typing.Optional[typing.Dict[str, str]] = None additional_authorized_imports: typing.Optional[typing.List[str]] = None planning_interval: typing.Optional[int] = None **kwargs )

这个 Agent 使用 ReAct 框架逐步解决给定的任务：当目标未达成时，agent 将执行思考和行动的循环。工具调用将由 LLM 以代码格式制定，然后进行解析和执行。

step

( log_entry: typing.Dict[str, typing.Any] )

在 ReAct 框架中执行一个步骤：agent 思考、行动并观察结果。错误在此处引发，它们在 run() 方法中被捕获并记录。

ManagedAgent

class transformers.ManagedAgent

( agent name description additional_prompting = None provide_run_summary = False )

工具

load_tool

transformers.load_tool

( task_or_repo_id model_repo_id = None token = None **kwargs )

参数

task_or_repo_id (str) — 要加载工具的任务或 Hub 上工具的仓库 ID。Transformers 中实现的任务包括：
- "document_question_answering"
- "image_question_answering"
- "speech_to_text"
- "text_to_speech"
- "translation"
model_repo_id (str, 可选) — 使用此参数可以使用与您选择的工具的默认模型不同的模型。
token (str, 可选) — 用于在 hf.co 上标识您的令牌。如果未设置，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
kwargs (附加关键字参数，可选) — 将拆分为两部分的附加关键字参数：所有与 Hub 相关的参数（例如 cache_dir、revision、subfolder）将在下载工具文件时使用，其他参数将传递给其 init。

快速加载工具的主函数，无论是在 Hub 上还是在 Transformers 库中。

加载工具意味着您将下载该工具并在本地执行它。始终在运行时加载下载的工具之前检查它，就像使用 pip/npm/apt 安装软件包一样。

tool

transformers.tool

( tool_function: typing.Callable )

参数

tool_function — 您的函数。应该为每个输入提供类型提示，并为输出提供类型提示。
Should 还应该包含一个文档字符串描述，其中包括一个“Args —”部分，其中描述了每个参数。

将函数转换为 Tool 子类的实例。

工具 (Tool)

class transformers.Tool

( *args **kwargs )

代理使用的函数的基本类。继承此类并实现 __call__ 方法以及以下类属性

description (str) — 对您的工具的功能、期望的输入和将返回的输出的简短描述。例如“这是一个从 url 下载文件的工具。它将 url 作为输入，并返回文件中包含的文本”。
name (str) — 一个执行性的名称，将在提示代理时用于您的工具。例如 "文本分类器" 或 "图像生成器"。
inputs (Dict[str, Dict[str, Union[str, type]]]) — 输入预期模式的字典。它有一个 type 键和一个 description 键。这由 launch_gradio_demo 使用或从您的工具创建一个漂亮的 Space，也可以在为您的工具生成的描述中使用。
output_type (type) — 工具输出的类型。这由 launch_gradio_demo 使用或从您的工具创建一个漂亮的 Space，也可以在为您的工具生成的描述中使用。

如果您的工具在可用之前需要执行昂贵的操作（例如加载模型），您还可以覆盖 setup() 方法。 setup() 将在您第一次使用您的工具时调用，而不是在实例化时调用。

from_gradio

( gradio_tool )

从 gradio 工具创建 Tool。

from_hub

( repo_id: str token: typing.Optional[str] = None **kwargs )

参数

repo_id (str) — Hub 上定义您的工具的仓库名称。
token (str, optional) — 用于在 hf.co 上标识您的令牌。如果未设置，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
kwargs （附加关键字参数，可选）— 将拆分为两部分的附加关键字参数：所有与 Hub 相关的参数（例如 cache_dir、revision、subfolder）将在下载工具文件时使用，其他参数将传递给其 init。

加载 Hub 上定义的工具。

从 Hub 加载工具意味着您将下载该工具并在本地执行它。始终在运行时加载从 Hub 下载的工具之前检查该工具，就像使用 pip/npm/apt 安装软件包一样。

from_langchain

( langchain_tool )

从 langchain 工具创建 Tool。

from_space

( space_id: str name: str description: str api_name: typing.Optional[str] = None token: typing.Optional[str] = None ) → Tool

参数

space_id (str) — Hub 上的 Space 的 ID。
name (str) — 工具的名称。
description (str) — 工具的描述。
api_name (str, optional) — 要使用的特定 api_name，如果 Space 有多个选项卡。如果未指定，则默认为第一个可用的 api。
token (str, optional) — 添加您的令牌以访问私有 Space 或增加您的 GPU 配额。

返回

Space，作为一个工具。

从 Hub 上给定的 Space ID 创建 Tool。

示例

image_generator = Tool.from_space(
    space_id="black-forest-labs/FLUX.1-schnell",
    name="image-generator",
    description="Generate an image from a prompt"
)
image = image_generator("Generate an image of a cool surfer in Tahiti")

face_swapper = Tool.from_space(
    "tuan2308/face-swap",
    "face_swapper",
    "Tool that puts the face shown on the first image on the second image. You can give it paths to images.",
)
image = face_swapper('./aymeric.jpeg', './ruth.jpg')

push_to_hub

( repo_id: str commit_message: str = 'Upload tool' private: typing.Optional[bool] = None token: typing.Union[bool, str, NoneType] = None create_pr: bool = False )

参数

repo_id (str) — 您要将工具推送到的仓库的名称。在推送到给定组织时，它应包含您的组织名称。
commit_message (str, optional, 默认为 "Upload tool") — 推送时提交的消息。
private (bool, optional) — 是否使仓库私有。如果为 None （默认值），则仓库将是公共的，除非组织的默认设置为私有。如果仓库已存在，则忽略此值。
token (bool 或 str, optional) — 用作远程文件的 HTTP 持票人授权的令牌。如果未设置，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
create_pr (bool, optional, 默认为 False) — 是否使用上传的文件创建 PR 或直接提交。

将工具上传到 Hub。

为了使此方法正常工作，您的工具必须在单独的模块（而不是 __main__）中定义。

例如

from my_tool_module import MyTool
my_tool = MyTool()
my_tool.push_to_hub("my-username/my-space")

save

( output_dir )

参数

output_dir (str) — 您要将工具保存在其中的文件夹。

保存工具的相关代码文件，以便可以将其推送到 Hub。这会将您的工具的代码复制到 output_dir 中，并自动生成

一个名为 tool_config.json 的配置文件
一个 app.py 文件，以便您的工具可以转换为 Space
一个 requirements.txt，其中包含您的工具使用的模块的名称（在检查其代码时检测到）

您应该仅使用此方法来保存定义在单独模块（而不是 __main__）中的工具。

setup

( )

在此处覆盖此方法，以进行任何昂贵且需要在开始使用工具之前执行的操作。例如加载大型模型。

Toolbox

class transformers.Toolbox

( tools: typing.List[transformers.agents.tools.Tool] add_base_tools: bool = False )

参数

tools (List[Tool]) — 用于实例化工具箱的工具列表
add_base_tools (bool, 默认为 False, 可选, 默认为 False) — 是否将 transformers 中可用的工具添加到工具箱。

工具箱包含 Agent 可以执行操作的所有工具，以及一些管理它们的方法。

add_tool

( tool: Tool )

参数

tool (Tool) — 要添加到工具箱的工具。

将工具添加到工具箱

clear_toolbox

( )

清空工具箱

remove_tool

( tool_name: str )

参数

tool_name (str) — 要从工具箱中移除的工具名称。

从工具箱中移除工具

show_tool_descriptions

( tool_description_template: str = None )

参数

tool_description_template (str, 可选) — 用于描述工具的模板。如果未提供，将使用默认模板。

返回工具箱中所有工具的描述

update_tool

( tool: Tool )

参数

tool (Tool) — 要更新到工具箱的工具。

根据工具名称更新工具箱中的工具。

PipelineTool

class transformers.PipelineTool

( model = None pre_processor = None post_processor = None device = None device_map = None model_kwargs = None token = None **hub_kwargs )

参数

model (str 或 PreTrainedModel, 可选) — 用于模型的检查点名称，或实例化的模型。如果未设置，则默认为类属性 default_checkpoint 的值。
pre_processor (str 或 Any, 可选) — 用于预处理器的检查点名称，或实例化的预处理器（可以是分词器、图像处理器、特征提取器或处理器）。如果未设置，则默认为 model 的值。
post_processor (str 或 Any, 可选) — 用于后处理器的检查点名称，或实例化的预处理器（可以是分词器、图像处理器、特征提取器或处理器）。如果未设置，则默认为 pre_processor。
device (int, str 或 torch.device, 可选) — 执行模型的设备。默认为任何可用的加速器（GPU、MPS 等），否则默认为 CPU。
device_map (str 或 dict, 可选) — 如果传入，将用于实例化模型。
model_kwargs (dict, 可选) — 发送到模型实例化的任何关键字参数。
token (str, 可选) — 用作远程文件的 HTTP Bearer 授权的令牌。如果未设置，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
hub_kwargs (附加关键字参数, 可选) — 发送到将从 Hub 加载数据的方法的任何其他关键字参数。

一个为 Transformer 模型量身定制的 Tool。除了基类 Tool 的类属性之外，您还需要指定

model_class (type) — 用于在此工具中加载模型的类。
default_checkpoint (str) — 当用户未指定检查点时应使用的默认检查点。
pre_processor_class (type, 可选, 默认为 AutoProcessor) — 用于加载预处理器的类
post_processor_class (type, 可选, 默认为 AutoProcessor) — 用于加载后处理器的类（当与预处理器不同时）。

decode

( outputs )

使用 post_processor 解码模型输出。

encode

( raw_inputs )

使用 pre_processor 准备 model 的输入。

forward

( inputs )

将输入传递给 model。

setup

( )

如有必要，实例化 pre_processor、model 和 post_processor。

launch_gradio_demo

transformers.launch_gradio_demo

( tool_class: Tool )

参数

tool_class (type) — 要为其启动演示的工具的类。

为工具启动 Gradio 演示。相应的工具类需要正确实现类属性 inputs 和 output_type。

stream_to_gradio

transformers.stream_to_gradio

( agent task: str test_mode: bool = False **kwargs )

使用给定的任务运行 agent，并将来自 agent 的消息作为 Gradio ChatMessages 流式传输。

ToolCollection

class transformers.ToolCollection

( collection_slug: str token: typing.Optional[str] = None )

参数

collection_slug (str) — 引用集合的集合 slug。
token (str, 可选) — 如果集合是私有的，则为身份验证令牌。

工具集合可以加载集合中的所有 Spaces，以便添加到 agent 的工具箱中。

[!NOTE] 只会获取 Spaces，因此您可以随意将模型和数据集添加到您的集合中，如果您希望此集合展示它们。

示例

>>> from transformers import ToolCollection, ReactCodeAgent

>>> image_tool_collection = ToolCollection(collection_slug="huggingface-tools/diffusion-tools-6630bb19a942c2306a2cdb6f")
>>> agent = ReactCodeAgent(tools=[*image_tool_collection.tools], add_base_tools=True)

>>> agent.run("Please draw me a picture of rivers and lakes.")

引擎

您可以自由创建和使用自己的引擎，以便 Agents 框架可以使用。这些引擎具有以下规范

遵循消息格式作为其输入 (List[Dict[str, str]]) 并返回一个字符串。
在 stop_sequences 参数中传递的序列之前停止生成输出

TransformersEngine

为方便起见，我们添加了一个 TransformersEngine，它实现了上述要点，并将预初始化的 Pipeline 作为输入。

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline, TransformersEngine

>>> model_name = "HuggingFaceTB/SmolLM-135M-Instruct"
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)
>>> model = AutoModelForCausalLM.from_pretrained(model_name)

>>> pipe = pipeline("text-generation", model=model, tokenizer=tokenizer)

>>> engine = TransformersEngine(pipe)
>>> engine([{"role": "user", "content": "Ok!"}], stop_sequences=["great"])

"What a "

class transformers.TransformersEngine

( pipeline: Pipeline model_id: typing.Optional[str] = None )

此引擎使用预初始化的本地文本生成 pipeline。

HfApiEngine

HfApiEngine 是一个引擎，它包装了一个 HF Inference API 客户端，用于执行 LLM。

>>> from transformers import HfApiEngine

>>> messages = [
...   {"role": "user", "content": "Hello, how are you?"},
...   {"role": "assistant", "content": "I'm doing great. How can I help you today?"},
...   {"role": "user", "content": "No need to help, take it easy."},
... ]

>>> HfApiEngine()(messages, stop_sequences=["conversation"])

"That's very kind of you to say! It's always nice to have a relaxed "

class transformers.HfApiEngine

( model: str = 'meta-llama/Meta-Llama-3.1-8B-Instruct' token: typing.Optional[str] = None max_tokens: typing.Optional[int] = 1500 timeout: typing.Optional[int] = 120 )

参数

model (str, 可选, 默认为 "meta-llama/Meta-Llama-3.1-8B-Instruct") — 用于推理的 Hugging Face 模型 ID。这可以是 Hugging Face 模型 Hub 中的路径或模型标识符。
token (str, 可选) — Hugging Face API 用于身份验证的令牌。如果未提供，则此类将使用存储在 Hugging Face CLI 配置中的令牌。
max_tokens (int, 可选, 默认为 1500) — 输出中允许的最大 token 数。
timeout (int, 可选, 默认为 120) — API 请求的超时时间，以秒为单位。

Raises

ValueError

ValueError — 如果未提供模型名称。

一个用于与 Hugging Face 的 Inference API 进行语言模型交互的类。

此引擎允许您使用 Inference API 与 Hugging Face 的模型进行通信。它可以在无服务器模式或专用端点中使用，支持停止序列和语法自定义等功能。

Agent 类型

Agent 可以处理工具之间的任何类型的对象；工具是完全多模态的，可以接受和返回文本、图像、音频、视频以及其他类型。为了提高工具之间的兼容性，以及为了在 ipython (jupyter、colab、ipython notebook, …) 中正确渲染这些返回值，我们围绕这些类型实现了包装类。

包装后的对象应继续像最初一样运行；文本对象应仍然像字符串一样运行，图像对象应仍然像 PIL.Image 一样运行。

这些类型有三个特定目的

在类型上调用 to_raw 应该返回底层对象
在类型上调用 to_string 应该将对象作为字符串返回：对于 AgentText 可能是字符串，但在其他实例中将是对象序列化版本的路径
在 ipython 内核中显示它应该正确显示对象

AgentText

class transformers.agents.agent_types.AgentText

( value )

Agent 返回的文本类型。行为类似于字符串。

AgentImage

class transformers.agents.agent_types.AgentImage

( value )

Agent 返回的图像类型。行为类似于 PIL.Image。

save

( output_bytes format **params )

参数

output_bytes (bytes) — 用于保存图像的输出字节。
format (str) — 用于输出图像的格式。该格式与 PIL.Image.save 中的格式相同。
**params — 传递给 PIL.Image.save 的其他参数。

将图像保存到文件。

to_raw

( )

返回该对象的“原始”版本。对于 AgentImage，它是一个 PIL.Image。

to_string

( )

返回该对象的字符串化版本。对于 AgentImage，它是图像序列化版本的路径。

AgentAudio

class transformers.agents.agent_types.AgentAudio

( value samplerate = 16000 )

代理返回的音频类型。

to_raw

( )

返回该对象的“原始”版本。它是 torch.Tensor 对象。

to_string

( )

返回该对象的字符串化版本。对于 AgentAudio，它是音频序列化版本的路径。

< > 在 GitHub 上更新

←拉取请求检查自动类→