Aan de slag met Semantische kernel

Artikel
07/02/2024

In slechts enkele stappen kunt u uw eerste AI-agent bouwen met Semantic Kernel in Python, .NET of Java. In deze handleiding wordt uitgelegd hoe u...

De benodigde pakketten installeren
Een back-and-forth-gesprek maken met een AI
Een AI-agent de mogelijkheid geven om uw code uit te voeren
Bekijk de AI-maakplannen onderweg

De SDK installeren

Semantic Kernel heeft verschillende NuGet-pakketten beschikbaar. Voor de meeste scenario's hebt u echter meestal alleen maar nodig Microsoft.SemanticKernel.

U kunt deze installeren met behulp van de volgende opdracht:

dotnet add package Microsoft.SemanticKernel

Raadpleeg het artikel over ondersteunde talen voor de volledige lijst met Nuget-pakketten.

Hier vindt u instructies voor toegang tot het SemanticKernel Python-pakket. Het is net zo eenvoudig als:

pip install semantic-kernel

Hier vindt u instructies voor toegang tot het SemanticKernel Java-pakket. Het is net zo eenvoudig als:

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

Snel aan de slag met notebooks

Als u een Python- of C#-ontwikkelaar bent, kunt u snel aan de slag met onze notebooks. Deze notebooks bieden stapsgewijze handleidingen over het gebruik van Semantic Kernel voor het bouwen van AI-agents.

Semantische kernelnotebooks

Volg deze stappen om aan de slag te gaan:

De Semantische kernelopslagplaats klonen
De opslagplaats openen in Visual Studio Code
Navigeer naar _/python/samples/getting_started
Open 00-getting-started.ipynb om aan de slag te gaan met het instellen van uw omgeving en het maken van uw eerste AI-agent.

Volg deze stappen om aan de slag te gaan:

De Semantische kernelopslagplaats klonen
De opslagplaats openen in Visual Studio Code
Navigeer naar _/dotnet/notebooks
Open 00-getting-started.ipynb om aan de slag te gaan met het instellen van uw omgeving en het maken van uw eerste AI-agent.

Uw eerste console-app schrijven

// 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());

De volgende back-and-forth-chat moet vergelijkbaar zijn met wat u in de console ziet. De functie-aanroepen zijn hieronder toegevoegd om te laten zien hoe de AI achter de schermen gebruikmaakt van de invoegtoepassing.

Role	Bericht
🔵Gebruiker	Schakel het licht in
🔴Assistent (functieoproep)	`LightsPlugin.GetState()`
🟢Tool	`off`
🔴Assistent (functieoproep)	`LightsPlugin.ChangeState(true)`
🟢Tool	`on`
🔴Assistent	Het licht is nu aan

Als u meer wilt weten over de bovenstaande code, gaan we deze in de volgende sectie opsplitsen.

De code begrijpen

Om het gemakkelijker te maken om zakelijke apps te bouwen met Semantic Kernel, hebben we een stapsgewijze handleiding gemaakt die u begeleidt bij het maken van een kernel en het gebruiken ervan om te communiceren met AI-services.

Semantische Kernel Python-kaart

Semantische Kernel DotNET-kaart

In de volgende secties pakken we het bovenstaande voorbeeld uit door stap 1, 2, 3, 4, 6, 9 en 10 te doorlopen. Alles wat u nodig hebt om een eenvoudige agent te bouwen die wordt aangedreven door een AI-service en uw code kan uitvoeren.

Pakketten importeren
AI-services toevoegen
Bedrijfsonderdelen ::: zone-end
De kernel bouwen
Geheugen toevoegen (overgeslagen)
Invoegtoepassingen toevoegen
Kernelargumenten maken (overgeslagen)
Prompts maken (overgeslagen)
Planning
Aanroepen

1) Pakketten importeren

Voor dit voorbeeld zijn we eerst begonnen met het importeren van de volgende pakketten:

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) AI-services toevoegen

Daarna voegen we het belangrijkste deel van een kernel toe: de AI-services die u wilt gebruiken. In dit voorbeeld hebben we een voltooiingsservice voor een Azure OpenAI-chat toegevoegd aan de kernelbouwer.

Notitie

In dit voorbeeld hebben we Azure OpenAI gebruikt, maar u kunt elke andere voltooiingsservice voor chats gebruiken. Raadpleeg het artikel over ondersteunde talen voor een volledige lijst met ondersteunde services. Als u hulp nodig hebt bij het maken van een andere service, raadpleegt u het artikel over AI-services. Daar vindt u richtlijnen voor het gebruik van OpenAI- of Azure OpenAI-modellen als services.

// 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) Enterprise-services toevoegen

Een van de belangrijkste voordelen van het gebruik van Semantische kernel is dat het ondersteuning biedt voor hoogwaardige services. In dit voorbeeld hebben we de logboekregistratieservice toegevoegd aan de kernel om fouten in de AI-agent op te sporen.

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) De kernel bouwen en services ophalen

Zodra de services zijn toegevoegd, bouwen we de kernel en halen we de voltooiingsservice voor chats op voor later gebruik.

Kernel kernel = builder.Build();

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

Zodra de kernel is geconfigureerd, halen we de chatvoltooiingsservice op voor later gebruik.

Notitie

In Python hoeft u de kernel niet expliciet te bouwen. In plaats daarvan hebt u rechtstreeks toegang tot de services vanuit het kernelobject.

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) Invoegtoepassingen toevoegen

Met invoegtoepassingen kunt u uw AI-agent de mogelijkheid bieden om uw code uit te voeren om informatie op te halen uit externe bronnen of om acties uit te voeren. In het bovenstaande voorbeeld hebben we een invoegtoepassing toegevoegd waarmee de AI-agent kan communiceren met een gloeilamp. Hieronder ziet u hoe u deze invoegtoepassing maakt.

Een systeemeigen invoegtoepassing maken

Hieronder ziet u dat het maken van een systeemeigen invoegtoepassing net zo eenvoudig is als het maken van een nieuwe klasse.

In dit voorbeeld hebben we een invoegtoepassing gemaakt waarmee een gloeilamp kan worden bewerkt. Hoewel dit een eenvoudig voorbeeld is, laat deze invoegtoepassing snel zien hoe u beide kunt ondersteunen...

Augmented Generation (RAG) ophalen door de AI-agent de status van de gloeilamp te geven
En taakautomatisering door de AI-agent toe te staan de gloeilamp in of uit te schakelen.

In uw eigen code kunt u een invoegtoepassing maken die communiceert met elke externe service of API om vergelijkbare resultaten te bereiken.

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);
  }
}

De invoegtoepassing toevoegen aan de kernel

Zodra u de invoegtoepassing hebt gemaakt, kunt u deze toevoegen aan de kernel, zodat de AI-agent er toegang toe heeft. In het voorbeeld hebben we de LightsPlugin klasse toegevoegd aan de kernel.

// 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) Planning

Semantische kernel maakt gebruik van functie-aanroepen, een systeemeigen functie van de meeste LLM's, om planning te bieden. Met functieaanroepen kunnen LLM's een bepaalde functie aanvragen (of aanroepen) om te voldoen aan de aanvraag van een gebruiker. Semantische kernel geeft vervolgens de aanvraag door aan de juiste functie in uw codebasis en retourneert de resultaten terug naar de LLM, zodat de AI-agent een definitief antwoord kan genereren.

Als u automatische functie-aanroepen wilt inschakelen, moeten we eerst de juiste uitvoeringsinstellingen maken, zodat Semantische kernel weet dat de functies in de kernel automatisch worden aangeroepen wanneer de AI-agent deze aanvraagt.

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) Aanroepen

Ten slotte roepen we de AI-agent aan met de invoegtoepassing. De voorbeeldcode laat zien hoe u een niet-streaming-antwoord genereert, maar u kunt ook een streaming-antwoord genereren met behulp van de GetStreamingChatMessageContentAsync methode.

// 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();

Volgende stappen

In deze handleiding hebt u geleerd hoe u snel aan de slag kunt gaan met Semantic Kernel door een eenvoudige AI-agent te bouwen die kan communiceren met een AI-service en uw code kunt uitvoeren. Bekijk onze uitgebreide voorbeelden voor meer voorbeelden en meer informatie over het bouwen van complexere AI-agents.

Delen via