A Szemantic Kernel használatának első lépései

Néhány lépésben létrehozhatja első AI-ügynökét a Szemantikus Kernel használatával Pythonban, .NET-ben vagy Java-ban. Ez az útmutató bemutatja, hogyan...

• A szükséges csomagok telepítése
• Oda-vissza beszélgetés létrehozása AI-vel
• A kód futtatásának lehetősége egy AI-ügynök számára
• Nézze meg, ahogy az AI terveket hoz létre menet közben

Az SDK telepítése

A Szemantic Kernel számos NuGet-csomaggal rendelkezik. A legtöbb forgatókönyv esetében azonban általában csak a szükséges Microsoft.SemanticKernel.

A következő paranccsal telepítheti:

dotnet add package Microsoft.SemanticKernel

A Nuget-csomagok teljes listájáért tekintse meg a támogatott nyelvekről szóló cikket.

A Python-csomag elérésére SemanticKernel vonatkozó utasítások itt érhetők el. Ez olyan egyszerű, mint:

pip install semantic-kernel

A jegyzetfüzetek gyors használatbavétele

Ha Ön Python- vagy C#-fejlesztő, gyorsan megkezdheti a jegyzetfüzetek használatát. Ezek a jegyzetfüzetek részletes útmutatókat nyújtanak arról, hogyan használható a Szemantic Kernel az AI-ügynökök létrehozására.

Első lépésként kövesse az alábbi lépéseket:

1. Klónozza a Szemantic Kernel-adattárat
2. Az adattár megnyitása a Visual Studio Code-ban
3. Lépjen a _/python/samples/getting_started
4. Nyissa meg a 00-getting-started.ipynb elemet a környezet beállításának megkezdéséhez és az első AI-ügynök létrehozásához!

Első lépésként kövesse az alábbi lépéseket:

1. Klónozza a Szemantic Kernel-adattárat
2. Az adattár megnyitása a Visual Studio Code-ban
3. Ugrás a _/dotnet/notebookokra
4. Nyissa meg a 00-getting-started.ipynb elemet a környezet beállításának megkezdéséhez és az első AI-ügynök létrehozásához!

Az első konzolalkalmazás írása

// 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() 
{
    ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
};

// 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.functions import kernel_function
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.connectors.ai.function_call_behavior import FunctionCallBehavior
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
    kernel.add_service(AzureChatCompletion(
        deployment_name="your_models_deployment_name",
        api_key="your_api_key",
        base_url="your_base_url",
    ))

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

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

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

    # Enable planning
    execution_settings = AzureChatPromptExecutionSettings(tool_choice="auto")
    execution_settings.function_call_behavior = FunctionCallBehavior.EnableFunctions(auto_invoke=True, filters={})

    # 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_contents(
            chat_history=history,
            settings=execution_settings,
            kernel=kernel,
            arguments=KernelArguments(),
        ))[0]

        # 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())

A következő oda-vissza csevegésnek hasonlónak kell lennie a konzolon láthatóhoz. Az alábbi függvényhívások bemutatják, hogyan használja az AI a beépülő modult a színfalak mögött.

Szerepkör	Üzenet
🔵Felhasználó	Kapcsolja ki a villanyt
🔴Asszisztens (függvényhívás)	LightsPlugin.GetState()
🟢Eszköz	off
🔴Asszisztens (függvényhívás)	LightsPlugin.ChangeState(true)
🟢Eszköz	on
🔴Asszisztens	A fény most be van kapcsolva

Ha többet szeretne megtudni a fenti kódról, a következő szakaszban bontjuk le.

A kód értelmezése

Annak érdekében, hogy megkönnyítsük a vállalati alkalmazások szemantikus kernellel való létrehozásának megkezdését, létrehoztunk egy részletes útmutatót, amely végigvezeti a kernel létrehozásának folyamatán és az AI-szolgáltatások használatára.

A következő szakaszokban kicsomagoljuk a fenti mintát az 1., 2., 3., 4., 6., 9. és 10. lépésben. Minden, amire szüksége van egy egyszerű ügynök létrehozásához, amelyet egy AI-szolgáltatás működtet, és képes futtatni a kódot.

1. Csomagok importálása
2. AI-szolgáltatások hozzáadása
3. Vállalati összetevők
4. A kernel létrehozása
5. Memória hozzáadása (kihagyva)
6. Beépülő modulok hozzáadása
7. Kernelargumentumok létrehozása (kihagyva)
8. Kérések létrehozása (kihagyva)
9. Tervezés
10. Hív

1) Csomagok importálása

Ebben a példában először a következő csomagok importálásával kezdtük:

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_call_behavior import FunctionCallBehavior
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,
)

2) AI-szolgáltatások hozzáadása

Ezt követően hozzáadjuk a kernel legfontosabb részét: a használni kívánt AI-szolgáltatásokat. Ebben a példában hozzáadtunk egy Azure OpenAI-csevegés-befejezési szolgáltatást a kernelszerkesztőhöz.

Feljegyzés

Ebben a példában az Azure OpenAI-t használtuk, de bármilyen más csevegés-befejezési szolgáltatást használhat. A támogatott szolgáltatások teljes listájának megtekintéséhez tekintse meg a támogatott nyelvekről szóló cikket. Ha segítségre van szüksége egy másik szolgáltatás létrehozásához, tekintse meg az AI-szolgáltatásokról szóló cikket. Itt útmutatást talál az OpenAI- vagy az Azure OpenAI-modellek szolgáltatásokként való használatához.

// 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",
))

3) Vállalati szolgáltatások hozzáadása

A Szemantic Kernel használatának egyik fő előnye, hogy támogatja a nagyvállalati szintű szolgáltatásokat. Ebben a példában hozzáadtuk a naplózási szolgáltatást a kernelhez az AI-ügynök hibakereséséhez.

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) A kernel létrehozása és a szolgáltatások lekérése

Miután hozzáadtuk a szolgáltatásokat, létrehozzuk a kernelt, és lekérjük a csevegés befejezésére szolgáló szolgáltatást későbbi használatra.

Kernel kernel = builder.Build();

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

Miután konfigurálta a kernelt, lekérjük a csevegés befejező szolgáltatását későbbi használatra.

Feljegyzés

A Pythonban nem kell explicit módon létrehoznia a kernelt. Ehelyett közvetlenül a kernelobjektumból érheti el a szolgáltatásokat.

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

6) Beépülő modulok hozzáadása

A beépülő modulok lehetővé teszik az AI-ügynök számára a kód futtatását a külső forrásokból származó információk lekéréséhez vagy műveletek végrehajtásához. A fenti példában hozzáadtunk egy beépülő modult, amely lehetővé teszi az AI-ügynök számára, hogy egy villanykörtével kommunikáljon. Az alábbiakban bemutatjuk, hogyan hozhatja létre ezt a beépülő modult.

Natív beépülő modul létrehozása

Az alábbiakban láthatja, hogy a natív beépülő modul létrehozása olyan egyszerű, mint egy új osztály létrehozása.

Ebben a példában létrehoztunk egy beépülő modult, amely képes módosítani egy villanykörtét. Bár ez egy egyszerű példa, ez a beépülő modul gyorsan bemutatja, hogyan támogathatja mindkettőt...

1. Kiterjesztett generáció (RAG) lekérése az AI-ügynöknek a villanykörte állapotának biztosításával
2. A feladatautomatizáláshoz pedig az AI-ügynök bekapcsolhatja vagy kikapcsolhatja a villanykörtét.

A saját kódjában létrehozhat egy beépülő modult, amely bármilyen külső szolgáltatással vagy API-val együttműködve hasonló eredményeket érhet el.

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

A beépülő modul hozzáadása a kernelhez

Miután létrehozta a beépülő modult, hozzáadhatja a kernelhez, hogy az AI-ügynök hozzáférhessen. A mintában hozzáadtuk az osztályt LightsPlugin a kernelhez.

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

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

9) Tervezés

A szemantikus kernel a függvényhívást használja – a legtöbb LLM natív funkcióját – a tervezéshez. Függvényhívás esetén az LLM-ek egy adott függvényt kérhetnek (vagy hívhatnak meg) a felhasználó kérésének teljesítéséhez. A Szemantic Kernel ezután a kódbázis megfelelő függvényének küldi a kérést, és visszaadja az eredményeket az LLM-nek, hogy az AI-ügynök végleges választ generáljon.

Az automatikus függvényhívás engedélyezéséhez először létre kell hoznunk a megfelelő végrehajtási beállításokat, hogy a Szemantic Kernel tudja, hogy automatikusan meghívja a függvényeket a kernelben, amikor az AI-ügynök kéri őket.

OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new() 
{
    ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
};

execution_settings = AzureChatPromptExecutionSettings(tool_choice="auto")
execution_settings.function_call_behavior = FunctionCallBehavior.EnableFunctions(auto_invoke=True, filters={})

10) Meghívás

Végül meghívjuk az AI-ügynököt a beépülő modullal. A mintakód bemutatja, hogyan hozhat létre nem streamelési választ, de streamelési választ is létrehozhat a GetStreamingChatMessageContentAsync módszerrel.

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

Következő lépések

Ebben az útmutatóban megtanulta, hogyan kezdheti el gyorsan a Szemantic Kernel használatát egy egyszerű AI-ügynök létrehozásával, amely képes kezelni egy AI-szolgáltatást, és futtatni a kódot. Ha további példákat szeretne látni, és megtudhatja, hogyan hozhat létre összetettebb AI-ügynököket, tekintse meg részletes példáinkat.