Erste Schritte mit semantischem Kernel

Artikel
07/02/2024

In nur wenigen Schritten können Sie Ihren ersten KI-Agent mit semantischem Kernel entweder in Python, .NET oder Java erstellen. In diesem Handbuch erfahren Sie, wie Sie...

Installieren der erforderlichen Pakete
Erstellen einer Hin- und Rückunterhaltung mit einer KI
Geben Sie einem KI-Agent die Möglichkeit, Ihren Code auszuführen
Sehen Sie sich die Ki-Erstellungspläne im Flug an

Installieren des SDK

Der semantische Kernel verfügt über mehrere NuGet-Pakete. Für die meisten Szenarien benötigen Microsoft.SemanticKernelSie in der Regel jedoch nur .

Sie können sie mit dem folgenden Befehl installieren:

dotnet add package Microsoft.SemanticKernel

Die vollständige Liste der Nuget-Pakete finden Sie im Artikel zu unterstützten Sprachen.

Anweisungen für den Zugriff auf das SemanticKernel Python-Paket finden Sie hier. Es ist so einfach wie:

pip install semantic-kernel

Anweisungen für den Zugriff auf das SemanticKernel Java-Paket finden Sie hier. Es ist so einfach wie:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.microsoft.semantic-kernel</groupId>
            <artifactId>semantickernel-bom</artifactId>
            <version>${sk.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
<dependency>
    <groupId>com.microsoft.semantic-kernel</groupId>
    <artifactId>semantickernel-api</artifactId>
</dependency>
<dependency>
    <groupId>com.microsoft.semantic-kernel</groupId>
    <artifactId>semantickernel-aiservices-openai</artifactId>
</dependency>
</dependencies>

Schnelle Schritte mit Notizbüchern

Wenn Sie Python- oder C#-Entwickler sind, können Sie schnell mit unseren Notizbüchern beginnen. Diese Notizbücher enthalten schrittweise Anleitungen zur Verwendung des semantischen Kernels zum Erstellen von KI-Agents.

Semantische Kernel-Notizbücher

Um zu beginnen, folgen Sie diesen Schritten:

Klonen des semantischen Kernel-Repositorys
Öffnen des Repositorys in Visual Studio Code
Navigieren Sie zu _/python/samples/getting_started
Öffnen Sie 00-getting-started.ipynb , um mit der Einstellung Ihrer Umgebung zu beginnen und Ihren ersten KI-Agent zu erstellen!

Um zu beginnen, folgen Sie diesen Schritten:

Klonen des semantischen Kernel-Repositorys
Öffnen des Repositorys in Visual Studio Code
Navigieren sie zu _/dotnet/notebooks
Öffnen Sie 00-getting-started.ipynb , um mit der Einstellung Ihrer Umgebung zu beginnen und Ihren ersten KI-Agent zu erstellen!

Schreiben Ihrer ersten Konsolen-App

// Import packages
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;

// Create a kernel with Azure OpenAI chat completion
var builder = Kernel.CreateBuilder().AddAzureOpenAIChatCompletion(modelId, endpoint, apiKey);

// Add enterprise components
builder.Services.AddLogging(services => services.AddConsole().SetMinimumLevel(LogLevel.Trace));

// Build the kernel
Kernel kernel = builder.Build();
var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();

// Add a plugin (the LightsPlugin class is defined below)
kernel.Plugins.AddFromType<LightsPlugin>("Lights");

// Enable planning
OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new() 
{
    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

// Create a history store the conversation
var history = new ChatHistory();

// Initiate a back-and-forth chat
string? userInput;
do {
    // Collect user input
    Console.Write("User > ");
    userInput = Console.ReadLine();

    // Add user input
    history.AddUserMessage(userInput);

    // Get the response from the AI
    var result = await chatCompletionService.GetChatMessageContentAsync(
        history,
        executionSettings: openAIPromptExecutionSettings,
        kernel: kernel);

    // Print the results
    Console.WriteLine("Assistant > " + result);

    // Add the message from the agent to the chat history
    history.AddMessage(result.Role, result.Content ?? string.Empty);
} while (userInput is not null);

import asyncio

from semantic_kernel import Kernel
from semantic_kernel.utils.logging import setup_logging
from semantic_kernel.functions import kernel_function
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase
from semantic_kernel.contents.chat_history import ChatHistory
from semantic_kernel.functions.kernel_arguments import KernelArguments

from semantic_kernel.connectors.ai.open_ai.prompt_execution_settings.azure_chat_prompt_execution_settings import (
    AzureChatPromptExecutionSettings,
)

async def main():
    # Initialize the kernel
    kernel = Kernel()

    # Add Azure OpenAI chat completion
    chat_completion = AzureChatCompletion(
        deployment_name="your_models_deployment_name",
        api_key="your_api_key",
        base_url="your_base_url",
    )
    kernel.add_service(chat_completion)

    # Set the logging level for  semantic_kernel.kernel to DEBUG.
    setup_logging()
    logging.getLogger("kernel").setLevel(logging.DEBUG)

    # Add a plugin (the LightsPlugin class is defined below)
    kernel.add_plugin(
        LightsPlugin(),
        plugin_name="Lights",
    )

    # Enable planning
    execution_settings = AzureChatPromptExecutionSettings()
    execution_settings.function_call_behavior = FunctionChoiceBehavior.Auto()

    # Create a history of the conversation
    history = ChatHistory()

    # Initiate a back-and-forth chat
    userInput = None
    while True:
        # Collect user input
        userInput = input("User > ")

        # Terminate the loop if the user says "exit"
        if userInput == "exit":
            break

        # Add user input to the history
        history.add_user_message(userInput)

        # Get the response from the AI
        result = await chat_completion.get_chat_message_content(
            chat_history=history,
            settings=execution_settings,
            kernel=kernel,
        )

        # Print the results
        print("Assistant > " + str(result))

        # Add the message from the agent to the chat history
        history.add_message(result)

# Run the main function
if __name__ == "__main__":
    asyncio.run(main())

OpenAIAsyncClient client = new OpenAIClientBuilder()
    .credential(new AzureKeyCredential(AZURE_CLIENT_KEY))
    .endpoint(CLIENT_ENDPOINT)
    .buildAsyncClient();

// Import the LightsPlugin
KernelPlugin lightPlugin = KernelPluginFactory.createFromObject(new LightsPlugin(),
    "LightsPlugin");

// Create your AI service client
ChatCompletionService chatCompletionService = OpenAIChatCompletion.builder()
    .withModelId(MODEL_ID)
    .withOpenAIAsyncClient(client)
    .build();

// Create a kernel with Azure OpenAI chat completion and plugin
Kernel kernel = Kernel.builder()
    .withAIService(ChatCompletionService.class, chatCompletionService)
    .withPlugin(lightPlugin)
    .build();

// Add a converter to the kernel to show it how to serialise LightModel objects into a prompt
ContextVariableTypes
    .addGlobalConverter(
        ContextVariableTypeConverter.builder(LightModel.class)
            .toPromptString(new Gson()::toJson)
            .build());

// Enable planning
InvocationContext invocationContext = new InvocationContext.Builder()
    .withReturnMode(InvocationReturnMode.LAST_MESSAGE_ONLY)
    .withToolCallBehavior(ToolCallBehavior.allowAllKernelFunctions(true))
    .build();

// Create a history to store the conversation
ChatHistory history = new ChatHistory();

// Initiate a back-and-forth chat
Scanner scanner = new Scanner(System.in);
String userInput;
do {
  // Collect user input
  System.out.print("User > ");

  userInput = scanner.nextLine();
  // Add user input
  history.addUserMessage(userInput);

  // Prompt AI for response to users input
  List<ChatMessageContent<?>> results = chatCompletionService
      .getChatMessageContentsAsync(history, kernel, invocationContext)
      .block();

  for (ChatMessageContent<?> result : results) {
    // Print the results
    if (result.getAuthorRole() == AuthorRole.ASSISTANT && result.getContent() != null) {
      System.out.println("Assistant > " + result);
    }
    // Add the message from the agent to the chat history
    history.addMessage(result);
  }
} while (userInput != null && !userInput.isEmpty());

Der folgende Back-and-Forth-Chat sollte mit dem in der Konsole angezeigten Inhalt vergleichbar sein. Die Funktionsaufrufe wurden unten hinzugefügt, um zu veranschaulichen, wie die KI das Plug-In hinter den Kulissen nutzt.

Role	`Message`
🔵Benutzer	Bitte schalten Sie das Licht um.
🔴Assistent (Funktionsaufruf)	`LightsPlugin.GetState()`
🟢Tool	`off`
🔴Assistent (Funktionsaufruf)	`LightsPlugin.ChangeState(true)`
🟢Tool	`on`
🔴Assistent	Das Licht ist jetzt eingeschaltet

Wenn Sie mehr über den obigen Code erfahren möchten, werden wir ihn im nächsten Abschnitt aufschlüsseln.

Grundlegendes zum Code

Um den Einstieg in die Erstellung von Unternehmens-Apps mit semantischem Kernel zu erleichtern, haben wir einen Schritt für Schritt erstellt, der Sie durch den Prozess des Erstellens eines Kernels führt und sie für die Interaktion mit KI-Diensten verwendet.

Semantic Kernel Python map

Semantic Kernel DotNET map

In den folgenden Abschnitten entpacken wir das obige Beispiel, indem wir die Schritte 1, 2, 3, 4, 6, 9 und 10 durchlaufen. Alles, was Sie benötigen, um einen einfachen Agent zu erstellen, der von einem KI-Dienst unterstützt wird und Ihren Code ausführen kann.

Importieren von Paketen
Hinzufügen von KI-Diensten
Enterprise-Komponenten ::: Zone-End
Erstellen des Kernels
Hinzufügen von Arbeitsspeicher (übersprungen)
Hinzufügen von Plug-Ins
Erstellen von Kernelargumenten (übersprungen)
Erstellen von Eingabeaufforderungen (übersprungen)
Planung
Invoke

1) Importieren von Paketen

In diesem Beispiel haben wir zunächst mit dem Importieren der folgenden Pakete begonnen:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;

import asyncio

from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase
from semantic_kernel.contents.chat_history import ChatHistory
from semantic_kernel.functions.kernel_arguments import KernelArguments

from semantic_kernel.connectors.ai.open_ai.prompt_execution_settings.azure_chat_prompt_execution_settings import (
    AzureChatPromptExecutionSettings,
)

import com.microsoft.semantickernel.Kernel;
import com.microsoft.semantickernel.aiservices.openai.chatcompletion.OpenAIChatCompletion;
import com.microsoft.semantickernel.contextvariables.ContextVariableTypeConverter;
import com.microsoft.semantickernel.contextvariables.ContextVariableTypes;
import com.microsoft.semantickernel.orchestration.InvocationContext;
import com.microsoft.semantickernel.orchestration.InvocationReturnMode;
import com.microsoft.semantickernel.orchestration.ToolCallBehavior;
import com.microsoft.semantickernel.plugin.KernelPlugin;
import com.microsoft.semantickernel.plugin.KernelPluginFactory;
import com.microsoft.semantickernel.services.chatcompletion.AuthorRole;
import com.microsoft.semantickernel.services.chatcompletion.ChatCompletionService;
import com.microsoft.semantickernel.services.chatcompletion.ChatHistory;
import com.microsoft.semantickernel.services.chatcompletion.ChatMessageContent;

2) Hinzufügen von KI-Diensten

Anschließend fügen wir den wichtigsten Teil eines Kernels hinzu: die KI-Dienste, die Sie verwenden möchten. In diesem Beispiel wurde dem Kernel-Generator ein Azure OpenAI-Chatabschlussdienst hinzugefügt.

Hinweis

In diesem Beispiel haben wir Azure OpenAI verwendet, aber Sie können jeden anderen Chatabschlussdienst verwenden. Die vollständige Liste der unterstützten Dienste finden Sie im Artikel zu unterstützten Sprachen. Wenn Sie Hilfe beim Erstellen eines anderen Diensts benötigen, lesen Sie den Artikel "KI-Dienste". Dort finden Sie Anleitungen zur Verwendung von OpenAI- oder Azure OpenAI-Modellen als Dienste.

// Create kernel
var builder = Kernel.CreateBuilder()
builder.AddAzureOpenAIChatCompletion(modelId, endpoint, apiKey);

# Initialize the kernel
kernel = Kernel()

# Add Azure OpenAI chat completion
kernel.add_service(AzureChatCompletion(
    deployment_name="your_models_deployment_name",
    api_key="your_api_key",
    base_url="your_base_url",
))

// Create your AI service client
ChatCompletionService chatCompletionService = OpenAIChatCompletion.builder()
    .withModelId(MODEL_ID)
    .withOpenAIAsyncClient(client)
    .build();

// Create a kernel with Azure OpenAI chat completion and plugin
Kernel kernel = Kernel.builder()
    .withAIService(ChatCompletionService.class, chatCompletionService)
    .withPlugin(lightPlugin)
    .build();

3) Hinzufügen von Unternehmensdiensten

Einer der Hauptvorteile der Verwendung des semantischen Kernels besteht darin, dass er Dienste auf Unternehmensniveau unterstützt. In diesem Beispiel haben wir den Protokollierungsdienst zum Kernel hinzugefügt, um den KI-Agent zu debuggen.

builder.Services.AddLogging(services => services.AddConsole().SetMinimumLevel(LogLevel.Trace));

import logging

# Set the logging level for  semantic_kernel.kernel to DEBUG.
logging.basicConfig(
    format="[%(asctime)s - %(name)s:%(lineno)d - %(levelname)s] %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
)
logging.getLogger("kernel").setLevel(logging.DEBUG)

4) Erstellen des Kernels und Abrufen von Diensten

Nachdem die Dienste hinzugefügt wurden, erstellen wir den Kernel und rufen den Chatabschlussdienst zur späteren Verwendung ab.

Kernel kernel = builder.Build();

// Retrieve the chat completion service
var chatCompletionService = kernel.Services.GetRequiredService<IChatCompletionService>();

Nachdem der Kernel konfiguriert wurde, rufen wir den Chatabschlussdienst zur späteren Verwendung ab.

Hinweis

In Python müssen Sie den Kernel nicht explizit erstellen. Stattdessen können Sie direkt über das Kernelobjekt auf die Dienste zugreifen.

chat_completion : AzureChatCompletion = kernel.get_service(type=ChatCompletionClientBase)

// Create a kernel with Azure OpenAI chat completion and plugin
Kernel kernel = Kernel.builder()
    .withAIService(ChatCompletionService.class, chatCompletionService)
    .withPlugin(lightPlugin)
    .build();

6) Plug-Ins hinzufügen

Mit Plug-Ins können Sie Ihrem KI-Agent die Möglichkeit geben, Ihren Code auszuführen, um Informationen aus externen Quellen abzurufen oder Aktionen auszuführen. Im obigen Beispiel haben wir ein Plug-In hinzugefügt, mit dem der KI-Agent mit einer Glühbirne interagieren kann. Unten zeigen wir Ihnen, wie Sie dieses Plug-In erstellen.

Erstellen eines nativen Plug-Ins

Unten können Sie sehen, dass das Erstellen eines nativen Plug-Ins so einfach ist wie das Erstellen einer neuen Klasse.

In diesem Beispiel haben wir ein Plug-In erstellt, das eine Glühbirne bearbeiten kann. Obwohl dies ein einfaches Beispiel ist, zeigt dieses Plug-In schnell, wie Sie beide unterstützen können...

Abrufen der Augmented Generation (RAG) durch Bereitstellung des KI-Agenten mit dem Zustand der Glühbirne
Und die Aufgabenautomatisierung , indem der KI-Agent die Glühbirne ein- oder ausschalten kann.

In Ihrem eigenen Code können Sie ein Plug-In erstellen, das mit jedem externen Dienst oder jeder API interagiert, um ähnliche Ergebnisse zu erzielen.

using System.ComponentModel;
using Microsoft.SemanticKernel;

public class LightsPlugin
{
   // Mock data for the lights
   private readonly List<LightModel> lights = new()
   {
      new LightModel { Id = 1, Name = "Table Lamp", IsOn = false },
      new LightModel { Id = 2, Name = "Porch light", IsOn = false },
      new LightModel { Id = 3, Name = "Chandelier", IsOn = true }
   };

   [KernelFunction("get_lights")]
   [Description("Gets a list of lights and their current state")]
   [return: Description("An array of lights")]
   public async Task<List<LightModel>> GetLightsAsync()
   {
      return lights;
   }

   [KernelFunction("change_state")]
   [Description("Changes the state of the light")]
   [return: Description("The updated state of the light; will return null if the light does not exist")]
   public async Task<LightModel?> ChangeStateAsync(int id, bool isOn)
   {
      var light = lights.FirstOrDefault(light => light.Id == id);

      if (light == null)
      {
         return null;
      }

      // Update the light with the new state
      light.IsOn = isOn;

      return light;
   }
}

public class LightModel
{
   [JsonPropertyName("id")]
   public int Id { get; set; }

   [JsonPropertyName("name")]
   public string Name { get; set; }

   [JsonPropertyName("is_on")]
   public bool? IsOn { get; set; }
}

from typing import Annotated
from semantic_kernel.functions import kernel_function

class LightsPlugin:
    lights = [
        {"id": 1, "name": "Table Lamp", "is_on": False},
        {"id": 2, "name": "Porch light", "is_on": False},
        {"id": 3, "name": "Chandelier", "is_on": True},
    ]

    @kernel_function(
        name="get_lights",
        description="Gets a list of lights and their current state",
    )
    def get_state(
        self,
    ) -> Annotated[str, "the output is a string"]:
        """Gets a list of lights and their current state."""
        return self.lights

    @kernel_function(
        name="change_state",
        description="Changes the state of the light",
    )
    def change_state(
        self,
        id: int,
        is_on: bool,
    ) -> Annotated[str, "the output is a string"]:
        """Changes the state of the light."""
        for light in self.lights:
            if light["id"] == id:
                light["is_on"] = is_on
                return light
        return None

public class LightsPlugin {

  // Mock data for the lights
  private final Map<Integer, LightModel> lights = new HashMap<>();

  public LightsPlugin() {
    lights.put(1, new LightModel(1, "Table Lamp", false));
    lights.put(2, new LightModel(2, "Porch light", false));
    lights.put(3, new LightModel(3, "Chandelier", true));
  }

  @DefineKernelFunction(name = "get_lights", description = "Gets a list of lights and their current state")
  public List<LightModel> getLights() {
    System.out.println("Getting lights");
    return new ArrayList<>(lights.values());
  }

  @DefineKernelFunction(name = "change_state", description = "Changes the state of the light")
  public LightModel changeState(
      @KernelFunctionParameter(name = "id", description = "The ID of the light to change") int id,
      @KernelFunctionParameter(name = "isOn", description = "The new state of the light") boolean isOn) {
    System.out.println("Changing light " + id + " " + isOn);
    if (!lights.containsKey(id)) {
      throw new IllegalArgumentException("Light not found");
    }

    lights.get(id).setIsOn(isOn);

    return lights.get(id);
  }
}

Hinzufügen des Plug-Ins zum Kernel

Nachdem Sie Ihr Plug-In erstellt haben, können Sie es dem Kernel hinzufügen, damit der KI-Agent darauf zugreifen kann. Im Beispiel haben wir die LightsPlugin Klasse zum Kernel hinzugefügt.

// Add the plugin to the kernel
kernel.Plugins.AddFromType<LightsPlugin>("Lights");

# Add the plugin to the kernel
kernel.add_plugin(
    LightsPlugin(),
    plugin_name="Lights",
)

// Import the LightsPlugin
KernelPlugin lightPlugin = KernelPluginFactory.createFromObject(new LightsPlugin(),
    "LightsPlugin");

9) Planung

Der semantische Kernel nutzt Funktionsaufrufe – ein systemeigenes Feature der meisten LLMs – um die Planung bereitzustellen. Mit Funktionsaufrufen können LLMs eine bestimmte Funktion anfordern (oder aufrufen), um die Anforderung eines Benutzers zu erfüllen. Der semantische Kernel marshallt dann die Anforderung an die entsprechende Funktion in Ihrer Codebasis und gibt die Ergebnisse zurück an die LLM zurück, damit der KI-Agent eine endgültige Antwort generieren kann.

Um den automatischen Funktionsaufruf zu aktivieren, müssen wir zuerst die entsprechenden Ausführungseinstellungen erstellen, damit der semantische Kernel die Funktionen im Kernel automatisch aufruft, wenn der KI-Agent sie anfordert.

OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
{
    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

execution_settings = AzureChatPromptExecutionSettings()
execution_settings.function_call_behavior = FunctionChoiceBehavior.Auto()

// Enable planning
InvocationContext invocationContext = new InvocationContext.Builder()
    .withReturnMode(InvocationReturnMode.LAST_MESSAGE_ONLY)
    .withToolCallBehavior(ToolCallBehavior.allowAllKernelFunctions(true))
    .build();

10) Aufrufen

Schließlich rufen wir den KI-Agent mit dem Plug-In auf. Der Beispielcode veranschaulicht, wie eine Nicht-Streaming-Antwort generiert wird, Sie können aber auch eine Streamingantwort mithilfe der GetStreamingChatMessageContentAsync Methode generieren.

// Create chat history
var history = new ChatHistory();

// Get the response from the AI
var result = await chatCompletionService.GetChatMessageContentAsync(
    history,
    executionSettings: openAIPromptExecutionSettings,
    kernel: kernel
);

# Create a history of the conversation
history = ChatHistory()

# Get the response from the AI
result = (await chat_completion.get_chat_message_contents(
    chat_history=history,
    settings=execution_settings,
    kernel=kernel,
    arguments=KernelArguments(),
))[0]

userInput = scanner.nextLine();
// Add user input
history.addUserMessage(userInput);

// Prompt AI for response to users input
List<ChatMessageContent<?>> results = chatCompletionService
    .getChatMessageContentsAsync(history, kernel, invocationContext)
    .block();

Nächste Schritte

In diesem Handbuch haben Sie gelernt, wie Sie schnell mit dem semantischen Kernel beginnen können, indem Sie einen einfachen KI-Agent erstellen, der mit einem KI-Dienst interagieren und Ihren Code ausführen kann. Weitere Beispiele und Informationen zum Erstellen komplexerer KI-Agents finden Sie in unseren ausführlichen Beispielen.

Freigeben über