آموزش smolagents؛ ساخت اولین ایجنت عملی در Hugging Face

آموزش smolagents بهترین قدم بعد از ساخت ایجنت از صفر است. در قسمت قبل دیدیم ساخت دستی یک ایجنت چقدر کار جزئی و تکراری دارد؛ از نوشتن پیام سیستمی تا متوقف‌کردن تولید در لحظه‌ی درست. کتابخانه‌های ایجنت بخش بزرگی از این کارها را خودشان انجام می‌دهند.

در این قسمت از مجموعه‌ی «از پرامپت تا دستیار هوش مصنوعی» اولین ایجنت واقعی را با smolagents می‌سازیم. ایجنتی که می‌تواند ساعت هر نقطه‌ی دنیا را بگوید، در وب جستجو کند و تصویر بسازد. در پایان هم آن را روی Hugging Face Spaces منتشر می‌کنیم تا با دوستان و همکارانتان به اشتراک بگذارید.

smolagents چیست؟

smolagents یک کتابخانه‌ی متن‌باز از Hugging Face برای ساخت ایجنت است. این کتابخانه عمداً سبک و ساده طراحی شده، اما پیچیدگی‌های ساخت ایجنت را پنهان می‌کند تا شما روی طراحی رفتار ایجنت تمرکز کنید.

تمرکز روی CodeAgent

ویژگی متمایز smolagents تمرکز روی CodeAgent است. CodeAgent نوعی ایجنت است که اقدام‌هایش را به شکل قطعه‌کد پایتون می‌نویسد، نه JSON. بعد با اجرای کد، نتیجه را مشاهده می‌کند.

رفتار این ایجنت دقیقاً همان چیزی است که در قسمت‌های قبل ساختیم. فکر می‌کند، اقدام می‌کند و مشاهده می‌کند و این چرخه را تا رسیدن به پاسخ نهایی تکرار می‌کند. تفاوت این است که حالا کتابخانه همه‌ی جزئیات را مدیریت می‌کند.

برای آشنایی بیشتر، مخزن smolagents در GitHub را هم ببینید. در قسمت سیزدهم CodeAgent را عمیق‌تر بررسی می‌کنیم.

ایجنت نمونه در عمل

برای اینکه تصویری از نتیجه‌ی کار داشته باشید، ویدئوی زیر ایجنتی را نشان می‌دهد که به ابزار تولید تصویر مجهز شده است. از ایجنت خواسته شده تصویر یک گربه را بسازد. ایجنت فکر می‌کند، ابزار را با کد صدا می‌زند و نتیجه را برمی‌گرداند.

آماده‌سازی قالب در Hugging Face Spaces

ساده‌ترین راه شروع، کپی یک قالب آماده است. دوره‌ی ایجنت‌های Hugging Face یک Space آماده به نام First_agent_template دارد. کپی این Space یعنی یک نسخه‌ی شخصی از آن روی حساب خودتان می‌سازید.

کپی Space و افزودن توکن

به صفحه‌ی قالب اولین ایجنت بروید و گزینه‌ی Duplicate را بزنید. بعد از ساخته‌شدن نسخه‌ی شخصی، ایجنت برای دسترسی به API مدل به توکن شما نیاز دارد:

1. از بخش تنظیمات حساب Hugging Face یک توکن با مجوز inference بسازید.
2. در Space خودتان به تب Settings بروید.
3. در بخش Variables and Secrets روی New Secret کلیک کنید.
4. یک Secret با نام HF_TOKEN بسازید و توکن را در آن بچسبانید.
5. تغییرات را ذخیره کنید.

توکن را هیچ‌وقت مستقیم در کد ننویسید. بخش Secrets دقیقاً برای همین ساخته شده است؛ همان اصلی که در قسمت سوم درباره‌ی کلید API گفتیم.

فایل app.py

در کل این درس فقط یک فایل را تغییر می‌دهید: app.py. آن را از تب Files در Space خودتان باز کنید. فایل با واردکردن کتابخانه‌های لازم شروع می‌شود:

from smolagents import CodeAgent, DuckDuckGoSearchTool, FinalAnswerTool, InferenceClientModel, load_tool, tool
import datetime
import pytz
import yaml
from Gradio_UI import GradioUI

کلاس اصلی ما CodeAgent است. GradioUI هم از فایل کمکی خود قالب می‌آید و رابط گفت‌وگو را می‌سازد. DuckDuckGoSearchTool یک ابزار آماده‌ی جستجوی وب است و load_tool برای بارگذاری ابزار از Hub به کار می‌رود.

تعریف ابزارها با دکوراتور tool

قالب دو ابزار نمونه دارد. یکی ابزاری ساختگی که هنوز کاری انجام نمی‌دهد و قرار است خودتان کاملش کنید. دیگری ابزاری واقعی که ساعت فعلی هر منطقه‌ی زمانی را برمی‌گرداند.

ابزار ساعت جهانی

این ابزار نام یک منطقه‌ی زمانی را می‌گیرد و ساعت محلی آنجا را برمی‌گرداند. به نحوه‌ی نوشتن docstring دقت کنید:

@tool
def get_current_time_in_timezone(timezone: str) -> str:
    """A tool that fetches the current local time in a specified timezone.
    Args:
        timezone: A string representing a valid timezone (e.g., 'Asia/Tehran').
    """
    try:
        tz = pytz.timezone(timezone)
        local_time = datetime.datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S")
        return f"The current local time in {timezone} is: {local_time}"
    except Exception as e:
        return f"Error fetching time for timezone '{timezone}': {e}"

اگر منطقه‌ی زمانی نامعتبر باشد، ابزار به‌جای شکستن برنامه یک پیام خطای روشن برمی‌گرداند. همان‌طور که در قسمت ابزارها گفتیم، مدل می‌تواند با دیدن این پیام راه دیگری امتحان کند.

دو قانون مهم برای ابزار در smolagents

قانون اول: نوع ورودی و خروجی تابع را مشخص کنید؛ مثل timezone: str و -> str. smolagents از همین نوع‌ها برای ساخت توضیح ابزار استفاده می‌کند.

قانون دوم: docstring باید قالب درستی داشته باشد. smolagents انتظار دارد همه‌ی آرگومان‌ها در بخش Args توضیح متنی داشته باشند. اگر توضیح آرگومانی جا بیفتد، کتابخانه خطا می‌دهد. این سخت‌گیری در واقع به نفع شماست، چون توضیح دقیق کیفیت استفاده‌ی مدل از ابزار را بالا می‌برد.

ساخت مدل و ایجنت

حالا مدل زبانی را که مغز ایجنت است تعریف می‌کنیم و ایجنت را با ابزارهایش می‌سازیم. قالب از مدل Qwen2.5-Coder-32B-Instruct استفاده می‌کند که از طریق همان Serverless API قسمت قبل در دسترس است.

تنظیم مدل

کلاس InferenceClientModel پشت صحنه از همان InferenceClient استفاده می‌کند که در ساخت ایجنت از صفر دیدیم:

model = InferenceClientModel(
    model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
    max_tokens=2096,
    temperature=0.5,
)

مدل‌هایی که در کدنویسی قوی‌اند، برای CodeAgent انتخاب بهتری‌اند، چون اقدام‌ها به شکل کد نوشته می‌شوند. اگر این مدل در دسترس نبود، یک مدل کدنویس دیگر از فهرست مدل‌های Hugging Face انتخاب کنید.

ساخت CodeAgent

حالا ایجنت را می‌سازیم. پیام سیستمی در فایل جداگانه‌ی prompts.yaml نگه داشته می‌شود تا تغییر و استفاده‌ی دوباره از آن راحت باشد:

with open("prompts.yaml") as stream:
    prompt_templates = yaml.safe_load(stream)

agent = CodeAgent(
    model=model,
    tools=[FinalAnswerTool(), get_current_time_in_timezone, DuckDuckGoSearchTool()],
    max_steps=6,
    prompt_templates=prompt_templates,
)
GradioUI(agent).launch()

به max_steps=6 دقت کنید؛ همان سقف قدمی که در قسمت دهم درباره‌اش صحبت کردیم. ابزار FinalAnswerTool را هم هرگز حذف نکنید، چون ایجنت پاسخ نهایی را با همین ابزار اعلام می‌کند. خط آخر هم یک رابط گرافیکی گفت‌وگو با Gradio می‌سازد.

افزودن توانایی‌های تازه به ایجنت

در قالب اولیه، ایجنت هیچ ابزاری جز پاسخ نهایی ندارد. هدف اصلی این درس این است که با افزودن ابزار، توانایی‌های تازه به ایجنت بدهید. هر ابزار تازه یعنی یک کار تازه که ایجنت می‌تواند انجام دهد.

ابزارهای آماده و ابزارهای Hub

دو منبع آماده برای ابزار دارید. اول ابزارهای داخلی smolagents مثل DuckDuckGoSearchTool که بدون هیچ تنظیمی جستجوی وب را ممکن می‌کند. دوم ابزارهایی که دیگران در Hugging Face Hub منتشر کرده‌اند.

مثلاً ابزار تولید تصویر قالب با یک خط از Hub بارگذاری می‌شود. فقط دقت کنید بارگذاری ابزار از Hub یعنی اجرای کد دیگران روی سیستم شما. پس فقط از منابع معتبر استفاده کنید و کد ابزار را پیش از استفاده ببینید.

ابزار اختصاصی خودتان

ابزار ساختگی قالب را به چیزی مفید تبدیل کنید. چند ایده: ابزاری که قیمت ارز را از یک API می‌گیرد، ابزاری که تاریخ میلادی را به شمسی تبدیل می‌کند، یا ابزاری که یک متن را خلاصه می‌کند.

چون این اولین تجربه‌ی شماست، کاملاً طبیعی است که ایجنت گاهی کند باشد یا خطا کند. بهترین راه یادگیری آزمایش است. ابزار اضافه کنید، مدل را عوض کنید و رفتار ایجنت را مقایسه کنید.

تمرین عملی؛ دستیار دوره‌ها در Spaces

دستیار پروژه‌ی مشترک را به یک ایجنت واقعی در Spaces تبدیل کنید:

1. ابزار search_courses را با دکوراتور @tool و docstring کامل در app.py تعریف کنید.
2. آن را همراه FinalAnswerTool به فهرست ابزارهای ایجنت اضافه کنید.
3. از رابط Gradio بپرسید «یک دوره‌ی پایتون مبتدی پیشنهاد بده» و مراحل فکر و اقدام ایجنت را در خروجی دنبال کنید.

اگر ایجنت ابزار را اشتباه صدا زد، اول docstring را دقیق‌تر کنید. بیشتر مشکلات ایجنت‌های تازه‌کار از توضیح مبهم ابزار شروع می‌شود.

سخن پایانی

این آموزش smolagents نشان داد ساخت یک ایجنت واقعی با کتابخانه‌ی مناسب چقدر سریع است. یک قالب آماده، چند ابزار با docstring دقیق، یک مدل کدنویس و یک CodeAgent با سقف قدم کافی است. نتیجه ایجنتی است که با رابط گرافیکی روی Hugging Face Spaces اجرا می‌شود و می‌توانید لینکش را با هر کسی به اشتراک بگذارید.

در قسمت سیزدهم عمیق‌تر به CodeAgent می‌پردازیم و می‌بینیم چرا نوشتن اقدام به شکل کد از JSON قدرتمندتر است.

این آموزش بر پایه‌ی بخش Let's Create Our First Agent Using smolagents از دوره‌ی آزاد Agents Course در Hugging Face (مجوز Apache-2.0) به فارسی بازنویسی و تکمیل شده است.