From 7989f095a260df8116d656bd316d0b55ff6637e4 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Mon, 27 Apr 2026 14:55:02 -0700 Subject: [PATCH 01/16] Update OpenAI models to gpt-4.1 family and AVM to 0.10.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Chat: gpt-4o-mini → gpt-4.1-mini (2025-04-14) - Synth: gpt-4o → gpt-4.1 (2025-04-14) - AVM: cognitive-services/account 0.7.1 → 0.10.0 - Add tier selection comments (Standard ↔ GlobalStandard) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- infra/main.bicep | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/infra/main.bicep b/infra/main.bicep index fbe874b..9dd6e39 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -56,14 +56,17 @@ module managedIdentity 'br/public:avm/res/managed-identity/user-assigned-identit } // Azure OpenAI model and configuration variables -var chatModelName = 'gpt-4o-mini' -var chatModelVersion = '2024-07-18' +// https://learn.microsoft.com/azure/ai-services/openai/concepts/models?tabs=python-secure%2Cglobal-standard%2Cstandard-chat-completions#models-by-deployment-type +// To change deployment type, swap 'Standard' ↔ 'GlobalStandard' in the sku name variables below. +// gpt-4o-mini Standard was deprecated 2026-03-31; use gpt-4.1-mini instead. +var chatModelName = 'gpt-4.1-mini' +var chatModelVersion = '2025-04-14' var chatModelApiVersion = '2024-08-01-preview' var chatModelType = 'Standard' var chatModelCapacity = 50 -var synthModelName = 'gpt-4o' -var synthModelVersion = '2024-11-20' +var synthModelName = 'gpt-4.1' +var synthModelVersion = '2025-04-14' var synthModelApiVersion = '2024-08-01-preview' var synthModelType = 'GlobalStandard' var synthModelCapacity = 50 @@ -88,7 +91,7 @@ var collectionName = 'hotel_data' var indexName = 'vectorIndex' var openAiServiceName = 'openai-${prefix}' -module openAi 'br/public:avm/res/cognitive-services/account:0.7.1' = { +module openAi 'br/public:avm/res/cognitive-services/account:0.10.0' = { name: 'openai' scope: resourceGroup params: { @@ -191,7 +194,7 @@ output AZURE_OPENAI_CHAT_DEPLOYMENT string = chatModelName output AZURE_OPENAI_CHAT_ENDPOINT string = openAi.outputs.endpoint output AZURE_OPENAI_CHAT_API_VERSION string = chatModelApiVersion -// Planner agent uses the same model as chat (gpt-4o-mini) +// Planner agent uses the same model as chat (gpt-4.1-mini) output AZURE_OPENAI_PLANNER_MODEL string = chatModelName output AZURE_OPENAI_PLANNER_DEPLOYMENT string = chatModelName output AZURE_OPENAI_PLANNER_ENDPOINT string = openAi.outputs.endpoint From 48599cae6c6f24cbb63c9511ac4e529f2483d4fc Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Mon, 27 Apr 2026 15:02:24 -0700 Subject: [PATCH 02/16] Add separate openAiLocation param with expanded region list OpenAI can now be deployed to a different region than other resources. Supported OpenAI regions: eastus, eastus2, eastus3, westus, westus2, westus3, northeurope, swedencentral. Defaults to main location if not specified. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- infra/main.bicep | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/infra/main.bicep b/infra/main.bicep index 9dd6e39..cd9b3fe 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -6,8 +6,7 @@ targetScope = 'subscription' param environmentName string @minLength(1) -@description('Location for the OpenAI resource') -// https://learn.microsoft.com/azure/ai-services/openai/concepts/models?tabs=python-secure%2Cglobal-standard%2Cstandard-chat-completions#models-by-deployment-type +@description('Location for all resources') @allowed([ 'eastus2' 'swedencentral' @@ -19,6 +18,21 @@ param environmentName string }) param location string +@description('Location for Azure OpenAI resource (defaults to main location if not specified). Not all models are available in all regions.') +// https://learn.microsoft.com/azure/ai-services/openai/concepts/models?tabs=python-secure%2Cglobal-standard%2Cstandard-chat-completions#models-by-deployment-type +@allowed([ + 'eastus' + 'eastus2' + 'eastus3' + 'westus' + 'westus2' + 'westus3' + 'northeurope' + 'swedencentral' +]) +@metadata({ azd: { type: 'location' } }) +param openAiLocation string = location + @description('Id of the principal to assign database and application roles.') param deploymentUserPrincipalId string = '' @@ -96,7 +110,7 @@ module openAi 'br/public:avm/res/cognitive-services/account:0.10.0' = { scope: resourceGroup params: { name: openAiServiceName - location: location + location: openAiLocation tags: tags kind: 'OpenAI' sku: 'S0' From 08fd85990b869783c59491d307c30d74fa7b91b6 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Mon, 27 Apr 2026 15:05:59 -0700 Subject: [PATCH 03/16] Add openAiLocation to bicepparam file Reads AZURE_OPENAI_LOCATION env var, falls back to AZURE_LOCATION. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- infra/main.bicepparam | 1 + 1 file changed, 1 insertion(+) diff --git a/infra/main.bicepparam b/infra/main.bicepparam index e374b7f..257cec9 100644 --- a/infra/main.bicepparam +++ b/infra/main.bicepparam @@ -2,6 +2,7 @@ using './main.bicep' param environmentName = readEnvironmentVariable('AZURE_ENV_NAME', 'development') param location = readEnvironmentVariable('AZURE_LOCATION', 'eastus2') +param openAiLocation = readEnvironmentVariable('AZURE_OPENAI_LOCATION', readEnvironmentVariable('AZURE_LOCATION', 'eastus2')) param deploymentUserPrincipalId = readEnvironmentVariable('AZURE_PRINCIPAL_ID', '') param currentUserPrincipalId = readEnvironmentVariable('CURRENT_USER_OBJECT_ID', readEnvironmentVariable('AZURE_PRINCIPAL_ID', '')) param documentDbAdminUsername = readEnvironmentVariable('DOCUMENTDB_ADMIN_USERNAME', 'docdbadmin') From 43f9415fe88a1915968e8b56be2b49645f19b376 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Mon, 27 Apr 2026 15:23:52 -0700 Subject: [PATCH 04/16] feat(infra): expose OpenAI model names and tiers as params Promote chatModelName, chatModelType, synthModelName, synthModelType, embeddingModelName, embeddingModelType from hardcoded vars to params with env var overrides in bicepparam. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- infra/main.bicep | 41 ++++++++++++++++++++++++++++++----------- infra/main.bicepparam | 11 +++++++++++ 2 files changed, 41 insertions(+), 11 deletions(-) diff --git a/infra/main.bicep b/infra/main.bicep index cd9b3fe..cf325ed 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -69,26 +69,45 @@ module managedIdentity 'br/public:avm/res/managed-identity/user-assigned-identit } } -// Azure OpenAI model and configuration variables +// Azure OpenAI model and configuration parameters // https://learn.microsoft.com/azure/ai-services/openai/concepts/models?tabs=python-secure%2Cglobal-standard%2Cstandard-chat-completions#models-by-deployment-type -// To change deployment type, swap 'Standard' ↔ 'GlobalStandard' in the sku name variables below. +// To change deployment type, swap 'Standard' ↔ 'GlobalStandard' in the sku name parameters below. // gpt-4o-mini Standard was deprecated 2026-03-31; use gpt-4.1-mini instead. -var chatModelName = 'gpt-4.1-mini' -var chatModelVersion = '2025-04-14' + +@description('Chat model name') +param chatModelName string = 'gpt-4.1-mini' + +@description('Chat model version') +param chatModelVersion string = '2025-04-14' + +@description('Chat model deployment type: Standard or GlobalStandard') +param chatModelType string = 'Standard' + var chatModelApiVersion = '2024-08-01-preview' -var chatModelType = 'Standard' var chatModelCapacity = 50 -var synthModelName = 'gpt-4.1' -var synthModelVersion = '2025-04-14' +@description('Synthesis model name') +param synthModelName string = 'gpt-4.1' + +@description('Synthesis model version') +param synthModelVersion string = '2025-04-14' + +@description('Synthesis model deployment type: Standard or GlobalStandard') +param synthModelType string = 'GlobalStandard' + var synthModelApiVersion = '2024-08-01-preview' -var synthModelType = 'GlobalStandard' var synthModelCapacity = 50 -var embeddingModelName = 'text-embedding-3-small' -var embeddingModelVersion = '1' +@description('Embedding model name') +param embeddingModelName string = 'text-embedding-3-small' + +@description('Embedding model version') +param embeddingModelVersion string = '1' + +@description('Embedding model deployment type: Standard or GlobalStandard') +param embeddingModelType string = 'Standard' + var embeddingModelApiVersion = '2023-05-15' -var embeddingModelType = 'Standard' var embeddingModelCapacity = 50 // Data and embedding configuration diff --git a/infra/main.bicepparam b/infra/main.bicepparam index 257cec9..1abfc61 100644 --- a/infra/main.bicepparam +++ b/infra/main.bicepparam @@ -7,3 +7,14 @@ param deploymentUserPrincipalId = readEnvironmentVariable('AZURE_PRINCIPAL_ID', param currentUserPrincipalId = readEnvironmentVariable('CURRENT_USER_OBJECT_ID', readEnvironmentVariable('AZURE_PRINCIPAL_ID', '')) param documentDbAdminUsername = readEnvironmentVariable('DOCUMENTDB_ADMIN_USERNAME', 'docdbadmin') param documentDbAdminPassword = 'TempP@ssw0rd123!' + +// OpenAI model configuration +param chatModelName = readEnvironmentVariable('AZURE_OPENAI_CHAT_MODEL', 'gpt-4.1-mini') +param chatModelVersion = readEnvironmentVariable('AZURE_OPENAI_CHAT_MODEL_VERSION', '2025-04-14') +param chatModelType = readEnvironmentVariable('AZURE_OPENAI_CHAT_MODEL_TYPE', 'Standard') +param synthModelName = readEnvironmentVariable('AZURE_OPENAI_SYNTH_MODEL', 'gpt-4.1') +param synthModelVersion = readEnvironmentVariable('AZURE_OPENAI_SYNTH_MODEL_VERSION', '2025-04-14') +param synthModelType = readEnvironmentVariable('AZURE_OPENAI_SYNTH_MODEL_TYPE', 'GlobalStandard') +param embeddingModelName = readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL', 'text-embedding-3-small') +param embeddingModelVersion = readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL_VERSION', '1') +param embeddingModelType = readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL_TYPE', 'Standard') From 31e8b5b5a88af1ae59dc9bef4716a1c876829519 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Mon, 27 Apr 2026 15:41:15 -0700 Subject: [PATCH 05/16] fix: default all OpenAI model tiers to Standard GlobalStandard has 0 quota on BAMI_DIBERRY_2 subscription. Standard tier has available quota for gpt-4.1 (1000K) and gpt-4.1-mini (5000K) in eastus2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- infra/main.bicep | 2 +- infra/main.bicepparam | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/infra/main.bicep b/infra/main.bicep index cf325ed..0e13faf 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -93,7 +93,7 @@ param synthModelName string = 'gpt-4.1' param synthModelVersion string = '2025-04-14' @description('Synthesis model deployment type: Standard or GlobalStandard') -param synthModelType string = 'GlobalStandard' +param synthModelType string = 'Standard' var synthModelApiVersion = '2024-08-01-preview' var synthModelCapacity = 50 diff --git a/infra/main.bicepparam b/infra/main.bicepparam index 1abfc61..3857f95 100644 --- a/infra/main.bicepparam +++ b/infra/main.bicepparam @@ -14,7 +14,7 @@ param chatModelVersion = readEnvironmentVariable('AZURE_OPENAI_CHAT_MODEL_VERSIO param chatModelType = readEnvironmentVariable('AZURE_OPENAI_CHAT_MODEL_TYPE', 'Standard') param synthModelName = readEnvironmentVariable('AZURE_OPENAI_SYNTH_MODEL', 'gpt-4.1') param synthModelVersion = readEnvironmentVariable('AZURE_OPENAI_SYNTH_MODEL_VERSION', '2025-04-14') -param synthModelType = readEnvironmentVariable('AZURE_OPENAI_SYNTH_MODEL_TYPE', 'GlobalStandard') +param synthModelType = readEnvironmentVariable('AZURE_OPENAI_SYNTH_MODEL_TYPE', 'Standard') param embeddingModelName = readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL', 'text-embedding-3-small') param embeddingModelVersion = readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL_VERSION', '1') param embeddingModelType = readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL_TYPE', 'Standard') From e961fcb868da73743efac6e17529942b99f9e6bc Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 10:37:24 -0700 Subject: [PATCH 06/16] docs: add OpenAI configuration env vars to README Document azd env set commands for customizing OpenAI location, model names, versions, and deployment SKUs before running azd up. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index dca121c..4c687e0 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,43 @@ This command will: - Provision all infrastructure resources in your Azure subscription - Generate a `.env` file in the root directory with all necessary connection strings and credentials +#### Configure OpenAI Settings (Optional) + +Before running `azd up`, you can customize the OpenAI deployment by setting environment variables. If not set, defaults are used. + +```bash +# Set OpenAI location (can differ from resource group location) +azd env set AZURE_OPENAI_LOCATION eastus2 + +# Chat model configuration +azd env set AZURE_OPENAI_CHAT_MODEL gpt-4.1-mini +azd env set AZURE_OPENAI_CHAT_MODEL_VERSION 2025-04-14 +azd env set AZURE_OPENAI_CHAT_MODEL_TYPE Standard + +# Synthesis model configuration +azd env set AZURE_OPENAI_SYNTH_MODEL gpt-4.1 +azd env set AZURE_OPENAI_SYNTH_MODEL_VERSION 2025-04-14 +azd env set AZURE_OPENAI_SYNTH_MODEL_TYPE Standard + +# Embedding model configuration +azd env set AZURE_OPENAI_EMBEDDING_MODEL text-embedding-3-small +azd env set AZURE_OPENAI_EMBEDDING_MODEL_VERSION 1 +azd env set AZURE_OPENAI_EMBEDDING_MODEL_TYPE Standard +``` + +| Variable | Default | Description | +|----------|---------|-------------| +| `AZURE_OPENAI_LOCATION` | Same as `AZURE_LOCATION` | Region for OpenAI resources | +| `AZURE_OPENAI_CHAT_MODEL` | `gpt-4.1-mini` | Chat completion model | +| `AZURE_OPENAI_CHAT_MODEL_VERSION` | `2025-04-14` | Chat model version | +| `AZURE_OPENAI_CHAT_MODEL_TYPE` | `Standard` | Deployment SKU (`Standard` or `GlobalStandard`) | +| `AZURE_OPENAI_SYNTH_MODEL` | `gpt-4.1` | Data synthesis model | +| `AZURE_OPENAI_SYNTH_MODEL_VERSION` | `2025-04-14` | Synthesis model version | +| `AZURE_OPENAI_SYNTH_MODEL_TYPE` | `Standard` | Deployment SKU | +| `AZURE_OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model | +| `AZURE_OPENAI_EMBEDDING_MODEL_VERSION` | `1` | Embedding model version | +| `AZURE_OPENAI_EMBEDDING_MODEL_TYPE` | `Standard` | Deployment SKU | + ### 2. Navigate to Your Sample Language Choose your preferred programming language and navigate to the sample directory: From 9c5fdc3600caaf9c26eeefc890c9914dfcd36b35 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 10:40:40 -0700 Subject: [PATCH 07/16] Add azd env get-values command for .env generation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4c687e0..7bcca52 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,12 @@ azd up This command will: - Prompt you to create a new Azure environment - Provision all infrastructure resources in your Azure subscription -- Generate a `.env` file in the root directory with all necessary connection strings and credentials + +After provisioning, export all environment variables to a `.env` file: + +```bash +azd env get-values > .env +``` #### Configure OpenAI Settings (Optional) From 429209b4ae1518003285226cd2c58d08bd5f6f33 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 10:51:35 -0700 Subject: [PATCH 08/16] docs: add flexible vector indexing note to all READMEs DocumentDB (MongoDB vCore) allows vector indexes to be created or dropped on existing collections at any time. Added note to root README and all sample READMEs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 3 +++ ai/vector-search-agent-go/README.md | 3 +++ ai/vector-search-agent-typescript/README.md | 3 +++ ai/vector-search-dotnet/README.md | 3 +++ ai/vector-search-go/README.md | 3 +++ ai/vector-search-java/README.md | 3 +++ ai/vector-search-python/README.md | 3 +++ ai/vector-search-typescript/README.md | 3 +++ 8 files changed, 24 insertions(+) diff --git a/README.md b/README.md index 7bcca52..54edc03 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,9 @@ azd env set AZURE_OPENAI_EMBEDDING_MODEL_TYPE Standard | `AZURE_OPENAI_EMBEDDING_MODEL_VERSION` | `1` | Embedding model version | | `AZURE_OPENAI_EMBEDDING_MODEL_TYPE` | `Standard` | Deployment SKU | + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ### 2. Navigate to Your Sample Language Choose your preferred programming language and navigate to the sample directory: diff --git a/ai/vector-search-agent-go/README.md b/ai/vector-search-agent-go/README.md index 5a040ac..4b97b3b 100644 --- a/ai/vector-search-agent-go/README.md +++ b/ai/vector-search-agent-go/README.md @@ -69,6 +69,9 @@ flowchart LR - Stateless execution with no conversation history - Suitable for single-turn query/response scenarios + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ## Prerequisites ### Azure Resources diff --git a/ai/vector-search-agent-typescript/README.md b/ai/vector-search-agent-typescript/README.md index 155cc21..77bfad8 100644 --- a/ai/vector-search-agent-typescript/README.md +++ b/ai/vector-search-agent-typescript/README.md @@ -29,6 +29,9 @@ By the end, you have a working two-agent system that connects Azure OpenAI and A > [!NOTE] > **Cost considerations:** This quickstart creates Azure OpenAI and Azure DocumentDB resources that incur costs. See [Azure OpenAI pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/) and [Azure DocumentDB pricing](https://azure.microsoft.com/pricing/details/cosmos-db/) for details. + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ## Prerequisites You can use the Azure Developer CLI to create the required Azure resources by running the `azd` commands in the sample repository. For more information, see [Deploy Infrastructure with Azure Developer CLI](https://github.com/Azure-Samples/documentdb-samples/). diff --git a/ai/vector-search-dotnet/README.md b/ai/vector-search-dotnet/README.md index 21d024f..48e000e 100644 --- a/ai/vector-search-dotnet/README.md +++ b/ai/vector-search-dotnet/README.md @@ -21,6 +21,9 @@ This .NET 8.0 sample application demonstrates vector similarity searches using A - Seamless integration with DocumentDB and Azure OpenAI services - Interactive menu-driven application + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ## Prerequisites ### Azure Services diff --git a/ai/vector-search-go/README.md b/ai/vector-search-go/README.md index 3a29b81..98f55e4 100644 --- a/ai/vector-search-go/README.md +++ b/ai/vector-search-go/README.md @@ -14,6 +14,9 @@ products: This project demonstrates vector search capabilities using Azure DocumentDB with Go. It includes implementations of three different vector index types: DiskANN, HNSW, and IVF, along with utilities for embedding generation and data management. + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ## Overview Vector search enables semantic similarity searching by converting text into high-dimensional vector representations (embeddings) and finding the most similar vectors in the database. This project shows how to: diff --git a/ai/vector-search-java/README.md b/ai/vector-search-java/README.md index 58ec72d..81d19a9 100644 --- a/ai/vector-search-java/README.md +++ b/ai/vector-search-java/README.md @@ -14,6 +14,9 @@ products: This project demonstrates vector search capabilities using Azure DocumentDB with Java. It includes implementations of three different vector index types: DiskANN, HNSW, and IVF. + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ## Overview Vector search enables semantic similarity searching by converting text into high-dimensional vector representations (embeddings) and finding the most similar vectors in the database. This project shows how to: diff --git a/ai/vector-search-python/README.md b/ai/vector-search-python/README.md index 3a46a45..c9a98bc 100644 --- a/ai/vector-search-python/README.md +++ b/ai/vector-search-python/README.md @@ -14,6 +14,9 @@ products: This project demonstrates vector search capabilities using Azure DocumentDB with Python. It includes implementations of three different vector index types: DiskANN, HNSW, and IVF, along with utilities for embedding generation and data management. + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ## Overview Vector search enables semantic similarity searching by converting text into high-dimensional vector representations (embeddings) and finding the most similar vectors in the database. This project shows how to: diff --git a/ai/vector-search-typescript/README.md b/ai/vector-search-typescript/README.md index 75017a2..b2fd117 100644 --- a/ai/vector-search-typescript/README.md +++ b/ai/vector-search-typescript/README.md @@ -14,6 +14,9 @@ products: This project demonstrates vector search capabilities using Azure DocumentDB with TypeScript/Node.js. It includes implementations of three different vector index types: DiskANN, HNSW, and IVF, along with utilities for embedding generation and data management. + +> [!NOTE] +> **Vector indexes can be created or dropped on existing collections at any time** — no special configuration is needed at resource creation. ## Overview Vector search enables semantic similarity searching by converting text into high-dimensional vector representations (embeddings) and finding the most similar vectors in the database. This project shows how to: From 77c40575cb76dc4367d1a1cb37a22ea0ef4aa959 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 11:22:34 -0700 Subject: [PATCH 09/16] infra: absorb PR #59 fixes (AVM bumps, API versions, secure password) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - managed-identity AVM 0.4.0 → 0.5.0 - cognitive-services AVM 0.10.0 → 0.14.0 - API versions → 2025-04-01-preview (chat + synth) - Remove hardcoded password, use readEnvironmentVariable This makes PR #70 a complete superset of PR #59. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- infra/main.bicep | 8 ++++---- infra/main.bicepparam | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/infra/main.bicep b/infra/main.bicep index 0e13faf..8e6778d 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -59,7 +59,7 @@ resource resourceGroup 'Microsoft.Resources/resourceGroups@2021-04-01' = { tags: tags } -module managedIdentity 'br/public:avm/res/managed-identity/user-assigned-identity:0.4.0' = { +module managedIdentity 'br/public:avm/res/managed-identity/user-assigned-identity:0.5.0' = { name: 'user-assigned-identity' scope: resourceGroup params: { @@ -83,7 +83,7 @@ param chatModelVersion string = '2025-04-14' @description('Chat model deployment type: Standard or GlobalStandard') param chatModelType string = 'Standard' -var chatModelApiVersion = '2024-08-01-preview' +var chatModelApiVersion = '2025-04-01-preview' var chatModelCapacity = 50 @description('Synthesis model name') @@ -95,7 +95,7 @@ param synthModelVersion string = '2025-04-14' @description('Synthesis model deployment type: Standard or GlobalStandard') param synthModelType string = 'Standard' -var synthModelApiVersion = '2024-08-01-preview' +var synthModelApiVersion = '2025-04-01-preview' var synthModelCapacity = 50 @description('Embedding model name') @@ -124,7 +124,7 @@ var collectionName = 'hotel_data' var indexName = 'vectorIndex' var openAiServiceName = 'openai-${prefix}' -module openAi 'br/public:avm/res/cognitive-services/account:0.10.0' = { +module openAi 'br/public:avm/res/cognitive-services/account:0.14.0' = { name: 'openai' scope: resourceGroup params: { diff --git a/infra/main.bicepparam b/infra/main.bicepparam index 3857f95..0f65f7d 100644 --- a/infra/main.bicepparam +++ b/infra/main.bicepparam @@ -6,7 +6,7 @@ param openAiLocation = readEnvironmentVariable('AZURE_OPENAI_LOCATION', readEnvi param deploymentUserPrincipalId = readEnvironmentVariable('AZURE_PRINCIPAL_ID', '') param currentUserPrincipalId = readEnvironmentVariable('CURRENT_USER_OBJECT_ID', readEnvironmentVariable('AZURE_PRINCIPAL_ID', '')) param documentDbAdminUsername = readEnvironmentVariable('DOCUMENTDB_ADMIN_USERNAME', 'docdbadmin') -param documentDbAdminPassword = 'TempP@ssw0rd123!' +param documentDbAdminPassword = readEnvironmentVariable('DOCUMENTDB_ADMIN_PASSWORD', '') // OpenAI model configuration param chatModelName = readEnvironmentVariable('AZURE_OPENAI_CHAT_MODEL', 'gpt-4.1-mini') From 40626ba27bda64effbbd61ba42f88ea505f3041d Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 12:44:40 -0700 Subject: [PATCH 10/16] Remove auto .env hook, add manual env setup to READMEs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ai/vector-search-dotnet/README.md | 14 ++++++++++++-- ai/vector-search-go/README.md | 10 ++++++++++ ai/vector-search-java/README.md | 13 +++++++++++-- ai/vector-search-python/README.md | 10 ++++++++++ ai/vector-search-typescript/README.md | 24 +++++++++--------------- azure.yaml | 21 +-------------------- 6 files changed, 53 insertions(+), 39 deletions(-) diff --git a/ai/vector-search-dotnet/README.md b/ai/vector-search-dotnet/README.md index 48e000e..80f014a 100644 --- a/ai/vector-search-dotnet/README.md +++ b/ai/vector-search-dotnet/README.md @@ -53,7 +53,17 @@ cd ai/vector-search-dotnet az login ``` -3. Update `appsettings.json` with your Azure service details: +3. Configure environment variables: + +The .NET sample reads configuration from `appsettings.json` and environment variables. After deploying with `azd up`, you can view your provisioned resource values: + +```bash +azd env get-values +``` + +Use these values to update `appsettings.json` or set them as environment variables. + +4. Update `appsettings.json` with your Azure service details: ```json { @@ -67,7 +77,7 @@ az login } ``` -4. Run the application: +5. Run the application: ```bash dotnet restore diff --git a/ai/vector-search-go/README.md b/ai/vector-search-go/README.md index 98f55e4..24c5064 100644 --- a/ai/vector-search-go/README.md +++ b/ai/vector-search-go/README.md @@ -119,6 +119,16 @@ az resource show \ ### Step 4: Configure Environment Variables +If you deployed Azure resources with `azd up` (from the repository root), create a `.env` file with your provisioned resource values: + +```bash +azd env get-values > .env +``` + +This creates a `.env` file with the connection strings and endpoints needed to run the sample. + +Alternatively, you can configure the environment manually: + 1. Copy the example environment file: ```bash diff --git a/ai/vector-search-java/README.md b/ai/vector-search-java/README.md index 81d19a9..4564d70 100644 --- a/ai/vector-search-java/README.md +++ b/ai/vector-search-java/README.md @@ -95,7 +95,16 @@ The `azd up` command will: - Deploy Azure DocumentDB (MongoDB vCore) cluster - Create a managed identity for secure access - Configure all necessary permissions and networking -- Generate a `.env` file with all connection information at the repository root + +### Configure environment variables + +After deploying with `azd up`, create a `.env` file with your provisioned resource values: + +```bash +azd env get-values > .env +``` + +This creates a `.env` file at the repository root with the connection strings and endpoints needed to run the sample. ### Compile the Project @@ -109,7 +118,7 @@ mvn clean compile ### Load Environment Variables -After deployment completes, load the environment variables from the generated `.env` file. The `set -a` command ensures variables are exported to child processes (like the Maven JVM): +Load the environment variables from the `.env` file. The `set -a` command ensures variables are exported to child processes (like the Maven JVM): ```bash # From the ai/vector-search-java directory diff --git a/ai/vector-search-python/README.md b/ai/vector-search-python/README.md index c9a98bc..e471519 100644 --- a/ai/vector-search-python/README.md +++ b/ai/vector-search-python/README.md @@ -96,6 +96,16 @@ Learn how to create an Azure DocumentDB account in the [official documentation]( ### Step 3: Configure Environment Variables +If you deployed Azure resources with `azd up` (from the repository root), create a `.env` file with your provisioned resource values: + +```bash +azd env get-values > .env +``` + +This creates a `.env` file with the connection strings and endpoints needed to run the sample. + +Alternatively, you can configure the environment manually: + 1. Copy the example environment file: ```bash cp .env.example .env diff --git a/ai/vector-search-typescript/README.md b/ai/vector-search-typescript/README.md index b2fd117..ac146ae 100644 --- a/ai/vector-search-typescript/README.md +++ b/ai/vector-search-typescript/README.md @@ -95,8 +95,16 @@ The `azd provision` command will: - Deploy Azure DocumentDB (MongoDB vCore) cluster - Create a managed identity for secure access - Configure all necessary permissions and networking -- Generate a `.env` file with all connection information at the root +### Configure environment variables + +After deploying with `azd up`, create a `.env` file with your provisioned resource values: + +```bash +azd env get-values > .env +``` + +This creates a `.env` file at the repository root with the connection strings and endpoints needed to run the sample. ### Install dependencies @@ -108,20 +116,6 @@ cd ai/vector-search-typescript npm install ``` -### Verify Environment Configuration - -After deployment completes, verify that the `.env` file was created in the repository root: - -```bash -# View the generated environment variables -cat ../../.env -``` - -The file should contain all necessary configuration including: -- Azure OpenAI endpoint and model information -- DocumentDB cluster name and database settings -- Embedding and data processing configuration - ## Build Compile the TypeScript code before running: diff --git a/azure.yaml b/azure.yaml index cb5b2e0..4eb4b8f 100644 --- a/azure.yaml +++ b/azure.yaml @@ -2,23 +2,4 @@ name: documentdb-samples services: -hooks: - postprovision: - posix: - sh: bash - run: | - # Get environment values for the application - azd env get-values > .env - echo "Environment configured. Data will be loaded after deployment." - windows: - shell: pwsh - run: | - azd env get-values > .env - Write-Host "Environment configured. Data will be loaded after deployment." - postdown: - windows: - shell: pwsh - run: "if (Test-Path .env) { rm .env }" - posix: - shell: sh - run: "[ -f .env ] && rm .env || true" + From 75ee491d37382400e1ef0cd7f1b535a5888b1726 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 13:02:31 -0700 Subject: [PATCH 11/16] Add azd deployment + env setup to agent READMEs - agent-go: Add 'Deploy Azure resources' section with azd up + azd env get-values > .env - agent-typescript: Update TIP to use 'azd env get-values > .env' export command Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ai/vector-search-agent-go/README.md | 19 +++++++++++++++++++ ai/vector-search-agent-typescript/README.md | 8 ++++++-- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/ai/vector-search-agent-go/README.md b/ai/vector-search-agent-go/README.md index 4b97b3b..2351050 100644 --- a/ai/vector-search-agent-go/README.md +++ b/ai/vector-search-agent-go/README.md @@ -111,6 +111,25 @@ vector-search-agent-go/ └── README.md ``` +## Deploy Azure resources + +1. Provision and deploy the infrastructure: + + ```bash + azd up + ``` + +1. When prompted, select your subscription and a location (for example, `swedencentral` or `eastus2`). + +1. After deployment completes, generate your `.env` file from the deployed environment: + + ```bash + azd env get-values > .env + ``` + +> [!TIP] +> Run `azd env get-values` at any time to regenerate the `.env` file with current environment values. + ## Installation 1. Clone the repository: diff --git a/ai/vector-search-agent-typescript/README.md b/ai/vector-search-agent-typescript/README.md index 77bfad8..3c32e63 100644 --- a/ai/vector-search-agent-typescript/README.md +++ b/ai/vector-search-agent-typescript/README.md @@ -101,10 +101,14 @@ Use the Azure Developer CLI (`azd`) to provision the required Azure OpenAI and D 1. When prompted, select your subscription and a location (for example, `swedencentral` or `eastus2`). -1. After deployment completes, `azd` outputs the environment variables you need. Copy them into your `.env` file (see [Configure environment variables](#configure-environment-variables)). +1. After deployment completes, generate your `.env` file from the deployed environment: + + ```bash + azd env get-values > .env + ``` > [!TIP] -> Run `azd env get-values` at any time to view the current environment values. +> Run `azd env get-values > .env` at any time to regenerate the `.env` file with current environment values. ## Configure environment variables From 112f0b9a2c7b48dc73d44ea26677658803177af6 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 13:12:26 -0700 Subject: [PATCH 12/16] Add troubleshooting section for OpenAI provisioning failures Document common failure modes (region availability, deployment type mismatch, quota limits) and remediation steps for Azure OpenAI provisioning issues. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index 54edc03..4949fc7 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,21 @@ Follow the language-specific instructions: Each sample demonstrates how to generate embeddings, create vector indexes, and perform semantic similarity searches with hotel data. +## Troubleshooting + +### Azure OpenAI provisioning fails + +If `azd up` fails when creating the Azure OpenAI resource or model deployments, the issue is typically one of: + +- **Region availability**: The selected model isn't available in your chosen region. Try a different `AZURE_OPENAI_LOCATION` (e.g., `eastus2`, `swedencentral`). +- **SKU/tier mismatch**: The model doesn't support the selected deployment type. Switch between `Standard` and `GlobalStandard` using `azd env set AZURE_OPENAI_CHAT_MODEL_TYPE GlobalStandard`. +- **Quota limits**: Your subscription has reached its quota for the selected model/region/tier combination. Check your quota in the Azure portal under **Azure OpenAI → Quotas**. + +All OpenAI model parameters — region, model name, version, and deployment type (Standard/GlobalStandard) — are configurable via `azd env set` before running `azd up`. See [Configure OpenAI Settings](#configure-openai-settings-optional) above for the full list. + +> [!TIP] +> Run `azd env set AZURE_OPENAI_LOCATION ` to deploy OpenAI to a different region than your other resources. Check [model availability by region](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#model-summary-table-and-region-availability) to find supported region/model/tier combinations. + ## Cleanup To delete all provisioned Azure resources: From 54f50fa4d586265d12def2fe2ff3968d62ee7115 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 13:27:28 -0700 Subject: [PATCH 13/16] Add model retirement and quota increase guidance to troubleshooting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4949fc7..c7189f0 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,8 @@ If `azd up` fails when creating the Azure OpenAI resource or model deployments, - **Region availability**: The selected model isn't available in your chosen region. Try a different `AZURE_OPENAI_LOCATION` (e.g., `eastus2`, `swedencentral`). - **SKU/tier mismatch**: The model doesn't support the selected deployment type. Switch between `Standard` and `GlobalStandard` using `azd env set AZURE_OPENAI_CHAT_MODEL_TYPE GlobalStandard`. -- **Quota limits**: Your subscription has reached its quota for the selected model/region/tier combination. Check your quota in the Azure portal under **Azure OpenAI → Quotas**. +- **Quota limits**: Your subscription has reached its quota for the selected model/region/tier combination. Check your quota in the Azure portal under **Azure OpenAI → Quotas**. You can request a quota increase or try a different region with available capacity. +- **Model retired or unavailable**: Azure OpenAI periodically retires older model versions. If deployment fails because a model version is no longer available, update to a supported version (e.g., `azd env set AZURE_OPENAI_CHAT_MODEL_VERSION `). See [Azure OpenAI model retirements](https://learn.microsoft.com/azure/ai-services/openai/concepts/model-retirements) for lifecycle status. All OpenAI model parameters — region, model name, version, and deployment type (Standard/GlobalStandard) — are configurable via `azd env set` before running `azd up`. See [Configure OpenAI Settings](#configure-openai-settings-optional) above for the full list. From 78be91609eceec9d793ac13bd6a2fb43ea941f1a Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 14:02:48 -0700 Subject: [PATCH 14/16] Add DOCUMENTDB_ADMIN_PASSWORD requirement to README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index c7189f0..b45800a 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,13 @@ Deploy the Azure DocumentDB cluster, Azure OpenAI, and other required resources: ```bash azd auth login +azd env set DOCUMENTDB_ADMIN_PASSWORD '' azd up ``` +> [!IMPORTANT] +> You must set `DOCUMENTDB_ADMIN_PASSWORD` before running `azd up`. The password must be 8–128 characters. + This command will: - Prompt you to create a new Azure environment - Provision all infrastructure resources in your Azure subscription From 24800adf185ab624d4d39411c9432416cf43332a Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 14:10:03 -0700 Subject: [PATCH 15/16] Fix BCP333: provide valid default for documentDbAdminPassword Empty default violated @minLength(8) constraint, breaking azd down/up. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 5 ++--- infra/main.bicepparam | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b45800a..ad6917a 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,11 @@ Deploy the Azure DocumentDB cluster, Azure OpenAI, and other required resources: ```bash azd auth login -azd env set DOCUMENTDB_ADMIN_PASSWORD '' azd up ``` -> [!IMPORTANT] -> You must set `DOCUMENTDB_ADMIN_PASSWORD` before running `azd up`. The password must be 8–128 characters. +> [!TIP] +> Set a custom admin password before provisioning: `azd env set DOCUMENTDB_ADMIN_PASSWORD ''`. If not set, a temporary default is used. This command will: - Prompt you to create a new Azure environment diff --git a/infra/main.bicepparam b/infra/main.bicepparam index 0f65f7d..92aebbc 100644 --- a/infra/main.bicepparam +++ b/infra/main.bicepparam @@ -6,7 +6,7 @@ param openAiLocation = readEnvironmentVariable('AZURE_OPENAI_LOCATION', readEnvi param deploymentUserPrincipalId = readEnvironmentVariable('AZURE_PRINCIPAL_ID', '') param currentUserPrincipalId = readEnvironmentVariable('CURRENT_USER_OBJECT_ID', readEnvironmentVariable('AZURE_PRINCIPAL_ID', '')) param documentDbAdminUsername = readEnvironmentVariable('DOCUMENTDB_ADMIN_USERNAME', 'docdbadmin') -param documentDbAdminPassword = readEnvironmentVariable('DOCUMENTDB_ADMIN_PASSWORD', '') +param documentDbAdminPassword = readEnvironmentVariable('DOCUMENTDB_ADMIN_PASSWORD', 'TempP@ss123!') // OpenAI model configuration param chatModelName = readEnvironmentVariable('AZURE_OPENAI_CHAT_MODEL', 'gpt-4.1-mini') From 6719f92ed3dd52707befb1001244f31afcf8597b Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 28 Apr 2026 16:08:36 -0700 Subject: [PATCH 16/16] chore: trigger CI rerun