Azure-Ressourcen für lokale Umgebungen erstellen
Dieses Thema richtet sich an Administratoren lokaler Windchill Systeme.
Übersicht
Das Windchill AI Assistant Plugin erfordert mehrere Microsoft Azure Dienste, um Windchill Benutzern in einer lokalen Umgebung KI-gestützte Funktionen bereitzustellen.
Das Plugin verwendet die folgenden Azure-Dienste:
• Azure AI Search – Für die Dokumentenindexierung und -suche
• Azure AI Foundry: Zum Abschließen von Chats und zur Vektorisierung von Dokumenten
• Azure Storage – Für die vorübergehende Erfassung von Dokumenten
• Azure Entra ID – Für die Verwaltung von Dienstprinzipalen und die rollenbasierte Zugriffssteuerung
• Azure-Bereitstellungsskripte: Für die automatisierte Bereitstellung der Infrastruktur
Alle erforderlichen Azure-Dienste werden mithilfe von Infrastructure as Code (IaC) über Vorlagen aus Azure Resource Manager (ARM) definiert und bereitgestellt.
Das Plugin authentifiziert sich bei Endpunkten in Azure AI Search, Azure AI Foundry und Azure Storage mithilfe von Azure Entra ID-Dienstprinzipalen. Die Autorisierung wird über die rollenbasierte Zugriffssteuerung erzwungen.
Konten für Azure AI Search, Azure AI Foundry und Azure Storage werden mit öffentlichen Endpunkten bereitgestellt, die durch konfigurierbare, IP-basierte Firewall-Regeln geschützt sind. Der Netzwerkzugriff kann auf genehmigte Client-IP-Bereiche beschränkt werden.
Der Bereitstellungsbesitzer ist dafür verantwortlich, diese Netzwerkzugriffssteuerungen in Übereinstimmung mit den Sicherheits- und Compliance-Anforderungen seiner Organisation zu prüfen und zu konfigurieren.
Voraussetzungen
Stellen Sie sicher, dass die folgenden Voraussetzungen erfüllt sind, bevor Sie Azure-Ressourcen für das Windchill AI Assistant Plugin bereitstellen:
• Python 3.10.0 oder höher ist auf dem System installiert, das für die Bereitstellung verwendet wird.
• Sie haben die Datei AI_Assistant_Plugin_Azure_IaC.zip heruntergeladen, die unten im Fenster Windchill AI Assistant - Konfiguration verfügbar ist.
◦ Klicken Sie im Plugin-Manager mit der rechten Maustaste auf Windchill AI Assistant, und wählen Sie Plugin konfigurieren aus.
 | Mit diesem Verfahren erstellte Azure-Ressourcen dürfen ausschließlich für das Windchill AI Assistant Plugin verwendet werden. |
Verfahren
Führen Sie die folgenden Schritte aus, um die erforderlichen Azure-Ressourcen zu erstellen:
Schritt Nr. | Aufgabe |
|---|---|
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 |
Schritt 1: Azure CLI installieren und Python überprüfen
Installieren Sie die Azure-Befehlszeilenschnittstelle (Command-Line Interface, CLI), und stellen Sie sicher, dass Python 3.10 oder höher auf dem Bereitstellungssystem verfügbar ist.
• Der Befehl az wird für die Kommunikation mit Azure während der Bereitstellung verwendet.
• Der Befehl python3 wird verwendet, um das Bereitstellungs-Hilfsskript auszuführen.
Spezifische Installationsanweisungen für Ihr Betriebssystem finden Sie in der offiziellen Dokumentation zum Azure Command-Line Interface (CLI).
Schritt 2: Azure-Ressourcengruppe erstellen
Erstellen Sie eine neue Azure-Ressourcengruppe, um die Ressourcen für Windchill AI Assistant zu hosten. Weitere Informationen finden Sie unter Ressourcengruppen verwalten.
 | Die Vorlage für Azure Resource Manager (ARM) wird in dieser Ressourcengruppe bereitgestellt. |
Schritt 3: Dienstprinzipal erstellen
Erstellen Sie einen Azure Entra ID-Dienstprinzipal für die Authentifizierung des Plugins bei Azure-Ressourcen.
1. Öffnen Sie ein Terminal oder eine Eingabeaufforderung in einem System, auf dem Azure CLI installiert ist.
2. Melden Sie sich mit einer Identität an, die Entra ID-Dienstprinzipale erstellen kann.
3. Führen Sie den folgenden Befehl aus, um einen neuen Dienstprinzipal zu erstellen:
az ad sp create-for-rbac \
--display-name "<Display name>"
--display-name "<Display name>"
Geben Sie in <Display name> den erforderlichen Anzeigenamen an. Beispiel: wcaiassistant-onprem-sp.
Der Befehl gibt Werte, die den folgenden ähneln, aus:
{
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
Speichern Sie client ID, client secret und tenant ID sicher.
Diese Werte sind später während der Plugin-Konfiguration erforderlich.
Rufen Sie die Objekt-ID des Dienstprinzipals ab, indem Sie den folgenden Befehl ausführen:
az ad sp show --id <client-id> --query id -o tsv
Die Objekt-ID wird zu einem späteren Zeitpunkt während der IaC-Konfiguration benötigt.
Schritt 4: Mit der Azure CLI anmelden und erforderliche Rollen überprüfen
1. Öffnen Sie ein Terminal oder eine Eingabeaufforderung, auf dem/der Azure CLI installiert ist.
3. Stellen Sie sicher, dass dem angemeldeten Benutzer oder Dienstprinzipal in der Ressourcengruppe die Rolle "Mitwirkender" oder zumindest die folgenden Rollen zugewiesen sind:
◦ Cognitive Services-Mitwirkender
◦ Cognitive Services OpenAI-Benutzer
◦ Suchdienst-Mitwirkender
◦ Speicherkonto-Mitwirkender
◦ Eine benutzerdefinierte Rolle, die die folgenden Aktionen zulässt:
▪ Microsoft.Resources/deploymentScripts/read
▪ Microsoft.Resources/deploymentScripts/write
4. Stellen Sie sicher, dass dem angemeldeten Benutzer oder Dienstprinzipal die Administratorrolle für rollenbasierte Zugriffssteuerung für die Ressourcengruppe zugewiesen ist.
Schritt 5: ARM-Vorlage und Parameterdatei vorbereiten
1. Kopieren Sie die folgenden Dateien in ein lokales Arbeitsverzeichnis:
◦ wcaia.json (ARM-Vorlagendatei)
◦ wcaia.parameters.json (Parameterdatei)
◦ deploy-wcaia.py (Bereitstellungs-Hilfsskript)
2. Bearbeiten Sie die Datei wcaia.parameters.json, und geben Sie Werte für die erforderlichen Parameter an.
 | Füllen Sie die zum Token gehörigen Parameter (z.B. management_token, management_token_expires_on, search_token und search_token_expires_on) nicht aus. Diese Werte werden automatisch vom Bereitstellungs-Hilfsskript festgelegt. |
a. Geben Sie den location aus den folgenden unterstützten Azure-Regionen an:
▪ australiaeast
▪ brazilsouth
▪ canadaeast
▪ eastus
▪ eastus2
▪ francecentral
▪ germanywestcentral
▪ italynorth
▪ japaneast
▪ koreacentral
▪ northcentralus
▪ polandcentral
▪ southafricanorth
▪ southcentralus
▪ spaincentral
▪ swedencentral
▪ switzerlandnorth
▪ uaenorth
▪ uksouth
▪ westus
▪ westus3
| | In der Microsoft-Dokumentation Azure AI Search regions list finden Sie regionsspezifische Einschränkungen, z.B.: • Kapazitätsbeschränkungen, die Bereitstellungsfehler verursachen können • Geringere Speichergrenzwerte (z.B. 25 GB statt 160 GB), die möglicherweise die Indexierung bestimmter Daten verhindern. • Fehlende Verfügbarkeitszonen, die die Verfügbarkeitsgarantien verringern können. |
b. Geben Sie Ressourcen-Tags in common_tags an (optional).
Wenn Ihre Organisation eine Tagging-Richtlinie erzwingt, kann das Fehlen erforderlicher Tags zu einem RequestDisallowedByPolicy Fehler bei der Ressourcenerstellung führen.
c. Legen Sie service_principal_id auf die Objekt-ID (auch Prinzipal-ID genannt) des Dienstprinzipals fest, der in Schritt 3: Dienstprinzipal erstellen erstellt wurde.
| | Dieser Wert ist nicht die Client-ID des Dienstprinzipals. Die Objekt-ID kann aus der Client-ID abgerufen werden, indem Sie den folgenden Befehl ausführen: az ad sp show --id <client-id> --query id -o tsv |
d. Füllen Sie allowed_ips mit einer Liste von IPv4-Adressen oder CIDR-Bereichen, die auf die Azure-Ressourcen zugreifen können.
▪ Fügen Sie die IP-Adressen für alle Hosts, die das Plugin ausführen, hinzu.
▪ Wenn Sie die Liste leer lassen ([]), wird die Firewall deaktiviert.
| | Azure-Ressourcen werden in öffentlichen Internetadressbereichen verfügbar gemacht. Geben Sie für Hosts auf internen Netzwerken (hinter NAT) die IP-Adresse für öffentlichen ausgehenden Datenverkehr (NAT Gateway) oder den CIDR-Bereich an. |
e. Legen Sie ai_search_partition_count auf die erforderliche Anzahl von Azure AI Search Standard S1-Partitionen fest. Weitere Informationen finden Sie unter Anzahl der Partitionen in Azure AI Search schätzen.
f. (Optional) Legen Sie den text_embedding_capacity Parameter nur dann auf einen niedrigeren Wert als den Standardwert von 4000 Kapazitätseinheiten (4 Millionen Token pro Minute) fest, wenn in der bereitgestellten AI Foundry-Region keine ausreichende Kapazität für das Texteinbettungsmodell verfügbar ist.
| | Die Indexierungsgeschwindigkeit hängt von der verfügbaren Texteinbettungskapazität ab. Wenn der konfigurierte Wert die verfügbaren Grenzwerte überschreitet, meldet das Bereitstellungs-Hilfsskript die tatsächlich verfügbare Kapazität. |
g. (Optional) Standardmäßig ist die Konfiguration storage_sku_name für die Redundanz des Azure-Speicherkontos auf Standard_LRS (lokal redundanter Speicher) festgelegt. Sie können diesen Wert in Regionen, in denen zusätzliche Optionen unterstützt werden, in eine andere Redundanzebene ändern.
| | Speichern Sie alle Anmeldeinformationen sicher im Sicherheitstresor Ihres Unternehmens, um bei Bedarf zuverlässigen Zugriff zu gewährleisten. |
Beispiel für eine Parameterdatei:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"management_token": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"management_token_expires_on": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"search_token": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"search_token_expires_on": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"location": {
"value": "swedencentral"
},
"common_tags": {
"value": {
"environment": "QA",
"purpose": "Windchill AI Assistant"
}
},
"service_principal_id": {
"value": "00000000-0000-0000-0000-000000000000"
},
"allowed_ips": {
"value": []
},
"ai_search_partition_count": {
"value": 1
},
"text_embedding_capacity": {
"value": 4000
},
"storage_sku_name": {
"value": “Standard_LRS”
} }
}
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"management_token": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"management_token_expires_on": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"search_token": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"search_token_expires_on": {
"value": "SET_BY_PYTHON_SCRIPT"
},
"location": {
"value": "swedencentral"
},
"common_tags": {
"value": {
"environment": "QA",
"purpose": "Windchill AI Assistant"
}
},
"service_principal_id": {
"value": "00000000-0000-0000-0000-000000000000"
},
"allowed_ips": {
"value": []
},
"ai_search_partition_count": {
"value": 1
},
"text_embedding_capacity": {
"value": 4000
},
"storage_sku_name": {
"value": “Standard_LRS”
} }
}
Schritt 6: Eindeutigen Bereitstellungsnamen definieren
Definieren Sie einen global eindeutigen Bereitstellungsnamen. Der Bereitstellungsname wird als Präfix für Azure-Ressourcennamen verwendet.
Der Bereitstellungsname muss die folgenden Anforderungen erfüllen:
• Er darf nur Kleinbuchstaben und Zahlen enthalten.
• Er darf höchstens 20 Zeichen enthalten.
Beispiele:
• acmeaidev
• companywcaiprod
• ai2025subscracme
Schritt 7: Azure-Ressourcen erstellen
Führen Sie zum Erstellen der erforderlichen Azure-Ressourcen den folgenden Befehl in dem Verzeichnis aus, das die ARM-Vorlagendateien und das Bereitstellungs-Hilfsskript enthält:
python3 deploy-wcaia.py
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
Dabei gilt:
• ${RESOURCE_GROUP} ist der Name der Azure-Ressourcengruppe.
• ${DEPLOYMENT_NAME} ist der eindeutige Vorlagen-Bereitstellungsname.
Konfigurationsausgabe vom Bereitstellungs-Hilfsskript
Nach einer erfolgreichen Bereitstellung generiert das Bereitstellungs-Hilfsskript die Konfigurationswerte, die zur Verbindung des Windchill AI Assistant Plugins mit seinen Azure-Diensten erforderlich sind. Diese Werte müssen während der Plugin-Konfiguration eingegeben werden.
Das Bereitstellungs-Hilfsskript stellt Konfigurationswerte für die folgenden Azure-Dienste bereit, die von Windchill AI Assistant verwendet werden:
• Azure AI Search
• Azure OpenAI
• Azure Storage
Verwenden Sie beim Konfigurieren des Plugins die vom Skript generierten Werte. Die Konfigurationsschritte werden unter Windchill AI Assistant Plugin konfigurieren beschrieben.
Sie können mit dem Bereitstellungs-Hilfsskript auch Konfigurationswerte aus einer bereits abgeschlossenen Bereitstellung abrufen, indem Sie das Skript mit der Befehlszeilenoption --skip-deployment ausführen.
| | • Der geheime Clientschlüssel für den Azure-Dienstprinzipal ist nur zum Zeitpunkt der Erstellung verfügbar. Wenn der geheime Clientschlüssel nicht länger verfügbar ist, müssen Sie einen neuen geheimen Clientschlüssel im Azure-Portal erstellen, bevor Sie mit der Plugin-Konfiguration fortfahren können. • In seltenen Fällen können vorübergehende Race-Bedingungen innerhalb des Azure-Bereitstellungsprozesses dazu führen, dass das Skript angehalten wird und einen Fehler meldet. Bereinigen Sie in diesem Fall alle Teilinstallationen, und führen Sie dann das Bereitstellungsskript erneut aus. |
Das folgende Beispiel zeigt eine typische Konfigurationsausgabe, die vom Bereitstellungs-Hilfsskript generiert wurde. Die tatsächlichen Werte variieren je nach Umgebung.
====================================
Windchill AI Assistant Configuration
Azure AI Search
Endpoint
https://acmedev-ai-search.search.windows.net
Index Name -- choose one of
default
another
Authentication Mode -- take from shared authentication configuration below
Azure OpenAI
Endpoint
https://acmedev-ai-foundry.cognitiveservices.azure.com/
Deployment
gpt-5-mini
Authentication Mode -- take from shared authentication configuration below
Azure Storage
Account Name
acmedevdti
Container Name -- choose the one matching the index name
default
another
Authentication Mode -- take from shared authentication configuration below
-------------------------------------
(shared authentication configuration)
Authentication Mode
Service Principal
Tenant ID
31c9c31c-7621-4f8f-ae11-4e462f1be7ed
Client ID
29e5ec38-166e-11f1-1322-af400926661b
Client Secret -- Only accessible after creation. Create new secret if needed.
-- Service Principal (App Registration) name: aiassistant-testapp
-- Service Principal (App Registration) ID: da8e89d4-1fbb-4c37-9f28-a88fa598ea40
-- Azure Portal: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Credentials/appId/29e5ec38-166e-11f1-1322-af400926661b
Windchill AI Assistant Configuration
Azure AI Search
Endpoint
https://acmedev-ai-search.search.windows.net
Index Name -- choose one of
default
another
Authentication Mode -- take from shared authentication configuration below
Azure OpenAI
Endpoint
https://acmedev-ai-foundry.cognitiveservices.azure.com/
Deployment
gpt-5-mini
Authentication Mode -- take from shared authentication configuration below
Azure Storage
Account Name
acmedevdti
Container Name -- choose the one matching the index name
default
another
Authentication Mode -- take from shared authentication configuration below
-------------------------------------
(shared authentication configuration)
Authentication Mode
Service Principal
Tenant ID
31c9c31c-7621-4f8f-ae11-4e462f1be7ed
Client ID
29e5ec38-166e-11f1-1322-af400926661b
Client Secret -- Only accessible after creation. Create new secret if needed.
-- Service Principal (App Registration) name: aiassistant-testapp
-- Service Principal (App Registration) ID: da8e89d4-1fbb-4c37-9f28-a88fa598ea40
-- Azure Portal: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Credentials/appId/29e5ec38-166e-11f1-1322-af400926661b