گسترش هسته معنایی: ایجاد پلاگین برای پرس و جوهای پویا

1. مقدمه

در آموزش قبلی نحوه پیکربندی و استفاده را بررسی کردیم هسته معنایی همراه با آرزو کنید y بودن برای ایجاد یک API اساسی که خلاصه های متنی را تولید می کند. حالا بیایید یک قدم جلوتر برویم و روی یکی از قدرتمندترین ویژگی‌های Semantic Kernel تمرکز کنیم: the پلاگین ها.

در این آموزش نحوه ایجاد و استفاده از افزونه ها در Semantic Kernel را خواهید آموخت. پلاگین ها کلاس ها یا مؤلفه هایی هستند که توابع خاصی را در خود محصور می کنند و به شما امکان می دهند قابلیت های هسته را با توانایی های سفارشی جدید گسترش دهید.

برای مثال، ما دو افزونه توسعه خواهیم داد:

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

پلاگین ها در Semantic Kernel به شما امکان می دهند مهارت های مدولار و قابل استفاده مجدد را اضافه کنید. این نه تنها مقیاس پذیری پروژه را تسهیل می کند، بلکه درها را برای ادغام خدمات خارجی یا منطق سفارشی به روشی ساده و کارآمد باز می کند.

توجه 💡: در اینجا می توانید کد منبع این آموزش را پیدا کنید: DevToPosts/SemanticKernelSeries/SemanticKernelLearning02 در اصلی · isaacOjeda/DevToPosts

2. پلاگین ها در Semantic Kernel چیست؟

پلاگین در Semantic Kernel چیست؟

و افزونه در Semantic Kernel کلاسی است که شامل متدهایی است که با ویژگی های خاص تزئین شده اند، مانند [KernelFunction]، عملکرد آن را در معرض کرنل قرار دهد. این اجازه می دهد تا آن توابع توسط کرنل فراخوانی شوند که گویی قسمت های داخلی سیستم شما هستند.

چرا از پلاگین ها استفاده کنیم؟

• مدولاریت: پلاگین ها منطق خاصی را در بر می گیرند و نگهداری و استفاده مجدد از آنها را آسان می کنند.
• انعطاف پذیری: می‌توانید برای انجام کارهایی مانند تعامل با APIهای خارجی، پردازش داده‌ها یا انجام محاسبات، افزونه‌هایی ایجاد کنید.
• ادغام ساده: پلاگین ها به راحتی در هسته ثبت می شوند و برای استفاده در API یا در جریان های پیچیده تر در دسترس قرار می گیرند.

اجزای کلیدی یک پلاگین

1. روش های تزئین شده با [KernelFunction]: این توابعی را که هسته می تواند فراخوانی کند مشخص می کند.
2. توضیحات: روش‌ها ممکن است شامل توضیحاتی برای مستندسازی هدفشان باشد که کشف آنها را آسان‌تر می‌کند.
3. وابستگی های خارجی: پلاگین ها می توانند با استفاده از الگوهایی که به عنوان شناخته می شوند با سرویس های خارجی مانند API ها تعامل داشته باشند IHttpClientFactory.

پلاگین هایی که در این آموزش خواهیم ساخت

• TimeInformation Service: افزونه ای که زمان فعلی را در UTC ارائه می دهد.
• WeatherInformation Service: افزونه ای که از یک API خارجی برای به دست آوردن موقعیت جغرافیایی و اطلاعات آب و هوا استفاده می کند.

هر دو پلاگین در هسته ما ادغام می شوند و از طریق API که در آموزش قبلی توسعه داده ایم در معرض دید قرار می گیرند.

پلاگین ها در Semantic Kernel چگونه کار می کنند؟

پلاگین های ثبت شده در هسته را می توان در زمان اجرا از طریق دستورات یا مستقیماً از طریق کد فراخوانی کرد. هسته به طور خودکار اجرای این روش ها را مدیریت می کند و به آنها اجازه می دهد تا در جریان های پردازش پیچیده ادغام شوند.

3. توسعه مثال

حالا که فهمیدیم پلاگین ها چیست هسته معنایی، ما قصد داریم دو افزونه سفارشی را در پروژه خود توسعه و ادغام کنیم:

1. TimeInformation Service: یک افزونه ساده که زمان فعلی را در UTC برمی گرداند.
2. WeatherInformation Service: یک افزونه پیشرفته تر که از یک API خارجی برای به دست آوردن اطلاعات در مورد آب و هوا در یک شهر استفاده می کند.

مرحله 1: افزونه ها را ایجاد کنید

TimeInformation Service

افزونه زیر زمان فعلی را با فرمت UTC ارائه می دهد. این یک مثال ساده برای درک نحوه عملکرد پلاگین های اساسی در Semantic Kernel است.

/// 

/// A plugin that returns the current time.
/// 
public class TimeInformationService
{
    [KernelFunction]
    [Description("Retrieves the current time in UTC.")]
    public string GetCurrentUtcTime() => DateTime.UtcNow.ToString("R");
}

در اینجا ما برجسته می کنیم:

• صفت [KernelFunction] روش را در معرض کرنل قرار می دهد.
• این روش زمان را در قالب “R” (RFC1123) برمی گرداند که قابل خواندن و استاندارد است.

WeatherInformation Service

این افزونه پیچیده تر است. اطلاعات مربوط به یک شهر (مختصات، کشور و غیره) و همچنین آب و هوای فعلی را با استفاده از خدمات خارجی دریافت می کند.

public class WeatherInformationService(IHttpClientFactory httpClientFactory)
{
    [KernelFunction]
    [Description("Get weather information for a city.")]
    public async Task<WeatherInfo> GetWeatherByCity(string cityName)
    {
        if (string.IsNullOrWhiteSpace(cityName))
            throw new ArgumentException("City name cannot be null or empty.", nameof(cityName));

        // Step 1: Get city coordinates
        var city = await GetCityCoordinatesAsync(cityName);

        // Step 2: Get weather data
        var weatherResult = await GetWeatherDataAsync(city.Latitude, city.Longitude);

        return new WeatherInfo
        {
            City = city.Name,
            Country = city.Country,
            Temperature = weatherResult.CurrentWeather.Temperature,
            WindSpeed = weatherResult.CurrentWeather.Windspeed,
            WeatherCode = weatherResult.CurrentWeather.Weathercode
        };
    }

    private async Task<GeocodingResult> GetCityCoordinatesAsync(string cityName)
    {
        // ...For more info, check the source code
    }

    private async Task<WeatherApiResponse> GetWeatherDataAsync(double latitude, double longitude)
    {
        // ...For more info, check the source code
    }
}

نکات کلیدی:

• این افزونه استفاده می کند IHttpClientFactory برای برقراری تماس های HTTP با API های خارجی.
  • همانطور که می بینید، تزریق وابستگی بدون مشکل کار می کند، بنابراین در اینجا می توانیم هر کاری را که برای انجام این افزونه نیاز داریم تزریق کنیم.
• Kernel از نام متدها و پارامترها برای معنی دادن به آنها استفاده می کند و بنابراین از آن مطابق درخواست درخواستی استفاده می کند.

مرحله 2: افزونه ها را در هسته ثبت کنید

برای اینکه هسته از این افزونه ها استفاده کند، باید آنها را در تنظیمات سرویس ثبت کنیم:

var kernel = builder.Services.AddKernel();

// Registrar el servicio de hora
kernel.ImportPlugin<TimeInformationService>();

// Registrar el servicio de clima
kernel.ImportPlugin<WeatherInformationService>();

مرحله 3: با استفاده از هسته پلاگین ها را در معرض دید قرار دهید

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

ما آزمایش را با یک نقطه پایانی ساده انجام خواهیم داد که دستور را فراخوانی می کند

app.MapPost("/api/chat", async (ChatRequest request, Kernel kernel) =>
{
    var settings = new OpenAIPromptExecutionSettings()
    {
        FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
    };

    // Aquí podríamos hacer un Prompt más explícito para el modelo si nuestra intención fuera
    // solo contestar preguntas sobre el clima.

    var response = await kernel.InvokePromptAsync(request.Question, new(settings));

    return Results.Ok(new
    {
        Result = response.ToString()
    });
});

توضیح کد

1. با استفاده از کرنل:
   • روش InvokePromptAsync از هسته برای پردازش درخواست و تعیین اینکه کدام عملکرد افزونه باید اجرا شود استفاده می کند.
   • در این صورت، هسته به طور خودکار روش صحیح را انتخاب می کند (GetCurrentUtcTime o GetWeatherByCity) بر اساس متن درخواستی.
2. ادغام انعطاف پذیر:
   • این ساختار به شما اجازه می‌دهد تا هر سوال یا متنی را ارسال کنید و کرنل را به تفسیر و انتخاب روش مناسب بسپارید.
     • همچنین می‌توانیم در جایی که صریحاً در مورد اینکه مدل می‌خواهیم از کدام پلاگین استفاده کند، اعلان‌هایی ایجاد کنیم، اما فعلاً آن را به صورت خودکار رها می‌کنیم و اجازه می‌دهیم مدل تصمیم بگیرد.

4. نقاط پایانی را تست کنید

با پیکربندی نقاط پایانی و ادغام افزونه ها در هسته، وقت آن است که آنها را تأیید کنید و ببینید چگونه کار می کنند.

مثال 1: آب و هوا را بررسی کنید

با استفاده از پستچی، درخواست زیر را به نقطه پایانی پیکربندی شده ارسال می کند:

{
  "question": "Cuál es el clima actual en Londres"
}

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

پاسخ چیزی شبیه به این خواهد بود:

{
    "result": "El clima actual en Londres es frío y nublado, con una temperatura de 8.6°C y un viento que sopla a 6.8 km/h. La codificación del tiempo es 3, lo que indica condiciones climáticas mezcladas, con algunas nubes y posibles lluvias."
}

مثال 2: با اطلاعات مربوط به یک شهر مشورت کنید

اکنون، یک کوئری متفاوت اجرا کنید، مانند این:

{
  "question": "Cuál es la población actual de Madrid?"
}

در این حالت، مدل به طور خودکار تابع دیگری را که در افزونه ثبت شده است فراخوانی می کند که مسئول به دست آوردن اطلاعات مربوط به یک شهر است:

پاسخ چیزی شبیه به این خواهد بود:

{
    "result": "La población actual de Madrid es de aproximadamente 3,255,594 personas, según la información proporcionada por el servicio de información geográfica."
}

آیا به قدرت پشت این ادغام توجه می کنید؟ با این پیکربندی، هسته می تواند کارهایی را انجام دهد که قبلاً به چندین سرویس جداگانه نیاز داشتند. همه چیز به نحوه ساختاربندی اعلان ها و عملکردهای پلاگین هایمان بستگی دارد.

و این تازه آغاز راه است! ما هنوز ویژگی های پیشرفته مانند حافظه معنایی y RAG (نسل افزایش یافته بازیابی)، اما با آنچه که در حال حاضر داریم، می‌توانیم راه‌حل‌های بسیار انعطاف‌پذیر و سفارشی‌سازی شده را برای هر دامنه یا صنعتی بسازیم.

با دستورات خاص تر، می توانید مشکلات پیچیده را حل کرده و فرآیندهای پیشرفته را خودکار کنید. تنها محدودیت، خلاقیت شما و نیازهای پروژه شماست.

5. کارکردها و ملاحظات نهایی را گسترش دهید

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

افزونه های بیشتری را وارد کنید

انعطاف پذیری از هسته معنایی این به ما امکان می دهد ویژگی های بیشتری را به پلاگین های خود اضافه کنیم یا افزونه های جدیدی ایجاد کنیم تا سایر زمینه های مورد علاقه را پوشش دهیم، مانند:

• تحلیل متن: حجم زیادی از داده های متنی را برای به دست آوردن خلاصه، استخراج کلمات کلیدی یا شناسایی موجودیت ها پردازش کنید.
• ادغام های خارجی: برای انجام کارهایی مانند مدیریت ایمیل ها، دسترسی به سیستم های تجاری یا انجام تراکنش ها، با API های شخص ثالث ارتباط برقرار کنید.
• پردازش تصویر: از خدماتی مانند OCR برای تشخیص متن در تصاویر یا انجام تجزیه و تحلیل بصری استفاده کنید.

از حافظه معنایی استفاده کنید

این حافظه معنایی Semantic Kernel می تواند اطلاعات مرتبط با زمینه را ذخیره و بازیابی کند. به عنوان مثال:

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

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

طراحی مناسب دستورات کلیدی برای بهبود دقت نتایج است. چند توصیه:

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

مقیاس پذیری و تولید

اگرچه در این مثال ها استفاده می کنیم بودن به صورت محلی برای جلوگیری از مشکلات زیرساختی، در یک محیط تولید می توانید بدون تغییر پایه کد خود تغییر دهید و از خدماتی مانند استفاده کنید OpenAI o Azure OpenAI برای استفاده از مقیاس پذیری و قابلیت اطمینان آن. این نشان می دهد:

• کلیدهای API را برای محیط های امن تعریف کنید.
• سیاست های دسترسی را با توجه به نیازهای سازمان خود پیکربندی کنید.
• نظارت بر استفاده و هزینه ها برای بهینه سازی عملکرد.

موارد استفاده تجاری

با عناصری که قبلاً پیاده‌سازی شده‌اند، می‌توانیم موارد عملی را تجسم کنیم که این قابلیت‌ها مفید هستند:

• دستیاران پشتیبانی: سوالات رایج را در زمان واقعی با اطلاعات همیشه به روز حل کنید.
• اتوماسیون کارهای تکراری: به عنوان مثال، تولید گزارش بر اساس داده ها یا اعلان های برنامه ریزی شده.
• سیستم های سفارشی: برنامه های هوشمندی که به صورت پویا با نیازهای کاربر سازگار می شوند، مانند داشبوردهای تعاملی یا چت بات های پیشرفته. ### نتیجه گیری

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

مزیت واقعی این فناوری در توانایی آن در تکامل نهفته است. می‌توانید با موارد استفاده ساده، مانند مثال‌های این آموزش، شروع کنید و به راه‌حل‌های پیچیده‌تر که منابع داده، حافظه معنایی و عملکرد پیشرفته را یکپارچه می‌کند، ارتقا دهید.

خلاقیت شما و نیازهای پروژه شما مسیر را تعیین می کند. اکنون که پایه را دارید، با چه چیزی خواهید ساخت هسته معنایی?