آموزش هوش مصنوعی

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

متوسط مطالعه در ۱۳ دقیقه بخش ۱۲ از ۵۰ در مسیر عملی هوش مصنوعی؛ از پرامپت تا ایجنت
mahdyar
· به‌روزرسانی
آموزش smolagents؛ ساخت اولین ایجنت عملی در Hugging Face

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

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

smolagents چیست؟

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

اگر ایجنت دستی قسمت قبل را آشپزی در خانه بدانیم، smolagents مثل آشپزخانه‌ی مجهز یک رستوران است. اجاق، ظرف و دستور کار آماده است و شما فقط غذا را طراحی می‌کنید. البته در این آشپزخانه هم اگر دستور پخت (پیام سیستمی و ابزارها) بد باشد، غذا خوب نمی‌شود.

تمرکز روی CodeAgent

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

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

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

آموزش smolagents؛ کتابخانه smolagents برای ساخت ایجنت هوش مصنوعی در Hugging Face

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

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

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

شروع آموزش smolagents؛ آماده‌سازی قالب در Spaces

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

Space را مثل یک غرفه‌ی آماده در نمایشگاه تصور کنید. میز، برق و تابلو را برگزارکننده داده است و شما فقط محصولتان را می‌چینید. به همین ترتیب، Hugging Face سرور و رابط وب را فراهم می‌کند و شما فقط کد ایجنت را می‌نویسید.

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

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

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

با این حال، توکن را هیچ‌وقت مستقیم در کد ننویسید. بخش Secrets (متغیرهای محرمانه) دقیقاً برای همین ساخته شده است؛ همان اصلی که در قسمت سوم درباره‌ی کلید API گفتیم. Secret مثل گاوصندوق غرفه است: کد شما از آن استفاده می‌کند، اما بازدیدکننده‌ها محتوایش را نمی‌بینند.

فایل app.py

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

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

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

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

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

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

دکوراتور (decorator) همان خط @tool بالای تابع است. کارش شبیه برچسبی است که روی شیشه‌ی ادویه می‌زنید: محتوای شیشه عوض نمی‌شود، اما حالا آشپز می‌داند داخلش چیست. یعنی @tool یک تابع معمولی پایتون را به ابزاری تبدیل می‌کند که ایجنت آن را می‌شناسد.

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

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

python
@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

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

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

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

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

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

تنظیم مدل

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

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

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

ساخت CodeAgent

در ادامه ایجنت را می‌سازیم. پیام سیستمی در فایل جداگانه‌ی prompts.yaml نگه داشته می‌شود تا تغییر و استفاده‌ی دوباره از آن راحت باشد. کد زیر نسخه‌ای است که ابزار ساعت و جستجو را هم به فهرست اضافه کرده است؛ در قالب خام فهرست ابزارها فقط final_answer را دارد:

python
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 (کتابخانه‌ی ساخت رابط وب برای مدل‌ها) می‌سازد.

آموزش smolagents در پنج قدم؛ از کپی قالب در Spaces تا انتشار ایجنت با Gradio

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

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

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

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

مثلاً ابزار تولید تصویر قالب با یک خط از Hub بارگذاری می‌شود:

python
image_generation_tool = load_tool("agents-course/text-to-image", trust_remote_code=True)

پارامتر trust_remote_code=True یعنی شما صریحاً اجازه می‌دهید کد نویسنده‌ی ابزار روی سیستمتان اجرا شود. پس فقط از منابع معتبر استفاده کنید و کد ابزار را پیش از استفاده ببینید.

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

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

برای مثال، ابزار تبدیل تاریخ با کتابخانه‌ی jdatetime این شکل را دارد. فقط jdatetime را به فایل requirements.txt در Space اضافه کنید و ابزار را در فهرست tools بگذارید:

python
import jdatetime

@tool
def to_jalali(date: str) -> str:
    """Converts a Gregorian date to the Persian (Jalali) calendar.
    Args:
        date: A Gregorian date in YYYY-MM-DD format, e.g. '2026-10-21'.
    """
    try:
        g = datetime.date.fromisoformat(date)
        return jdatetime.date.fromgregorian(date=g).strftime("%Y/%m/%d")
    except ValueError as e:
        return f"Invalid date '{date}': {e}"

حالا اگر بپرسید «۲۱ اکتبر ۲۰۲۶ به شمسی چه روزی است؟»، ایجنت ابزار را صدا می‌زند و پاسخ ۱۴۰۵/۰۷/۲۹ را برمی‌گرداند. چون این اولین تجربه‌ی شماست، کاملاً طبیعی است که ایجنت گاهی کند باشد یا خطا کند. پس بهترین راه یادگیری آزمایش است. ابزار اضافه کنید، مدل را عوض کنید و رفتار ایجنت را مقایسه کنید.

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

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

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

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

سخن پایانی

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

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

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

برای مطالعه بیشتر

برای دنبال کردن عمیق‌تر این بحث، منابع زیر را به ترتیب از ساده به تخصصی بخوانید.

پرسش‌های پرتکرار

smolagents چیست؟

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

برای شروع smolagents چه چیزی لازم است؟

یک حساب Hugging Face و یک توکن دسترسی با مجوز inference. با کپی قالب آماده‌ی دوره در Spaces، حتی بدون نصب چیزی روی کامپیوتر خودتان می‌توانید اولین ایجنت را اجرا کنید.

چرا ابزار final_answer را نباید حذف کرد؟

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

docstring ابزار در smolagents چه اهمیتی دارد؟

smolagents توضیح ابزار و هر آرگومان را از docstring می‌خواند و به مدل نشان می‌دهد. docstring باید برای همه‌ی آرگومان‌ها توضیح متنی در بخش Args داشته باشد و نوع ورودی و خروجی تابع هم مشخص باشد.

دیدگاه‌ها

هنوز دیدگاهی ثبت نشده است. شروع‌کننده باشید — پرسش و اصلاح را با آغوش باز می‌پذیریم.

دیدگاه بگذارید

برای **پررنگ**، *مورب*، `کد` و لینک از Markdown استفاده کنید. لینک‌ها nofollow هستند.

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

تصویر کد امنیتی پنج‌رقمی

در حال دریافت کد امنیتی…

مهلت کد تمام شد. روی «کد جدید» بزنید.