AZD初学者：结构化学习之旅

本文集文档发布于灏天文库

4.配置模板

文档摘要

配置模板 !!! tip "完成本模块后，您将能够：" [ ] 理解 的用途 [ ] 理解 的结构 [ ] 理解 azd 生命周期 的价值 [ ] 实验 3： !!! prompt " 文件的作用是什么？使用代码块并逐行解释" 文件是 Azure Developer CLI (azd) 的配置文件。它定义了如何将您的应用程序部署到 Azure，包括基础设施、服务、部署钩子和环境变量。

4. 配置模板

!!! tip "完成本模块后，您将能够："

- [ ] 理解 `azure.yaml` 的用途
- [ ] 理解 `azure.yaml` 的结构
- [ ] 理解 azd 生命周期 `hooks` 的价值
- [ ] **实验 3：**
​

!!! prompt "azure.yaml 文件的作用是什么？使用代码块并逐行解释"

  `azure.yaml` 文件是 **Azure Developer CLI (azd) 的配置文件**。它定义了如何将您的应用程序部署到 Azure，包括基础设施、服务、部署钩子和环境变量。
​

1. 目的与功能

azure.yaml 文件是一个 AI代理应用程序的部署蓝图，它可以：

  1. 在部署前验证环境
  2. 配置 Azure AI 服务（AI Hub、AI Project、Search 等）
  3. 将 Python 应用程序部署到 Azure 容器应用
  4. 配置 AI 模型以支持聊天和嵌入功能
  5. 设置监控和追踪以管理 AI 应用程序
  6. 处理新建和现有 Azure AI 项目场景

该文件支持 一键部署 (azd up) 完整的 AI 代理解决方案，包括验证、配置和后续部署设置。

??? info "展开查看：azure.yaml"

  `azure.yaml` 文件定义了 Azure Developer CLI 如何在 Azure 中部署和管理此 AI 代理应用程序。我们逐行解析它。

  ```yaml title="" linenums="0"

  # yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
  # TODO: 我们是否需要 hooks？
  # TODO: 我们是否需要所有变量？

  name: azd-get-started-with-ai-agents
  metadata:
  template: azd-get-started-with-ai-agents@1.0.2
  requiredVersions:
  azd: ">=1.14.0"

  hooks:
  preup:
  posix:
        shell: sh
        run: chmod u+r+x ./scripts/validate_env_vars.sh; ./scripts/validate_env_vars.sh
        interactive: true
        continueOnError: false
  windows:
        shell: pwsh
        run: ./scripts/validate_env_vars.ps1
        interactive: true
        continueOnError: false      
  postprovision:
  windows:
        shell: pwsh
        run: ./scripts/write_env.ps1
        continueOnError: true
        interactive: true
  posix:
        shell: sh
        run: chmod u+r+x ./scripts/write_env.sh; ./scripts/write_env.sh;
        continueOnError: true
        interactive: true
  postdeploy:
  windows:
        shell: pwsh
        run: ./scripts/postdeploy.ps1
        continueOnError: true
        interactive: true
  posix:
        shell: sh
        run: chmod u+r+x ./scripts/postdeploy.sh; ./scripts/postdeploy.sh;
        continueOnError: true
        interactive: true
  services:
  api_and_frontend:
  project: ./src
  language: py
  host: containerapp
  docker:
        image: api_and_frontend
        remoteBuild: true
  pipeline:
  variables:
  - AZURE_RESOURCE_GROUP
  - AZURE_AIHUB_NAME
  - AZURE_AIPROJECT_NAME
  - AZURE_AISERVICES_NAME
  - AZURE_SEARCH_SERVICE_NAME
  - AZURE_APPLICATION_INSIGHTS_NAME
  - AZURE_CONTAINER_REGISTRY_NAME
  - AZURE_KEYVAULT_NAME
  - AZURE_STORAGE_ACCOUNT_NAME
  - AZURE_LOG_ANALYTICS_WORKSPACE_NAME
  - USE_CONTAINER_REGISTRY
  - USE_APPLICATION_INSIGHTS
  - USE_AZURE_AI_SEARCH_SERVICE
  - AZURE_AI_AGENT_NAME
  - AZURE_AI_AGENT_ID
  - AZURE_AI_AGENT_DEPLOYMENT_NAME
  - AZURE_AI_AGENT_DEPLOYMENT_SKU
  - AZURE_AI_AGENT_DEPLOYMENT_CAPACITY
  - AZURE_AI_AGENT_MODEL_NAME
  - AZURE_AI_AGENT_MODEL_FORMAT
  - AZURE_AI_AGENT_MODEL_VERSION
  - AZURE_AI_EMBED_DEPLOYMENT_NAME
  - AZURE_AI_EMBED_DEPLOYMENT_SKU
  - AZURE_AI_EMBED_DEPLOYMENT_CAPACITY
  - AZURE_AI_EMBED_MODEL_NAME
  - AZURE_AI_EMBED_MODEL_FORMAT
  - AZURE_AI_EMBED_MODEL_VERSION
  - AZURE_AI_EMBED_DIMENSIONS
  - AZURE_AI_SEARCH_INDEX_NAME
  - AZURE_EXISTING_AIPROJECT_RESOURCE_ID
  - AZURE_EXISTING_AIPROJECT_ENDPOINT
  - AZURE_EXISTING_AGENT_ID
  - ENABLE_AZURE_MONITOR_TRACING
  - AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED
  ```
​

2. 文件解析

我们逐部分解析文件，了解它的功能和意义。

2.1 头部和模式 (1-3)

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
​
  • 第 1 行：提供 YAML 语言服务器模式验证，用于 IDE 支持和智能提示

2.2 项目元数据 (5-10)

name: azd-get-started-with-ai-agents
metadata:
  template: azd-get-started-with-ai-agents@1.0.2
requiredVersions:
  azd: ">=1.14.0"
​
  • 第 5 行：定义 Azure Developer CLI 使用的项目名称
  • 第 6-7 行：指定基于模板版本 1.0.2
  • 第 8-9 行：要求 Azure Developer CLI 版本 1.14.0 或更高

2.3 部署钩子 (11-40)

hooks:
  preup:
    posix:
      shell: sh
      run: chmod u+r+x ./scripts/validate_env_vars.sh; ./scripts/validate_env_vars.sh
      interactive: true
      continueOnError: false
    windows:
      shell: pwsh
      run: ./scripts/validate_env_vars.ps1
      interactive: true
      continueOnError: false      
​

  • 第 11-20 行：预部署钩子 - 在运行 azd up 之前执行

    - 在 Unix/Linux 上：使验证脚本可执行并运行
- 在 Windows 上：运行 PowerShell 验证脚本
- 两者均为交互式，若失败将停止部署
​
  postprovision:
    windows:
      shell: pwsh
      run: ./scripts/write_env.ps1
      continueOnError: true
      interactive: true
    posix:
      shell: sh
      run: chmod u+r+x ./scripts/write_env.sh; ./scripts/write_env.sh;
      continueOnError: true
      interactive: true
​

  • 第 21-30 行：后置资源配置钩子 - 在 Azure 资源创建后执行

    • 执行写入环境变量的脚本
    • 即使脚本失败也继续部署 (continueOnError: true)
  postdeploy:
    windows:
      shell: pwsh
      run: ./scripts/postdeploy.ps1
      continueOnError: true
      interactive: true
    posix:
      shell: sh
      run: chmod u+r+x ./scripts/postdeploy.sh; ./scripts/postdeploy.sh;
      continueOnError: true
      interactive: true
​

  • 第 31-40 行：后置部署钩子 - 在应用程序部署后执行

    • 执行最终设置脚本
    • 即使脚本失败也继续

2.4 服务配置 (41-48)

此部分配置您要部署的应用服务。

services:
  api_and_frontend:
    project: ./src
    language: py
    host: containerapp
    docker:
      image: api_and_frontend
      remoteBuild: true
​

  • 第 42 行：定义名为 "api_and_frontend" 的服务

  • 第 43 行：指向 ./src 目录作为源代码位置

  • 第 44 行：指定 Python 为编程语言

  • 第 45 行：使用 Azure 容器应用作为托管平台

  • 第 46-48 行：Docker 配置

    - 使用 "api_and_frontend" 作为镜像名称
- 在 Azure 中远程构建 Docker 镜像（而非本地）
​

2.5 管道变量 (49-76)

这些变量用于在 CI/CD 管道中运行 azd 以实现自动化。

pipeline:
  variables:
    - AZURE_RESOURCE_GROUP
    - AZURE_AIHUB_NAME
    - AZURE_AIPROJECT_NAME
    - AZURE_AISERVICES_NAME
    - AZURE_SEARCH_SERVICE_NAME
    - AZURE_APPLICATION_INSIGHTS_NAME
    - AZURE_CONTAINER_REGISTRY_NAME
    - AZURE_KEYVAULT_NAME
    - AZURE_STORAGE_ACCOUNT_NAME
    - AZURE_LOG_ANALYTICS_WORKSPACE_NAME
    - USE_CONTAINER_REGISTRY
    - USE_APPLICATION_INSIGHTS
    - USE_AZURE_AI_SEARCH_SERVICE
    - AZURE_AI_AGENT_NAME
    - AZURE_AI_AGENT_ID
    - AZURE_AI_AGENT_DEPLOYMENT_NAME
    - AZURE_AI_AGENT_DEPLOYMENT_SKU
    - AZURE_AI_AGENT_DEPLOYMENT_CAPACITY
    - AZURE_AI_AGENT_MODEL_NAME
    - AZURE_AI_AGENT_MODEL_FORMAT
    - AZURE_AI_AGENT_MODEL_VERSION
    - AZURE_AI_EMBED_DEPLOYMENT_NAME
    - AZURE_AI_EMBED_DEPLOYMENT_SKU
    - AZURE_AI_EMBED_DEPLOYMENT_CAPACITY
    - AZURE_AI_EMBED_MODEL_NAME
    - AZURE_AI_EMBED_MODEL_FORMAT
    - AZURE_AI_EMBED_MODEL_VERSION
    - AZURE_AI_EMBED_DIMENSIONS
    - AZURE_AI_SEARCH_INDEX_NAME
    - AZURE_EXISTING_AIPROJECT_RESOURCE_ID
    - AZURE_EXISTING_AIPROJECT_ENDPOINT
    - AZURE_EXISTING_AGENT_ID
    - ENABLE_AZURE_MONITOR_TRACING
    - AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED
​

此部分定义了 部署期间 使用的环境变量，按类别组织：

  • Azure 资源名称 (第 51-60 行)：
    - 核心 Azure 服务资源名称，例如资源组、AI Hub、AI Project 等
  • 功能开关 (第 61-63 行)：
    - 启用/禁用特定 Azure 服务的布尔变量
  • AI 代理配置 (第 64-71 行)：
    - 主 AI 代理的配置，包括名称、ID、部署设置、模型详情
  • AI 嵌入配置 (第 72-79 行)：
    - 用于向量搜索的嵌入模型配置
  • 搜索与监控 (第 80-84 行)：
    - 搜索索引名称、现有资源 ID 和监控/追踪设置

3. 了解环境变量

以下环境变量控制您的部署配置和行为，按主要用途组织。大多数变量有合理的默认值，但您可以根据具体需求或现有 Azure 资源进行自定义。

3.1 必需变量

# Core Azure Configuration
AZURE_ENV_NAME                    # Environment name (used in resource naming)
AZURE_LOCATION                    # Deployment region
AZURE_SUBSCRIPTION_ID             # Target subscription
AZURE_RESOURCE_GROUP              # Resource group name
AZURE_PRINCIPAL_ID                # User principal for RBAC

# Resource Names (Auto-generated if not specified)
AZURE_AIHUB_NAME                  # AI Foundry hub name
AZURE_AIPROJECT_NAME              # AI project name
AZURE_AISERVICES_NAME             # AI services account name
AZURE_STORAGE_ACCOUNT_NAME        # Storage account name
AZURE_CONTAINER_REGISTRY_NAME     # Container registry name
AZURE_KEYVAULT_NAME               # Key Vault name (if used)
​

3.2 模型配置

# Chat Model Configuration
AZURE_AI_AGENT_MODEL_NAME         # Default: gpt-4o-mini
AZURE_AI_AGENT_MODEL_FORMAT       # Default: OpenAI (or Microsoft)
AZURE_AI_AGENT_MODEL_VERSION      # Default: latest available
AZURE_AI_AGENT_DEPLOYMENT_NAME    # Deployment name for chat model
AZURE_AI_AGENT_DEPLOYMENT_SKU     # Default: Standard
AZURE_AI_AGENT_DEPLOYMENT_CAPACITY # Default: 80 (thousands of TPM)

# Embedding Model Configuration  
AZURE_AI_EMBED_MODEL_NAME         # Default: text-embedding-3-small
AZURE_AI_EMBED_MODEL_FORMAT       # Default: OpenAI
AZURE_AI_EMBED_MODEL_VERSION      # Default: latest available
AZURE_AI_EMBED_DEPLOYMENT_NAME    # Deployment name for embeddings
AZURE_AI_EMBED_DEPLOYMENT_SKU     # Default: Standard
AZURE_AI_EMBED_DEPLOYMENT_CAPACITY # Default: 50 (thousands of TPM)

# Agent Configuration
AZURE_AI_AGENT_NAME               # Agent display name
AZURE_EXISTING_AGENT_ID           # Use existing agent (optional)
​

3.3 功能开关

# Optional Services
USE_APPLICATION_INSIGHTS         # Default: true
USE_AZURE_AI_SEARCH_SERVICE      # Default: false
USE_CONTAINER_REGISTRY           # Default: true

# Monitoring and Tracing
ENABLE_AZURE_MONITOR_TRACING     # Default: false
AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED # Default: false

# Search Configuration
AZURE_AI_SEARCH_INDEX_NAME       # Search index name
AZURE_SEARCH_SERVICE_NAME        # Search service name
​

3.4 AI 项目配置

# Use Existing Resources
AZURE_EXISTING_AIPROJECT_RESOURCE_ID    # Full resource ID of existing AI project
AZURE_EXISTING_AIPROJECT_ENDPOINT       # Endpoint URL of existing project
​

3.5 检查您的变量

使用 Azure Developer CLI 查看和管理您的环境变量：

# View all environment variables for current environment
azd env get-values

# Get a specific environment variable
azd env get-value AZURE_ENV_NAME

# Set an environment variable
azd env set AZURE_LOCATION eastus

# Set multiple variables from a .env file
azd env set --from-file .env
​
发布者: 作者: 转发
评论区 (0)
U
0/500