Začínáme se sémantickým jádrem

Článek
07/02/2024

V několika krocích můžete vytvořit svého prvního agenta AI se sémantickým jádrem v Pythonu, .NET nebo Javě. Tato příručka vám ukáže, jak...

Instalace potřebných balíčků
Vytvoření back-and-forth konverzace s AI
Poskytněte agentovi AI možnost spustit váš kód.
Sledujte, jak AI průběžně vytváří plány

Instalace sady SDK

Sémantické jádro má k dispozici několik balíčků NuGet. Pro většinu scénářů však obvykle potřebujete Microsoft.SemanticKernelpouze .

Můžete ho nainstalovat pomocí následujícího příkazu:

dotnet add package Microsoft.SemanticKernel

Úplný seznam balíčků NuGet najdete v článku o podporovaných jazycích.

Pokyny pro přístup k SemanticKernel balíčku Pythonu najdete tady. Je to stejně snadné jako:

pip install semantic-kernel

Pokyny pro přístup k SemanticKernel balíčku Java najdete tady. Je to stejně snadné jako:

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

Rychlé zahájení práce s poznámkovými bloky

Pokud jste vývojář Pythonu nebo C#, můžete s našimi poznámkovými bloky rychle začít. Tyto poznámkové bloky poskytují podrobné pokyny k vytváření agentů AI pomocí sémantického jádra.

Poznámkové bloky sémantického jádra

Chcete-li začít, postupujte následovně:

Klonování úložiště sémantických jader
Otevření úložiště v editoru Visual Studio Code
Přejděte na _/python/samples/getting_started
Otevřete 00-getting-started.ipynb , abyste mohli začít s nastavením prostředí a vytvořením prvního agenta AI.

Chcete-li začít, postupujte následovně:

Klonování úložiště sémantických jader
Otevření úložiště v editoru Visual Studio Code
Přejděte na _/dotnet/notebooks
Otevřete 00-getting-started.ipynb , abyste mohli začít s nastavením prostředí a vytvořením prvního agenta AI.

Psaní první konzolové aplikace

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

Následující back-and-forth chat by měl být podobný tomu, co vidíte v konzole. Volání funkcí byla přidána níže, aby ukázala, jak umělá inteligence využívá modul plug-in na pozadí.

Role	Zpráva
🔵Uživatel	Přepněte světlo.
🔴Asistent (volání funkce)	`LightsPlugin.GetState()`
🟢Nástroj	`off`
🔴Asistent (volání funkce)	`LightsPlugin.ChangeState(true)`
🟢Nástroj	`on`
🔴Asistent	Světlo je teď zapnuté.

Pokud se zajímáte o další informace o výše uvedeném kódu, rozdělíme ho v další části.

Vysvětlení kódu

Abychom vám usnadnili vytváření podnikových aplikací pomocí sémantického jádra, vytvořili jsme krok za krokem, který vás provede procesem vytvoření jádra a jeho používání k interakci se službami AI.

Mapa Pythonu sémantického jádra

Mapa sémantického jádra DotNET

V následujících částech rozbalíme výše uvedený vzorek procházením kroků 1, 2, 3, 4, 6, 9 a 10. Všechno, co potřebujete k vytvoření jednoduchého agenta, který využívá službu AI, a může spustit váš kód.

Import balíčků
Přidání služeb AI
Podnikové komponenty ::: zone-end
Sestavení jádra
Přidání paměti (vynecháno)
Přidání modulů plug-in
Vytvoření argumentů jádra (vynecháno)
Vytváření výzev (vynecháno)
Plánování
Vyvolat

1) Import balíčků

Pro tuto ukázku jsme nejprve začali importem následujících balíč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_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) Přidání služeb AI

Potom přidáme nejdůležitější část jádra: služby AI, které chcete použít. V tomto příkladu jsme do tvůrce jádra přidali službu dokončování chatu Azure OpenAI.

Poznámka:

V tomto příkladu jsme použili Azure OpenAI, ale můžete použít jakoukoli jinou službu dokončování chatu. Úplný seznam podporovaných služeb najdete v článku o podporovaných jazycích. Pokud potřebujete pomoc s vytvořením jiné služby, přečtěte si článek o službách AI. Tady najdete pokyny k používání modelů OpenAI nebo Azure OpenAI jako služeb.

// 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) Přidání podnikových služeb

Jednou z hlavních výhod používání sémantického jádra je to, že podporuje služby na podnikové úrovni. V této ukázce jsme do jádra přidali službu protokolování, která pomáhá ladit agenta AI.

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) Sestavení jádra a načtení služeb

Po přidání služeb pak sestavíme jádro a načteme službu pro dokončování chatu pro pozdější použití.

Kernel kernel = builder.Build();

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

Po nakonfigurování jádra pak načteme službu dokončování chatu pro pozdější použití.

Poznámka:

V Pythonu nemusíte explicitně sestavovat jádro. Místo toho můžete přistupovat ke službám přímo z objektu jádra.

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) Přidání modulů plug-in

Pomocí modulů plug-in můžete agentovi AI poskytnout možnost spustit kód, který načítá informace z externích zdrojů nebo provádí akce. V předchozím příkladu jsme přidali modul plug-in, který agentovi AI umožňuje interakci s žárovkou. Níže vám ukážeme, jak vytvořit tento modul plug-in.

Vytvoření nativního modulu plug-in

Níže vidíte, že vytvoření nativního modulu plug-in je stejně jednoduché jako vytvoření nové třídy.

V tomto příkladu jsme vytvořili modul plug-in, který může manipulovat s žárovkou. I když je to jednoduchý příklad, tento modul plug-in rychle ukazuje, jak můžete podporovat obojí...

Načtení rozšířené generace (RAG) poskytnutím agenta AI se stavem žárovky
Automatizace úloh tím, že agentovi AI umožní zapnout nebo vypnout žárovku.

Ve vlastním kódu můžete vytvořit modul plug-in, který komunikuje s jakoukoli externí službou nebo rozhraním API, abyste dosáhli podobných výsledků.

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

Přidání modulu plug-in do jádra

Po vytvoření modulu plug-in ho můžete přidat do jádra, aby k němu mohl přistupovat agent AI. V ukázce jsme přidali LightsPlugin třídu do jádra.

// 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) Plánování

Sémantické jádro využívá k plánování funkci volání – nativní funkci většiny LLM. S voláním funkce můžou LLM požadovat (nebo volat) konkrétní funkci, aby uspokojily požadavek uživatele. Sémantické jádro pak zařadí požadavek do příslušné funkce v základu kódu a vrátí výsledky zpět do LLM, aby agent AI mohl vygenerovat konečnou odpověď.

Abychom povolili automatické volání funkcí, musíme nejprve vytvořit odpovídající nastavení spuštění, aby sémantické jádro vědělo, že funkce v jádru automaticky vyvolá, když je agent AI požádá.

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) Vyvolání

Nakonec vyvoláme agenta AI s modulem plug-in. Ukázkový kód ukazuje, jak vygenerovat odpověď bez streamování, ale pomocí metody můžete také vygenerovat odpověď GetStreamingChatMessageContentAsync streamování.

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

Další kroky

V této příručce jste zjistili, jak rychle začít se sémantickým jádrem vytvořením jednoduchého agenta AI, který může pracovat se službou AI a spouštět váš kód. Další příklady a informace o vytváření složitějších agentů AI najdete v našich podrobných ukázkách.

Sdílet prostřednictvím