Systeemeigen functies begrijpen

Voltooid

Systeemeigen functies zijn functies die zijn geschreven in systeemeigen code die kunnen worden aangeroepen door de Semantische Kernel SDK in uw toepassing. Ze zijn handig voor het uitvoeren van taken die grote taalmodellen (LLM) niet zelfstandig kunnen uitvoeren. U kunt een systeemeigen functie beschouwen als een vaardigheid die uw toepassing kan uitvoeren.

In latere modules leert u hoe u de Semantische kernel gebruikt om automatisch systeemeigen functies aan te roepen die u maakt en uw logica te combineren met prompts voor de LLM. Door chatvoltooiingsservices met functionele vaardigheden te combineren, kunt u een AI-agent maken die een breed scala aan taken kan uitvoeren. Maar voorlopig richten we ons op het ontwerpen van systeemeigen functies.

Systeemeigen functies hebben een bepaalde indeling en een aanbevolen bestandsstructuur die door de kernel moet worden gebruikt. Systeemeigen functies moeten de KernelFunction decorator gebruiken in hun definities. Ze gebruiken ook een Description veld voor parameters. Voorbeeld:

[KernelFunction, Description("Convert an amount of currency to USD")]
public static string ConvertCurrency(
  [Description("The currency")] string currency, 
  [Description("The amount")] double amount)
{
  // Code to convert currency
}

U kunt uw systeemeigen functies als invoegtoepassing in de kernel importeren. Klassen met systeemeigen functies moeten worden geplaatst in een map Invoegtoepassingen. Gerelateerde functies moeten in hetzelfde bestand worden geplaatst om de code georganiseerd te houden. U kunt ook submappen in de map Invoegtoepassingen gebruiken om uw code verder te ordenen.

Stel dat u een takenlijsttoepassing hebt. Een gebruiker wil een item in de takenlijst voltooien. Het grote taalmodel (LLM) heeft rechtstreeks geen toegang tot de takenlijst van de gebruiker, maar u kunt een systeemeigen functie schrijven om toegang te krijgen tot de lijst en een item als voltooid te markeren. Het takenlijstbestand kan bijvoorbeeld het volgende bevatten:

{
  "todoList": [
    {
      "task": "Complete coding exercise",
      "completed": false
    },
    {
      "task": "Practice Mandarin",
      "completed": false
    },
    {
      "task": "Buy groceries",
      "completed": false
    }
  ]
}

U kunt een bestand TodoListPlugin.cs maken in de map Invoegtoepassingen met code om de voltooide taak te markeren:

using System.ComponentModel;
using System.Text.Json;
using System.Text.Json.Nodes;
using Microsoft.SemanticKernel;

public class TodoListPlugin
{
    [KernelFunction, Description("Mark a todo list item as complete")]
    public static string CompleteTask([Description("The task to complete")] string task)
    {
        // Read the JSON file
        string jsonFilePath = $"{Directory.GetCurrentDirectory()}/todo.txt";
        string jsonContent = File.ReadAllText(jsonFilePath);

        // Parse the JSON content
        JsonNode todoData = JsonNode.Parse(jsonContent);

        // Find the task and mark it as complete
        JsonArray todoList = (JsonArray) todoData["todoList"];
        foreach (JsonNode taskNode in todoList)
        {
            if (taskNode["task"].ToString() == task)
            {
                taskNode["completed"] = true;
                break;
            }
        }

        // Save the modified JSON back to the file
        File.WriteAllText(jsonFilePath, JsonSerializer.Serialize(todoData));
        return $"Task '{task}' marked as complete.";
    }
}

Let op de KernelFunction decorator op de CompleteTask functie. Deze decorator vertelt de kernel dat deze functie toegankelijk is. De Description decorator vertelt de kernel wat de functie doet. De functie accepteert de task als tekenreeks. Variabelen van kernelfuncties moeten een beschrijving bevatten waarin wordt uitgelegd wat de variabele is. Deze functie retourneert ook een tekenreeks die de gebruiker laat weten dat de taak is gemarkeerd als voltooid.

In het Program.cs bestand kunt u deze systeemeigen functie importeren en aanroepen, vergelijkbaar met hoe u een van de ingebouwde invoegtoepassingen zou aanroepen. Voorbeeld:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Plugins.Core;

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
  "your-deployment-name",
  "your-endpoint",
  "your-api-key",
  "deployment-model");
var kernel = builder.Build();
kernel.ImportPluginFromType<TodoListPlugin>();

var result = await kernel.InvokeAsync<string>(
  "TodoListPlugin", 
  "CompleteTask", 
  new() {{ "task", "Buy groceries" }}
);
Console.WriteLine(result);

In dit voorbeeld kernel.InvokeAsync wordt aangeroepen met de naam van de invoegtoepassing, de functienaam en de argumenten. Het task argument is ingesteld op 'Boodschappen kopen'. De functie markeert de taak als voltooid in het takenlijstbestand en retourneert een bericht aan de gebruiker.

Nu kan uw AI-agent de gebruiker helpen taken uit te voeren op de takenlijst. U kunt er eventueel voor kiezen om het retourtype van de functie in de InvokeAsync aanroep aan te geven. Anders wordt een FunctionResult object geretourneerd.

In de volgende oefening oefent u met het maken van uw eigen invoegtoepassingen met systeemeigen functies.