应用程序接口
主要类
代理和工具
原文：
huggingface.co/docs/transformers/v4.37.2/en/main_classes/agent
Transformers Agents 是一个实验性 API，随时可能发生变化。代理返回的结果可能会有所不同，因为 API 或底层模型可能会发生变化。
要了解更多关于代理和工具的信息，请确保阅读入门指南。此页面包含底层类的 API 文档。
代理
我们提供三种类型的代理：HfAgent 使用开源模型的推理端点，LocalAgent 在本地使用您选择的模型，OpenAiAgent 使用 OpenAI 封闭模型。
HfAgent
class transformers.HfAgent
( url_endpoint token = None chat_prompt_template = None run_prompt_template = None additional_tools = None )
参数
url_endpoint（str）— 要使用的 url 端点的名称。token（str，可选）— 用作远程文件的 HTTP 令牌的授权。如果未设置，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。chat_prompt_template（str，可选）— 如果要覆盖chat方法的默认模板，请传递您自己的提示。在这种情况下，提示应该在此存储库中的名为chat_prompt_template.txt的文件中。run_prompt_template（str，可选）— 如果要覆盖run方法的默认模板，请传递您自己的提示。在这种情况下，提示应该在此存储库中的名为run_prompt_template.txt的文件中。additional_tools（Tool，工具列表或具有工具值的字典，可选）— 除默认工具外要包含的任何其他工具。如果传递具有与默认工具相同名称的工具，则将覆盖该默认工具。
使用推理端点生成代码的代理。
示例：
from transformers import HfAgent agent = HfAgent("https://api-inference.huggingface.co/models/bigcode/starcoder") agent.run("Is the following `text` (in Spanish) positive or negative?", text="¡Este es un API muy agradable!")
LocalAgent
class transformers.LocalAgent
( model tokenizer chat_prompt_template = None run_prompt_template = None additional_tools = None )
参数
model（PreTrainedModel，工具列表或具有工具值的字典，可选）— 除默认工具外要包含的任何其他工具。如果传递具有与默认工具相同名称的工具，则将覆盖该默认工具。
使用本地模型和分词器生成代码的代理。
示例：
import torch from transformers import AutoModelForCausalLM, AutoTokenizer, LocalAgent checkpoint = "bigcode/starcoder" model = AutoModelForCausalLM.from_pretrained(checkpoint, device_map="auto", torch_dtype=torch.bfloat16) tokenizer = AutoTokenizer.from_pretrained(checkpoint) agent = LocalAgent(model, tokenizer) agent.run("Draw me a picture of rivers and lakes.")
from_pretrained
( pretrained_model_name_or_path **kwargs )
参数
pretrained_model_name_or_path(str或os.PathLike) — Hub 上的存储库名称或包含模型和分词器的本地路径的文件夹的名称。kwargs(Dict[str, Any], optional) — 传递给 from_pretrained()的关键字参数。
从预训练检查点构建LocalAgent的便利方法。
示例：
import torch from transformers import LocalAgent agent = LocalAgent.from_pretrained("bigcode/starcoder", device_map="auto", torch_dtype=torch.bfloat16) agent.run("Draw me a picture of rivers and lakes.")
OpenAiAgent
class transformers.OpenAiAgent
( model = 'text-davinci-003' api_key = None chat_prompt_template = None run_prompt_template = None additional_tools = None )
参数
model(str, optional, 默认为"text-davinci-003") — 要使用的 OpenAI 模型的名称。api_key(str, optional) — 要使用的 API 密钥。如果未设置，将查找环境变量"OPENAI_API_KEY"。chat_prompt_template(str, optional) — 如果要覆盖chat方法的默认模板，请传递您自己的提示。可以是实际的提示模板，也可以是存储库 ID（在 Hugging Face Hub 上）。在这种情况下，提示应该在此存储库中的名为chat_prompt_template.txt的文件中。run_prompt_template(str, optional) — 如果要覆盖run方法的默认模板，请传递您自己的提示。可以是实际的提示模板，也可以是存储库 ID（在 Hugging Face Hub 上）。在这种情况下，提示应该在此存储库中的名为run_prompt_template.txt的文件中。additional_tools(Tool，工具列表或具有工具值的字典，optional) — 除默认工具之外包含的任何其他工具。如果传递具有与默认工具之一相同名称的工具，则将覆盖该默认工具。
使用 openai API 生成代码的代理。
openAI 模型以生成模式使用，因此即使对于chat() API，最好使用像"text-davinci-003"这样的模型，而不是 chat-GPT 变体。对 chat-GPT 模型的适当支持将在下一个版本中提供。
示例：
from transformers import OpenAiAgent agent = OpenAiAgent(model="text-davinci-003", api_key=xxx) agent.run("Is the following `text` (in Spanish) positive or negative?", text="¡Este es un API muy agradable!")
AzureOpenAiAgent
class transformers.AzureOpenAiAgent
( deployment_id api_key = None resource_name = None api_version = '2022-12-01' is_chat_model = None chat_prompt_template = None run_prompt_template = None additional_tools = None )
参数
deployment_id(str) — 要使用的部署的 Azure openAI 模型的名称。api_key(str, optional) — 要使用的 API 密钥。如果未设置，将查找环境变量"AZURE_OPENAI_API_KEY"。resource_name(str, optional) — 您的 Azure OpenAI 资源的名称。如果未设置，将查找环境变量"AZURE_OPENAI_RESOURCE_NAME"。api_version(str, optional, 默认为"2022-12-01") — 用于此代理的 API 版本。is_chat_mode(bool, optional) — 您是否使用完成模型或聊天模型（请参见上面的说明，聊天模型效率不高）。默认情况下，gpt将在deployment_id中或不在其中。chat_prompt_template(str, optional) — 如果要覆盖chat方法的默认模板，请传递您自己的提示。可以是实际的提示模板，也可以是存储库 ID（在 Hugging Face Hub 上）。在这种情况下，提示应该在此存储库中的名为chat_prompt_template.txt的文件中。run_prompt_template(str, optional) — 如果要覆盖run方法的默认模板，请传递您自己的提示。可以是实际的提示模板，也可以是存储库 ID（在 Hugging Face Hub 上）。在这种情况下，提示应该在此存储库中的名为run_prompt_template.txt的文件中。additional_tools(Tool，工具列表或具有工具值的字典，optional) — 除默认工具之外包含的任何其他工具。如果传递具有与默认工具之一相同名称的工具，则将覆盖该默认工具。
使用 Azure OpenAI 生成代码的代理。查看官方文档以了解如何在 Azure 上部署 openAI 模型
openAI 模型以生成模式使用，因此即使对于 chat() API，最好使用像 "text-davinci-003" 这样的模型，而不是 chat-GPT 变体。chat-GPT 模型的适当支持将在下一个版本中提供。
示例：
from transformers import AzureOpenAiAgent agent = AzureAiAgent(deployment_id="Davinci-003", api_key=xxx, resource_name=yyy) agent.run("Is the following `text` (in Spanish) positive or negative?", text="¡Este es un API muy agradable!")
代理
class transformers.Agent
( chat_prompt_template = None run_prompt_template = None additional_tools = None )
参数
chat_prompt_template(str, 可选) — 如果要覆盖chat方法的默认模板，则传递您自己的提示。在这种情况下，提示应该在此 repo 中名为chat_prompt_template.txt的文件中。run_prompt_template(str, 可选) — 如果要覆盖run方法的默认模板，则传递您自己的提示。在这种情况下，提示应该在此 repo 中名为run_prompt_template.txt的文件中。additional_tools(Tool, 工具列表或具有工具值的字典, 可选) — 除默认工具外要包含的任何其他工具。如果传递一个与默认工具中的某个同名的工具，那么默认工具将被覆盖。
包含主要 API 方法的所有代理的基类。
chat
( task return_code = False remote = False **kwargs )
参数
task(str) — 要执行的任务return_code(bool, 可选, 默认为False) — 是否只返回代码而不评估它。remote(bool, 可选, 默认为False) — 是否使用远程工具（推理端点）而不是本地工具。kwargs(额外的关键字参数, 可选) — 在评估代码时发送给代理的任何关键字参数。
向代理发送一个新的请求。将使用其历史记录中的先前请求。
示例：
from transformers import HfAgent agent = HfAgent("https://api-inference.huggingface.co/models/bigcode/starcoder") agent.chat("Draw me a picture of rivers and lakes") agent.chat("Transform the picture so that there is a rock in there")
run
( task return_code = False remote = False **kwargs )
参数
task(str) — 要执行的任务return_code(bool, 可选, 默认为False) — 是否只返回代码而不评估它。remote(bool, 可选, 默认为False) — 是否使用远程工具（推理端点）而不是本地工具。kwargs(额外的关键字参数, 可选) — 在评估代码时发送给代理的任何关键字参数。
向代理发送一个请求。
示例：
from transformers import HfAgent agent = HfAgent("https://api-inference.huggingface.co/models/bigcode/starcoder") agent.run("Draw me a picture of rivers and lakes")
prepare_for_new_chat
( )
清除之前调用 chat() 的历史记录。
工具
load_tool
transformers.load_tool
( task_or_repo_id model_repo_id = None remote = False token = None **kwargs )
参数
task_or_repo_id(str) — 要加载工具的任务或 Hub 上工具的 repo ID。在 Transformers 中实现的任务有：
"文档问答""图像字幕""图像问答""图像分割""语音到文本""摘要""文本分类""文本问答""文本到语音""翻译"
model_repo_id(str, 可选) — 使用此参数来使用与您选择的工具不同的模型。remote(bool, 可选, 默认为False) — 是否通过下载模型或（如果可用）使用推理端点来使用您的工具。token(str, 可选) — 用于在 hf.co 上识别您的令牌。如果未设置，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。kwargs（额外的关键字参数，可选） — 将被分成两部分的额外关键字参数：所有与 Hub 相关的参数（如cache_dir、revision、subfolder）将在下载工具文件时使用，其他参数将传递给其 init。
快速加载工具的主要函数，无论是在 Hub 上还是在 Transformers 库中。
工具
class transformers.Tool
( *args **kwargs )
代理使用的函数的基类。子类化这个类并实现__call__方法以及以下类属性：
description(str) — 您的工具的简短描述，它做什么，它期望的输入以及它将返回的输出。例如‘这是一个从url下载文件的工具。它以url作为输入，并返回文件中包含的文本’。name(str) — 一个表现性的名称，将在提示代理时用于您的工具。例如"text-classifier"或"image_generator"。inputs(List[str]) — 期望输入的模态列表（与调用中的顺序相同）。模态应为"text"、"image"或"audio"。仅供launch_gradio_demo使用或为您的工具创建一个漂亮的空间。outputs(List[str]) — 工具返回的模态列表（与调用方法返回的顺序相同）。模态应为"text"、"image"或"audio"。仅供launch_gradio_demo使用或为您的工具创建一个漂亮的空间。
如果您的工具有一个昂贵的操作需要在可用之前执行（例如加载模型），您也可以重写方法 setup()。setup()将在您第一次使用工具时调用，但不会在实例化时调用。
from_gradio
( gradio_tool )
从 gradio 工具创建一个 Tool。
from_hub
( repo_id: str model_repo_id: Optional = None token: Optional = None remote: bool = False **kwargs )
参数
repo_id(str) — 在 Hub 上定义您的工具的 repo 的名称。model_repo_id(str, 可选) — 如果您的工具使用模型并且想要使用不同于默认的模型，您可以将第二个 repo ID 或端点 url 传递给此参数。token(str, 可选) — 用于在 hf.co 上识别您的令牌。如果未设置，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。remote(bool, 可选，默认为False) — 是否通过下载模型或（如果可用）使用推理端点来使用您的工具。kwargs（额外的关键字参数，可选） — 将被分成两部分的额外关键字参数：所有与 Hub 相关的参数（如cache_dir、revision、subfolder）将在下载工具文件时使用，其他参数将传递给其 init。
加载在 Hub 上定义的工具。
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(bool或str, 可选) — 用作远程文件的 HTTP bearer 授权的令牌。如果未设置，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。create_pr(bool, 可选, 默认为False) — 是否创建一个带有上传文件的 PR 或直接提交。
将工具上传到 Hub。
save
( output_dir )
参数
output_dir(str) — 您想要保存工具的文件夹。
保存与您的工具相关的代码文件，以便将其推送到 Hub。这将在output_dir中复制您的工具的代码，并自动生成：
- 一个名为
tool_config.json的配置文件 - 一个
app.py文件，以便将您的工具转换为一个空间 - 一个包含您的工具使用的模块名称的
requirements.txt文件（在检查其代码时检测到）。
您应该只使用此方法来保存在单独模块中定义的工具（不是__main__）。
setup
( )
在此处覆盖任何昂贵且需要在开始使用工具之前执行的操作的方法。例如加载一个大模型。
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 加载数据的方法的任何额外关键字参数。
一个 Tool 专为 Transformer 模型定制。除了基类 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。
RemoteTool
class transformers.RemoteTool
( endpoint_url = None token = None tool_class = None )
参数
endpoint_url（str，可选）—要使用的端点的 url。token（str，可选）—用作远程文件的 HTTP bearer 授权的令牌。如果未设置，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。tool_class（type，可选）—如果这是现有工具的远程版本，则相应的tool_class。将有助于确定何时应将输出转换为另一种类型（如图像）。
将向推理端点发出请求的 Tool。
extract_outputs
( outputs )
您可以在您的自定义类 RemoteTool 中覆盖此方法，以对端点的输出应用一些自定义后处理。
prepare_inputs
( *args **kwargs )
准备接收到的输入以便通过 HTTP 客户端将数据发送到端点。如果在实例化时提供了tool_class，则位置参数将与tool_class的签名匹配。图像将被编码为字节。
您可以在您的自定义类 RemoteTool 中覆盖此方法。
launch_gradio_demo
transformers.launch_gradio_demo
( tool_class: Tool )
参数
tool_class（type）—要启动演示的工具类。
启动工具的 gradio 演示。相应的工具类需要正确实现类属性inputs和outputs。
Agent 类型
代理可以处理工具之间的任何类型的对象；工具完全多模态，可以接受和返回文本、图像、音频、视频等类型。为了增加工具之间的兼容性，并正确在 ipython（jupyter、colab、ipython 笔记本等）中呈现这些返回，我们实现了这些类型的包装类。
包装对象应继续最初的行为；文本对象仍应表现为字符串，图像对象仍应表现为PIL.Image。
这些类型有三个特定目的：
- 在类型上调用
to_raw应该返回底层对象 - 在类型上调用
to_string应该将对象作为字符串返回：在AgentText的情况下可以是字符串，但在其他实例中将是对象的序列化版本的路径 - 在 ipython 内核中显示它应该正确显示对象
AgentText
class transformers.tools.agent_types.AgentText
( value )
代理返回的文本类型。表现为字符串。
Transformers 4.37 中文文档（十三）（2）https://developer.aliyun.com/article/1564947
