代理和工具
Transformers 代理是一个实验性 API,随时可能发生变化。代理返回的结果可能会有所不同,因为 API 或底层模型容易发生变化。
要详细了解代理和工具,请务必阅读介绍指南。此页面包含底层类的 API 文档。
代理
我们提供两种类型的代理,基于主要的 Agent 类
- CodeAgent 一次性操作,生成代码来解决任务,然后立即执行。
- ReactAgent 逐步操作,每一步包括一个想法,然后调用并执行一个工具。它有两个类
- ReactJsonAgent 使用 JSON 编写其工具调用。
- ReactCodeAgent 使用 Python 代码编写其工具调用。
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 )
执行工具调用
< source >( tool_name: str arguments: Dict )
使用提供的输入执行工具并返回结果。 如果参数引用状态变量,此方法会将参数替换为状态中的实际值。
extract_action
< source >( llm_output: str split_token: str )
从 LLM 输出解析操作
将在子类中实现
将日志中过去的 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 )
一个代理类,使用单个代码块解决给定的任务。它会计划所有操作,然后一次性执行所有操作。
如果您想更改代码在 `run` 方法中的清理方式,请重写此方法。
run
< source >( task: str return_generated_code: bool = False **kwargs )
运行代理执行给定的任务。
React 代理
类 transformers.ReactAgent
< source >( 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 引擎选择。
以直接模式运行代理,仅在最后返回输出:应仅在 run
方法中启动。
planning_step
< source >( task is_first_step: bool = False iteration: int = None )
由代理定期使用,以计划下一步达到目标的步骤。
此方法根据代理交互的日志,为任务提供最终答案。
run
< source >( task: str stream: bool = False reset: bool = True **kwargs )
运行代理执行给定的任务。
以流模式运行代理,并在执行步骤时生成步骤:仅应在 run
方法中启动。
类 transformers.ReactJsonAgent
< source >( 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 格式制定,然后进行解析和执行。
在 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 以代码格式制定,然后进行解析和执行。
在 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_dir
、revision
、subfolder
)将用于下载工具文件,其他参数将传递给其初始化函数。
快速加载工具的主要函数,无论是在 Hub 上还是在 Transformers 库中。
加载工具意味着您将下载该工具并在本地执行。在加载工具到运行时之前,请务必检查您要下载的工具,就像您使用 pip/npm/apt 安装软件包时所做的那样。
tool
将函数转换为 Tool 子类的实例。
Tool
代理使用的函数的基类。继承此类并实现 __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_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_dir
、revision
、subfolder
)将在下载工具文件时使用,其他参数将传递给其初始化函数。
加载在 Hub 上定义的工具。
从 Hub 加载工具意味着您将下载该工具并在本地执行。在运行时加载工具之前,请务必先检查您要下载的工具,就像使用 pip/npm/apt 安装软件包时所做的那样。
从 langchain 工具创建一个 Tool。
push_to_hub
< source >( 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 (
bool
或str
,可选) — 用于远程文件的 HTTP 持有者授权的令牌。如果未设置,将使用运行huggingface-cli login
时生成的令牌(存储在~/.huggingface
中)。 - create_pr (
bool
,可选,默认为False
) — 是否使用上传的文件创建 PR 或直接提交。
将工具上传到 Hub。
要使此方法正常工作,您的工具必须已在单独的模块中定义(而不是 __main__
)。
保存工具的相关代码文件,以便将其推送到 Hub。这会将您的工具代码复制到 output_dir
中,并自动生成
- 名为
tool_config.json
的配置文件 - 一个
app.py
文件,以便您的工具可以转换为空间 - 一个
requirements.txt
,其中包含工具使用的模块的名称(在检查其代码时检测到)
您应该只使用此方法保存在单独模块中定义的工具(而不是 __main__
)。
在此处覆盖此方法,以进行任何昂贵且需要在开始使用工具之前执行的操作。例如加载大型模型。
Toolbox
class transformers.Toolbox
< source >( tools: List add_base_tools: bool = False )
工具箱包含代理可以执行操作的所有工具,以及一些管理它们的方法。
将工具添加到工具箱
清空工具箱
从工具箱中删除工具
show_tool_descriptions
< source >( tool_description_template: str = None )
返回工具箱中所有工具的描述
根据工具名称更新工具箱中的工具。
PipelineTool
类 transformers.PipelineTool
< source >( 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 持有者授权的令牌。如果未设置,将使用运行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) — 用于加载后处理器(当与预处理器不同时)的类。
使用 post_processor
解码模型输出。
使用 pre_processor
为 model
准备输入。
通过 model
发送输入。
如有必要,实例化 pre_processor
、model
和 post_processor
。
launch_gradio_demo
为工具启动 gradio 演示。相应的工具类需要正确实现类属性 inputs
和 output_type
。
stream_to_gradio
使用给定的任务运行代理,并将代理的消息作为 gradio ChatMessages 流式传输。
ToolCollection
类 transformers.ToolCollection
< 源代码 >( collection_slug: str token: Optional = None )
工具集合允许加载集合中的所有空间,以便添加到代理的工具箱中。
[!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 框架可以使用它们。 这些引擎具有以下规范
- 请遵循消息格式作为其输入(
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 "
此引擎使用预先初始化的本地文本生成管道。
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 "
此引擎利用 Hugging Face 的 Inference API 服务,可以是无服务器的,也可以使用专用端点。
代理类型
代理可以处理工具之间任何类型的对象;工具是完全多模态的,可以接受和返回文本、图像、音频、视频以及其他类型。 为了提高工具之间的兼容性,以及在 ipython(jupyter、colab、ipython notebooks 等)中正确呈现这些返回值,我们围绕这些类型实现了包装类。
包装后的对象应继续保持其初始行为;文本对象仍应表现为字符串,图像对象仍应表现为 PIL.Image
。
这些类型有三个特定用途
- 对该类型调用
to_raw
应该返回底层对象 - 对该类型调用
to_string
应该返回对象的字符串形式:对于AgentText
来说,可以是字符串本身,而对于其他实例,则将是对象序列化版本的路径 - 在 ipython 内核中显示它应该正确显示对象
AgentText
代理返回的文本类型。行为类似于字符串。
AgentImage
代理返回的图像类型。行为类似于 PIL.Image。
save
< 来源 >( output_bytes 格式 **params )
将图像保存到文件。
返回该对象的“原始”版本。对于 AgentImage,它是 PIL.Image。
返回该对象的字符串化版本。对于 AgentImage,它是图像序列化版本的路径。
AgentAudio
代理返回的音频类型。
返回该对象的“原始”版本。它是一个 torch.Tensor
对象。
返回该对象的字符串化版本。对于 AgentAudio,它是音频序列化版本的路径。