Build 2026 で発表のあった Cosmos DB の新機能で注目している一つが、これまで Change Feed やデータの書き込み時に Embedding の生成を行う必要があったのが、コンテナーのポリシーを設定するだけで自動的に Embedding の生成が行われる Integrated Embeddings です。Embedding の処理自体は基本的に同じで、固有の処理というものが出てこないため Integrated Embeddings を使うことで追加の Azure Functions が必要なくなるのは嬉しい部分です。
ちなみに Change Feed は考慮せずに同じコンテナーに対して書き込みを行うと無限ループになってしまいますが、Integrated Embeddings ではそのあたりの対応も組み込まれているのでよりシンプルに使えます。
ブログを書いている Integrated Embeddings の PM が E2E のサンプルを公開してくれているので、サクッと試したい場合はこのコードを動かすだけで確認できます。Python ベースですが基本は Cosmos DB SDK を使っているので、他の言語に読み替えることも容易なはずです。
実際に Integrated Embeddings を利用するには以下のように事前に準備が必要です。特に Integrated Embeddings 自体の有効化は Public Preview であっても、現時点では自由に有効化出来るのではなくフォームからの申請*1が必要になっています。
申請を行ってから実際に Integrated Embeddings が有効化されるまで 1 週間ほどかかるようなので、試したい場合には早めにフォームから申請しておくのが良いです。
- Integrated Embeddings の有効化
- Vector Search の有効化
- All Versions and Deletes Change Feed の有効化
- Cosmos DB アカウントで Managed Identity の有効化と Default Identity の設定
- Microsoft Foundry で Embedding モデルのデプロイと権限の付与
それ以外は Cosmos DB アカウントからユーザーが自由に有効化出来るものと、Microsoft Foundry での作業が必要になるものだけなので簡単です。Vector Search と All Versions and Deletes Change Feed については以下のエントリで書いているので、実際の手順はこちらを参照してください。
Microsoft Foundry での Embedding モデルのデプロイについては説明はしませんが、Cosmos DB に割り当てた Managed Identity の権限だけは少し注意が必要そうです。以前の Azure OpenAI Service と呼ばれていた時とは異なり、Microsoft Foundry には Project という概念が追加されているのと、それに伴ってエンドポイントの形式も異なっています。
念のため以下のドキュメントの記述通りに Cognitive Services OpenAI User ロールを Microsoft Foundry のプロジェクトではなくアカウントに対して割り当てて確認をしています。
A role assignment on the Microsoft Foundry resource that grants the Azure Cosmos DB managed identity the Cognitive Services OpenAI User role, so it can make inference API calls to the embedding model.
Integrated Embeddings in Azure Cosmos DB (Preview) - Azure Cosmos DB | Microsoft Learn
アカウントに対して権限を割り当てるとプロジェクトにも継承されるので、検証中は無難な方を選んで置いた形です。
後ほど指定する Microsoft Foundry への Azure OpenAI エンドポイントも、現在デフォルトで表示されるようになった https://<foundry-resource-name>.openai.azure.com/openai/v1 ではなく https://<foundry-resource-name>.openai.azure.com/ にしています。
この辺りは GA までに最新の Microsoft Foundry に対応した形で更新されることを期待したいです。ここからは実際に Integrated Embeddings を試すための必要な設定について、いくつかポイントを絞って書いていきます。
Default Identity を Managed Identity に変更
CMK を使う場合以外で Cosmos DB で Managed Identity を有効化する機会がほぼないのですが、Integrated Embeddings では Managed Identity を使って Microsoft Foundry へのアクセスを行うので、有効化した上で Default Identity として指定する必要があります。Default Identity は Cosmos DB を普通に使う上でほぼ意識しないですが、Managed Identity を使う場合には必要なものです。
普通にデプロイを行うと defaultIdentity は FirstPartyIdentity になっているので、これを SystemAssignedIdentity か UserAssignedIdentity に変更します。Azure Portal に変更する機能は用意されていないので、Azure CLI などを使って行う必要があります。
# System Assigned Managed Identity を使う az cosmosdb update --resource-group <resource-group-name> --name <cosmos-account-name> --default-identity SystemAssignedIdentity
これで Cosmos DB が Managed Identity を使って外部サービスを扱えるようになります。今回の有効化の手順の中で抜け落ちやすい部分なので注意が必要です。
現在は Public Preview 中ということもあって設定ミスがあった場合もエラーなどが分かりやすく発生するわけではなく、
Integrated Embeddings を有効化した Vector Embedding Policy を作成
これまでも Vector Search を使う場合に必要だった vectorEmbeddingPolicy を定義するのですが、Integrated Embeddings では新しく embeddingSource プロパティが追加されているので、ここで Embedding 生成対象とするプロパティや OpenAI エンドポイント、Embedding モデルなどを指定します。
まだ Azure Portal では embeddingSource の指定は出来ないので、SDK や Bicep などを使う必要があります。SDK を使っても Policy 自体は JSON で指定する必要があるので、正直なところ Bicep を使う方が分かりやすいです。
vectorEmbeddingPolicy: {
vectorEmbeddings: [
{
path: '/embedding'
dataType: 'float32'
dimensions: 1536
distanceFunction: 'cosine'
embeddingSource: {
sourcePaths: [
'/title'
'/description'
]
deploymentName: 'text-embedding-3-small'
modelName: 'text-embedding-3-small'
endpoint: 'https://<foundry-resource-name>.openai.azure.com/'
authType: 'Entra'
}
}
]
}実際の定義を見てもらえば理解できると思いますが、特徴としては sourcePaths で複数のプロパティが指定できる点です。Embedding 専用のデータ構造を変える必要なく、複数のプロパティを含めた Embedding を生成できるのは便利です。もちろん複数の Embedding を定義出来るので、かなり柔軟な Vector Search の実装が可能です。
コンテナーをデプロイするために必要な Bicep による定義全体は以下のようになります。基本は Vector Search の時と変わらないので、Integrated Embeddings への対応も簡単に出来るはずです。
resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2026-04-01-preview' existing = {
name: '<cosmos-account-name>'
}
resource sqlDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2026-04-01-preview' existing = {
parent: cosmosAccount
name: '<cosmos-database-name>'
}
resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2026-04-01-preview' = {
parent: sqlDatabase
name: '<cosmos-container-name>'
properties: {
resource: {
id: '<cosmos-container-name>'
partitionKey: {
paths: [
'/id'
]
kind: 'Hash'
}
indexingPolicy: {
indexingMode: 'consistent'
automatic: true
includedPaths: [
{
path: '/*'
}
]
excludedPaths: [
{
path: '/"_etag"/?'
}
{
path: '/embedding/*'
}
]
vectorIndexes: [
{
path: '/embedding'
type: 'quantizedFlat'
}
]
}
vectorEmbeddingPolicy: {
vectorEmbeddings: [
{
path: '/embedding'
dataType: 'float32'
dimensions: 1536
distanceFunction: 'cosine'
embeddingSource: {
sourcePaths: [
'/title'
'/description'
]
deploymentName: 'text-embedding-3-small'
modelName: 'text-embedding-3-small'
endpoint: 'https://<foundry-resource-name>.openai.azure.com/'
authType: 'Entra'
}
}
]
}
}
options: {
autoscaleSettings: {
maxThroughput: 1000
}
}
}
}この定義をビルドして Azure Portal や Azure CLI でデプロイすると、Integrated Embeddings が有効なコンテナーが完成します。フォームから申請していない場合やまだ有効化されていない場合はエラーとなります。
公式ドキュメントでは SDK からの作成のみサポートされているように書かれていますが、Bicep / ARM Template と SDK は同じ API を叩いているので問題なく動作します。
データを投入して Embedding が生成されることを確認
Integrated Embeddings が有効なコンテナーを作ってしまえば、後はこれまで通りにデータを追加するだけで非同期で Embedding が作成されます。内部的には Change Feed が使われるので項目を作成してから Embedding が生成されるまで、実測では数秒程度のラグが発生する点は注意が必要です。
気になるコスト面ですが、Integrated Embeddings を有効化した場合は Change Feed の読み取りと Embedding の書き込み、そして Microsoft Foundry 側のモデルコストが発生し、Change Feed の読み取りを行っている処理のコンピューティングコストは発生しないようです。
現在の実装では Change Feed を読み取り、Embedding のプロパティのみを Patch で書きこむようになっているので、Cosmos DB の RU 消費は最小限に抑えられているようです。書き込みに対して必ず 1 回は Embedding に伴う読み込みと書き込みが発生するため、消費 RU は増えるので Autoscale を設定しておくのがベストでしょう。
この後は Vector Search を実際に行うと思いますが、現在 Integrated Embeddings が有効化されているコンテナーに対してのクエリが C# の Cosmos DB SDK では失敗する問題を確認しています。Node.js の Cosmos DB SDK では発生しないので C# SDK の問題だと考えていますが、C# で検証を考えている場合は注意です。
