Pular para o conteúdo principal

Smolagents do Hugging Face: Um guia com exemplos

Saiba como simplificar a criação de agentes de IA com a nova biblioteca Python da Hugging Face, smolagents, e acompanhe um projeto de demonstração para vê-lo em ação.
Actualizado 17 de jan. de 2025  · 8 min de leitura

A smolagents da Hugging Face é uma nova biblioteca Python que simplifica a criação de agentes de IAtornando-os mais acessíveis para os desenvolvedores.

Neste blog, apresentarei a biblioteca smolagents, explicarei por que ela é útil e orientarei você em um projeto de demonstração para mostrar seus recursos. 

O que são os Smolagents da Hugging Face?

Conforme descrito no blog de anúncio do Hugging Face blog de anúncios da Hugging Facesmolagents é "uma biblioteca muito simples que libera recursos agênticos para modelos de linguagem". Mas por que precisamos de bibliotecas para criar agentes?

Em sua essência, os agentes são alimentados por LLMs para resolver dinamicamente uma tarefa, observando seus ambientes, fazendo planos e executando esses planos com sua caixa de ferramentas. A criação desses agentes, embora não seja impossível, exige que você escreva muitos componentes do zero. Esses componentes garantem que os agentes funcionem adequadamente sem consumir o crédito da API e o tempo de execução. As estruturas agênticas facilitam isso para que você não tenha que reinventar as rodas.

As estruturas de agentes de IA são frequentemente criticadas com base em dois pontos:

  1. Eles criam muitas camadas de abstração, o que os torna rígidos e difíceis de depurar.
  2. Eles se concentram em "fluxos de trabalho" em vez de criar agentes que possam colaborar dinamicamente por conta própria.

Por outro lado, os smolagents têm qualidades que os tornam muito promissores para essas aplicações agênticas:

  • As abstrações da estrutura são mantidas em um nível mínimo.
  • Embora a maioria das estruturas faça com que os agentes definam suas ações no formato JSON/texto, a abordagem principal do smolagents é Agentes de código na qual as ações são escritas como trechos de código Python (isso é diferente dos agentes que escrevem código).
  • Por ser uma estrutura Hugging Face, o smolagents se integra bem ao Hub e à biblioteca Transformers. Você pode usar muitos modelos do hub (alguns deles só podem ser usados como usuário Pro) e também pode trabalhar com modelos proprietários da OpenAI, Anthropic, etc.
  • Você pode utilizar facilmente as ferramentas já fornecidas ou definir suas ferramentas personalizadas com o mínimo de esforço, quase tão simples quanto escrever uma função Python.

Essas qualidades são o que, no papel, tornam os smolagents um plug-and-play com agentes de IA com pouco esforço, então vamos ver se elas se mantêm na prática.

Criando um projeto de demonstração com o Smolagents

Nesta seção, criaremos uma demonstração simples com smolagents. Nosso aplicativo fará com que um agente obtenha o artigo mais votado no Hugging Face Artigos diários página. Criamos nossas ferramentas personalizadas para o agente e as vemos funcionando em ação.

Hugging Face's Daily Papers, uma boa fonte para você ficar por dentro dos principais artigos de pesquisa diários.

Daily Papers, uma boa fonte para você ficar por dentro dos principais artigos de pesquisa diários.

Configuração de smolagents

Para usar smolagents, você só precisa instalar a biblioteca e fornecer um token Hugging Face. A facilidade de configuração da estrutura é um ponto positivo.

Para instalar o pacote, execute:

pip install smolagents

Criação de ferramentas personalizadas

Embora a estrutura forneça ferramentas integradas que você pode usar imediatamente (por exemplo, DuckDuckGoSearchTool), a criação de ferramentas personalizadas é igualmente simples. Para nosso propósito, criamos quatro ferramentas, cada uma com uma finalidade específica:

  • Obter o título do principal jornal diário.
  • Obter o ID do documento usando seu título.
  • Baixando o artigo de arXiv com o ID.
  • Ler o arquivo PDF baixado.

Uma causa comum de erros de agente é o uso da ferramenta. Para otimizar as ferramentas para fins agênticos, é importante garantir que os agentes entendam claramente qual ferramenta usar e como usá-la. Para conseguir isso, seja o mais explícito possível ao definir essas ferramentas:

  • Escolha um nome informativo para a função.
  • As entradas e saídas da função devem ter dicas de tipo.
  • Você deve incluir uma descrição da finalidade da ferramenta. Isso serve como um manual para o agente.

Agora vamos criar nossa primeira ferramenta personalizada para analisar a página dos jornais diários e obter o título do jornal mais importante:

from smolagents import tool 
# import packages that are used in our tools
import requests
from bs4 import BeautifulSoup
import json

@tool
def get_hugging_face_top_daily_paper() -> str:
    """
    This is a tool that returns the most upvoted paper on Hugging Face daily papers.
    It returns the title of the paper
    """
    try:
      url = "<https://huggingface.co/papers>"
      response = requests.get(url)
      response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
      soup = BeautifulSoup(response.content, "html.parser")

      # Extract the title element from the JSON-like data in the "data-props" attribute
      containers = soup.find_all('div', class_='SVELTE_HYDRATER contents')
      top_paper = ""

      for container in containers:
          data_props = container.get('data-props', '')
          if data_props:
              try:
                  # Parse the JSON-like string
                  json_data = json.loads(data_props.replace('&quot;', '"'))
                  if 'dailyPapers' in json_data:
                      top_paper = json_data['dailyPapers'][0]['title']
              except json.JSONDecodeError:
                  continue

      return top_paper
    except requests.exceptions.RequestException as e:
      print(f"Error occurred while fetching the HTML: {e}")
      return None

Observe o decorador @tool, a nomenclatura clara da ferramenta, as dicas de tipo e a docstring. Da mesma forma, definimos a ferramenta get_paper_id_by_title para obter o ID do artigo pelo título, para que você possa baixá-lo do arXiv. Para essa ferramenta, utilizamos a API do Hugging Face.

from huggingface_hub import HfApi

@tool
def get_paper_id_by_title(title: str) -> str:
    """
    This is a tool that returns the arxiv paper id by its title.
    It returns the title of the paper

    Args:
        title: The paper title for which to get the id.
    """
    api = HfApi()
    papers = api.list_papers(query=title)
    if papers:
        paper = next(iter(papers))
        return paper.id
    else:
        return None

Você pode fazer o download do documento usando seu ID usando o pacote Python arxiv. Salvamos o jornal localmente com um nome específico, que usamos para ler:

import arxiv

@tool
def download_paper_by_id(paper_id: str) -> None:
    """
    This tool gets the id of a paper and downloads it from arxiv. It saves the paper locally 
    in the current directory as "paper.pdf".

    Args:
        paper_id: The id of the paper to download.
    """
    paper = next(arxiv.Client().results(arxiv.Search(id_list=[paper_id])))
    paper.download_pdf(filename="paper.pdf")
    return None

Para ler um arquivo PDF, você pode usar o pacote pypdf. Leremos apenas as três primeiras páginas do documento para economizar o uso de tokens.

from pypdf import PdfReader

@tool
def read_pdf_file(file_path: str) -> str:
    """
    This function reads the first three pages of a PDF file and returns its content as a string.
    Args:
        file_path: The path to the PDF file.
    Returns:
        A string containing the content of the PDF file.
    """
    content = ""
    reader = PdfReader('paper.pdf')
    print(len(reader.pages))
    pages = reader.pages[:3]
    for page in pages:
        content += page.extract_text()
    return content

Se você definir ferramentas personalizadas e o agente tiver dificuldades para usá-las corretamente ou passar os argumentos corretos, considere tornar os nomes das funções e das variáveis, bem como as descrições das ferramentas, mais claros e explícitos.

Executando o agente

Com nossas ferramentas configuradas, agora podemos inicializar e executar nosso agente. Usamos o modelo Qwen2.5-Coder-32B-Instruct, que é de uso gratuito. As ferramentas de que um agente precisa podem ser passadas durante a definição do agente. Você pode ver que o processo de definição e execução de um agente requer um código mínimo:

from smolagents import CodeAgent, HfApiModel

model_id = "Qwen/Qwen2.5-Coder-32B-Instruct"

model = HfApiModel(model_id=model_id, token=<YOUR-API>)
agent = CodeAgent(tools=[get_hugging_face_top_daily_paper,
                         get_paper_id_by_title,
                         download_paper_by_id,
                         read_pdf_file],
                  model=model,
                  add_base_tools=True)

agent.run(
    "Summarize today's top paper on Hugging Face daily papers by reading it.",
)

À medida que o agente opera, ele produz seu processo passo a passo. Isso nos permite ver como ele define suas ações no código enquanto utiliza as ferramentas personalizadas que fornecemos:

Saída do agente do Smolagent na etapa 0

Saída do agente na etapa 0

O agente pode terminar de ler o documento na primeira etapa (Etapa 0). Na segunda etapa, o modelo lista os pontos principais do documento, novamente em uma lista Python.

A saída do agente do smolagent na etapa 1.

Saída do agente na etapa 1

Na terceira etapa (Etapa 2), o agente cria um resumo dos pontos principais e o imprime na etapa final (Etapa 3).

A saída do agente do smolagent nas etapas 2 e 3.

Saída do agente nas etapas 2 e 3.

O agente foi capaz de identificar quais ferramentas usar em cada etapa e concluiu a tarefa sem erros. Observe que todo o pipeline poderia ser otimizado para usar menos ferramentas, mas eu estava curioso para verificar como o agente utiliza várias chamadas de ferramentas.

Em tarefas mais desafiadoras, que exigem raciocínio mais complexo ou uso de ferramentas, você também pode usar modelos mais capazes como a espinha dorsal de seus agentes, como os oferecidos pela OpenAI ou pela Claude.

Conclusão

O que você procura em uma estrutura agêntica? Sua resposta deixa claro qual deles usar, mas se for uma estrutura simples que não seja sobrecarregada por abstrações, que ofereça a você controle, tenha boas integrações e forneça o básico sem tomar o controle, então o smolagents é uma boa opção para experimentar.

Estar bem integrado ao ecossistema da Hugging Face significa ter mais modelos e ferramentas à mão, além do suporte da comunidade de código aberto. A estrutura funciona bem no que promete. Ele poderia se beneficiar de mais ferramentas integradas, e podemos cruzar os dedos para que isso aconteça à medida que ele for sendo desenvolvido.

Se você quiser saber mais sobre agentes de IA e smolagents, não perca estes recursos:


Hesam Sheikh Hassani's photo
Author
Hesam Sheikh Hassani
LinkedIn
Twitter

Estudante de mestrado em Inteligência Artificial e redatora técnica de IA. Compartilho insights sobre a mais recente tecnologia de IA, tornando a pesquisa de ML acessível e simplificando tópicos complexos de IA necessários para manter você na vanguarda.

Temas

Aprenda IA com estes cursos!

Certificação disponível

curso

Trabalhando com o Hugging Face

4 hr
5.5K
Navegue e use o extenso repositório de modelos e conjuntos de dados disponíveis no Hugging Face Hub.
Ver DetalhesRight Arrow
Iniciar curso
Ver maisRight Arrow
Relacionado

tutorial

Criando agentes LangChain para automatizar tarefas em Python

Um tutorial abrangente sobre a criação de agentes LangChain com várias ferramentas para automatizar tarefas em Python usando LLMs e modelos de bate-papo usando OpenAI.
Bex Tuychiev's photo

Bex Tuychiev

14 min

tutorial

Introdução ao Text Embeddings com a API OpenAI

Explore nosso guia sobre como usar a API OpenAI para criar incorporações de texto. Descubra suas aplicações na classificação de textos, recuperação de informações e detecção de similaridade semântica.
Zoumana Keita 's photo

Zoumana Keita

7 min

tutorial

Criando um transformador com o PyTorch

Saiba como criar um modelo Transformer usando o PyTorch, uma ferramenta avançada de aprendizado de máquina moderno.
Arjun Sarkar's photo

Arjun Sarkar

26 min

tutorial

Tutorial da API de assistentes da OpenAI

Uma visão geral abrangente da API Assistants com nosso artigo, que oferece uma análise aprofundada de seus recursos, usos no setor, orientação de configuração e práticas recomendadas para maximizar seu potencial em vários aplicativos de negócios.
Zoumana Keita 's photo

Zoumana Keita

14 min

tutorial

Guia de torchchat do PyTorch: Configuração local com Python

Saiba como configurar o torchchat do PyTorch localmente com Python neste tutorial prático, que fornece orientação e exemplos passo a passo.
François Aubry's photo

François Aubry

tutorial

Como criar aplicativos LLM com o tutorial LangChain

Explore o potencial inexplorado dos modelos de linguagem grandes com o LangChain, uma estrutura Python de código aberto para criar aplicativos avançados de IA.
Moez Ali's photo

Moez Ali

12 min

Ver maisVer mais