Боби 3. Абзорҳо

Боби 3. Абзорҳо

Яке аз хусусиятҳои муҳими агентҳои зеҳни сунъӣ қобилияти иҷро кардани амалҳо мебошад. Тавре дидем, ин тавассути истифодаи абзорҳо (Tools) анҷом меёбад.

Дар ин боб меомӯзем, ки абзорҳо чистанд, чӣ гуна онҳоро самаранок тарҳрезӣ кунем ва чӣ гуна тавассути паёми системавӣ ба агент муаррифӣ намоем.

Бо додани абзорҳои мувофиқ ба агент ва шарҳи равшани тарзи кори онҳо, метавонед имкониятҳои зеҳни сунъии худро хеле васеъ кунед.

Дар ин боб меомӯзем

• Абзор чист ва чаро LLM ба он ниёз дорад.
• LLM абзорро чӣ гуна «даъват» мекунад, ҳарчанд худаш коде иҷро намекунад.
• Тавсифи абзор барои модел: дастӣ ва автоматӣ бо декоратори @tool.
• MCP — стандарти умумии пайваст кардани абзорҳо.
• Барои хонандагони пешрафта (дар охири боб): коди декоратори @tool ва усули __call__.

Абзори зеҳни сунъӣ чист?

Абзор функсияест, ки барои истифода ба LLM пешниҳод мешавад. Ин функсия бояд ҳадафи равшан дошта бошад.

Баъзе абзорҳои маъмул дар агентҳои зеҳни сунъӣ:

Инҳо танҳо намунаанд. Дар амал барои ҳар ниёзи муайян абзор сохтан мумкин аст.

Абзори хуб бояд қобилияти LLM-ро пурра кунад.

Масалан, агар ҳисобҳои арифметикӣ лозим бошанд, додани абзори ҳисобкунак нисбат ба такя ба қобилияти дохилии модел натиҷаи боэътимодтар медиҳад.

LLM идомаи промптро дар асоси чизҳое пешгӯӣ мекунад, ки ҳангоми омӯзиш омӯхтааст. Дониши дохилии он худ аз худ бо рӯйдодҳои нав нав намешавад. Аз ин рӯ, агар агент ба маълумоти ҷорӣ ниёз дошта бошад, бояд онро тавассути абзор дастрас кунем.

Масалан, агар аз LLM бе абзори ҷустуҷӯ дар бораи обу ҳавои имрӯз пурсед, он метавонад маълумоти сохтаву нодуруст пешниҳод кунад.

Абзор бояд чиро дар бар гирад?

• Тавсифи матнӣ: Ифодаи равшане, ки ин функсия умуман чи кор мекунад (модел бо ҳамин матн мефаҳмад, ки кай ин абзорро даъват кунад).
• Қисми иҷрокунанда (Callable): Худи функсия, ки амали воқеиро иҷро мекунад.
• Аргументҳо бо намудҳо: Муайян кардани намуди маълумот (str, int, float), то модел аргументи хато нафиристад.
• Натиҷа (Ихтиёрӣ): Намуди маълумоте, ки пас аз иҷро баргардонида мешавад.

Абзорҳо чӣ гуна кор мекунанд?

Дар модели матние, ки ин ҷо баррасӣ мекунем, LLM вуруди матнӣ мегирад ва баромади матнӣ медиҳад. Он мустақилона коди абзорро иҷро намекунад.

Вақте мегӯем «ба агент абзор медиҳем», дар назар дорем, ки:

1. Ба LLM мавҷудияти абзорро мефаҳмонем.
2. Тарзи истифодаи онро менависем.
3. Ба модел дастур медиҳем, ки ҳангоми зарурат дархости даъвати абзорро тавлид кунад.

Масалан, абзоре дорем, ки обу ҳавои ҷойи муайянро аз интернет мегирад. Агар аз LLM дар бораи обу ҳавои Париж пурсем, модел мефаҳмад, ки бояд аз ҳамин абзор истифода барад.

Ба ҷойи он ки худ маълумоти обу ҳаворо дастрас кунад, даъватеро монанди ин тавлид мекунад:

weather_tool("Paris")

Сипас муҳити иҷрои агент:

1. Ҷавоби моделро мехонад.
2. Даъвати абзорро муайян мекунад.
3. Абзорро аз номи модел иҷро мекунад.
4. Маълумоти воқеии обу ҳаворо мегирад.

Қадамҳои даъвати абзор одатан ба корбар пурра нишон дода намешаванд. Агент натиҷаи онҳоро ҳамчун паёми нав ба гуфтугӯ илова карда, контексти навшударо боз ба LLM медиҳад.

Модел ин иттилооти иловагиро коркард мекунад ва барои корбар ҷавоби табиӣ месозад.

Аз назари корбар чунин менамояд, ки LLM мустақиман бо абзор кор кард. Аммо дар воқеият муҳити иҷрои агент тамоми раванди иҷрои абзорро дар паси саҳна идора кардааст.

Дар бобҳои оянда ин равандро бештар баррасӣ мекунем.

Абзорҳоро чӣ гуна ба LLM муаррифӣ мекунем?

Ҷавоби пурра метавонад мураккаб намояд, аммо ғояи асосӣ сода аст: тавсифи матнии абзорҳои дастрасро ба модел пешниҳод мекунем, масалан ҳамчун қисми промпти системавӣ.

Барои дуруст кор кардани ин равиш, бояд ду чизро бисёр дақиқ баён кунем:

• Абзор чӣ кор мекунад?
• Кадом вурудҳои мушаххасро интизор аст?

Аз ҳамин сабаб тавсифи абзорҳоро аксаран бо сохторҳои дақиқ, монанди забонҳои барномасозӣ ё JSON, медиҳанд. Истифодаи чунин қолаб ҳатмӣ нест: ҳар қолаби равшан, дақиқ ва яксон метавонад мувофиқ бошад.

Биёед мисоли мушаххасро бинем.

Абзори содаи ҳисобкунак месозем, ки танҳо ду адади бутунро зарб мекунад:

def calculator(a: int, b: int) -> int:
    """Ду адади бутунро зарб мекунад."""
    return a * b

Абзори мо calculator ном дорад. Он ду адади бутунро зарб мекунад ва чунин вурудҳо мегирад:

• a (int) — адади бутун.
• b (int) — адади бутун.

Натиҷа низ адади бутун аст:

• int — ҳосилзарби a ва b.

Ҳамаи ин ҷузъиёт муҳиманд. Онҳоро дар як тавсифи матнӣ ҷамъ мекунем, то LLM абзорро фаҳмад:

Номи абзор: calculator
Тавсиф: Ду адади бутунро зарб мекунад.
Аргументҳо: a: int, b: int
Баргардонидани натиҷа: int

Модел маҳз ҳамин маълумотро мехоҳем дар бораи абзор бидонад.

Вақте ин тавсифро ҳамчун қисми вуруд ба LLM медиҳем, модел мефаҳмад, ки ин абзор аст, кадом аргументҳоро бояд пешниҳод кунад ва аз натиҷа чӣ интизор шавад.

Агар абзорҳои дигар илова кунем, бояд қолабро яксон нигоҳ дорем. Ин раванди дастӣ метавонад осебпазир бошад: эҳтимол баъзе ҷузъиётро фаромӯш кунем.

Оё роҳи беҳтар вуҷуд дорад?

Қолаббандии автоматии тавсифи абзорҳо

Абзори мо дар Python навишта шудааст ва таърифи функсия аллакай маълумоти заруриро дорад:

• Ном: calculator.
• Тавсиф: матни docstring — «Ду адади бутунро зарб мекунад».
• Вурудҳо ва навъҳояшон: ду аргументи int.
• Навъи баромад: int.

Забонҳои барномасозӣ барои ҳамин муфиданд: онҳо ифодакунанда, кӯтоҳ ва дақиқ мебошанд.

Метавонем коди функсияро ҳамчун мушаххасоти абзор ба LLM диҳем. Аммо барои интихоби абзор тарзи амалисозии дохилии он муҳим нест. Модел асосан бояд инҳоро донад:

• Номи абзор.
• Вазифаи он.
• Вурудҳои интизоршаванда.
• Натиҷаи баргардонидашаванда.

Бо истифодаи қобилияти худсанҷии сохтори код — introspection дар Python, метавон ин маълумотро автоматӣ гирифт.

Барои ин функсия бояд:

• Номи маънодор дошта бошад.
• Тавзеҳи docstring дошта бошад.
• Навъҳоро бо type hints муайян кунад.

Коде менависем, ки қисмҳои заруриро аз таърифи функсия мегирад. Баъд барои абзор эълон кардани функсия танҳо декоратори Python лозим мешавад.

Декоратор сатрест, ки бо аломати @ оғоз шуда, болои таърифи функсия навишта мешавад. Python функсияи моро ба функсияи декоратор медиҳад ва ба ҷойи он натиҷаи декораторро нигоҳ медорад; ҳамин тавр декоратор ба функсия қобилияти нав илова мекунад. Дар мисоли зер @tool функсияи оддии calculator-ро ба абзоре табдил медиҳад, ки усули to_string() дорад:

@tool
def calculator(a: int, b: int) -> int:
    """Ду адади бутунро зарб мекунад."""
    return a * b

print(calculator.to_string())

Бо амалисозии декоратор, функсияи to_string() чунин тавсифро автоматӣ месозад:

Tool Name: calculator, Description: Ду адади бутунро зарб мекунад., Arguments: a: int, b: int, Outputs: int

Ин ҳамон маълумотест, ки пештар дастӣ навиштем.

Амалисозии умумии синфи Tool

Синфи умумии Tool месозем, ки барои абзорҳои гуногун такроран истифода мешавад.

Ин амалисозӣ намунаи омӯзишӣ аст, аммо ба равишҳои воқеии бисёр китобхонаҳо монанд мебошад.

from typing import Callable

class Tool:
    """
    Синфе, ки як порчаи коди такроран истифодашаванда —
    абзор — ро ифода мекунад.

    Хусусиятҳо:
        name (str): Номи абзор.
        description (str): Тавсифи матнии вазифаи абзор.
        func (callable): Функсияе, ки абзор мепӯшонад.
        arguments (list): Рӯйхати аргументҳо.
        outputs (str): Навъи натиҷаи функсия.
    """

    def __init__(
        self,
        name: str,
        description: str,
        func: Callable,
        arguments: list,
        outputs: str
    ):
        self.name = name
        self.description = description
        self.func = func
        self.arguments = arguments
        self.outputs = outputs

    def to_string(self) -> str:
        """
        Ном, тавсиф, аргументҳо ва баромади абзорро
        ба шакли матнӣ бармегардонад.
        """
        args_str = ", ".join([
            f"{arg_name}: {arg_type}"
            for arg_name, arg_type in self.arguments
        ])

        return (
            f"Tool Name: {self.name},"
            f" Description: {self.description},"
            f" Arguments: {args_str},"
            f" Outputs: {self.outputs}"
        )

Шояд код мураккаб намояд, аммо агар қадам ба қадам бинем, вазифаи он равшан аст.

Бо ин синф абзорро чунин сохтан мумкин аст:

calculator_tool = Tool(
    "calculator",                       # Ном
    "Ду адади бутунро зарб мекунад.",   # Тавсиф
    calculator,                         # Функсияи даъватшаванда
    [("a", "int"), ("b", "int")],        # Ном ва навъи вурудҳо
    "int",                              # Навъи баромад
)

Навиштани ин рӯйхатҳо дастӣ дилгиркунанда аст ва хато кардан осон. Python метавонад ном, аргументҳо ва тавсифи функсияро худаш хонад (бо модули inspect), ва декоратори @tool маҳз ҳамин корро мекунад: аз функсияи оддӣ объекти Tool месозад.

Коди декоратор дар охири боб: «Коди декоратори @tool» (қисми «Барои хонандагони пешрафта»).

Бо декоратори омода, абзорро чунин муайян мекунем:

@tool
def calculator(a: int, b: int) -> int:
    """Ду адади бутунро зарб мекунад."""
    return a * b

print(calculator.to_string())

Усули to_string() тавсифи барои LLM мувофиқро автоматӣ бармегардонад:

Tool Name: calculator, Description: Ду адади бутунро зарб мекунад., Arguments: a: int, b: int, Outputs: int

Ин тавсиф ба промпти системавӣ ворид мешавад: модел аз он мефаҳмад, ки кадом абзор ҳаст ва онро бо кадом аргументҳо даъват кардан мумкин аст.

Дар боби 4 (қисми «Амалҳо») бештар меомӯзем, ки агент абзори сохтаи моро чӣ гуна даъват мекунад.

Model Context Protocol — MCP: интерфейси ягонаи абзорҳо

Model Context Protocol (MCP) протоколи кушодаест, ки тарзи пешниҳод кардани абзорҳо аз ҷониби барномаҳо ба LLM-ҳоро стандартӣ аст. Протокол маҷмӯи қоидаҳои умумист, ки ду барнома барои фаҳмидани ҳамдигар риоя мекунанд — монанди забони умумие, ки ҳарду медонанд.

MCP чунин имкониятҳо медиҳад:

• Маҷмӯи рӯзафзуни пайвастшавиҳои омода барои истифода бо моделҳо.
• Чандирӣ барои иваз кардани таъминкунандагони LLM.
• Равишҳои беҳтарин барои ҳифзи додаҳо дар зерсохтори шумо.

Яъне ҳар чаҳорчӯбае, ки MCP-ро дастгирӣ мекунад, метавонад аз абзорҳои мувофиқ бо ин протокол истифода барад. Барои ҳар чаҳорчӯба аз нав сохтани ҳамон интерфейси абзор лозим намешавад.

MCP дар боби 9 муфассалтар баррасӣ мешавад: дар он ҷо сервери MCP месозем ва онро ба агент пайваст мекунем.

Чӣ омӯхтем?

Абзорҳо дар васеъ кардани қобилиятҳои агентҳои зеҳни сунъӣ нақши муҳим доранд.

• Абзор чист? Функсияест, ки имкониятҳои иловагӣ медиҳад, масалан ҳисоб кардан ё дастрасӣ ба додаҳои берунӣ.
• Абзорро чӣ гуна муайян мекунем? Бо тавсифи равшан, вурудҳо, баромад ва функсияи даъватшаванда.
• Чаро абзорҳо заруранд? Онҳо ба агент имкон медиҳанд маҳдудияти донишҳои собити моделро ҷуброн кунад, бо маълумоти ҷорӣ кор намояд ва амалҳои махсусро иҷро кунад.

Акнун ба ҷараёни кори агент (Agent Workflow) мегузарем. Дар он мебинед, ки агент чӣ гуна мушоҳида мекунад, мулоҳиза менамояд ва амал мекунад. Боби 4 ҳамаи донишҳои то ин ҷо омӯхтаро ба ҳам мепайвандад ва барои сохтани агенти пурра коршоями худатон замина мегузорад.

Чиро бояд дар ёд дошт

• Абзор функсияи оддии Python аст, ки ба LLM пешниҳод мешавад: ном, тавсиф, аргументҳо ва навъи натиҷа дорад.
• LLM худаш абзорро иҷро намекунад: он танҳо матни даъватро менависад (масалан, weather_tool("Paris")), ва барномаи агент абзорро иҷро карда, натиҷаро ба модел бармегардонад.
• Модел абзорҳоро аз тавсифи матнии онҳо дар промпти системавӣ мешиносад; аз ин рӯ тавсиф бояд равшан ва дақиқ бошад.
• Тавсифи абзорро дастӣ навиштан мумкин аст, аммо беҳтар аст онро аз худи функсия (ном, docstring, type hints) автоматӣ гирем — декоратори @tool ҳамин корро мекунад.
• MCP стандарти умумист, ки ба як абзор имкон медиҳад дар чаҳорчӯбаҳои гуногун бе тағйир кор кунад.

Барои хонандагони пешрафта

Ин қисм барои хониши аввал ҳатмӣ нест. Дар он тафсилоти техникӣ, формулаҳо ва коди пурра оварда шудаанд. Агар китобро бори аввал мехонед, метавонед онро гузаронед ва ба боби навбатӣ гузаред.

Коди декоратори @tool

Аммо модули inspect-и Python метавонад ҳамаи ин маълумотро барои мо автоматӣ гирад. Декоратори @tool ҳамин корро мекунад.

Коди декоратор чунин аст:

import inspect

def tool(func):
    """
    Аз функсияи додашуда объекти Tool месозад.
    Ном, аргументҳо ва навъи натиҷа аз имзои функсия,
    тавсиф аз docstring гирифта мешаванд.
    """
    signature = inspect.signature(func)

    arguments = []
    for param in signature.parameters.values():
        annotation = param.annotation
        type_name = getattr(annotation, "__name__", str(annotation))
        arguments.append((param.name, type_name))

    returns = signature.return_annotation
    if returns is inspect.Signature.empty:
        outputs = "Навъи натиҷа нишон дода нашудааст"
    else:
        outputs = getattr(returns, "__name__", str(returns))

    description = inspect.getdoc(func) or "Тавсиф нест."

    return Tool(
        name=func.__name__,
        description=description,
        func=func,
        arguments=arguments,
        outputs=outputs,
    )

Декоратор аз имзои функсия (inspect.signature) ном ва навъи ҳар аргумент ва навъи натиҷаро мегирад, тавсифро аз docstring мехонад ва ҳамаашро ба объекти Tool медиҳад.

Усули __call__: истифодаи абзор ҳамчун функсия

Синфи Tool-и асосии боб танҳо тавсифи абзорро месозад. Барои он ки объекти абзорро мисли функсияи оддӣ даъват кардан мумкин бошад (масалан, calculator(3, 4)), ба синф усули махсуси __call__ илова мекунем:

class Tool:
    # ... __init__ ва to_string() мисли пештар ...

    def __call__(self, *args, **kwargs):
        """
        Функсияи дохилиро бо аргументҳои пешниҳодшуда
        даъват мекунад.
        """
        return self.func(*args, **kwargs)

*args ва **kwargs ҳамаи аргументҳои додашударо, чӣ бе ном ва чӣ бо ном, бе тағйир ба функсияи аслӣ мегузаронанд.