Azure Cosmos DBのEmbeddingGenerator更新でまず押さえるべき結論は、.NET SDKプレビューにICosmosEmbeddingGeneratorをクライアント全体で設定するための公開APIが追加されたものの、現時点ではクエリ実行時に自動で埋め込みを生成する実行処理はまだ接続されていないという点です。つまり、すぐに本番クエリの動作が変わる更新ではありません。開発者や管理者が今やるべきことは、プレビューSDKの採用判断、ベクトル検索・ハイブリッド検索の設計、埋め込み生成処理の責務分担、認証・リトライ・コスト管理を事前に確認することです。(GitHub)
Azure Cosmos DB EmbeddingGenerator更新の要点
今回の「EmbeddingGenerator: Adds ICosmosEmbeddingGenerator client-wide configuration (preview)」は、Azure Cosmos DB .NET SDK v3系のプレビュー機能として、V0のquery-time embedding generationに向けた公開APIの土台を追加する更新です。PRは2026年5月19日にmainへマージされ、changelog上ではUnreleasedのFeatures Addedとして記載されています。(GitHub)
重要なのは、APIの入口だけが先に追加されたという点です。PR本文でも、今回の変更は「public surface only」であり、pipeline resolverやbindingは後続PRで入ると説明されています。したがって、WithEmbeddingGenerator()でgeneratorを設定しても、現時点のこの変更だけでGenerateEmbeddings(...)を含むクエリが自動的に埋め込み生成されるわけではありません。(GitHub)
実務上は、次のように理解すると判断しやすくなります。
| 観点 | 今回できるようになること | まだ期待しないほうがよいこと |
|---|---|---|
| SDK設計 | ICosmosEmbeddingGeneratorの実装クラスを用意し、CosmosClient単位で設定する準備 | クエリ実行時にSDKが自動で埋め込みAPIを呼ぶ完全な実行パス |
| 本番影響 | 通常のAzure Cosmos DBクエリや既存のベクトル検索には直接影響しにくい | 既存アプリの検索結果やRU消費が即座に変わること |
| 開発者対応 | preview APIのコンパイル確認、実装方針の整理、テスト設計 | GA相当の安定APIとして長期運用前提で固定すること |
| 管理者対応 | SDKバージョン、プレビュー採用ポリシー、認証情報、コスト監視の準備 | すぐに運用ルールを全面変更すること |
追加された主な公開API
今回の更新では、Azure Cosmos DB .NET SDKにEmbeddingGenerator関連の公開面が追加されています。中心になるのは、ICosmosEmbeddingGenerator、CosmosEmbeddingResult、CosmosClientOptions.EmbeddingGenerator、CosmosClientBuilder.WithEmbeddingGenerator()、CosmosClient.EmbeddingGeneratorです。(GitHub)
ICosmosEmbeddingGenerator
ICosmosEmbeddingGeneratorは、クエリに含まれるテキストからfloat32のベクトル埋め込みを生成するための契約です。メソッドは、入力テキストのリスト、埋め込みサービスのendpoint、deploymentName、dimensions、CancellationTokenを受け取り、CosmosEmbeddingResultを返します。(GitHub)
代表的なシグネチャは次の形です。
public interface ICosmosEmbeddingGenerator
{
Task<CosmosEmbeddingResult> GenerateEmbeddingsAsync(
IReadOnlyList<string> texts,
string endpoint,
string deploymentName,
int dimensions,
CancellationToken cancellationToken = default);
}この設計から分かるポイントは、Azure Cosmos DB SDK本体が特定の埋め込みプロバイダーに固定されるのではなく、利用者側がAzure OpenAIなどのサービスを呼び出す実装を差し込める余地を持たせていることです。
CosmosEmbeddingResult
CosmosEmbeddingResultは、生成されたベクトルと補助的な診断情報を返すための型です。Vectorsには入力テキストと同じ順序でReadOnlyMemory<float>のベクトルが入り、任意でTotalTokensとLatencyを持てます。PR上のコメントでは、これらの診断情報は将来的にCosmosDiagnosticsへ表面化する想定が示されています。(GitHub)
実装時に特に重要なのは、入力テキスト数と返却ベクトル数を一致させること、そして各ベクトルの次元数をdimensionsに合わせることです。ここがずれると、ベクトル検索の精度低下だけでなく、実行時エラーや期待しないクエリ失敗につながります。
クライアント全体の設定
EmbeddingGeneratorは、CosmosClientBuilderまたはCosmosClientOptionsからクライアント全体の既定設定として指定できます。PRでは次のような設定例が示されています。(GitHub)
var client = new CosmosClientBuilder(endpoint, credential)
.WithEmbeddingGenerator(myGenerator)
.Build();
ICosmosEmbeddingGenerator current = client.EmbeddingGenerator;または、CosmosClientOptionsで指定します。
var client = new CosmosClient(endpoint, key, new CosmosClientOptions
{
EmbeddingGenerator = myGenerator,
});この設定は「client-wide」、つまりCosmosClientインスタンス全体に対する設定です。複数のContainerやクエリで同じCosmosClientを共有しているアプリでは、どのクエリにgeneratorが適用される設計になるのかを、後続の実行パイプライン実装が公開された時点で必ず確認してください。
現時点で変わらないこと
今回のAzure Cosmos DB EmbeddingGenerator更新は、既存のAzure Cosmos DBアカウント、コンテナー、ベクトルインデックス、保存済みベクトルデータを直接変更するものではありません。
すでにアプリ側で次のような処理をしている場合、今回のPRだけで処理を置き換える必要はありません。
- ユーザーの検索語をアプリ側でAzure OpenAIなどに送り、埋め込みを生成する
- 生成したベクトルを
VectorDistanceのパラメーターとして渡す - 事前に文書の埋め込みを生成し、Azure Cosmos DBのアイテム内に保存する
- 既存のベクトルインデックスやハイブリッド検索用の設計を運用している
Azure Cosmos DBのベクトル検索では、コンテナーのvector embedding policyやvector indexing policy、VectorDistance関数を使って類似検索を行います。公式ドキュメントでも、ベクトル検索の前提として、ベクトル埋め込みの作成、ベクトルパスの指定、ベクトルインデックスの設定が説明されています。(Microsoft Learn)
今回の変更は、その検索クエリ時点で「検索語からベクトルを生成する処理」をSDK側に組み込むための準備段階と見るのが自然です。
対象になる開発者・管理者
今回の更新を追うべきなのは、主にAzure Cosmos DB for NoSQLでベクトル検索、ハイブリッド検索、RAG、AIエージェントのメモリ検索を実装しているチームです。
特に次の立場の人は確認しておく価値があります。
| 対象者 | 確認すべき理由 |
|---|---|
| .NET開発者 | preview SDKでICosmosEmbeddingGeneratorの実装やDI登録方針を検討する必要がある |
| AIアプリ開発者 | クエリ時の埋め込み生成をアプリ側で行うか、SDKの仕組みに寄せるかを判断する必要がある |
| Azure管理者 | 埋め込み生成サービスのendpoint、認証方式、キー管理、コスト監視を設計する必要がある |
| SRE・運用担当 | 将来的に検索クエリが外部AIサービス呼び出しを伴う場合、レイテンシや障害影響を監視する必要がある |
| セキュリティ担当 | 検索語、埋め込みベクトル、認証情報がログや診断に残らないよう確認する必要がある |
逆に、Azure Cosmos DBを通常のドキュメントDBとして使っているだけのアプリ、ベクトル検索を使っていないアプリ、.NET SDKプレビューを採用していないアプリでは、すぐに対応が必要になる可能性は低いです。
実装前に確認したい設定項目
EmbeddingGeneratorは、単にクラスを1つ実装すれば終わりではありません。クエリ時に埋め込み生成が実行されるようになると、検索処理の中にAIモデル呼び出し、認証、ネットワーク、課金、リトライが入ります。設計を誤ると、検索の遅延やコスト増、障害時の連鎖失敗が起きやすくなります。
| 確認項目 | 判断基準 | 失敗しやすいポイント |
|---|---|---|
| SDKバージョン | ICosmosEmbeddingGeneratorが含まれるpreviewパッケージか確認する | changelogでは#5838がUnreleased扱いのため、既存previewに含まれると決めつける |
| endpoint | Azure OpenAIなど、埋め込み生成先のエンドポイントを環境別に管理する | 開発・本番で同じendpointやキーを使い回す |
| deploymentName | コンテナーのベクトルポリシーと同じモデル系列を使う | 保存済みベクトルと検索語ベクトルで異なるモデルを使う |
| dimensions | VectorEmbeddingPolicyのdimensionsと一致させる | モデルの既定次元を返してしまい、コンテナー側の次元とずれる |
| スレッド安全性 | 1つのgeneratorインスタンスが並列に呼ばれても壊れない設計にする | mutableな状態をインスタンス変数に持ち、並列クエリで競合する |
| リトライ | 埋め込みサービス側の429、5xx、ネットワーク障害を実装側で扱う | Cosmos DB SDK側のリトライにすべて任せられると誤解する |
| キャンセル | CancellationTokenをHTTP呼び出しへ渡す | 呼び出しがキャンセルされず、タイムアウト後も外部APIが動き続ける |
| 診断 | latency、token数、エラー種別を観測できるようにする | 検索語やベクトルをそのままログに出す |
| リソース解放 | HttpClientやSDKクライアントのライフサイクルを管理する | Cosmos DB SDKがgenerator内部のリソースまでDisposeすると誤解する |
PR上のICosmosEmbeddingGeneratorコメントでは、実装はスレッドセーフであること、リトライや認証は実装側の責任であること、SDKはgeneratorインスタンスを保持するが破棄しないことが示されています。(GitHub)
ICosmosEmbeddingGenerator実装時の考え方
実装クラスでは、少なくとも次の条件を満たすように設計します。
public sealed class MyEmbeddingGenerator : ICosmosEmbeddingGenerator
{
public async Task<CosmosEmbeddingResult> GenerateEmbeddingsAsync(
IReadOnlyList<string> texts,
string endpoint,
string deploymentName,
int dimensions,
CancellationToken cancellationToken = default)
{
if (texts is null)
{
throw new ArgumentNullException(nameof(texts));
}
var startedAt = DateTimeOffset.UtcNow;
// ここでAzure OpenAIなどの埋め込み生成サービスを呼び出す
// endpoint、deploymentName、dimensions、cancellationTokenを必ず反映する
IReadOnlyList<ReadOnlyMemory<float>> vectors = await GenerateWithProviderAsync(
texts,
endpoint,
deploymentName,
dimensions,
cancellationToken);
if (vectors.Count != texts.Count)
{
throw new InvalidOperationException("入力テキスト数と返却ベクトル数が一致していません。");
}
foreach (ReadOnlyMemory<float> vector in vectors)
{
if (vector.Length != dimensions)
{
throw new InvalidOperationException("返却ベクトルの次元数が要求値と一致していません。");
}
}
return new CosmosEmbeddingResult(
vectors,
totalTokens: null,
latency: DateTimeOffset.UtcNow - startedAt);
}
}このコードは考え方を示すための例です。実際には、利用する埋め込みサービスのSDK、認証方式、レート制限、バッチ上限、例外型に合わせて実装します。
ポイントは、dimensionsを無視しないことです。Azure Cosmos DBのベクトルポリシーでは、ベクトルのpath、data type、dimensions、distance functionが重要な設定になります。公式ドキュメントでも、dimensionsは各ベクトルの長さを示す設定として説明されています。(Microsoft Learn)
また、PRのコメントでは、保存側のVectorDataTypeがUint8、Int8、Float16であっても、query-time vectorsはfloat32として送られる説明があります。generator実装側は、保存データの量子化形式に合わせて勝手にint8などを返すのではなく、契約どおりfloat32ベクトルを返す前提で設計します。(GitHub)
既存のベクトル検索設計との関係
Azure Cosmos DBでベクトル検索を行う基本は、これまでどおりです。文書側に埋め込みベクトルを保存し、コンテナーにvector embedding policyとvector indexを設定し、クエリでVectorDistanceを使います。Microsoft Learnでは、ベクトルインデックスにより低レイテンシ、高スループット、RU消費削減が期待できること、またflat、quantizedFlat、diskANNといったindex typeが説明されています。(Microsoft Learn)
今回のEmbeddingGeneratorは、特に「検索語をベクトル化してからクエリする」部分に関係します。従来はアプリ側で次のように処理していました。
float[] embedding = await embeddingService.CreateEmbeddingAsync("food recipe");
var queryDef = new QueryDefinition(
"SELECT TOP 10 c.title, VectorDistance(c.contentVector, @embedding) AS score " +
"FROM c ORDER BY VectorDistance(c.contentVector, @embedding)")
.WithParameter("@embedding", embedding);将来的にquery-time embedding generationが実行パイプラインに組み込まれると、アプリ側で明示的にベクトル化するコードの一部をSDK側の仕組みに寄せられる可能性があります。ただし、今回のPR時点ではまだその実行処理は接続されていないため、既存の手動埋め込み生成フローを急いで削除するのは避けるべきです。
移行・展開時の注意点
今回の更新を受けて、すぐに本番移行するというより、まずは将来の変更に備えて設計を整理する段階です。
preview SDKを本番へ入れる前に確認する
今回のAPIはpreview surfaceです。changelogでは#5838がUnreleasedに置かれており、2026年5月18日の3.61.0-preview.0には別の機能追加が並んでいます。つまり、利用時点でどのNuGetパッケージに含まれているかを必ず確認する必要があります。(GitHub)
確認手順は次の順で進めると安全です。
| 手順 | 確認内容 |
|---|---|
| 依存関係の確認 | Microsoft.Azure.Cosmosのバージョンとpreview採用可否を確認する |
| コンパイル確認 | ICosmosEmbeddingGenerator、CosmosEmbeddingResult、WithEmbeddingGenerator()が参照できるか確認する |
| 単体テスト | 入力件数、出力件数、ベクトル次元、キャンセル、例外処理をテストする |
| 結合テスト | 実際の埋め込みサービスを呼ばず、モックgeneratorでSDK設定だけを検証する |
| 本番判断 | runtime behaviorが実装された後、リリースノートと公式ドキュメントを再確認する |
既存の手動ベクトル化処理は残しておく
すでにアプリ側で埋め込みを生成してVectorDistanceに渡している場合、今回の更新だけを理由にその処理を削除しないでください。現時点で必要なのは、将来的な移行に備えて、埋め込み生成処理をサービスクラスとして切り出し、ICosmosEmbeddingGeneratorにも流用しやすい形に整理することです。
たとえば、次のように分けておくと移行しやすくなります。
| レイヤー | 役割 |
|---|---|
EmbeddingProvider | Azure OpenAIなど外部サービスを呼ぶ低レベル処理 |
ICosmosEmbeddingGenerator実装 | Cosmos DB SDKの契約に合わせて入力・出力を変換する処理 |
| 検索サービス | ユーザー入力、フィルター、TOP N、結果整形を扱う処理 |
| 設定管理 | endpoint、deploymentName、dimensions、認証情報を環境ごとに管理する処理 |
この分離をしておくと、SDK側の実行パイプラインが後続リリースで実装された場合でも、既存の埋め込み生成ロジックを再利用しやすくなります。
RUとレイテンシを二重に見る
クエリ時の埋め込み生成が実装されると、検索のレイテンシはAzure Cosmos DB側だけでは決まりません。埋め込み生成サービスの応答時間、モデルの混雑、ネットワーク、リトライも加わります。
Azure Cosmos DBのベクトル検索では、公式ドキュメントでもSELECTにTOP Nを使うことが推奨されています。TOP Nがないと、必要以上に多くの結果を返そうとしてRU消費とレイテンシが増えやすくなります。(Microsoft Learn)
実務では、次のメトリックを分けて観測してください。
- Cosmos DB query duration
- RU消費量
- 埋め込み生成APIのlatency
- 埋め込み生成APIのエラー率
- 429や5xxの発生回数
- retry回数
- token使用量
- 検索結果のクリック率や正答率
検索品質だけでなく、コストと安定性も同時に見ないと、本番導入後に「検索は便利になったが、遅い・高い・落ちやすい」という問題が起きます。
管理者が確認すべきセキュリティと運用ポイント
EmbeddingGeneratorは、AIサービスへの接続情報を扱います。Azure Cosmos DB本体のキー管理だけでなく、埋め込み生成サービス側の認証情報も運用対象になります。
特に注意したいのは、検索語そのものです。RAGや社内検索では、ユーザーが入力した検索語に個人情報、社内文書名、顧客名、障害情報などが含まれることがあります。これを外部の埋め込みサービスへ送る設計になるため、ログ、診断、監査、データ保持ポリシーを確認してください。
| 項目 | 確認ポイント |
|---|---|
| 認証情報 | APIキーをコードやリポジトリに埋め込まず、Key VaultやManaged Identityの利用を検討する |
| ログ | raw text、ベクトル配列、認証ヘッダーをログ出力しない |
| 障害時 | 埋め込み生成サービスが落ちた場合に検索全体を止めるか、代替検索にフォールバックするか決める |
| コスト | query-time embeddingは検索回数に比例してコストが増える可能性がある |
| キャッシュ | 同じ検索語が多い場合、短期間のembedding cacheで重複課金を抑えられるか検討する |
| データ境界 | 送信先リージョン、データ処理条件、社内規定との整合性を確認する |
特に管理者は、preview機能を有効化する前に「どの環境で試すか」を決めるべきです。最初から本番のCosmosClientに設定するのではなく、開発環境や検証用サブスクリプションで挙動と監視を確認するのが安全です。
開発チームが今やるべきこと
今回のAzure Cosmos DB EmbeddingGenerator更新に対して、開発チームがすぐに取るべき行動は次の3つです。
preview APIの採用可否を決める
まず、組織としてpreview SDKを試せるかを確認します。preview APIは将来的に名前、シグネチャ、挙動が変わる可能性があります。プロダクションコードに直接組み込むのではなく、検証ブランチやPoCで試すのが現実的です。
generator実装の責務を整理する
ICosmosEmbeddingGeneratorの実装では、単に埋め込みAPIを呼ぶだけでは不十分です。次の責務をどこに置くか決めてください。
- 入力テキストのバリデーション
- バッチ分割
- 次元数チェック
- リトライ
- キャンセル
- latency計測
- token使用量の取得
- 認証情報の取得
- 例外の変換
- キャッシュ
これらを実装クラスに詰め込みすぎるとテストしづらくなります。外部サービス呼び出し部分とCosmos DB SDK契約への変換部分は分けるのがおすすめです。
既存クエリを棚卸しする
将来的にquery-time embedding generationを使う候補になるクエリを洗い出します。
向いているのは、ユーザーの自然文検索をその場でベクトル化する検索です。たとえば、FAQ検索、商品説明検索、ドキュメント検索、サポート履歴検索、エージェントメモリ検索などです。
一方で、定型クエリや完全一致検索、フィルター中心の検索では、EmbeddingGeneratorを使うメリットは限定的です。無理にベクトル化すると、余計なコストと遅延が増えるだけです。
よくある誤解
WithEmbeddingGenerator()を設定すればすぐ自動ベクトル化される？
現時点ではそう判断しないほうが安全です。今回のPRは公開APIの追加が中心で、実行時のresolverやbindingは後続PRに回ると説明されています。(GitHub)
既存のベクトル検索コードは不要になる？
すぐには不要になりません。既存の手動ベクトル化、VectorDistance、vector embedding policy、vector indexの設計は引き続き重要です。
generatorは毎回newしてもよい？
避けたほうがよいです。クライアント全体に設定する前提なので、HTTP接続や認証クライアントを含む実装ではライフサイクル管理が重要です。並列呼び出しに耐えられるよう、スレッドセーフな実装にしてください。
dimensionsはモデル任せでよい？
よくありません。Cosmos DB側のベクトルポリシーと、埋め込み生成で返すベクトルの次元は一致させる必要があります。特に、次元を指定できる埋め込みモデルを使う場合は、dimensions引数を必ず反映する設計にしてください。
まとめ：今は「本番移行」ではなく「設計準備」のタイミング
Azure Cosmos DBのEmbeddingGenerator更新は、.NET SDKプレビューでquery-time embedding generationを実現するための重要な一歩です。ただし、今回追加されたのは主にICosmosEmbeddingGeneratorとクライアント全体の設定口であり、実際のクエリパイプラインへの接続はまだ後続作業です。
管理者と開発者は、今すぐ本番の検索処理を置き換えるのではなく、次の順で準備を進めるのが安全です。
- 利用中の
Microsoft.Azure.CosmosSDKバージョンとpreview採用ルールを確認する - 既存のベクトル検索・ハイブリッド検索クエリを棚卸しする
- 埋め込み生成処理を
ICosmosEmbeddingGeneratorへ移行しやすい形に分離する - endpoint、deploymentName、dimensions、認証情報、リトライ、ログ方針を整理する
- 後続PRや正式なpreviewパッケージのリリース後に、検証環境で実行時挙動を確認する
この更新は、Azure Cosmos DBをRAGやAIエージェントの検索基盤として使うチームにとって、将来の実装負荷を下げる可能性があります。一方で、外部AIサービス呼び出しが検索パスに入る設計になるため、性能・コスト・セキュリティの確認を後回しにしないことが重要です。
コメント