Grundlegendes zu nativen Funktionen

Abgeschlossen

Native Funktionen sind Funktionen, die in nativem Code geschrieben werden, der vom Semantic Kernel-SDK in Ihrer Anwendung aufgerufen werden kann. Sie sind nützlich für das Ausführen von Aufgaben, die Large Language Models (LLMs) nicht alleine ausführen können. Sie können sich eine native Funktion wie eine Fähigkeit vorstellen, die Ihre Anwendung ausführen kann.

In späteren Modulen erfahren Sie, wie Sie Semantic Kernel verwenden, um native Funktionen, die Sie erstellen, automatisch aufzurufen und Ihre Logik mit Prompts an das LLM zu kombinieren. Durch die Kombination von Chatvervollständigungsdiensten mit funktionalen Skills können Sie einen KI-Agent erstellen, der eine Vielzahl von Aufgaben ausführen kann. Jetzt konzentrieren Sie sich jedoch auf das Entwerfen nativer Funktionen.

Systemeigene Funktionen weisen ein bestimmtes Format und eine empfohlene Dateistruktur auf, die vom Kernel verwendet werden soll. Native Funktionen sollten den KernelFunction-Decorator in ihren Definitionen verwenden. Sie verwenden auch ein Description-Feld für Parameter. Zum Beispiel:

[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
}

Sie können Ihre nativen Funktionen als Plug-In in den Kernel importieren. Klassen, die native Funktionen enthalten, sollten in einem Verzeichnis mit der Bezeichnung „Plugins“ platziert werden. Verwandte Funktionen sollten in derselben Datei platziert werden, damit der Code organisiert bleibt. Sie können auch Unterverzeichnisse im Verzeichnis „Plugins“ verwenden, um Ihren Code weiter zu organisieren.

Angenommen, Sie haben eine Anwendung für To-do-Listen. Ein Benutzer möchte ein Element auf seiner To-do-Liste abschließen. Das Large Language Model (LLM) kann nicht direkt auf die To-do-Liste des Benutzers zugreifen, aber Sie können eine native Funktion schreiben, um auf die Liste zuzugreifen und ein Element als erledigt zu markieren. Die Datei mit der To-do-Liste kann beispielsweise Folgendes enthalten:

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

Sie können die Datei TodoListPlugin.cs im Verzeichnis „Plugins“ mit Code erstellen, um die Aufgabe als erledigt zu markieren:

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.";
    }
}

Beachten Sie den KernelFunction Decorator bei der Funktion CompleteTask. Dieser Decorator teilt dem Kernel mit, dass auf diese Funktion zugegriffen werden kann. Der Description Decorator teilt dem Kernel mit, was die Funktion tut. Die Funktion akzeptiert task als Zeichenfolge. Variablen von Kernelfunktionen sollten eine Beschreibung enthalten, die erläutert, welchen Zweck die Variable hat. Diese Funktion gibt auch eine Zeichenfolge zurück, mit der der Benutzer informiert wird, dass die Aufgabe als erledigt markiert wurde.

In der Program.cs Datei können Sie diese systemeigene Funktion importieren und aufrufen, ähnlich wie Sie eines der integrierten Plug-Ins aufrufen. Zum Beispiel:

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 diesem Beispiel wird kernel.InvokeAsync mit dem Plug-In-Namen, Funktionsnamen und Argumenten aufgerufen. Das task-Argument wird auf „Buy groceries“ festgelegt. Die Funktion markiert die Aufgabe in der To-do-Liste als erledigt und gibt eine Nachricht an den Benutzer zurück.

Jetzt kann Ihr KI-Agent dem Benutzer helfen, Aufgaben in seiner To-Do-Liste auszuführen. Optional können Sie den Rückgabetyp der Funktion im InvokeAsync Aufruf angeben. Andernfalls wird ein FunctionResult Objekt zurückgegeben.

In der nächsten Übung üben Sie das Erstellen Ihrer eigenen Plug-Ins mit nativen Funktionen.