Prise en main du noyau sémantique

Article
07/02/2024

En quelques étapes, vous pouvez créer votre premier agent IA avec le noyau sémantique en Python, .NET ou Java. Ce guide vous montre comment...

Installer les packages nécessaires
Créer une conversation back-and-forth avec une IA
Donnez à un agent IA la possibilité d’exécuter votre code
Regardez les plans de création d’IA à la volée

Installation du SDK

Le noyau sémantique comporte plusieurs packages NuGet disponibles. Toutefois, pour la plupart des scénarios, vous n’avez généralement besoin Microsoft.SemanticKernelque de .

Vous pouvez l’installer à l’aide de la commande suivante :

dotnet add package Microsoft.SemanticKernel

Pour obtenir la liste complète des packages Nuget, reportez-vous à l’article sur les langues prises en charge.

Des instructions pour accéder au SemanticKernel package Python sont disponibles ici. C’est aussi simple que :

pip install semantic-kernel

Des instructions pour accéder au SemanticKernel package Java sont disponibles ici. C’est aussi simple que :

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

Prise en main rapide des notebooks

Si vous êtes développeur Python ou C#, vous pouvez rapidement commencer à utiliser nos notebooks. Ces notebooks fournissent des guides pas à pas sur l’utilisation du noyau sémantique pour générer des agents IA.

Notebooks de noyau sémantique

Pour commencer, suivez ces étapes :

Cloner le référentiel du noyau sémantique
Ouvrir le dépôt dans Visual Studio Code
Accédez à _/python/samples/getting_started
Ouvrez 00-getting-started.ipynb pour commencer à définir votre environnement et à créer votre premier agent IA !

Pour commencer, suivez ces étapes :

Cloner le référentiel du noyau sémantique
Ouvrir le dépôt dans Visual Studio Code
Accédez à _/dotnet/notebooks
Ouvrez 00-getting-started.ipynb pour commencer à définir votre environnement et à créer votre premier agent IA !

Écriture de votre première application console

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

La conversation back-and-forth suivante doit être similaire à ce que vous voyez dans la console. Les appels de fonction ont été ajoutés ci-dessous pour montrer comment l’IA tire parti du plug-in en arrière-plan.

Rôle	Message
🔵Utilisateur	Basculez la lumière
🔴Assistant (appel de fonction)	`LightsPlugin.GetState()`
🟢Outil	`off`
🔴Assistant (appel de fonction)	`LightsPlugin.ChangeState(true)`
🟢Outil	`on`
🔴Assistant	La lumière est maintenant allumée

Si vous souhaitez en savoir plus sur le code ci-dessus, nous allons le décomposer dans la section suivante.

Présentation du code

Pour faciliter la création d’applications d’entreprise avec le noyau sémantique, nous avons créé une étape par étape qui vous guide tout au long du processus de création d’un noyau et de son utilisation pour interagir avec les services IA.

Mappage Python du noyau sémantique

Mappage DotNET du noyau sémantique

Dans les sections suivantes, nous allons décompresser l’exemple ci-dessus en parcourant les étapes 1, 2, 3, 4, 6, 9 et 10. Tout ce dont vous avez besoin pour créer un agent simple qui est alimenté par un service IA et peut exécuter votre code.

Importer des packages
Ajouter des services IA
Composants d’entreprise ::: zone-end
Générer le noyau
Ajouter de la mémoire (ignorée)
Ajouter des plug-ins
Créer des arguments de noyau (ignorés)
Créer des invites (ignorées)
Planification
Appeler

1) Importer des packages

Pour cet exemple, nous avons d’abord commencé par importer les packages suivants :

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) Ajouter des services IA

Ensuite, nous ajoutons la partie la plus importante d’un noyau : les services IA que vous souhaitez utiliser. Dans cet exemple, nous avons ajouté un service d’achèvement de conversation Azure OpenAI au générateur de noyau.

Remarque

Dans cet exemple, nous avons utilisé Azure OpenAI, mais vous pouvez utiliser n’importe quel autre service d’achèvement de conversation. Pour afficher la liste complète des services pris en charge, reportez-vous à l’article sur les langues prises en charge. Si vous avez besoin d’aide pour créer un autre service, reportez-vous à l’article des services IA. Vous y trouverez des conseils sur l’utilisation des modèles OpenAI ou Azure OpenAI en tant que 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) Ajouter des services d’entreprise

L’un des principaux avantages de l’utilisation du noyau sémantique est qu’il prend en charge les services de niveau entreprise. Dans cet exemple, nous avons ajouté le service de journalisation au noyau pour aider à déboguer l’agent IA.

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) Générer le noyau et récupérer des services

Une fois les services ajoutés, nous créons ensuite le noyau et récupérons le service d’achèvement de conversation pour une utilisation ultérieure.

Kernel kernel = builder.Build();

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

Une fois le noyau configuré, nous récupérons ensuite le service d’achèvement de conversation pour une utilisation ultérieure.

Remarque

En Python, vous n’avez pas besoin de générer explicitement le noyau. Au lieu de cela, vous pouvez accéder aux services directement à partir de l’objet noyau.

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) Ajouter des plug-ins

Avec les plug-ins, vous pouvez donner à votre agent IA la possibilité d’exécuter votre code pour récupérer des informations à partir de sources externes ou d’effectuer des actions. Dans l’exemple ci-dessus, nous avons ajouté un plug-in qui permet à l’agent IA d’interagir avec une ampoule. Ci-dessous, nous allons vous montrer comment créer ce plug-in.

Créer un plug-in natif

Vous pouvez voir ci-dessous que la création d’un plug-in natif est aussi simple que la création d’une classe.

Dans cet exemple, nous avons créé un plug-in qui peut manipuler une ampoule. Bien qu’il s’agit d’un exemple simple, ce plug-in montre rapidement comment vous pouvez prendre en charge les deux...

Récupération de génération augmentée (RAG) en fournissant à l’agent IA l’état de l’ampoule
Et l’automatisation des tâches en permettant à l’agent IA d’activer ou de désactiver l’ampoule.

Dans votre propre code, vous pouvez créer un plug-in qui interagit avec n’importe quel service externe ou API pour obtenir des résultats similaires.

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

Ajouter le plug-in au noyau

Une fois que vous avez créé votre plug-in, vous pouvez l’ajouter au noyau afin que l’agent IA puisse y accéder. Dans l’exemple, nous avons ajouté la LightsPlugin classe au noyau.

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

Le noyau sémantique tire parti de l’appel de fonction, une fonctionnalité native de la plupart des machines virtuelles LLM, pour fournir une planification. Avec l’appel de fonction, les llms peuvent demander (ou appeler) une fonction particulière pour satisfaire la demande d’un utilisateur. Le noyau sémantique marshale ensuite la requête à la fonction appropriée dans votre codebase et retourne les résultats au LLM afin que l’agent IA puisse générer une réponse finale.

Pour activer l’appel automatique de fonctions, nous devons d’abord créer les paramètres d’exécution appropriés afin que le noyau sémantique sache appeler automatiquement les fonctions dans le noyau lorsque l’agent IA les demande.

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

Enfin, nous vocons l’agent IA avec le plug-in. L’exemple de code montre comment générer une réponse non en streaming, mais vous pouvez également générer une réponse de diffusion en continu à l’aide de la GetStreamingChatMessageContentAsync méthode.

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

Étapes suivantes

Dans ce guide, vous avez appris à démarrer rapidement avec le noyau sémantique en créant un agent IA simple capable d’interagir avec un service IA et d’exécuter votre code. Pour voir d’autres exemples et découvrir comment créer des agents IA plus complexes, consultez nos exemples détaillés.

Partager via