Komma igång med semantisk kernel

Artikel
07/02/2024

I bara några få steg kan du skapa din första AI-agent med semantisk kernel i antingen Python, .NET eller Java. Den här guiden visar hur du...

Installera nödvändiga paket
Skapa en konversation fram och tillbaka med en AI
Ge en AI-agent möjlighet att köra din kod
Titta på AI-skapandeplaner i farten

Installera SDK

Semantisk kernel har flera Tillgängliga NuGet-paket. I de flesta scenarier behöver Microsoft.SemanticKerneldu dock vanligtvis bara .

Du kan installera den med hjälp av följande kommando:

dotnet add package Microsoft.SemanticKernel

Den fullständiga listan över Nuget-paket finns i artikeln språk som stöds.

Instruktioner för att komma åt Python-paketet SemanticKernel finns här. Det är så enkelt som:

pip install semantic-kernel

Instruktioner för åtkomst till SemanticKernel Java-paketet finns här. Det är så enkelt som:

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

Kom snabbt igång med notebook-filer

Om du är Python- eller C#-utvecklare kan du snabbt komma igång med våra notebook-filer. De här notebook-filerna innehåller stegvisa guider om hur du använder semantisk kernel för att skapa AI-agenter.

Semantiska kernelanteckningsböcker

Följ dessa steg för att komma igång:

Klona lagringsplatsen semantisk kernel
Öppna lagringsplatsen i Visual Studio Code
Gå till _/python/samples/getting_started
Öppna 00-getting-started.ipynb för att komma igång med att konfigurera din miljö och skapa din första AI-agent!

Följ dessa steg för att komma igång:

Klona lagringsplatsen semantisk kernel
Öppna lagringsplatsen i Visual Studio Code
Gå till _/dotnet/notebooks
Öppna 00-getting-started.ipynb för att komma igång med att konfigurera din miljö och skapa din första AI-agent!

Skriva din första konsolapp

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

Följande fram och tillbaka-chatt bör likna det du ser i konsolen. Funktionsanropen har lagts till nedan för att visa hur AI:n utnyttjar plugin-programmet i bakgrunden.

Roll	Meddelande
🔵Användare	Växla ljuset
🔴Assistent (funktionsanrop)	`LightsPlugin.GetState()`
🟢Verktyg	`off`
🔴Assistent (funktionsanrop)	`LightsPlugin.ChangeState(true)`
🟢Verktyg	`on`
🔴Assistent	Ljuset är nu på

Om du är intresserad av att förstå mer om koden ovan delar vi upp den i nästa avsnitt.

Förstå koden

För att göra det enklare att komma igång med att skapa företagsappar med semantisk kernel har vi skapat ett steg för steg som vägleder dig genom processen att skapa en kernel och använda den för att interagera med AI-tjänster.

Semantisk Kernel Python-karta

Semantisk Kernel DotNET-karta

I följande avsnitt packar vi upp exemplet ovan genom att gå igenom steg 1, 2, 3, 4, 6, 9 och 10. Allt du behöver för att skapa en enkel agent som drivs av en AI-tjänst och kan köra din kod.

Importera paket
Lägga till AI-tjänster
Företagskomponenter ::: zone-end
Skapa kerneln
Lägg till minne (hoppas över)
Lägga till plugin-program
Skapa kernelargument (hoppas över)
Skapa prompter (hoppades över)
Planerad
Åkalla

1) Importera paket

För det här exemplet började vi först med att importera följande paket:

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) Lägg till AI-tjänster

Efteråt lägger vi till den viktigaste delen av en kernel: de AI-tjänster som du vill använda. I det här exemplet har vi lagt till en Tjänst för slutförande av Azure OpenAI-chatt till kernelverktyget.

Kommentar

I det här exemplet använde vi Azure OpenAI, men du kan använda andra tjänster för chattens slutförande. En fullständig lista över tjänster som stöds finns i artikeln språk som stöds. Om du behöver hjälp med att skapa en annan tjänst kan du läsa artikeln AI-tjänster. Där hittar du vägledning om hur du använder OpenAI- eller Azure OpenAI-modeller som tjänster.

// 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) Lägg till företagstjänster

En av de största fördelarna med att använda semantisk kernel är att den stöder tjänster i företagsklass. I det här exemplet har vi lagt till loggningstjänsten i kerneln för att felsöka AI-agenten.

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) Skapa kerneln och hämta tjänster

När tjänsterna har lagts till skapar vi sedan kerneln och hämtar tjänsten för chattens slutförande för senare användning.

Kernel kernel = builder.Build();

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

När kerneln har konfigurerats hämtar vi sedan tjänsten för chattens slutförande för senare användning.

Kommentar

I Python behöver du inte uttryckligen skapa kerneln. I stället kan du komma åt tjänsterna direkt från kernelobjektet.

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) Lägg till plugin-program

Med plugin-program kan du ge AI-agenten möjlighet att köra koden för att hämta information från externa källor eller utföra åtgärder. I exemplet ovan har vi lagt till ett plugin-program som gör att AI-agenten kan interagera med en glödlampa. Nedan visar vi hur du skapar det här plugin-programmet.

Skapa ett inbyggt plugin-program

Nedan ser du att det är lika enkelt att skapa ett inbyggt plugin-program som att skapa en ny klass.

I det här exemplet har vi skapat ett plugin-program som kan manipulera en glödlampa. Även om detta är ett enkelt exempel visar plugin-programmet snabbt hur du kan stödja båda...

Hämtning av utökad generation (RAG) genom att ge AI-agenten tillståndet för glödlampan
Och uppgiftsautomatisering genom att låta AI-agenten aktivera eller inaktivera glödlampan.

I din egen kod kan du skapa ett plugin-program som interagerar med alla externa tjänster eller API:er för att uppnå liknande resultat.

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

Lägg till plugin-programmet i kerneln

När du har skapat plugin-programmet kan du lägga till det i kerneln så att AI-agenten kan komma åt det. I exemplet har vi lagt till LightsPlugin klassen i kerneln.

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

Semantisk kernel använder funktionsanrop – en inbyggd funktion i de flesta LLM:er – för att tillhandahålla planering. Med funktionsanrop kan LLM:er begära (eller anropa) en viss funktion för att uppfylla en användares begäran. Semantisk kernel konverterar sedan begäran till lämplig funktion i din kodbas och returnerar resultatet tillbaka till LLM så att AI-agenten kan generera ett slutligt svar.

För att aktivera automatiska funktionsanrop måste vi först skapa lämpliga körningsinställningar så att semantisk kernel vet att automatiskt anropa funktionerna i kerneln när AI-agenten begär dem.

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

Slutligen anropar vi AI-agenten med plugin-programmet. Exempelkoden visar hur du genererar ett icke-strömmande svar, men du kan också generera ett strömningssvar med hjälp GetStreamingChatMessageContentAsync av metoden.

// 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ästa steg

I den här guiden har du lärt dig hur du snabbt kommer igång med Semantic Kernel genom att skapa en enkel AI-agent som kan interagera med en AI-tjänst och köra din kod. Om du vill se fler exempel och lära dig hur du skapar mer komplexa AI-agenter kan du läsa våra djupgående exempel.

Dela via