Mulai menggunakan Semantic Kernel
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.
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.
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.