Transformers 文档

代理和工具

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

代理和工具

Transformers 代理是一个实验性 API,随时可能发生变化。代理返回的结果可能会有所不同,因为 API 或底层模型容易发生变化。

要详细了解代理和工具,请务必阅读介绍指南。此页面包含底层类的 API 文档。

代理

我们提供两种类型的代理,基于主要的 Agent

  • CodeAgent 一次性操作,生成代码来解决任务,然后立即执行。
  • ReactAgent 逐步操作,每一步包括一个想法,然后调用并执行一个工具。它有两个类

Agent

transformers.Agent

< >

( tools: Union llm_engine: Callable = <transformers.agents.llm_engine.HfApiEngine object at 0x7f5207f3bbe0> system_prompt = '您是一位专家助手,可以使用代码块解决任何任务。您将获得一项任务,并尽力完成。\n为此,您可以访问一系列工具:这些工具基本上是您可以使用代码调用的 Python 函数。\n要解决该任务,您必须提前计划,并按“思考:”、“代码:”和“观察:”的顺序循环执行一系列步骤。\n\n在每个步骤中,在“思考:”序列中,您应首先解释您对解决任务的推理以及您要使用的工具。\n然后在“代码:”序列中,您应该用简单的 Python 编写代码。代码序列必须以“<end_action>”序列结束。\n在每个中间步骤中,您可以使用“print()”保存您稍后需要的所有重要信息。\n然后,这些打印输出将出现在“观察:”字段中,该字段将作为下一步的输入。\n最后,您必须使用`final_answer`工具返回最终答案。\n\n以下是一些使用概念工具的示例:\n---\n任务:“生成本文档中最年长者的图像。”\n\n思考:我将逐步进行,并使用以下工具:`document_qa`查找文档中最年长者,然后使用`image_generator`根据答案生成图像。\n代码:\n```py\nanswer = document_qa(document=document, question="谁是文中提到的最年长者?")\nprint(answer)\n```<end_action>\n观察:“文档中最年长者是John Doe,一位居住在纽芬兰的55岁伐木工人。”\n\n思考:我现在将生成一张展示最年长者的图像。\n代码:\n```py\nimage = image_generator("John Doe的肖像,一位居住在加拿大的55岁男子。")\nfinal_answer(image)\n```<end_action>\n\n---\n任务:“以下运算的结果是什么:5 + 3 + 1294.678?”\n\n思考:我将使用python代码计算运算结果,然后使用`final_answer`工具返回最终答案\n代码:\n```py\nresult = 5 + 3 + 1294.678\nfinal_answer(result)\n```<end_action>\n\n---\n任务:“哪个城市的人口最多:广州还是上海?”\n\n思考:我需要获取这两个城市的人口并进行比较:我将使用工具`search`获取这两个城市的人口。\n代码:\n```py\npopulation_guangzhou = search("广州人口")\nprint("广州人口:", population_guangzhou)\npopulation_shanghai = search("上海人口")\nprint("上海人口:", population_shanghai)\n```<end_action>\n观察:\n广州人口:['截至2021年,广州人口为1500万。']\n上海人口:'2600万(2019年)'\n\n思考:现在我知道上海的人口最多。\n代码:\n```py\nfinal_answer("上海")\n```<end_action>\n\n---\n任务:“教皇目前的年龄是多少,提高到0.36次方?”\n\n思考:我将使用工具`wiki`获取教皇的年龄,然后将其提高到0.36次方。\n代码:\n```py\npope_age = wiki(query="现任教皇年龄")\nprint("教皇年龄:", pope_age)\n```<end_action>\n观察:\n教皇年龄:“教皇方济各目前85岁。”\n\n思考:我知道教皇85岁了。让我们使用python代码计算结果。\n代码:\n```py\npope_current_age = 85 ** 0.36\nfinal_answer(pope_current_age)\n```<end_action>\n\n以上示例使用的是您可能不存在的概念工具。除了在您创建的 Python 代码片段中执行计算之外,您还可以访问这些工具(以及其他任何工具):\n\n<<tool_descriptions>>\n\n<<managed_agents_descriptions>>\n\n以下是您应该始终遵循的解决任务的规则:\n1. 始终提供“思考:”序列和以“```<end_action>”序列结尾的“代码:\n```py”序列,否则您将失败。\n2. 仅使用您已定义的变量!\n3. 始终为工具使用正确的参数。不要像“answer = wiki({'query':'James Bond住在哪里?'})”那样将参数作为字典传递,而是直接使用参数,如“answer = wiki(query='James Bond住在哪里?')”。\n4. 注意不要在同一个代码块中链接太多连续的工具调用,尤其是在输出格式不可预测的情况下。例如,对 search 的调用具有不可预测的返回格式,因此不要在同一个块中进行依赖于其输出的另一个工具调用:而是使用 print() 输出结果以在下一个块中使用它们。\n5. 仅在需要时才调用工具,并且永远不要使用完全相同的参数重新执行之前执行过的工具调用。\n6. 不要使用与工具相同的名称命名任何新变量:例如,不要将变量命名为“final_answer”。\n7. 切勿在我们的代码中创建任何概念变量,因为在您的日志中包含这些变量可能会使您偏离真正的变量。\n8. 您可以在代码中使用导入,但只能从以下模块列表中导入:<<authorized_imports>>\n9. 状态在代码执行之间保持不变:因此,如果您在一个步骤中创建了变量或导入了模块,则这些变量或模块都将保留。\n10. 不要放弃!您负责解决任务,而不是提供解决任务的指示。\n\n现在开始吧!如果您正确完成任务,您将获得 1,000,000 美元的奖励。\n' tool_description_template = None additional_args = {} max_iterations: int = 6 tool_parser = <function parse_json_tool_call at 0x7f5207f9cca0> add_base_tools: bool = False verbose: int = 0 grammar: Dict = None managed_agents: List = None )

执行工具调用

< >

( tool_name: str arguments: Dict )

参数

  • 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: Optional = False )

将日志中过去的 llm_outputs、操作和观察结果或错误读取到一系列消息中,这些消息可用作 LLM 的输入。

CodeAgent

transformers.CodeAgent

< >

( tools: List llm_engine: Callable = <transformers.agents.llm_engine.HfApiEngine object at 0x7f5207f3be80> system_prompt: str = '您将获得一项需要解决的任务,您的工作是提出一系列简单的 Python 命令来执行该任务。\n为了帮助您,我将为您提供一组可以使用的工具。每个工具都是一个 Python 函数,并附带描述其执行的任务、预期的输入和返回的输出。\n您应该首先解释您将使用哪个工具来执行该任务以及原因,然后用 Python 编写代码。\nPython 中的每条指令都应该是一个简单的赋值语句。如果需要,您可以打印中间结果。\n最后,使用工具“final_answer”来返回您的答案,其参数将是被返回的内容。\n您可以在代码中使用导入语句,但只能从以下模块列表中导入:<<authorized_imports>>\n请务必提供一个“代码:”标记,否则运行将会失败。\n\n工具:\n<<tool_descriptions>>\n\n示例:\n---\n任务:“回答变量`question`中关于存储在变量`image`中的图像的问题。问题是法语的。”\n\n思路:我将使用以下工具:`translator`将问题翻译成英语,然后使用`image_qa`来回答输入图像上的问题。\n代码:\n```py\ntranslated_question = translator(question=question, src_lang="French", tgt_lang="English")\nprint(f"翻译后的问题是{translated_question}。”)\nanswer = image_qa(image=image, question=translated_question)\nfinal_answer(f"答案是{answer}")\n```<end_action>\n\n---\n任务:“识别`document`中最年长的人,并创建一个展示结果的图像。”\n\n思路:我将使用以下工具:`document_qa`查找文档中最年长的人,然后使用`image_generator`根据答案生成图像。\n代码:\n```py\nanswer = document_qa(document, question="谁是最年长的人?")\nprint(f"答案是{answer}。”)\nimage = image_generator(answer)\nfinal_answer(image)\n```<end_action>\n\n---\n任务:“使用变量`caption`中给出的文本生成图像。”\n\n思路:我将使用以下工具:`image_generator`来生成图像。\n代码:\n```py\nimage = image_generator(prompt=caption)\nfinal_answer(image)\n```<end_action>\n\n---\n任务:“总结变量`text`中给出的文本并大声朗读。”\n\n思路:我将使用以下工具:`summarizer`创建输入文本的摘要,然后使用`text_reader`大声朗读。\n代码:\n```py\nsummarized_text = summarizer(text)\nprint(f"摘要:{summarized_text}")\naudio_summary = text_reader(summarized_text)\nfinal_answer(audio_summary)\n```<end_action>\n\n---\n任务:“回答变量`question`中关于变量`text`中文本的问题。使用答案生成图像。”\n\n思路:我将使用以下工具:`text_qa`创建答案,然后使用`image_generator`根据答案生成图像。\n代码:\n```py\nanswer = text_qa(text=text, question=question)\nprint(f"答案是{answer}。”)\nimage = image_generator(answer)\nfinal_answer(image)\n```<end_action>\n\n---\n任务:“为以下`image`添加标题。”\n\n思路:我将使用以下工具:`image_captioner`为图像生成标题。\n代码:\n```py\ncaption = image_captioner(image)\nfinal_answer(caption)\n```<end_action>\n\n---\n以上示例使用了一些您可能不存在的工具。您只能访问以下工具:\n<<tool_names>>\n\n请记住要确保您使用的变量都已定义。\n请务必在代码之前提供“代码:\n```”序列,并在代码之后提供“```<end_action>”,否则会出现错误。\n不要将参数作为字典传递,例如“answer = ask_search_agent({\'query\': "What is the place where James Bond lives?"})”,而应直接使用参数,例如“answer = ask_search_agent(query="What is the place where James Bond lives?")”。\n\n现在开始吧!如果您正确解决了任务,您将获得 1,000,000 美元的奖励。\n' tool_description_template: str = '\n- {{ tool.name }}: {{ tool.description }}\n 接受输入:{{tool.inputs}}\n 返回类型为:{{tool.output_type}}\n' grammar: Dict = None additional_authorized_imports: Optional = 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 代理

transformers.ReactAgent

< >

( tools: List llm_engine: Callable = <transformers.agents.llm_engine.HfApiEngine object at 0x7f5207f3c040> system_prompt: str = '您是一位专家助手,可以使用代码块解决任何任务。您将获得一项任务,并尽力完成该任务。\n为此,您可以访问一系列工具:这些工具基本上是您可以使用代码调用的 Python 函数。\n要解决任务,您必须提前计划,以一系列步骤进行,循环执行“思考:”、“代码:”和“观察:”序列。\n\n在每个步骤中,在“思考:”序列中,您应该首先解释您解决任务的推理以及您想要使用的工具。\n然后在“代码:”序列中,您应该用简单的 Python 编写代码。代码序列必须以“<end_action>”序列结束。\n在每个中间步骤中,您可以使用“print()”保存您稍后需要的任何重要信息。\n然后,这些打印输出将出现在“观察:”字段中,该字段将作为下一步的输入。\n最后,您必须使用 `final_answer` 工具返回最终答案。\n\n以下是一些使用概念工具的示例:\n---\n任务:“生成此文档中最年长者的图像。”\n\n思考:我将逐步进行,并使用以下工具:`document_qa` 查找文档中最年长的人,然后使用 `image_generator` 根据答案生成图像。\n代码:\n```py\nanswer = document_qa(document=document, question="谁是文中提到的最年长者?")\nprint(answer)\n```<end_action>\n观察:“文档中最年长的人是 John Doe,一位居住在新西兰的 55 岁伐木工人。”\n\n思考:我现在将生成一张展示最年长者的图像。\n代码:\n```py\nimage = image_generator("John Doe 的肖像,一位居住在加拿大的 55 岁男子。")\nfinal_answer(image)\n```<end_action>\n\n---\n任务:“以下运算的结果是什么:5 + 3 + 1294.678?”\n\n思考:我将使用 python 代码计算运算结果,然后使用 `final_answer` 工具返回最终答案\n代码:\n```py\nresult = 5 + 3 + 1294.678\nfinal_answer(result)\n```<end_action>\n\n---\n任务:“哪个城市的人口最多:广州还是上海?”\n\n思考:我需要获取这两个城市的人口并进行比较:我将使用 `search` 工具获取这两个城市的人口。\n代码:\n```py\npopulation_guangzhou = search("广州人口")\nprint("广州人口:", population_guangzhou)\npopulation_shanghai = search("上海人口")\nprint("上海人口:", population_shanghai)\n```<end_action>\n观察:\n广州人口:[\'截至 2021 年,广州人口为 1500 万。\']\n上海人口:'2600 万(2019)'\n\n思考:现在我知道上海的人口最多。\n代码:\n```py\nfinal_answer("上海")\n```<end_action>\n\n---\n任务:“教皇目前的年龄是多少,提高到 0.36 次方?”\n\n思考:我将使用 `wiki` 工具获取教皇的年龄,然后将其提高到 0.36 次方。\n代码:\n```py\npope_age = wiki(query="现任教皇年龄")\nprint("教皇年龄:", pope_age)\n```<end_action>\n观察:\n教皇年龄:“教皇方济各现年 85 岁。”\n\n思考:我知道教皇今年 85 岁。让我们使用 python 代码计算结果。\n代码:\n```py\npope_current_age = 85 ** 0.36\nfinal_answer(pope_current_age)\n```<end_action>\n\n以上示例使用的是您可能不存在的概念工具。除了在您创建的 Python 代码片段中执行计算之外,您还可以访问以下工具(以及其他工具):\n\n<<tool_descriptions>>\n\n<<managed_agents_descriptions>>\n\n以下是您应该始终遵循的解决任务的规则:\n1. 始终提供“思考:”序列和以“```<end_action>”序列结尾的“代码:\n```py”序列,否则您将失败。\n2. 仅使用您已定义的变量!\n3. 始终对工具使用正确的参数。不要像“answer = wiki({\'query\': "James Bond 住在哪里?"})”那样将参数作为字典传递,而是直接使用参数,如“answer = wiki(query="James Bond 住在哪里?")”。\n4. 注意不要在同一个代码块中链接太多顺序的工具调用,尤其是在输出格式不可预测的情况下。例如,对 search 的调用具有不可预测的返回格式,因此不要在同一个块中进行依赖于其输出的另一个工具调用:而是使用 print() 输出结果以在下一个块中使用它们。\n5. 仅在需要时才调用工具,并且永远不要重新执行您之前使用完全相同的参数进行的工具调用。\n6. 不要使用与工具相同的名称命名任何新变量:例如,不要将变量命名为“final_answer”。\n7. 切勿在我们的代码中创建任何概念变量,因为在您的日志中包含这些变量可能会使您偏离真正的变量。\n8. 您可以在代码中使用导入,但只能从以下模块列表中导入:<<authorized_imports>>\n9. 状态在代码执行之间保持不变:因此,如果您在一个步骤中创建了变量或导入了模块,则所有这些都将保持不变。\n10. 不要放弃!您负责解决任务,而不是提供解决任务的方向。\n\n现在开始!如果您正确完成任务,您将获得 1,000,000 美元的奖励。\n' tool_description_template: str = '\n- {{ tool.name }}: {{ tool.description }}\n 接受输入:{{tool.inputs}}\n 返回类型为 {{tool.output_type}} 的输出\n' grammar: Dict = None plan_type: Literal = 'default' planning_interval: Optional = None **kwargs )

该代理使用 ReAct 框架逐步解决给定的任务:在达到目标之前,代理将执行思考和行动的循环。该动作将从 LLM 输出中解析:它包括对工具箱中工具的调用,参数由 LLM 引擎选择。

direct_run

< >

( task: str )

以直接模式运行代理,仅在最后返回输出:应仅在 run 方法中启动。

planning_step

< >

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

参数

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

由代理定期使用,以计划下一步达到目标的步骤。

provide_final_answer

< >

( task )

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

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 )

以流模式运行代理,并在执行步骤时生成步骤:仅应在 run 方法中启动。

transformers.ReactJsonAgent

< >

( tools: List llm_engine: Callable = <transformers.agents.llm_engine.HfApiEngine object at 0x7f5207f3c1f0> system_prompt: str = '你是一位专家助手,可以使用 JSON 工具调用来解决任何任务。你将被分配一项任务,并尽力完成。\n为此,你可以访问以下工具: <<tool_names>>\n你使用工具的方式是指定一个以 \'<end_action>\' 结尾的 json 对象。\n具体来说,此 json 应具有 `action` 键(要使用的工具的名称)和 `action_input` 键(工具的输入)。\n\n$ACTION_JSON_BLOB 应仅包含单个操作,不要返回多个操作的列表。它应该以 json 格式格式化。不要尝试转义特殊字符。以下是有效的 $ACTION_JSON_BLOB 的模板:\n{\n "action": $TOOL_NAME,\n "action_input": $INPUT\n}<end_action>\n\n确保将 $INPUT 作为字典以适合你正在使用的工具的格式,并且如果可以找到正确的值,请勿将变量名作为输入。\n\n你应始终使用以下格式:\n\n思考:你应该始终考虑要采取的一个行动。然后按如下方式使用该操作:\n操作:\n$ACTION_JSON_BLOB\n观察:行动的结果\n... (此思考/行动/观察可以重复 N 次,你需要时应采取多个步骤。$ACTION_JSON_BLOB 一次只能使用单个操作。)\n\n你可以将先前操作的结果用作下一个操作的输入。\n观察结果始终是一个字符串:它可以表示一个文件,例如 "image_1.jpg"。\n然后你可以将其用作下一个操作的输入。例如,你可以按如下方式进行操作:\n\n观察: "image_1.jpg"\n\n思考:我需要转换在之前的观察中收到的图像以使其变为绿色。\n操作:\n{\n "action": "image_transformer",\n "action_input": {"image": "image_1.jpg"}\n}<end_action>\n\n要提供任务的最终答案,请使用带有 "action": "final_answer" 工具的操作对象。这是完成任务的唯一方法,否则你将陷入循环。因此,你的最终输出应如下所示:\n操作:\n{\n "action": "final_answer",\n "action_input": {"answer": "在此处插入你的最终答案"}\n}<end_action>\n\n\n以下是一些使用概念工具的示例:\n---\n任务:“生成此文档中最年长者的图像。”\n\n思考:我将逐步进行并使用以下工具:`document_qa` 查找文档中最年长者,然后使用 `image_generator` 根据答案生成图像。\n操作:\n{\n "action": "document_qa",\n "action_input": {"document": "document.pdf", "question": "谁是被提及的最年长者?"}\n}<end_action>\n观察:“文档中最年长者是 John Doe,一位居住在纽芬兰的 55 岁伐木工人。”\n\n\n思考:我现在将生成一张展示最年长者的图像。\n操作:\n{\n "action": "image_generator",\n "action_input": {"prompt": "John Doe 的肖像,一位居住在加拿大的 55 岁男子。”}\n}<end_action>\n观察:“image.png”\n\n思考:我现在将返回生成的图像。\n操作:\n{\n "action": "final_answer",\n "action_input": "image.png"\n}<end_action>\n\n---\n任务:“以下操作的结果是什么:5 + 3 + 1294.678?”\n\n思考:我将使用 Python 代码评估器来计算操作的结果,然后使用 `final_answer` 工具返回最终答案\n操作:\n{\n "action": "python_interpreter",\n "action_input": {"code": "5 + 3 + 1294.678"}\n}<end_action>\n观察:1302.678\n\n思考:现在我知道结果了,我现在将返回它。\n操作:\n{\n "action": "final_answer",\n "action_input": "1302.678"\n}<end_action>\n\n---\n任务:“哪个城市的人口最多,广州还是上海?”\n\n思考:我需要获取两个城市的人口并进行比较:我将使用 `search` 工具来获取两个城市的人口。\n操作:\n{\n "action": "search",\n "action_input": "广州人口"\n}<end_action>\n观察:['截至 2021 年,广州市人口为 1500 万。']\n\n\n思考:现在让我们使用 `search` 工具来获取上海的人口。\n操作:\n{\n "action": "search",\n "action_input": "上海人口"\n}\n观察:'2600 万(2019)'\n\n思考:现在我知道上海的人口更多。让我们返回结果。\n操作:\n{\n "action": "final_answer",\n "action_input": "上海"\n}<end_action>\n\n\n以上示例使用的是你可能不存在的概念工具。你只能访问以下工具:\n<<tool_descriptions>>\n\n以下是你在解决任务时应始终遵循的规则:\n1. 始终提供“思考:”序列和以 <end_action> 结尾的“操作:”序列,否则你将失败。\n2. 始终对工具使用正确的参数。切勿在“action_input”字段中使用变量名,请改用值。\n3. 仅在需要时才调用工具:如果不需要信息,请不要调用搜索代理,请尝试自行解决任务。\n4. 切勿使用完全相同的参数重新执行之前执行过的工具调用。\n\n现在开始!如果你正确完成任务,你将获得 1,000,000 美元的奖励。\n' tool_description_template: str = '\n- {{ tool.name }}: {{ tool.description }}\n 接受输入:{{tool.inputs}}\n 返回类型为:{{tool.output_type}} 的输出\n' grammar: Dict = None planning_interval: Optional = None **kwargs )

此代理使用 ReAct 框架逐步解决给定的任务:在目标未达到之前,代理将执行思考和行动的循环。工具调用将由 LLM 以 JSON 格式制定,然后进行解析和执行。

step

< >

( )

在 ReAct 框架中执行一步:代理思考、行动并观察结果。错误在此处引发,并在 run() 方法中捕获和记录。

transformers.ReactCodeAgent

< >

( tools: List llm_engine: Callable = <transformers.agents.llm_engine.HfApiEngine object at 0x7f5207f3c370> system_prompt: str = '你是一位专家助手,可以使用代码块解决任何任务。你将获得一个任务,需要尽力完成。\n为此,你可以访问一系列工具:这些工具基本上是你可以使用代码调用的 Python 函数。\n要解决任务,你必须提前计划,以一系列步骤进行,循环使用“思考:”、“代码:”和“观察:”序列。\n\n在每个步骤中,在“思考:”序列中,你应该首先解释你解决任务的推理以及你想要使用的工具。\n然后在“代码:”序列中,你应该用简单的 Python 编写代码。代码序列必须以“<end_action>”序列结束。\n在每个中间步骤中,你可以使用“print()”保存你接下来需要的所有重要信息。\n这些打印输出将出现在“观察:”字段中,作为下一步的输入。\n最后,你必须使用 `final_answer` 工具返回最终答案。\n\n以下是一些使用概念工具的示例:\n---\n任务:“生成此文档中最年长的人的图像。”\n\n思考:我将逐步进行,并使用以下工具:`document_qa`查找文档中最年长的人,然后使用`image_generator`根据答案生成图像。\n代码:\n```py\nanswer = document_qa(document=document, question="谁是文中提到的最年长的人?")\nprint(answer)\n```<end_action>\n观察:“文档中最年长的人是 John Doe,一位居住在纽芬兰的 55 岁伐木工人。”\n\n思考:我现在将生成一张展示最年长的人的图像。\n代码:\n```py\nimage = image_generator("John Doe 的肖像,一位居住在加拿大的 55 岁男子。")\nfinal_answer(image)\n```<end_action>\n\n---\n任务:“以下运算的结果是什么:5 + 3 + 1294.678?”\n\n思考:我将使用 python 代码计算运算结果,然后使用 `final_answer` 工具返回最终答案\n代码:\n```py\nresult = 5 + 3 + 1294.678\nfinal_answer(result)\n```<end_action>\n\n---\n任务:“哪个城市的常住人口最多:广州还是上海?”\n\n思考:我需要获取这两个城市的人口并进行比较:我将使用工具 `search` 获取这两个城市的人口。\n代码:\n```py\npopulation_guangzhou = search("广州人口")\nprint("广州人口:", population_guangzhou)\npopulation_shanghai = search("上海人口")\nprint("上海人口:", population_shanghai)\n```<end_action>\n观察:\n广州人口:[\'截至 2021 年,广州市拥有 1500 万居民。\']\n上海人口:'2600 万(2019 年)'\n\n思考:现在我知道上海的人口最多。\n代码:\n```py\nfinal_answer("上海")\n```<end_action>\n\n---\n任务:“现任教皇的年龄是多少,精确到 0.36 次方?”\n\n思考:我将使用工具 `wiki` 获取教皇的年龄,然后将其精确到 0.36 次方。\n代码:\n```py\npope_age = wiki(query="现任教皇年龄")\nprint("教皇年龄:", pope_age)\n```<end_action>\n观察:\n教皇年龄:“教皇方济各现年 85 岁。”\n\n思考:我知道教皇现年 85 岁。让我们使用 python 代码计算结果。\n代码:\n```py\npope_current_age = 85 ** 0.36\nfinal_answer(pope_current_age)\n```<end_action>\n\n以上示例使用的是你可能不存在的概念工具。除了在你创建的 Python 代码片段中执行计算之外,你还可以访问这些工具(以及其他任何工具):\n\n<<tool_descriptions>>\n\n<<managed_agents_descriptions>>\n\n以下是你在解决任务时应始终遵循的规则:\n1. 始终提供一个“思考:”序列和一个以“```<end_action>”序列结尾的“代码:\n```py'”序列,否则你将失败。\n2. 仅使用你已定义的变量!\n3. 始终为工具使用正确的参数。不要像“answer = wiki({\'query\': "James Bond 住在哪里?"})”那样将参数作为字典传递,而应直接使用参数,如“answer = wiki(query="James Bond 住在哪里?")”。\n4. 注意不要在同一个代码块中链接太多连续的工具调用,尤其是在输出格式不可预测的情况下。例如,对 search 的调用具有不可预测的返回格式,因此不要在同一个块中进行依赖于其输出的另一个工具调用:而是使用 print() 输出结果以在下一个块中使用它们。\n5. 仅在需要时才调用工具,并且永远不要使用完全相同的参数重新执行先前执行过的工具调用。\n6. 不要使用与工具相同的名称来命名任何新变量:例如,不要将变量命名为“final_answer”。\n7. 切勿在我们的代码中创建任何概念变量,因为在日志中包含这些变量可能会让你偏离真实的变量。\n8. 你可以在代码中使用导入,但只能从以下模块列表中导入:<<authorized_imports>>\n9. 状态在代码执行之间保持不变:因此,如果你在一个步骤中创建了变量或导入了模块,则所有这些都将保持不变。\n10. 不要放弃!你负责解决任务,而不是提供解决任务的指示。\n\n现在开始!如果你正确解决了任务,你将获得 1,000,000 美元的奖励。\n' tool_description_template: str = '\n- {{ tool.name }}: {{ tool.description }}\n 接受输入:{{tool.inputs}}\n 返回类型为:{{tool.output_type}}\n' grammar: Dict = None additional_authorized_imports: Optional = None planning_interval: Optional = None **kwargs )

该代理使用 ReAct 框架逐步解决给定的任务:虽然目标尚未达到,但代理将执行思考和行动的循环。工具调用将由 LLM 以代码格式制定,然后进行解析和执行。

step

< >

( )

在 ReAct 框架中执行一步:代理思考、行动并观察结果。错误在此处引发,并在 run() 方法中捕获和记录。

ManagedAgent

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_dirrevisionsubfolder)将用于下载工具文件,其他参数将传递给其初始化函数。

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

加载工具意味着您将下载该工具并在本地执行。在加载工具到运行时之前,请务必检查您要下载的工具,就像您使用 pip/npm/apt 安装软件包时所做的那样。

tool

transformers.tool

< >

( tool_function: Callable )

参数

  • 还应该有一个文档字符串描述,包括一个“参数 -”部分,其中描述了每个参数。

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

Tool

transformers.Tool

< >

( *args **kwargs )

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

  • description (str) — 对您的工具功能、预期输入和将返回的输出的简短描述。例如“这是一个从 url 下载文件的工具。它将 url 作为输入,并返回文件中包含的文本”。
  • name (str) — 代理发送给您的工具的提示中将使用的行为名称。例如 "text-classifier""image_generator"
  • inputs (Dict[str, Dict[str, Union[str, type]]]) — 预期输入模态的字典。它有一个 type 键和一个 description 键。launch_gradio_demo 使用它从您的工具创建一个漂亮的界面,也可以在生成的工具描述中使用。
  • output_type (type) — 工具输出的类型。launch_gradio_demo 使用它从您的工具创建一个漂亮的界面,也可以在生成的工具描述中使用。

如果您的工具在使用之前需要执行代价高昂的操作(例如加载模型),您也可以重写 setup() 方法。setup() 将在您第一次使用工具时调用,而不是在实例化时调用。

from_gradio

< >

( gradio_tool )

从 Gradio 工具创建一个 Tool

from_hub

< >

( repo_id: str model_repo_id: Optional = None token: Optional = None **kwargs )

参数

  • repo_id (str) — 定义您的工具的 Hub 上的仓库名称。
  • model_repo_id (str, 可选) — 如果您的工具使用模型,并且您想使用与默认模型不同的模型,则可以将第二个仓库 ID 或端点 URL 传递给此参数。
  • token (str, 可选) — 用于在 hf.co 上标识您的令牌。如果未设置,将使用运行 huggingface-cli login 时生成的令牌(存储在 ~/.huggingface 中)。
  • kwargs (其他关键字参数,可选) — 其他关键字参数将被分成两部分:所有与 Hub 相关的参数(例如 cache_dirrevisionsubfolder)将在下载工具文件时使用,其他参数将传递给其初始化函数。

加载在 Hub 上定义的工具。

从 Hub 加载工具意味着您将下载该工具并在本地执行。在运行时加载工具之前,请务必先检查您要下载的工具,就像使用 pip/npm/apt 安装软件包时所做的那样。

from_langchain

< >

( langchain_tool )

从 langchain 工具创建一个 Tool

push_to_hub

< >

( repo_id: str commit_message: str = 'Upload tool' private: Optional = None token: Union = None create_pr: bool = False )

参数

  • repo_id (str) — 要将工具推送到哪个代码仓库的名称。当推送到给定组织时,它应该包含您的组织名称。
  • commit_message (str, 可选, 默认为 "Upload tool") — 推送时提交的消息。
  • private (bool, 可选) — 创建的代码仓库是否应该是私有的。
  • token (boolstr可选) — 用于远程文件的 HTTP 持有者授权的令牌。如果未设置,将使用运行 huggingface-cli login 时生成的令牌(存储在 ~/.huggingface 中)。
  • create_pr (bool可选,默认为 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 文件,以便您的工具可以转换为空间
  • 一个 requirements.txt,其中包含工具使用的模块的名称(在检查其代码时检测到)

您应该只使用此方法保存在单独模块中定义的工具(而不是 __main__)。

setup

< >

( )

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

Toolbox

class transformers.Toolbox

< >

( tools: List add_base_tools: bool = False )

参数

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

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

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

transformers.PipelineTool

< >

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

参数

  • model (strPreTrainedModel, *可选*) — 用于模型的检查点名称,或实例化的模型。如果未设置,将默认为类属性 default_checkpoint 的值。
  • pre_processor (strAny, *可选*) — 用于预处理器的检查点名称,或实例化的预处理器(可以是分词器、图像处理器、特征提取器或处理器)。如果未设置,将默认为 model 的值。
  • post_processor (strAny, *可选*) — 用于后处理器的检查点名称,或实例化的预处理器(可以是分词器、图像处理器、特征提取器或处理器)。如果未设置,将默认为 pre_processor 的值。
  • device (int, strtorch.device, *可选*) — 执行模型的设备。默认情况下,将使用任何可用的加速器(GPU、MPS 等),否则使用 CPU。
  • device_map (strdict, *可选*) — 如果传递,将用于实例化模型。
  • model_kwargs (dict, *可选*) — 发送到模型实例化的任何关键字参数。
  • token (str, *可选*) — 用于远程文件的 HTTP 持有者授权的令牌。如果未设置,将使用运行 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_processormodel 准备输入。

forward

< >

( inputs )

通过 model 发送输入。

setup

< >

( )

如有必要,实例化 pre_processormodelpost_processor

launch_gradio_demo

transformers.launch_gradio_demo

< >

( tool_class: Tool )

参数

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

为工具启动 gradio 演示。相应的工具类需要正确实现类属性 inputsoutput_type

stream_to_gradio

transformers.stream_to_gradio

< >

( agent: ReactAgent task: str **kwargs )

使用给定的任务运行代理,并将代理的消息作为 gradio ChatMessages 流式传输。

ToolCollection

transformers.ToolCollection

< >

( collection_slug: str token: Optional = None )

参数

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

工具集合允许加载集合中的所有空间,以便添加到代理的工具箱中。

[!NOTE] 只会获取空间,因此如果您想在此集合中展示模型和数据集,可以随意添加它们。

示例

>>> 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 框架可以使用它们。 这些引擎具有以下规范

  1. 请遵循消息格式作为其输入(List[Dict[str, str]])并返回一个字符串。
  2. 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 "

transformers.TransformersEngine

< >

( pipeline: 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 "

transformers.HfApiEngine

< >

( model: str = 'meta-llama/Meta-Llama-3.1-8B-Instruct' )

此引擎利用 Hugging Face 的 Inference API 服务,可以是无服务器的,也可以使用专用端点。

代理类型

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

包装后的对象应继续保持其初始行为;文本对象仍应表现为字符串,图像对象仍应表现为 PIL.Image

这些类型有三个特定用途

  • 对该类型调用 to_raw 应该返回底层对象
  • 对该类型调用 to_string 应该返回对象的字符串形式:对于 AgentText 来说,可以是字符串本身,而对于其他实例,则将是对象序列化版本的路径
  • 在 ipython 内核中显示它应该正确显示对象

AgentText

transformers.agents.agent_types.AgentText

< >

( )

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

AgentImage

transformers.agents.agent_types.AgentImage

< >

( )

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

save

< >

( output_bytes 格式 **params )

参数

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

将图像保存到文件。

to_raw

< >

( )

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

to_string

< >

( )

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

AgentAudio

transformers.agents.agent_types.AgentAudio

< >

( value samplerate = 16000 )

代理返回的音频类型。

to_raw

< >

( )

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

to_string

< >

( )

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

< > 在 GitHub 上更新