Hugging Face's logo

smolagents 文档

模型

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

模型

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

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

模型

您可以自由创建和使用自己的模型来驱动您的 Agent。

您可以为您的 Agent 使用任何 model 可调用对象，只要

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

为了定义您的 LLM，您可以创建一个 custom_model 方法，该方法接受 消息 列表，并返回一个带有包含文本的 .content 属性的对象。此可调用对象还需要接受一个 stop_sequences 参数，该参数指示何时停止生成。

from huggingface_hub import login, InferenceClient

login("<YOUR_HUGGINGFACEHUB_API_TOKEN>")

model_id = "meta-llama/Llama-3.3-70B-Instruct"

client = InferenceClient(model=model_id)

def custom_model(messages, stop_sequences=["Task"]):
    response = client.chat_completion(messages, stop=stop_sequences, max_tokens=1000)
    answer = response.choices[0].message
    return answer

此外，custom_model 还可以接受 grammar 参数。如果您在 Agent 初始化时指定了 grammar，则此参数将传递给模型调用，并带有您在初始化时定义的 grammar，以允许 约束生成，以便强制生成格式正确的 Agent 输出。

TransformersModel

为了方便起见，我们添加了一个 TransformersModel，它通过为初始化时给定的 model_id 构建本地 transformers 管道来实现上述要点。

from smolagents import TransformersModel

model = TransformersModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct")

print(model([{"role": "user", "content": [{"type": "text", "text": "Ok!"}]}], stop_sequences=["great"]))
>>> What a

您的机器上必须安装 transformers 和 torch。如果不是这种情况，请运行 pip install smolagents[transformers]。

class smolagents.TransformersModel

< >

( model_id: typing.Optional[str] = None device_map: typing.Optional[str] = None torch_dtype: typing.Optional[str] = None trust_remote_code: bool = False **kwargs )

参数

  • model_id (str) — 用于推理的 Hugging Face 模型 ID。这可以是 Hugging Face 模型中心的路径或模型标识符。例如，"Qwen/Qwen2.5-Coder-32B-Instruct"。
  • device_map (str, 可选) — 用于初始化模型的 device_map。
  • torch_dtype (str, 可选) — 用于初始化模型的 torch_dtype。
  • trust_remote_code (bool, 默认值 False) — Hub 上的一些模型需要运行远程代码：对于此模型，您必须将此标志设置为 True。
  • kwargs (dict, 可选) — 您想要在 model.generate() 中使用的任何其他关键字参数，例如 max_new_tokens 或 device。
  • **kwargs — 传递给 model.generate() 的其他关键字参数，例如 max_new_tokens 或 device。

引发

ValueError

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

一个使用 Hugging Face 的 Transformers 库进行语言模型交互的类。

此模型允许您使用 Transformers 库在本地加载和使用 Hugging Face 的模型。它支持停止序列和语法自定义等功能。

您的机器上必须安装 transformers 和 torch。如果不是这种情况，请运行 pip install smolagents[transformers]。

示例

>>> engine = TransformersModel(
...     model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
...     device="cuda",
...     max_new_tokens=5000,
... )
>>> messages = [{"role": "user", "content": "Explain quantum mechanics in simple terms."}]
>>> response = engine(messages, stop_sequences=["END"])
>>> print(response)
"Quantum mechanics is the branch of physics that studies..."

HfApiModel

HfApiModel 包装了 huggingface_hub 的 InferenceClient，用于执行 LLM。它同时支持 HF 自己的 Inference API 以及 Hub 上提供的所有 Inference Providers。

from smolagents import HfApiModel

messages = [
  {"role": "user", "content": [{"type": "text", "text": "Hello, how are you?"}]}
]

model = HfApiModel()
print(model(messages))
>>> Of course! If you change your mind, feel free to reach out. Take care!

class smolagents.HfApiModel

< >

( model_id: str = 'Qwen/Qwen2.5-Coder-32B-Instruct' provider: typing.Optional[str] = None token: typing.Optional[str] = None timeout: typing.Optional[int] = 120 client_kwargs: dict[str, typing.Any] | None = None custom_role_conversions: dict[str, str] | None = None **kwargs )

参数

  • model_id (str, 可选, 默认值 "Qwen/Qwen2.5-Coder-32B-Instruct") — 用于推理的 Hugging Face 模型 ID。这可以是 Hugging Face 模型中心的模型标识符，也可以是已部署 Inference Endpoint 的 URL。目前，它默认为 "Qwen/Qwen2.5-Coder-32B-Instruct"，但这在未来可能会更改。
  • provider (str, 可选) — 用于推理的提供商名称。可以是 "replicate"、"together"、"fal-ai"、"sambanova" 或 "hf-inference"。默认为 hf-inference (HF Inference API)。
  • token (str, 可选) — Hugging Face API 用于身份验证的令牌。此令牌需要被授权“调用无服务器 Inference API”。如果模型是门控的（如 Llama-3 模型），则令牌还需要“读取您可以访问的所有公共门控存储库的内容的权限”。如果未提供，该类将尝试使用环境变量“HF_TOKEN”，否则使用存储在 Hugging Face CLI 配置中的令牌。
  • timeout (int, 可选, 默认为 120) — API 请求的超时时间，以秒为单位。
  • client_kwargs (dict[str, Any], 可选) — 要传递给 Hugging Face InferenceClient 的其他关键字参数（如 provider、token、timeout 等）。
  • custom_role_conversions (dict[str, str], 可选) — 自定义角色转换映射，用于将消息角色转换为其他角色。对于不支持特定消息角色（如“system”）的特定模型很有用。
  • **kwargs — 要传递给 Hugging Face API 的其他关键字参数。

引发

ValueError

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

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

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

示例

>>> engine = HfApiModel(
...     model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
...     token="your_hf_token_here",
...     max_tokens=5000,
... )
>>> messages = [{"role": "user", "content": "Explain quantum mechanics in simple terms."}]
>>> response = engine(messages, stop_sequences=["END"])
>>> print(response)
"Quantum mechanics is the branch of physics that studies..."

create_client

< >

( )

创建 Hugging Face 客户端。

LiteLLMModel

LiteLLMModel 利用 LiteLLM 来支持来自各种提供商的 100 多个 LLM。您可以在模型初始化时传递 kwargs，这些 kwargs 将在每次使用模型时使用，例如在下面我们传递 temperature。

from smolagents import LiteLLMModel

messages = [
  {"role": "user", "content": [{"type": "text", "text": "Hello, how are you?"}]}
]

model = LiteLLMModel(model_id="anthropic/claude-3-5-sonnet-latest", temperature=0.2, max_tokens=10)
print(model(messages))

class smolagents.LiteLLMModel

< >

( model_id: typing.Optional[str] = None api_base = None api_key = None custom_role_conversions: dict[str, str] | None = None flatten_messages_as_text: bool | None = None **kwargs )

参数

  • model_id (str) — 服务器上使用的模型标识符 (例如 “gpt-3.5-turbo”)。
  • api_base (str, 可选) — 调用模型的提供商 API 的基本 URL。
  • api_key (str, 可选) — 用于身份验证的 API 密钥。
  • custom_role_conversions (dict[str, str], 可选) — 自定义角色转换映射，用于转换其他角色中的消息角色。对于不支持特定消息角色（如“system”）的特定模型非常有用。
  • flatten_messages_as_text (bool, 可选) — 是否将消息展平为文本。对于以“ollama”、“groq”、“cerebras”开头的模型，默认为 True。
  • **kwargs — 传递给 OpenAI API 的其他关键字参数。

使用 LiteLLM Python SDK 访问数百个 LLM 的模型。

create_client

< >

( )

创建 LiteLLM 客户端。

OpenAIServerModel

此类允许您调用任何与 OpenAIServer 兼容的模型。以下是如何设置它（您可以自定义 api_base url 以指向另一个服务器）

import os
from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="gpt-4o",
    api_base="https://api.openai.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

class smolagents.OpenAIServerModel

< >

( model_id: str api_base: typing.Optional[str] = None api_key: typing.Optional[str] = None organization: typing.Optional[str] = None project: typing.Optional[str] = None client_kwargs: dict[str, typing.Any] | None = None custom_role_conversions: dict[str, str] | None = None flatten_messages_as_text: bool = False **kwargs )

参数

  • model_id (str) — 服务器上使用的模型标识符 (例如 “gpt-3.5-turbo”)。
  • api_base (str, 可选) — 兼容 OpenAI 的 API 服务器的基本 URL。
  • api_key (str, 可选) — 用于身份验证的 API 密钥。
  • organization (str, 可选) — 用于 API 请求的组织。
  • project (str, 可选) — 用于 API 请求的项目。
  • client_kwargs (dict[str, Any], 可选) — 传递给 OpenAI 客户端的其他关键字参数（例如 organization、project、max_retries 等）。
  • custom_role_conversions (dict[str, str], 可选) — 自定义角色转换映射，用于转换其他角色中的消息角色。对于不支持特定消息角色（如“system”）的特定模型非常有用。
  • flatten_messages_as_text (bool, 默认值 False) — 是否将消息展平为文本。
  • **kwargs — 传递给 OpenAI API 的其他关键字参数。

此模型连接到兼容 OpenAI 的 API 服务器。

AzureOpenAIServerModel

AzureOpenAIServerModel 允许您连接到任何 Azure OpenAI 部署。

下面您可以找到如何设置它的示例，请注意，您可以省略 azure_endpoint、api_key 和 api_version 参数，前提是您已设置相应的环境变量 — AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY 和 OPENAI_API_VERSION。

请注意 OPENAI_API_VERSION 缺少 AZURE_ 前缀，这是由于底层 openai 包的设计方式所致。

import os

from smolagents import AzureOpenAIServerModel

model = AzureOpenAIServerModel(
    model_id = os.environ.get("AZURE_OPENAI_MODEL"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    api_version=os.environ.get("OPENAI_API_VERSION")    
)

class smolagents.AzureOpenAIServerModel

< >

( model_id: str azure_endpoint: typing.Optional[str] = None api_key: typing.Optional[str] = None api_version: typing.Optional[str] = None client_kwargs: dict[str, typing.Any] | None = None custom_role_conversions: dict[str, str] | None = None **kwargs )

参数

  • model_id (str) — 连接时使用的模型部署名称 (例如 “gpt-4o-mini”)。
  • azure_endpoint (str, 可选) — Azure 端点，包括资源，例如 https://example-resource.azure.openai.com/。如果未提供，将从 AZURE_OPENAI_ENDPOINT 环境变量中推断。
  • api_key (str, 可选) — 用于身份验证的 API 密钥。如果未提供，将从 AZURE_OPENAI_API_KEY 环境变量中推断。
  • api_version (str, 可选) — 要使用的 API 版本。如果未提供，将从 OPENAI_API_VERSION 环境变量中推断。
  • client_kwargs (dict[str, Any], 可选) — 传递给 AzureOpenAI 客户端的其他关键字参数（例如 organization、project、max_retries 等）。
  • custom_role_conversions (dict[str, str], 可选) — 自定义角色转换映射，用于转换其他角色中的消息角色。对于不支持特定消息角色（如“system”）的特定模型非常有用。
  • **kwargs — 传递给 Azure OpenAI API 的其他关键字参数。

此模型连接到 Azure OpenAI 部署。

MLXModel

from smolagents import MLXModel

model = MLXModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct")

print(model([{"role": "user", "content": "Ok!"}], stop_sequences=["great"]))
>>> What a

您的机器上必须安装 mlx-lm。如果不是这种情况，请运行 pip install smolagents[mlx-lm]。

class smolagents.MLXModel

< >

( model_id: str tool_name_key: str = 'name' tool_arguments_key: str = 'arguments' trust_remote_code: bool = False **kwargs )

参数

  • model_id (str) — 用于推理的 Hugging Face 模型 ID。这可以是 Hugging Face 模型 Hub 的路径或模型标识符。
  • tool_name_key (str) — 用于检索工具名称的键，通常可以在模型的聊天模板中找到。
  • tool_arguments_key (str) — 用于检索工具参数的键，通常可以在模型的聊天模板中找到。
  • trust_remote_code (bool) — Hub 上的一些模型需要运行远程代码：对于此模型，您需要将此标志设置为 True。
  • kwargs (dict, 可选) — 您希望在 model.generate() 中使用的任何其他关键字参数，例如 max_tokens。

用于与使用 Apple 芯片上的 MLX 加载的模型进行交互的类。

您的机器上必须安装 mlx-lm。如果不是这种情况，请运行 pip install smolagents[mlx-lm]。

示例

>>> engine = MLXModel(
...     model_id="mlx-community/Qwen2.5-Coder-32B-Instruct-4bit",
...     max_tokens=10000,
... )
>>> messages = [
...     {
...         "role": "user",
...         "content": [
...             {"type": "text", "text": "Explain quantum mechanics in simple terms."}
...         ]
...     }
... ]
>>> response = engine(messages, stop_sequences=["END"])
>>> print(response)
"Quantum mechanics is the branch of physics that studies..."

VLLMModel

使用 vLLM 进行快速 LLM 推理和服务的模型。

from smolagents import VLLMModel

model = VLLMModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct")

print(model([{"role": "user", "content": "Ok!"}], stop_sequences=["great"]))

您必须在您的机器上安装 vllm。如果尚未安装，请运行 pip install smolagents[vllm]。

class smolagents.VLLMModel

< >

( model_id **kwargs )

参数

  • model_id (str) — 用于推理的 Hugging Face 模型 ID。这可以是 Hugging Face 模型 Hub 的路径或模型标识符。

使用 vLLM 进行快速 LLM 推理和服务的模型。

< > 更新 在 GitHub 上

←代理相关对象 工具相关对象→