Mulai menggunakan Semantic Kernel

Artikel
07/02/2024

Hanya dalam beberapa langkah, Anda dapat membangun agen AI pertama Anda dengan Semantic Kernel baik di Python, .NET, atau Java. Panduan ini akan menunjukkan kepada Anda cara...

Menginstal paket yang diperlukan
Membuat percakapan bolak-balik dengan AI
Memberi agen AI kemampuan untuk menjalankan kode Anda
Tonton rencana pembuatan AI dengan cepat

Menginstal SDK

Semantic Kernel memiliki beberapa paket NuGet yang tersedia. Namun, untuk sebagian besar skenario, Anda biasanya hanya memerlukan Microsoft.SemanticKernel.

Anda dapat menginstalnya menggunakan perintah berikut:

dotnet add package Microsoft.SemanticKernel

Untuk daftar lengkap paket Nuget, silakan lihat artikel bahasa yang didukung.

Instruksi untuk mengakses SemanticKernel paket Python tersedia di sini. Ini sem mudah seperti:

pip install semantic-kernel

Mulai menggunakan buku catatan dengan cepat

Jika Anda adalah pengembang Python atau C#, Anda bisa dengan cepat memulai notebook kami. Notebook ini menyediakan panduan langkah demi langkah tentang cara menggunakan Semantic Kernel untuk membangun agen AI.

Buku catatan Kernel Semantik

Ikuti langkah-langkah berikut untuk memulai.

Mengkloning repositori Kernel Semantik
Buka repositori di Visual Studio Code
Navigasi ke _/python/samples/getting_started
Buka 00-getting-started.ipynb untuk mulai mengatur lingkungan Anda dan membuat agen AI pertama Anda!

Ikuti langkah-langkah berikut untuk memulai.

Mengkloning repositori Kernel Semantik
Buka repositori di Visual Studio Code
Navigasi ke _/dotnet/notebooks
Buka 00-getting-started.ipynb untuk mulai mengatur lingkungan Anda dan membuat agen AI pertama Anda!

Menulis aplikasi konsol pertama Anda

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

Obrolan bolak-balik berikut harus mirip dengan apa yang Anda lihat di konsol. Panggilan fungsi telah ditambahkan di bawah ini untuk menunjukkan bagaimana AI memanfaatkan plugin di belakang layar.

Peran	Pesan
🔵Pengguna	Silakan alihkan lampu
🔴Asisten (panggilan fungsi)	`LightsPlugin.GetState()`
🟢Alat	`off`
🔴Asisten (panggilan fungsi)	`LightsPlugin.ChangeState(true)`
🟢Alat	`on`
🔴Asisten	Lampu sekarang menyala

Jika Anda tertarik untuk memahami lebih lanjut tentang kode di atas, kami akan memecahnya di bagian berikutnya.

Memahami kode

Untuk mempermudah mulai membangun aplikasi perusahaan dengan Semantic Kernel, kami telah membuat langkah demi langkah yang memandu Anda melalui proses pembuatan kernel dan menggunakannya untuk berinteraksi dengan layanan AI.

Peta Python Kernel Semantik

Peta DotNET Kernel Semantik

Di bagian berikut, kita akan membuka kemasan sampel di atas dengan menelusuri langkah 1, 2, 3, 4, 6, 9, dan 10. Semua yang Anda butuhkan untuk membangun agen sederhana yang didukung oleh layanan AI dan dapat menjalankan kode Anda.

Impor paket
Menambahkan layanan AI
Komponen perusahaan
Membangun kernel
Tambahkan memori (dilewati)
Menambahkan plugin
Membuat argumen kernel (dilewati)
Membuat perintah (dilewati)
Perencanaan
Memohon

1) Impor paket

Untuk sampel ini, pertama-tama kita mulai dengan mengimpor paket berikut:

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) Tambahkan layanan AI

Setelah itu, kami menambahkan bagian terpenting dari kernel: layanan AI yang ingin Anda gunakan. Dalam contoh ini, kami menambahkan layanan penyelesaian obrolan Azure OpenAI ke penyusun kernel.

Catatan

Dalam contoh ini, kami menggunakan Azure OpenAI, tetapi Anda dapat menggunakan layanan penyelesaian obrolan lainnya. Untuk melihat daftar lengkap layanan yang didukung, lihat artikel bahasa yang didukung. Jika Anda memerlukan bantuan untuk membuat layanan yang berbeda, lihat artikel layanan AI. Di sana, Anda akan menemukan panduan tentang cara menggunakan model OpenAI atau Azure OpenAI sebagai layanan.

// 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) Tambahkan layanan perusahaan

Salah satu manfaat utama menggunakan Semantic Kernel adalah mendukung layanan tingkat perusahaan. Dalam sampel ini, kami menambahkan layanan pengelogan ke kernel untuk membantu men-debug agen 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) Bangun kernel dan ambil layanan

Setelah layanan ditambahkan, kami kemudian membangun kernel dan mengambil layanan penyelesaian obrolan untuk digunakan nanti.

Kernel kernel = builder.Build();

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

Setelah kernel dikonfigurasi, kami kemudian mengambil layanan penyelesaian obrolan untuk digunakan nanti.

Catatan

Di Python, Anda tidak perlu secara eksplisit membangun kernel. Sebagai gantinya, Anda dapat mengakses layanan langsung dari objek kernel.

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

6) Tambahkan plugin

Dengan plugin, dapat memberi agen AI Anda kemampuan untuk menjalankan kode Anda untuk mengambil informasi dari sumber eksternal atau untuk melakukan tindakan. Dalam contoh di atas, kami menambahkan plugin yang memungkinkan agen AI berinteraksi dengan bola lampu. Di bawah ini, kami akan menunjukkan kepada Anda cara membuat plugin ini.

Membuat plugin asli

Di bawah ini, Anda dapat melihat bahwa membuat plugin asli sesering membuat kelas baru.

Dalam contoh ini, kami telah membuat plugin yang dapat memanipulasi bola lampu. Meskipun ini adalah contoh sederhana, plugin ini dengan cepat menunjukkan bagaimana Anda dapat mendukung keduanya...

Pengambilan Augmented Generation (RAG) dengan menyediakan agen AI dengan status bola lampu
Dan otomatisasi tugas dengan memungkinkan agen AI menyalakan atau mematikan bola lampu.

Dalam kode Anda sendiri, Anda dapat membuat plugin yang berinteraksi dengan layanan eksternal atau API apa pun untuk mencapai hasil yang sama.

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

Menambahkan plugin ke kernel

Setelah membuat plugin, Anda dapat menambahkannya ke kernel sehingga agen AI dapat mengaksesnya. Dalam sampel, kami menambahkan LightsPlugin kelas ke 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",
)

9) Perencanaan

Kernel Semantik memanfaatkan pemanggilan fungsi–fitur asli dari sebagian besar LLM–untuk memberikan perencanaan. Dengan panggilan fungsi, LLM dapat meminta (atau memanggil) fungsi tertentu untuk memenuhi permintaan pengguna. Semantic Kernel kemudian melakukan marsekal permintaan ke fungsi yang sesuai di basis kode Anda dan mengembalikan hasilnya kembali ke LLM sehingga agen AI dapat menghasilkan respons akhir.

Untuk mengaktifkan panggilan fungsi otomatis, pertama-tama kita perlu membuat pengaturan eksekusi yang sesuai sehingga Kernel Semantik tahu untuk secara otomatis memanggil fungsi di kernel ketika agen AI memintanya.

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

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

10) Panggil

Akhirnya, kami memanggil agen AI dengan plugin. Kode sampel menunjukkan cara menghasilkan respons non-streaming, tetapi Anda juga dapat menghasilkan respons streaming dengan menggunakan metode .GetStreamingChatMessageContentAsync

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

Langkah berikutnya

Dalam panduan ini, Anda mempelajari cara memulai dengan cepat Semantic Kernel dengan membangun agen AI sederhana yang dapat berinteraksi dengan layanan AI dan menjalankan kode Anda. Untuk melihat lebih banyak contoh dan mempelajari cara membangun agen AI yang lebih kompleks, lihat sampel mendalam kami.

Bagikan melalui