.NET AI と Machine Learning

入力

入力	必須	説明
タスク説明	はい	AI/ML機能が達成すべき内容（例：「サポートチケットの分類」、「ドキュメントの要約」）
データ説明	はい	入力データの種類と形状（構造化/表形式、非構造化テキスト、画像、混合）
デプロイ制約	いいえ	クラウド対ローカル、レイテンシ SLO、予算、オフライン要件
既存プロジェクトコンテキスト	いいえ	現在の .csproj、既存パッケージ、ターゲットフレームワーク

ワークフロー

ステップ 1: 決定木を使用してタスクを分類する

開発者のタスクを以下の決定木に照らし合わせて評価し、適切なテクノロジーを選択します。どのブランチが適用されるか、そしてその理由を述べます。

タスク種別	テクノロジー	根拠
構造化/表形式データ：分類、回帰、クラスタリング、異常検出、推奨	ML.NET (Microsoft.ML)	再現性がある（固定シード とデータセットが与えられた場合）、クラウド依存なし、これらのタスク向けの専門的モデル
自然言語理解、生成、要約、非構造化テキストに対する推論（単一プロンプト → レスポンス、ツール呼び出しなし）	Microsoft.Extensions.AI 経由の LLM (IChatClient)	パターンマッチングを超えた言語モデル機能が必要、オーケストレーション不要
エージェンティックワークフロー：ツール/関数呼び出し、複数ステップの推論、エージェントループ、マルチエージェント協調	Microsoft Agent Framework (Microsoft.Agents.AI) を Microsoft.Extensions.AI 上に構築	オーケストレーション、ツール振り分け、イテレーション制御、ガードレールが必要（IChatClient だけでは提供されない）
GitHub Copilot 拡張機能、カスタムエージェント、または開発者ワークフローツールの構築	GitHub Copilot SDK (GitHub.Copilot.SDK)	Copilot エージェントランタイムと統合し、IDE および CLI 拡張性を提供
本番環境で事前学習済みまたはファインチューニング済みのカスタムモデルを実行	ONNX Runtime (Microsoft.ML.OnnxRuntime)	ハードウェアアクセラレーション推論、モデルフォーマット非依存
クラウド依存のないローカル/オフライン LLM 推論	OllamaSharp と Ollama でサポートされているローカル AI モデル	プライバシーに敏感、エアギャップ、またはコスト制限のあるシナリオ
セマンティック検索、RAG、またはエンベディング保存	Microsoft.Extensions.VectorData.Abstractions + ベクトル データベース プロバイダー（例：Azure AI Search、Milvus、MongoDB、pgvector、Pinecone、Qdrant、Redis、SQL）	プロバイダー非依存の抽象化によるベクトル類似度検索、データベース固有のコネクタパッケージと組み合わせ（多くはコミュニティツールキットに移行中）
ドキュメントをベクトルストアに取り込む、チャンク化、ロードする	Microsoft.Extensions.AI.DataIngestion (プレビュー) + Microsoft.Extensions.VectorData.Abstractions (MEVD)	ドキュメント解析、テキストチャンキング、エンベディング生成、ベクトルデータベースへのアップサートを処理、Microsoft.Extensions.VectorData.Abstractions と組み合わせ
構造化 ML 予測と自然言語推論の両方	ハイブリッド：予測用 ML.NET + 推論レイヤー用 LLM	疎結合を保つ、ML.NET が再現可能なスコアリングを処理、LLM が説明を追加

重要ルール： ML.NET が得意なタスク（表形式データの分類、回帰、クラスタリング）に LLM を使用しないでください。LLM はこれらのタスクではより遅く、より高価で、非決定的です。

ステップ 1b: 正しいライブラリレイヤーを選択する

タスクタイプを特定した後、適切なライブラリレイヤーを選択します。これらのライブラリはスタックを形成し、各レイヤーは下のレイヤーの上に構築されます。間違ったレイヤーの使用は、非決定的なエージェント動作の主要な原因です。

レイヤー	ライブラリ	NuGet パッケージ	使用時期
抽象化	Microsoft.Extensions.AI (MEAI)	Microsoft.Extensions.AI	チャット、エンベディング、またはツール呼び出しのプロバイダー非依存インターフェースが必要な場合。これは基盤です — 常に含めてください。IChatClient を直接使用するのは、ツール呼び出しやエージェントループのない簡単なプロンプト入出力シナリオのみです。タスクがツール、エージェント、または複数ステップの推論を含む場合、上記のオーケストレーションレイヤーを追加する必要があります。
プロバイダー SDK	OpenAI、Azure.AI.OpenAI、Azure.AI.Inference、OllamaSharp	OpenAI、Azure.AI.OpenAI、Azure.AI.Inference、OllamaSharp	具体的な LLM プロバイダー実装が必要な場合。これらは AddChatClient 経由で MEAI にワイヤリングされます。直接 OpenAI アクセスの場合は OpenAI を、Azure OpenAI の場合は Azure.AI.OpenAI を、Azure AI Foundry / GitHub Models の場合は Azure.AI.Inference を、ローカル Ollama の場合は OllamaSharp を使用します。MEAI で公開されていないプロバイダー固有機能が必要な場合のみ直接使用します。
オーケストレーション	Microsoft Agent Framework	Microsoft.Agents.AI (プレリリース)	タスクにツール/関数呼び出し、エージェントループ、複数ステップの推論、マルチエージェント協調、持続的コンテキスト、またはグラフベースワークフローが含まれる場合。シナリオがエージェントまたはツールを含む場合は必須 — IChatClient でツール振り分けループを手書きしないでください。 MEAI の上に構築されます。注： このパッケージは現在プレリリース段階です — インストールするには dotnet add package Microsoft.Agents.AI --prerelease を使用してください。
Copilot 統合	GitHub Copilot SDK	GitHub.Copilot.SDK	GitHub Copilot ランタイムと統合する拡張機能またはツールを構築している場合 — カスタムエージェント、IDE 拡張機能、または Copilot エージェントプラットフォームを活用する開発者ワークフロー自動化。

ライブラリ選択の決定ルール

1. MEAI で開始します。 すべての AI 統合は Microsoft.Extensions.AI で IChatClient / IEmbeddingGenerator 抽象化を使用します。これはプロバイダースワップ可能性とテスト可能性を確保します。

2. プロバイダー SDK を追加します (OpenAI、Azure.AI.OpenAI) として MEAI の背後にある具体的実装として。ビジネスロジックでプロバイダー SDK を直接呼び出さないでください — 常に MEAI 抽象化を経由してください。

3. ツールまたはエージェントを含むタスクには Agent Framework (Microsoft.Agents.AI) を使用します。 タスクがツール呼び出しのない単一プロンプト → レスポンスの場合、MEAI で十分です。以下のいずれかが適用される場合必ず Microsoft.Agents.AI を使用してください：

   • ツール/関数呼び出し（エージェントが呼び出すツールを決定）
   • ターン間で状態が保持される複数ステップの推論
   • 目標に達成するまでイテレーションするエージェントループ
   • ハンドオフプロトコルを備えたマルチエージェント協調
   • グラフベースまたは持続的ワークフロー

   これらのパターンを IChatClient で手書きで実装しないでください — Agent Framework はイテレーション制限、観測可能性、再実装するには誤りやすいツール振り分けを提供します。

4. Copilot 拡張機能を構築する場合のみ Copilot SDK を追加します。 目的が GitHub Copilot プラットフォーム（CLI、IDE、または Copilot Chat）内で実行されるカスタムエージェントまたはツールの構築である場合、GitHub.Copilot.SDK を使用します。これは一般的な LLM オーケストレーションライブラリではなく、Copilot 拡張性専用です。

5. レイヤーをスキップしないでください。 MEAI なしで Agent Framework を使用しないでください。MEAI と同じワークフロー内で HttpClient を使用して OpenAI に呼び出さないでください。各レイヤーは下のレイヤーに依存します。

ステップ 2: パッケージを選択してプロジェクトをセットアップする

選択したテクノロジーブランチに必要なパッケージのみをインストールします。競合する抽象化を混在させないでください。

クラシック ML パッケージ

<PackageReference Include="Microsoft.ML" Version="4.*" />
<PackageReference Include="Microsoft.ML.AutoML" Version="0.*" />
<!-- カスタム数値作業が必要な場合のみ: -->
<PackageReference Include="System.Numerics.Tensors" Version="10.*" />
<PackageReference Include="MathNet.Numerics" Version="5.*" />
<!-- データ探索用のみ: -->
<PackageReference Include="Microsoft.Data.Analysis" Version="0.*" />

使用しないでください Accord.NET — アーカイブされており保守されていません。

最新 AI パッケージ

<!-- 常に抽象化レイヤーで開始 -->
<PackageReference Include="Microsoft.Extensions.AI" Version="9.*" />

<!-- オーケストレーション（エージェント、ワークフロー、ツール、メモリ） — プレリリース; dotnet add package Microsoft.Agents.AI --prerelease を使用 -->
<PackageReference Include="Microsoft.Agents.AI" Version="1.*-*" />

<!-- クラウド LLM プロバイダー（1つ選択） -->
<PackageReference Include="Azure.AI.OpenAI" Version="2.*" />
<!-- または -->
<PackageReference Include="OpenAI" Version="2.*" />

<!-- クライアント側トークンカウント（コスト管理用） -->
<PackageReference Include="Microsoft.ML.Tokenizers" Version="2.*" />

<!-- ローカル LLM 推論 -->
<PackageReference Include="OllamaSharp" Version="5.*" />

<!-- カスタムモデル推論 -->
<PackageReference Include="Microsoft.ML.OnnxRuntime" Version="1.*" />

<!-- ベクトルストア抽象化 -->
<PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.*" />

<!-- ドキュメント取り込み、チャンキング、ベクトルストア読み込み（プレビュー） -->
<PackageReference Include="Microsoft.Extensions.AI.DataIngestion" Version="9.*-*" />

<!-- Copilot プラットフォーム拡張性 -->
<PackageReference Include="GitHub.Copilot.SDK" Version="1.*" />

スタック一貫性ルール： 生 SDK 呼び出し（OpenAI への HttpClient）を Microsoft.Extensions.AI、Microsoft Agent Framework、または同じワークフロー内の Copilot SDK と混在させないでください。ワークフロー境界ごとに 1 つの抽象化レイヤーを選択し、コミットしてください。ステップ 1b のレイヤリングルールを参照してください。

依存性注入でサービスを登録する

すべての AI/ML サービスは DI 経由で登録する必要があります。ビジネスロジックでクライアントを直接インスタンス化しないでください。

// IOptions<T> 経由の設定
services.Configure<AiOptions>(configuration.GetSection("AI"));

// 抽象化経由で AI クライアントを登録
services.AddChatClient(builder => builder
    .UseOpenAIChatClient("gpt-4o-mini-2024-07-18"));

ステップ 3: ガードレールで実装する

選択したテクノロジーブランチのガードレールを適用します。生成されたすべての実装は以下のルールに従う必要があります。

クラシック ML ガードレール

1. 再現性：ML コンテキストで常にランダムシードを設定します：

   var mlContext = new MLContext(seed: 42);
   

2. データ分割：常に train/test（およびオプションで検証）に分割します。トレーニングデータで評価しないでください：

   var split = mlContext.Data.TrainTestSplit(data, testFraction: 0.2);
   

3. メトリクスログ：常にタスクに適切な評価メトリクスを計算およびログします：

   var metrics = mlContext.BinaryClassification.Evaluate(predictions);
   logger.LogInformation("AUC: {Auc:F4}, F1: {F1:F4}", metrics.AreaUnderRocCurve, metrics.F1Score);
   

4. AutoML 優先：初期モデル選択に mlContext.Auto() を推奨し、その後手動で改善します。

5. PredictionEngine プーリング：ASP.NET Core では、常にプール済み予測エンジンを使用します — シングルトンは不可：

   services.AddPredictionEnginePool<ModelInput, ModelOutput>()
       .FromFile(modelPath);
   

LLM 統合ガードレール

1. 温度：常に明示的に設定します。事実/決定的なタスクでは 0 を使用します：

   var options = new ChatOptions
   {
       Temperature = 0f,
       MaxOutputTokens = 1024,
   };
   

2. 構造化出力：常に LLM 出力を強く型付けされたオブジェクトにパースし、フォールバック処理を行います：

   var result = await chatClient.GetResponseAsync<MySchema>(prompt, options, cancellationToken);
   

3. リトライロジック：常に指数バックオフでリトライを実装します：

   services.AddChatClient(builder => builder
       .UseOpenAIChatClient(modelId)
       .Use(new RetryingChatClient(maxRetries: 3)));
   

4. コスト制御：常にトークン使用量を推定してログします。リクエストを送信する前に Microsoft.ML.Tokenizers を使用してクライアント側でトークンをカウントし、予算を予防的に強制できるようにします。品質要件を満たす最小モデルティアを選択します（例：gpt-4o-mini を gpt-4o の前に）。

5. シークレット管理：API キーをハードコードしないでください。Azure Key Vault、ユーザーシークレット、または環境変数を使用します：

   var apiKey = configuration["AI:ApiKey"]
       ?? throw new InvalidOperationException("AI:ApiKey not configured");
   

6. モデルバージョンピン止め：動作のドリフトを減らすため正確なモデルバージョンを指定します：

   // 単に "gpt-4o" ではなく、特定の日付付きバージョンにピン止め
   var modelId = "gpt-4o-2024-08-06";
   

エージェンティックワークフロー ガードレール

0. すべてのエージェンティックワークフローで Microsoft.Agents.AI を使用します。 IChatClient でツール振り分けループまたは複数ステップのエージェント推論を手で実装しないでください。Agent Framework は ChatClientAgent（または AgentWorker）を提供し、ツール呼び出し → 結果 → 再プロンプトサイクルを組み込みガードレールで処理します。以下のすべてのルールは Microsoft.Agents.AI を使用していることを前提としています。

1. イテレーション制限：エージェントループの暴走実行を防ぐため常にキャップします：

   var settings = new AgentInvokeOptions
   {
       MaximumIterations = 10,
   };
   

2. コスト上限：実行あたりのトークン予算を実装し、到達時に終了します。Microsoft.ML.Tokenizers を使用してプロンプトと完了トークンをローカルでカウント、各イテレーション前に予算と比較します。

3. 観測可能性：エージェント ステップごとに非機密メタデータをログに記録します。生の message.Content をログに記録しないでください — ユーザープロンプト、ツール出力、シークレット、または PII が含まれる可能性があり、集中ロギングシステムにプレーンテキストで保持されます：

   await foreach (var message in agent.InvokeStreamingAsync(history, settings))
   {
       logger.LogDebug("Agent step: Role={Role}, ContentLength={Length}",
           message.Role, message.Content?.Length ?? 0);
   }
   

4. ツールスキーマ：明示的なツール/関数スキーマを説明と共に定義します。暗黙的なツール検出に頼らないでください。

5. シンプリティ優先：マルチエージェントが必要でない限り、単一エージェント with ツールを推奨します。

RAG ガードレール

1. エンベディングキャッシング：クエリのたびに同じコンテンツを再エンベディングしないでください。エンベディングをベクトルストアにキャッシュします。

2. チャンキング戦略：固定サイズチャンキングではなくセマンティックチャンキング（段落/セクション境界で分割）を使用します。チャンク自体で有用なコンテキストを確保します。

3. 関連性閾値：低関連性チャンクをコンテキストに挿入しないでください。最小類似度スコアを設定します：

   var results = await vectorStore.SearchAsync(query, new VectorSearchOptions
   {
       Top = 5,
       MinimumScore = 0.75f,
   });
   

4. 出典帰属：どのチャンクが最終レスポンスに貢献したかを追跡します。出力に出典参照を含めます。

5. バッチエンベディング：可能な限りエンベディング API 呼び出しをバッチし、レイテンシとコストを削減します。

ステップ 4: 非決定性を処理する

ソリューションが LLM 呼び出しまたはエージェンティックワークフローを含む場合、非決定性を明示的に対処します：

1. 認識する：LLM 出力は温度 0 でも非決定的である（バッチ、量子化、モデル更新による）ことを開発者に知らせます。

2. 出力を検証する：すべての LLM レスポンスに対してスキーマ検証とコンテンツ主張チェックを実装します。

3. グレースフルデグラデーション：LLM が予期しない、不正形式、または空の出力を返す場合のフォールバックパスを設計します：

   var response = await chatClient.GetResponseAsync<ClassificationResult>(prompt, options);
   if (response is null || !response.IsValid())
   {
       logger.LogWarning("LLM returned invalid response, falling back to rule-based classifier");
       return ruleBasedClassifier.Classify(input);
   }
   

4. 評価ハーネス：イテレーション対象のプロンプトについて、黄金データセットと評価スキャフォルドを作成し、時系列でプロンプト品質を測定することを推奨します。

5. モデルバージョンピン止め：特定の日付付きモデルバージョン（例：gpt-4o-2024-08-06）にピン止めし、デプロイ間のドリフトを削減します。

ステップ 5: パフォーマンスとコスト制御を適用する

1. 接続プーリング：すべての外部サービスに IHttpClientFactory と DI 管理クライアントを使用します。

2. レスポンスキャッシング：繰り返されるまたは同様のクエリをキャッシュします。適切な場合、LLM レスポンスのセマンティックキャッシングを検討します。

3. ストリーミング：ユーザー向けシナリオで LLM レスポンスに IAsyncEnumerable を使用し、最初のトークンまでの時間を削減します：

   await foreach (var update in chatClient.GetStreamingResponseAsync(prompt, options))
   {
       yield return update.Text;
   }
   

4. ヘルスチェック：外部 AI サービス依存関係のヘルスチェックを実装します：

   services.AddHealthChecks()
       .AddCheck<OpenAIHealthCheck>("openai");
   

5. ML.NET 予測プーリング：Web アプリケーションでは、常に PredictionEnginePool<TIn, TOut> を使用してください。単一の PredictionEngine インスタンスは不可（スレッドセーフではない）です。

ステップ 6: 実装を検証する

1. プロジェクトを構築し、警告がないことを確認します：

   dotnet build -c Release -warnaserror
   

2. テストを実行します（AI/ML 動作を検証する統合テストを含む）：

   dotnet test -c Release
   

3. ML.NET パイプラインについては、評価メトリクスがプロジェクトの品質バーを満たし、モデルが正しくシリアライズおよび読み込み可能であることを確認します。

4. LLM 統合については、構造化出力パースが有効な応答と不正形式の応答の両方を処理することを確認します。

5. RAG パイプラインについては、取得が関連結果を返し、無関係なチャンクがフィルタリングされることを確認します。

検証

• テクノロジー選択が決定木に従う — LLM は ML.NET が処理するタスクに使用されない
• すべての AI/ML サービスが依存性注入で登録されている
• 設定が IOptions<T> パターンを使用 — ハードコード値なし
• API キーが安全なソースから読み込まれている — ソースコードまたはコミット済み設定ファイルにない
• ML.NET パイプラインがランダムシードを設定し、評価用にデータを分割している
• LLM 呼び出しが温度、最大トークン、リトライロジックを明示的に設定している
• エージェンティックワークフローがイテレーション制限とコスト上限を設定している
• RAG パイプラインがチャンキング、関連性閾値、出典帰属を実装している
• 非決定的出力が検証とフォールバックパスを備えている
• dotnet build -c Release -warnaserror がクリーンに完了する

避けるべきアンチパターン

コードをレビューまたは生成するとき、以下のパターンが検出されたら、フラグを立てて開発者をリダイレクトします：

アンチパターン	リダイレクト
構造化/表形式データの分類に LLM を使用	代わりに ML.NET を使用 — より高速、安価、決定的
リトライまたはタイムアウトロジックなしで LLM API を呼び出す	RetryingChatClient または Polly ベースのリトライを指数バックオフで追加
ソースコントロールにコミット済みの appsettings.json に API キーを保存	ユーザーシークレット（開発）、環境変数、または Azure Key Vault（本番）を使用
新規プロジェクトで Accord.NET を使用	ML.NET に移行 — Accord.NET はアーカイブされており保守されていない
.NET でカスタムニューラルネットワークをゼロから構築	ONNX Runtime 経由で事前学習済みモデルを使用するか、LLM API を呼び出す
チャンキング戦略または関連性フィルタリングなしの RAG	セマンティックチャンキングを実装し、最小類似度スコア閾値を設定
イテレーション制限またはコスト上限のないエージェントループ	MaximumIterations とトークン予算上限を追加
MEAI IChatClient を同じプロバイダーへの生 HttpClient 呼び出しと一緒に使用	1 つの抽象化レイヤーを選択しコミット
Microsoft.Agents.AI の代わりに IChatClient でツール呼び出しまたはエージェントループを手で実装	Microsoft.Agents.AI を使用 — イテレーション制限（MaximumIterations）、組み込みツール振り分け、観測可能性フック、コスト制御を提供。手書きループはこれらのガードレールを欠いている
単一プロンプト→レスポンス呼び出しに Agent Framework を使用	MEAI IChatClient を直接使用 — Agent Framework は複数ステップオーケストレーション用
一般的 LLM アプリに Copilot SDK を使用	Copilot SDK は Copilot プラットフォーム拡張専用 — スタンドアロンアプリには MEAI + Agent Framework を使用
ビジネスロジックで MEAI を通さず直接 OpenAI SDK を呼び出す	AddChatClient 経由でプロバイダーを登録し、ビジネスコードで IChatClient に依存
ASP.NET Core でシングルトンとして PredictionEngine を使用	PredictionEnginePool<TIn, TOut> を使用 — PredictionEngine はスレッドセーフではない
ref struct パラメータを持つデリゲートに Func<ReadOnlySpan<T>> を使用	カスタムデリゲート型を定義 — ref struct はジェネリック型引数になれない
新規プロジェクトで Microsoft.SemanticKernel を使用	Microsoft.Extensions.AI + Microsoft.Agents.AI を使用 — Semantic Kernel は LLM オーケストレーションとツール呼び出しのこれらの新しい抽象化で置き換えられた

一般的な落とし穴

落とし穴	ソリューション
LLM でのエンジニアリング過剰	最もシンプルなアプローチ（ルール、ML.NET）で開始し、シンプルな方法が不十分な場合のみ LLM 機能を追加
トレーニングデータで ML モデルを評価	常に TrainTestSplit を使用し、ホールドアウトテストセットでメトリクスを報告
デプロイ間での LLM 出力ドリフト	特定の日付付きモデルバージョン（例：gpt-4o-2024-08-06）にピン止め
トークンコスト（予期しない出費）	MaxOutputTokens を設定、トークンカウント用 Microsoft.ML.Tokenizers を使用、リクエストあたりトークンをログ、予算閾値でアラート
再現不可能な ML トレーニング	MLContext(seed: N) を設定し、コードと並んでトレーニングデータをバージョニング
RAG が無関係コンテキストを返す	最小類似度スコアを設定し、注入チャンク数を制限
ML.NET モデルのコールドスタートレイテンシ	アプリケーション起動中に PredictionEnginePool をプレウォーム
同じクラスに Microsoft Agent Framework + 生 OpenAI SDK を使用	ワークフロー境界ごとに 1 つのオーケストレーションレイヤーを選択