Gehostete Agent-Infrastruktur mit der Azure Developer CLI

Die Azure Developer CLI (azd) kann Bicep- oder Terraform-Infrastruktur aus den deklarierten azure.yamlDiensten generieren. Wählen Sie Terraform mit azd ai agent init --infra=terraform, oder Bicep mit --infra=bicep. Beim Ausführen von azd provision wird die ausgewählte Infrastruktur angewendet.

Infrastrukturbereitstellung und Agentbereitstellung sind getrennt. Terraform oder Bicep verwalten unterstützende Azure-Ressourcen; azd deploy erstellt die Data-Plane-Version des gehosteten Agents. Informationen zum Verwalten des Agenten selbst mit Terraform anstelle von Azd finden Sie unter Bereitstellen eines gehosteten Agenten mit Terraform.

Was bereitgestellt wird

Standardmäßig erstellt azd ai agent init keine Infrastructure-as-Code-Dateien. Verwenden Sie --infra oder --infra=bicep, um Bicep-Infrastruktur hinzuzufügen. Verwenden Sie --infra=terraform, um Terraform-Infrastruktur hinzuzufügen und infra.provider: terraform festzulegen.

Wenn Sie Bicep Infrastruktur hinzufügen, basieren die Vorlagen auf dem azd-ai-starter-basic-Repository und erstellen die folgenden Azure Ressourcen:

Die Vorlagen erstellen abhängig von den in azure.yaml deklarierten Diensten und Abhängigkeiten weitere Ressourcen:

• Agent-Funktionseinstellungen – deklarieren Sie die Azure Ressourcen, die Agentstatus, Vektordaten und Dateien enthalten. Legen Sie sie fest, wenn Agents ihren eigenen Speicher verwenden müssen.
• Grounding with Bing oder Grounding with Bing Custom Search: Für das Websuchtool.
• Azure KI-Suche – zur Suchfundierung.
• Azure Storage – für Dateivorgänge.

Projektstruktur

Für Bicep weist ein generiertes Projekt die folgende Struktur auf:

infra/
|-- main.bicep                 # Main deployment template (subscription-scoped)
|-- main.parameters.json       # Parameter bindings to azd environment variables
|-- abbreviations.json         # Naming convention abbreviations
\-- core/
    |-- ai/                    # Foundry account, project, and connections
    |-- host/                  # Container registry
    |-- monitor/               # Application Insights and Log Analytics
    |-- search/                # Azure AI Search (conditional)
    \-- storage/               # Azure Storage (conditional)

Wie Parameter fließen

Für Bicep ordnet azd die main.parameters.json Datei Umgebungsvariablen Parametern zu:

{
  "environmentName": { "value": "${AZURE_ENV_NAME}" },
  "location": { "value": "${AZURE_LOCATION}" },
  "aiFoundryResourceName": { "value": "${AZURE_AI_ACCOUNT_NAME}" },
  "aiProjectDeploymentsJson": { "value": "${AI_PROJECT_DEPLOYMENTS=[]}" }
}

Während azd provision löst azd diese ${VAR}-Verweise aus der Umgebung (.azure/<env>/.env) auf und übergibt sie an die Bicep-Bereitstellung. Ausgaben aus der Bereitstellung, z. B. der Foundry-Projektendpunkt, der Modellbereitstellungsname und der Containerregistrierungsendpunkt, werden zur Verwendung durch azd deploy, azd ai agent run und die azd ai-Ressourcenbefehle in die Umgebung zurückgeschrieben.

Terraform-Infrastruktur

Für ein neues Projekt generiert azd ai agent init --infra=terraform Dateien wie die folgenden:

infra/
|-- main.tf
|-- provider.tf
|-- variables.tf
|-- outputs.tf
|-- main.tfvars.json
\-- .azd-foundry

Containerbasierte Dienste können auch container-registry.tf generieren. Vorhandene Projekte können ihre Infrastruktur beibehalten und eine separate Foundry-Ebene unter infra/foundry/ erhalten. Verwenden Sie das tatsächliche generierte Layout, anstatt Dateien zwischen Ebenen zu verschieben.

Die Terraform-Konfiguration stellt das Foundry-Konto, das Projekt, die Modellbereitstellungen und die zugehörigen Ressourcen bereit, die von den ausgewählten Diensten benötigt werden. Die Erstellung der Containerregistrierung hängt vom Bereitstellungsmodus und der Imagekonfiguration ab.

main.tfvars.json bindet Infrastruktureingaben an azd-Umgebungswerte. outputs.tf stellt azd nach der Bereitstellung Werte wie den Foundry-Projektendpunkt zur Verfügung. Diese Bindungen sind Teil des azd-Workflows; gehen Sie nicht davon aus, dass eine generierte Parameterdatei mit einer eigenständigen terraform applyDatei unverändert funktioniert.

Um die Terraform-Infrastruktur anzupassen, bearbeiten Sie die generierten .tf-Dateien, behalten Sie die für Ihre Agent-Dienste benötigten Ausgaben bei, und führen Sie azd provision aus. Überprüfen Sie den Terraform-Plan, bevor Sie Infrastrukturänderungen anwenden.

Terraform State und CI/CD

Die generierten Dateien initialisieren kein Backend für den Remote-Status. Konfigurieren Sie bei Teambereitstellungen den in Azure Storage gespeicherten Status, separate State-Schlüssel für jede Umgebung und die erforderlichen Backend-Berechtigungen, bevor Sie CI/CD konfigurieren.

Siehe Einrichten von CI/CD mit Terraform für den Bereitstellungsfluss und Verwenden von Terraform mit azd für die Back-End-Konfiguration.

Einschränkungen beim Terraform-Auswurf

Der Terraform-Ejection-Pfad unterstützt die Service-network:-Konfiguration in der aktuellen Foundry-Agents-Erweiterung nicht. Überprüfen Sie vorhandene Ressourceneinschränkungen, bevor Sie ein Projekt auswerfen, das bereits über eine Infrastruktur verfügt. Ejection ist keine allgemeine Migration des Zustands von Bicep zu Terraform, und das Löschen von Produktionsressourcen ist keine Voraussetzung für den Umstieg auf Terraform.

Vorhandene Ressourcen

Die Bicep-Vorlagen unterstützen das Herstellen einer Verbindung mit vorhandenen Azure Ressourcen, anstatt neue zu erstellen. Dies ist nützlich, wenn Ihr Team bereits über eine gemeinsame Infrastruktur verfügt.

Legen Sie diese Variablen mit azd env set fest, bevor Sie azd provision ausführen.

Anpassen der Infrastruktur

Das infra/-Verzeichnis ist Standardbestandteil der azd-Infrastruktur. So fügen Sie Bicep Ressourcen hinzu oder ändern sie:

1. Bearbeiten infra/main.bicep oder Hinzufügen neuer Module unter infra/core/.
2. Fügen Sie main.parameters.json neue Parameter mit ${VAR}-Bindungen hinzu.
3. Legen Sie die entsprechenden azd Umgebungsvariablen mit azd env set fest.
4. Führen Sie azd provision aus, um die Änderungen anzuwenden.

Änderungen an den Bicep-Dateien bleiben über Bereitstellungen hinweg erhalten.

Regionseinschränkungen

Die Vorlage main.bicep beschränkt location auf Regionen, in denen gehostete Agenten unterstützt werden. Wenn Sie in einer Region bereitstellen müssen, die nicht in der Liste der zulässigen Regionen enthalten ist, aktualisieren Sie den @allowed-Decorator in main.bicep.

Verwandte Inhalte

• Azure.yaml-Referenz für gehostete Agents
• Einrichten von CI/CD für gehostete Agents
• azd-ai-starter-basic Repository