Merge pull request #70 from diberry/infra/update-openai-models-tier

diberry · web-flow · commit 9db626acbd31 · 2026-04-29T06:54:45.000-07:00
Update infra: gpt-4.1 models, AVM 0.10.0, tier comments
diff --git 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 '<your-secure-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 <new-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 <region>` 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/infra/main.bicepparam b/infra/main.bicepparam
