diff --git a/README.md b/README.md index dca121c..ad6917a 100644 --- a/README.md +++ b/README.md @@ -19,11 +19,59 @@ azd auth login azd up ``` +> [!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 - 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) + +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 | + + +> [!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: @@ -63,6 +111,22 @@ 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**. 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. + +> [!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: diff --git a/ai/vector-search-agent-go/README.md b/ai/vector-search-agent-go/README.md index 5a040ac..2351050 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 @@ -108,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 155cc21..3c32e63 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/). @@ -98,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 diff --git a/ai/vector-search-dotnet/README.md b/ai/vector-search-dotnet/README.md index 21d024f..80f014a 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 @@ -50,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 { @@ -64,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 3a29b81..24c5064 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: @@ -116,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 58ec72d..4564d70 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: @@ -92,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 @@ -106,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 3a46a45..e471519 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: @@ -93,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 75017a2..ac146ae 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: @@ -92,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 @@ -105,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" + diff --git a/infra/main.bicep b/infra/main.bicep index fbe874b..8e6778d 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 = '' @@ -45,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: { @@ -55,23 +69,45 @@ 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' -var chatModelApiVersion = '2024-08-01-preview' -var chatModelType = 'Standard' +// 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 parameters below. +// gpt-4o-mini Standard was deprecated 2026-03-31; use gpt-4.1-mini instead. + +@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 = '2025-04-01-preview' var chatModelCapacity = 50 -var synthModelName = 'gpt-4o' -var synthModelVersion = '2024-11-20' -var synthModelApiVersion = '2024-08-01-preview' -var synthModelType = 'GlobalStandard' +@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 = 'Standard' + +var synthModelApiVersion = '2025-04-01-preview' 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 @@ -88,12 +124,12 @@ 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.14.0' = { name: 'openai' scope: resourceGroup params: { name: openAiServiceName - location: location + location: openAiLocation tags: tags kind: 'OpenAI' sku: 'S0' @@ -191,7 +227,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 diff --git a/infra/main.bicepparam b/infra/main.bicepparam index e374b7f..92aebbc 100644 --- a/infra/main.bicepparam +++ b/infra/main.bicepparam @@ -2,7 +2,19 @@ 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') -param documentDbAdminPassword = 'TempP@ssw0rd123!' +param documentDbAdminPassword = readEnvironmentVariable('DOCUMENTDB_ADMIN_PASSWORD', 'TempP@ss123!') + +// 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', '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')