セマンティックカーネル - .Net V1 移行ガイド

Note

このドキュメントは最終的なものであり、ますます良くなります!

このガイドは、v1 より前のバージョンの .NET Semantic Kernel SDK から v1 以降へのアップグレードを支援することを目的としています。このドキュメントの参照として使用される v1 より前のバージョンは、変更の大部分が発生し始めた最初のベータリリースの前の最後のバージョンである 0.26.231009 バージョンでした。

パッケージの変更

多くのパッケージが再定義、削除、および名前変更された結果、適切なクリーンアップと名前空間の簡略化を行ったことを考慮すると、古いパッケージの多くを名前変更、非推奨、削除する必要があります。次の表は、パッケージの変更点を示しています。

Microsoft.SemanticKernelで始まるすべてのパッケージは、簡潔にするために..プレフィックスで切り捨てられました。

以前の名前	V1 名	バージョン	理由
..Connectors.AI.HuggingFace	..Connectors.HuggingFace	preview
..Connectors.AI.OpenAI	..Connectors.OpenAI	v1
..Connectors.AI.Oobabooga	MyIA.SemanticKernel.Connectors.AI.Oobabooga	alpha	コミュニティ駆動型コネクタ ⚠️まだv1以上の準備ができていません
..Connectors.Memory.Kusto	..Connectors.Kusto	alpha
..Connectors.Memory.DuckDB	..Connectors.DuckDB	alpha
..Connectors.Memory.Pinecone	..Connectors.Pinecone	alpha
..Connectors.Memory.Redis	..Connectors.Redis	alpha
..Connectors.Memory.Qdrant	..Connectors.Qdrant	alpha
--	..Connectors.Postgres	alpha
..Connectors.Memory.AzureCognitiveSearch	..Connectors.Memory.AzureAISearch	alpha
..Functions.Semantic	-削除-		Core でマージ済み
..Reliability.Basic	-削除-		.NET 依存関係挿入に置き換えられました
..Reliability.Polly	-削除-		.NET 依存関係挿入に置き換えられました
..TemplateEngine.Basic	-削除-		Core でマージ済み
..Planners.Core	..Planners.OpenAI Planners.Handlebars	preview
--	..Experimental.Agents	alpha
--	..Experimental.Orchestration.Flow	v1

信頼性パッケージ - .NET 依存関係挿入に置き換えられました

信頼性の基本パッケージと Polly パッケージは、.net 依存関係の挿入 ConfigureHttpClientDefaults サービスコレクション拡張機能を使用して、目的の回復性ポリシーを HttpClient インスタンスに挿入できるようになりました。

// Before
var retryConfig = new BasicRetryConfig
{
    MaxRetryCount = 3,
    UseExponentialBackoff = true,
};
retryConfig.RetryableStatusCodes.Add(HttpStatusCode.Unauthorized);
var kernel = new KernelBuilder().WithRetryBasic(retryConfig).Build();

// After
builder.Services.ConfigureHttpClientDefaults(c =>
{
    // Use a standard resiliency policy, augmented to retry on 401 Unauthorized for this example
    c.AddStandardResilienceHandler().Configure(o =>
    {
        o.Retry.ShouldHandle = args => ValueTask.FromResult(args.Outcome.Result?.StatusCode is HttpStatusCode.Unauthorized);
    });
});

パッケージの削除と必要な変更

以下のいずれかのパッケージを使用する場合は、V1 が使用する最新バージョンと一致していることを確認します。

[パッケージ名]	バージョン
Microsoft.Extensions.Configuration	8.0.0
Microsoft.Extensions.Configuration.Binder	8.0.0
Microsoft.Extensions.Configuration.EnvironmentVariables	8.0.0
Microsoft.Extensions.Configuration.Json	8.0.0
Microsoft.Extensions.Configuration.UserSecrets	8.0.0
Microsoft.Extensions.DependencyInjection	8.0.0
Microsoft.Extensions.DependencyInjection.Abstractions	8.0.0
Microsoft.Extensions.Http	8.0.0
Microsoft.Extensions.Http.Resilience	8.0.0
Microsoft.Extensions.Logging	8.0.0
Microsoft.Extensions.Logging.Abstractions	8.0.0
Microsoft.Extensions.Logging.Console	8.0.0

規則名の変更

内部の名前付け規則の多くは、AI コミュニティがどのように名前を付けるかをより適切に反映するように変更されました。 OpenAI が大規模なシフトを開始し、Prompt、Plugins、Models、RAG などの用語が形成されたので、コミュニティが SDK の使用を理解しやすくするために、これらの用語に合わせる必要があることを明確にしました。

以前の名前	V1 名
セマンティック関数	Prompt 関数
ネイティブ関数	メソッド関数
コンテキスト変数	カーネル引数
要求の設定	プロンプト実行の設定
テキストの入力候補	テキストの生成
画像の生成	テキストから画像へ
スキル	プラグイン

コード名の変更

会話名の変更に続いて、コード名の多くも新しい名前付け規則をより適切に反映するように変更されました。また、コードを読みやすくするために、Abbreaviations も削除されました。

以前の名前	V1 名
ContextVariables	KernelArguments
ContextVariables.Set	KernelArguments.Add
IImageGenerationService	ITextToImageService
ITextCompletionService	ITextGenerationService
Kernel.CreateSemanticFunction	Kernel.CreateFunctionFromPrompt
Kernel.ImportFunctions	Kernel.ImportPluginFrom____
Kernel.ImportSemanticFunctionsFromDirectory	Kernel.ImportPluginFromPromptDirectory
Kernel.RunAsync	Kernel.InvokeAsync
NativeFunction	MethodFunction
OpenAIRequestSettings	OpenAIPromptExecutionSettings
RequestSettings	PromptExecutionSettings
SKException	KernelException
SKFunction	KernelFunction
SKFunctionMetadata	KernelFunctionAttribute
SKJsonSchema	KernelJsonSchema
SKParameterMetadata	KernelParameterMetadata
SKPluginCollection	KernelPluginCollection
SKReturnParameterMetadata	KernelReturnParameterMetadata
SemanticFunction	PromptFunction
SKContext	FunctionResult (出力)

名前空間の簡略化

以前の名前空間には、プロジェクト内のディレクトリ名と 1 対 1 に一致する深い階層がありました。これは一般的な方法ですが、セマンティックカーネルパッケージのコンシューマーは、コードに多数の異なる usingを追加する必要がありました。セマンティックカーネルパッケージ内の名前空間の数を減らして、機能の大部分がメインの Microsoft.SemanticKernel 名前空間に含まれるようにすることにしました。詳細については、下を参照してください。

以前の名前	V1 名
Microsoft.SemanticKernel.Orchestration	Microsoft.SemanticKernel
Microsoft.SemanticKernel.Connectors.AI.*	Microsoft.SemanticKernel.Connectors.*
Microsoft.SemanticKernel.SemanticFunctions	Microsoft.SemanticKernel
Microsoft.SemanticKernel.Events	Microsoft.SemanticKernel
Microsoft.SemanticKernel.AI.*	Microsoft.SemanticKernel.*
Microsoft.SemanticKernel.Connectors.AI.OpenAI.*	Microsoft.SemanticKernel.Connectors.OpenAI
Microsoft.SemanticKernel.Connectors.AI.HuggingFace.*	Microsoft.SemanticKernel.Connectors.HuggingFace

カーネル

Kernel インスタンスを作成して使用するコードが簡略化されました。開発者は独自のKernel実装を作成する必要がないように、IKernel インターフェイスは削除されました。 Kernel クラスは、サービスとプラグインのコレクションを表します。現在の Kernel インスタンスは、セマンティックカーネルの背後にある設計理念と一致するすべての場所で使用できます。

IKernel インターフェイスが Kernel クラスに変更されました。
Kernel.ImportFunctions は削除され、 Kernel.ImportPluginFrom____に置き換えられました。 ____ は、 Functions、 Object、 PromptDirectory、 Type、 Grp 、または OpenAIAsyncなどです。
```
// Before
var textFunctions = kernel.ImportFunctions(new StaticTextPlugin(), "text");

// After
var textFunctions = kernel.ImportPluginFromObject(new StaticTextPlugin(), "text");
```

Kernel.RunAsync が削除され、 Kernel.InvokeAsyncに置き換えられました。シフトされたパラメーターの順序。関数が最初です。

// Before
KernelResult result = kernel.RunAsync(textFunctions["Uppercase"], "Hello World!");

// After
FunctionResult result = kernel.InvokeAsync(textFunctions["Uppercase"], new() { ["input"] = "Hello World!" });

Kernel.InvokeAsyncでは、KernelResultではなくFunctionResultが返されるようになりました。

Kernel.InvokeAsync は、呼び出しごとに最初のパラメーターとして 1 つの関数のみを対象とします。パイプライン処理はサポートされていません。チェーン動作を実現するには、 Example 60 を使用します。

❌ サポート対象外

KernelResult result = await kernel.RunAsync(" Hello World! ",
    textFunctions["TrimStart"],
    textFunctions["TrimEnd"],
    textFunctions["Uppercase"]);

✔️ 呼び出しごとに 1 つの関数

var trimStartResult = await kernel.InvokeAsync(textFunctions["TrimStart"], new() { ["input"] = " Hello World! " });
var trimEndResult = await kernel.InvokeAsync(textFunctions["TrimEnd"], new() { ["input"] = trimStartResult.GetValue<string>() });
var finalResult = await kernel.InvokeAsync(textFunctions["Uppercase"], new() { ["input"] = trimEndResult.GetValue<string>() });

✔️ プラグインカーネルインジェクションを使用したチェーン

// Plugin using Kernel injection
public class MyTextPlugin
{
    [KernelFunction]
    public async Task<string> Chain(Kernel kernel, string input)
    {
        var trimStartResult = await kernel.InvokeAsync("textFunctions", "TrimStart", new() { ["input"] = input });
        var trimEndResult = await kernel.InvokeAsync("textFunctions", "TrimEnd", new() { ["input"] = trimStartResult.GetValue<string>() });
        var finalResult = await kernel.InvokeAsync("textFunctions", "Uppercase", new() { ["input"] = trimEndResult.GetValue<string>() });

        return finalResult.GetValue<string>();
    }
}

var plugin = kernel.ImportPluginFromObject(new MyTextPlugin(), "textFunctions");
var finalResult = await kernel.InvokeAsync(plugin["Chain"], new() { ["input"] = " Hello World! "});

Kernel.InvokeAsync は文字列を入力として受け入れなくなりました。代わりに KernelArguments インスタンスを使用してください。関数が最初の引数になり、入力引数を KernelArguments インスタンスとして指定する必要があります。
```
// Before
var result = await kernel.RunAsync("I missed the F1 final race", excuseFunction);

// After
var result = await kernel.InvokeAsync(excuseFunction, new() { ["input"] = "I missed the F1 final race" });
```
Kernel.ImportSemanticFunctionsFromDirectory が削除され、 Kernel.ImportPluginFromPromptDirectoryに置き換えられました。
Kernel.CreateSemanticFunction が削除され、 Kernel.CreateFunctionFromPromptに置き換えられました。
- 引数: OpenAIRequestSettings は現在 OpenAIPromptExecutionSettings

コンテキスト変数

ContextVariables はKernelArguments として再定義され、ディクショナリになりました。ここで、キーは引数の名前、値は引数の値です。 SetやGetなどのメソッドが削除され、代わりに共通辞書 Add またはインデクサー []を使用して値を設定および取得する必要があります。

// Before
var variables = new ContextVariables("Today is: ");
variables.Set("day", DateTimeOffset.Now.ToString("dddd", CultureInfo.CurrentCulture));

// After
var arguments = new KernelArguments() {
  ["input"] = "Today is: ",
  ["day"] = DateTimeOffset.Now.ToString("dddd", CultureInfo.CurrentCulture)
};

// Initialize directly or use the dictionary indexer below
arguments["day"] = DateTimeOffset.Now.ToString("dddd", CultureInfo.CurrentCulture);

カーネルビルダー

KernelBuilder は、より直感的で使いやすくするために多くの変更が加えられました。また、.NET ビルダーのアプローチに合わせて簡単に、より一致するようにしました。

KernelBuilderの作成は、Kernel.CreateBuilder() メソッドを使用してのみ作成できるようになりました。

この変更により、任意のコードベースで KernelBuilder をより簡単かつ簡単に使用でき、複雑さとメンテナンスのオーバーヘッドを増やす複数の方法ではなく、ビルダーを使用する 1 つの主な方法が保証されます。
```
// Before
IKernel kernel = new KernelBuilder().Build();

// After
var builder = Kernel.CreateBuilder().Build();
```
KernelBuilder.With... の名前が KernelBuilder.Add... に変更されました。
- WithOpenAIChatCompletionService の名前が AddOpenAIChatCompletionService に変更されました。
- WithAIService<ITextCompletion>
KernelBuilder.WithLoggerFactory は使用されません。代わりに、依存関係挿入アプローチを使用してロガーファクトリを追加します。
```
IKernelBuilder builder = Kernel.CreateBuilder();
builder.Services.AddLogging(c => c.AddConsole().SetMinimumLevel(LogLevel.Information));
```
WithAIService<T> 依存関係の挿入

以前は、 KernelBuilder には削除されたメソッド WithAIService<T> があり、開発者が依存関係挿入コンテナーにサービスを追加できるように、新しい ServiceCollection Services プロパティが公開されていました。つまり、次のようになります。
```
builder.Services.AddSingleton<ITextGenerationService>()
```

カーネルの結果

カーネルがプラグインのコンテナーになり、1 つの関数だけを実行するようになったため、 KernelResult エンティティを持つ必要がなくなり、カーネルからのすべての関数呼び出しで FunctionResultが返されるようになりました。

SKContext

内部およびコミュニティからの多くの議論とフィードバックの後、API を簡素化し、より直感的にするために、 SKContext の概念はさまざまなエンティティ (関数入力用の KernelArguments と関数出力用の FunctionResult ) に表示されました。

Kernel関数呼び出しに必要な引数を作成する重要な決定により、SKContextが削除され、KernelArgumentsとFunctionResultが導入されました。

KernelArguments は、以前に SKContext.Variables プロパティに保持されていた関数呼び出しの入力引数を保持するディクショナリです。

FunctionResult は、 Kernel.InvokeAsync メソッドの出力であり、以前に SKContext.Result プロパティに保持されていた関数呼び出しの結果を保持します。

新しいプラグインの抽象化

KernelPlugin Entity: V1 より前には、プラグイン中心のエンティティの概念はありませんでした。これはV1で変更され、カーネルに追加するすべての関数に対して、それが属するプラグインを取得します。

プラグインの不変性

プラグインは既定で不変として、すぐに使用できる DefaultKernelPlugin 実装によって作成されます。つまり、作成後に変更または変更することはできません。

また、カーネル内で同じ名前を共有するプラグインをインポートしようとすると、キー違反の例外が発生します。

KernelPlugin抽象化を追加することで、可変性をサポートする可能性のある動的実装が可能になり、Example 69で変更可能なプラグインを実装する方法の例を示しました。

複数のプラグインを 1 つに結合する

ディレクトリからプラグインを作成し、同じプラグインのメソッド関数を後で追加しようとすると、両方のプラグインを個別に作成し、それらを単一のプラグインに組み合わせて関数を反復処理して、 kernel.ImportPluginFromFunctions("myAggregatePlugin", myAggregatedFunctions) 拡張機能を使用して最終的なプラグインに集約する別のアプローチを使用しない限り、機能しません。

試験的属性機能の使用。

この機能は、V1 で変更または完全に削除できる機能をマークするために導入されました。

モードの詳細については、現在リリースされている試験的機能の一覧ここで確認してください。

構成ファイルのプロンプト

プロンプト構成ファイルには、既定および複数のサービス/モデル構成を含む主要な変更が導入されました。

注意すべきその他の名前付けの変更:

completion の名前が execution_settings に変更されました。
input の名前が input_variables に変更されました。
defaultValue の名前が default に変更されました。
parameters の名前が input_variables に変更されました。

service_idに一致したexecution_settings内の各プロパティ名は、サービス/モデルの実行設定を構成するために使用されます。つまり、次のようになります。

// The "service1" execution settings will be used to configure the OpenAIChatCompletion service
Kernel kernel = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion(serviceId: "service1", modelId: "gpt-4")

以前

{
  "schema": 1,
  "description": "Given a text input, continue it with additional text.",
  "type": "completion",
  "completion": {
    "max_tokens": 4000,
    "temperature": 0.3,
    "top_p": 0.5,
    "presence_penalty": 0.0,
    "frequency_penalty": 0.0
  },
  "input": {
    "parameters": [
      {
        "name": "input",
        "description": "The text to continue.",
        "defaultValue": ""
      }
    ]
  }
}

After

{
  "schema": 1,
  "description": "Given a text input, continue it with additional text.",
  "execution_settings": {
    "default": {
      "max_tokens": 4000,
      "temperature": 0.3,
      "top_p": 0.5,
      "presence_penalty": 0.0,
      "frequency_penalty": 0.0
    },
    "service1": {
      "model_id": "gpt-4",
      "max_tokens": 200,
      "temperature": 0.2,
      "top_p": 0.0,
      "presence_penalty": 0.0,
      "frequency_penalty": 0.0,
      "stop_sequences": ["Human", "AI"]
    },
    "service2": {
      "model_id": "gpt-3.5_turbo",
      "max_tokens": 256,
      "temperature": 0.3,
      "top_p": 0.0,
      "presence_penalty": 0.0,
      "frequency_penalty": 0.0,
      "stop_sequences": ["Human", "AI"]
    }
  },
  "input_variables": [
    {
      "name": "input",
      "description": "The text to continue.",
      "default": ""
    }
  ]
}

Last updated on 2024-11-03