Hugging Face'in Smolagents'i: Örneklerle Bir Rehber

Hugging Face’in Smolagents’i Nedir?

Hugging Face’in duyuru blogunda belirtildiği gibi, smolagents “dil modelleri için ajan yeteneklerinin kilidini açan son derece basit bir kütüphanedir.” Peki neden ajanlar oluşturmak için kütüphanelere ihtiyaç duyuyoruz?

Özünde, ajanlar LLM’ler tarafından desteklenir ve ortamlarını gözlemleyerek, planlar yaparak ve bu planları araç kutularından yararlanarak uygulayarak bir görevi dinamik biçimde çözerler. Bu ajanları oluşturmak, imkansız olmasa da, birçok bileşeni sıfırdan yazmanızı gerektirir. Bu bileşenler, ajanların API kredinizi ve yürütme sürenizi tüketmeden düzgün çalışmasını sağlar. Ajan çerçeveleri, tekerleği yeniden icat etmek zorunda kalmamanız için bunu kolaylaştırır.

YZ ajan çerçeveleri genellikle şu iki noktayla eleştirilir:

1. Çok fazla soyutlama katmanı eklerler; bu da onları katı ve hata ayıklaması zor hale getirir.
2. Ajanların kendi kendilerine dinamik iş birliği yapmalarından ziyade “iş akışlarına” odaklanırlar.

Öte yandan smolagents, bu ajan uygulamaları için umut verici kılan niteliklere sahiptir:

• Çerçevenin soyutlamaları minimumda tutulmuştur.
• Çoğu çerçeve, ajanların eylemlerini JSON/metin formatında tanımlamasını isterken smolagents’in ana yaklaşımı, eylemlerin Python kod parçacıkları olarak yazıldığı Kod Ajanlarıdır (bu, kod yazan ajanlardan farklıdır).
• Bir Hugging Face çerçevesi olarak smolagents, Hub ve Transformers kütüphanesiyle iyi entegre olur. Hub’daki birçok modeli kullanabilirsiniz (bazıları yalnızca Pro kullanıcılar için kullanılabilir) ve ayrıca OpenAI, Anthropic vb. gibi kapalı modellerle de çalışabilirsiniz.
• Halihazırda sunulan araçları kolayca kullanabilir veya neredeyse bir Python fonksiyonu yazmak kadar basit bir şekilde özel araçlarınızı minimum çabayla tanımlayabilirsiniz.

Bu nitelikler, teoride smolagents’i az çabayla tak-çalıştır YZ ajanları için uygun kılar; şimdi pratikte de böyle olup olmadığına bakalım.

Smolagents ile Bir Demo Projesi Oluşturma

Bu bölümde smolagents ile basit bir demo oluşturacağız. Uygulamamız, bir ajanın Hugging Face Daily Papers sayfasındaki en çok oy alan makaleyi almasını sağlayacak. Ajan için özel araçlarımızı oluşturup çalışmasını izleyeceğiz.

Daily Papers, günlük en iyi araştırma makalelerini takip etmek için iyi bir kaynaktır.

smolagents’i kurma

smolagents’i kullanmak için yalnızca kütüphaneyi kurmanız ve bir Hugging Face jetonu sağlamanız yeterlidir. Çerçevenin kolay kurulumu olumlu bir noktadır.

Paketi kurmak için şunu çalıştırın:

pip install smolagentsAltyapı:

Özel araçlar geliştirme

Çerçeve, kutudan çıkar çıkmaz kullanabileceğiniz yerleşik araçlar sağlasa da (ör. DuckDuckGoSearchTool), özel araçlarınızı geliştirmek de aynı derecede kolaydır. Amacımız için, her biri belirli bir görev için dört araç oluşturuyoruz:

• Günün en üst sıradaki makalesinin başlığını alma.
• Başlığını kullanarak makalenin kimliğini (ID) alma.
• Kimliği kullanarak arXiv'den makaleyi indirme.
• İndirilen PDF dosyasını okuma.

Ajan hatalarının yaygın bir nedeni araç kullanımıdır. Araçları ajansal amaçlara uygun hale getirmek için, ajanların hangi aracı ne zaman ve nasıl kullanacağını net biçimde anlamasını sağlamak önemlidir. Bunu başarmak için bu araçları tanımlarken mümkün olduğunca açık olun:

• Fonksiyon için bilgilendirici bir ad seçin.
• Fonksiyonun girdi ve çıktılarına tür ipuçları (type hints) ekleyin.
• Aracın amacına dair bir açıklama mutlaka eklenmelidir. Bu, ajan için bir kılavuz işlevi görür.

Şimdi günlük makaleler sayfasını ayrıştırıp en üstteki makalenin başlığını almak için ilk özel aracımızı oluşturalım:

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 NoneAltyapı:

@tool dekoratörüne, aracın net adlandırılmasına, tür ipuçlarına ve docstring’e dikkat edin. Benzer şekilde, arXiv’den indirebilmek için başlığa göre makale kimliğini almak üzere get_paper_id_by_title aracını tanımlıyoruz. Bu araç için Hugging Face’in API’sinden yararlanıyoruz.

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 NoneAltyapı:

Makaleyi kimliğini kullanarak indirmek Python’daki arxiv paketiyle yapılabilir. Makaleyi yerel olarak belirli bir adla kaydediyoruz ve ardından okumak için bu adı kullanıyoruz:

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 NoneAltyapı:

Bir PDF dosyasını okumak için pypdf paketini kullanabilirsiniz. Jeton kullanımını azaltmak için yalnızca makalenin ilk üç sayfasını okuyacağız.

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 contentAltyapı:

Özel araçlar tanımlayıp ajanın bunları doğru kullanmakta ya da doğru argümanları geçirmekte zorlandığını görürseniz, fonksiyon ve değişken adlarını, ayrıca araç açıklamalarını daha net ve açık hale getirmeyi düşünün.

Ajanı Çalıştırma

Araçlarımızı hazırladıktan sonra ajanimizi başlatıp çalıştırabiliriz. Ücretsiz olan Qwen2.5-Coder-32B-Instruct modelini kullanıyoruz. Bir ajanın ihtiyaç duyduğu araçlar, ajan tanımlanırken geçirilebilir. Bir ajanı tanımlama ve çalıştırma sürecinin minimum kod gerektirdiğini görebilirsiniz:

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.",
)Altyapı:

Ajan çalışırken sürecini adım adım çıktı olarak verir. Bu sayede, sağladığımız özel araçlardan yararlanırken eylemlerini kodla nasıl tanımladığını görebiliriz:

Adım 0’da ajan çıktısı

Ajan, makaleyi ilk adımda (Adım 0) okumayı bitirebilir. İkinci adımda model, makalenin kilit noktalarını yine bir Python listesi olarak listeler.

Adım 1’de ajan çıktısı

Üçüncü adımda (Adım 2) ajan, kilit noktaların bir özetini oluşturur ve son adımda (Adım 3) bunu yazdırır.

Adımlar 2, 3’te ajan çıktısı.

Ajan, her adımda hangi araçları kullanacağını belirleyebildi ve görevi hatasız tamamladı. Tüm hattın daha az araç kullanacak şekilde optimize edilebileceğini unutmayın; ancak ajanın birden fazla araç çağrısını nasıl kullandığını görmek istedim.

Daha karmaşık akıl yürütme veya araç kullanımı gerektiren zorlu görevlerde, ajanlarınızın omurgası olarak OpenAI veya Claude gibi daha yetkin modelleri de kullanabilirsiniz.

Sonuç

Bir ajan çerçevesinde ne arıyorsunuz? Bu soruya vereceğiniz yanıt hangisini kullanmanız gerektiğini netleştirir; ancak soyutlamalarla şişmemiş, size kontrol veren, iyi entegrasyonlara sahip ve direksiyona geçmeden temel unsurları sağlayan basit bir çerçeve istiyorsanız, smolagents denemeye değer bir seçenek.

Hugging Face ekosistemine iyi entegre olması, daha fazla model ve aracı elinizin altında bulundurmanız ve açık kaynak topluluğunun desteği anlamına gelir. Çerçeve, vaat ettiklerini iyi yerine getiriyor. Daha fazla yerleşik araçtan fayda görebilir; geliştirilirken bunun gerçekleştiğini görmeyi umabiliriz.

YZ ajanları ve smolagents hakkında daha fazla okumak isterseniz, şu kaynakları kaçırmayın:

• YZ Ajanlarına Giriş: Auto-GPT, AgentGPT ve BabyAGI ile Başlangıç
• YZ Ajanlarını Anlamak: Otonom Sistemlerin Geleceği
• Smolagents belgeleri: 
• Smolagents deposu