How to Configure Azure OpenAI Client with API Version, Endpoint, and Deployment

Use the create_azure_openai_client utility function from shared/python/api_utils.py or instantiate AzureOpenAI directly with azure_endpoint, api_version, and api_key parameters while loading credentials from environment variables.

The microsoft/generative-ai-for-beginners repository provides production-ready patterns for configuring the Azure OpenAI client. Proper configuration requires setting the API version, endpoint URL, and deployment name while keeping sensitive credentials out of source code.

Using the Utility Function (Recommended)

The repository includes a centralized helper that standardizes client creation across all lessons.

Implementation Details in api_utils.py

Located in shared/python/api_utils.py, the create_azure_openai_client function handles credential validation and client instantiation. The implementation spans lines 100-104 for the function signature and lines 48-52 for the return statement:

def create_azure_openai_client(
    endpoint: Optional[str] = None,
    api_key: Optional[str] = None,
    api_version: str = "2024-02-01"
) -> Any:
    ...
    return AzureOpenAI(
        azure_endpoint=_endpoint,
        api_key=_api_key,
        api_version=api_version
    )

The function reads AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY from environment variables when arguments are omitted, raising a ValueError if either is missing. You can override the default API version (2024-02-01) with any supported preview or GA version.

from shared.python.api_utils import create_azure_openai_client
from dotenv import load_dotenv
import os

load_dotenv()

client = create_azure_openai_client(
    api_version="2023-12-01-preview"
)

deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT")
response = client.chat.completions.create(
    model=deployment,
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

Direct Client Instantiation

For learning exercises or quick prototypes, you can instantiate the client directly without the utility wrapper.

Example from aoai-app.py

The file 06-text-generation-apps/python/aoai-app.py demonstrates minimal configuration in lines 10-14:

from openai import AzureOpenAI
import os
from dotenv import load_dotenv

load_dotenv()

client = AzureOpenAI(
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version="2024-02-01"
)

The deployment name is loaded separately from AZURE_OPENAI_DEPLOYMENT and passed to the chat.completions.create method (line 23), keeping the client configuration decoupled from model selection.

Managing Environment Variables and Deployment Names

The repository uses a .env file template (.env.copy) to define required variables:

• AZURE_OPENAI_ENDPOINT – Your Azure OpenAI resource URL (e.g., https://my-resource.openai.azure.com/)
• AZURE_OPENAI_API_KEY – Your access key from the Azure portal
• AZURE_OPENAI_DEPLOYMENT – The deployment name you assigned to your model in Azure AI Studio

The python-dotenv package loads these into os.environ before client instantiation, ensuring credentials never appear in committed code.

When calling chat completions, specify the deployment via the model parameter:

deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT")
response = client.chat.completions.create(
    model=deployment,
    messages=[{"role": "user", "content": "Hello"}]
)

Summary

• Use create_azure_openai_client from shared/python/api_utils.py for reusable, validated client configuration across multiple lessons.
• Pass azure_endpoint, api_key, and api_version directly to AzureOpenAI() for simple scripts or learning exercises.
• Store credentials in a .env file and load them with python-dotenv to keep secrets out of source control.
• Specify the model deployment name separately when calling chat.completions.create, not during client initialization.

Frequently Asked Questions

What is the default API version used in the repository?

The default API version is 2024-02-01, defined in the create_azure_openai_client function signature in shared/python/api_utils.py. You can override this with any supported Azure OpenAI API version, such as 2023-12-01-preview for early access to new features.

How does the repository handle missing environment variables?

The create_azure_openai_client utility validates that both AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY are present, either as function arguments or environment variables. If either is missing, the function raises a ValueError with a descriptive message before attempting to instantiate the client.

Where should I store my Azure OpenAI credentials?

According to the repository patterns, credentials should be stored in a .env file at the project root (using the provided .env.copy template). The python-dotenv library loads these variables into the process environment at runtime, ensuring that sensitive keys and endpoints never appear in committed source code.

How do I specify the model deployment in API calls?

The deployment name (the identifier you assigned when deploying the model in Azure AI Studio) is passed to the model parameter of client.chat.completions.create(), not during client initialization. Retrieve this value from the AZURE_OPENAI_DEPLOYMENT environment variable and pass it at request time to switch between different models without recreating the client.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}