Creazione di risorse di Azure per l'ambiente locale
Il destinatario del presente argomento è l'amministratore del sistema Windchill locale.
Panoramica
Il plug-in Windchill AI Assistant richiede diversi servizi di Microsoft Azure per fornire funzionalità basate sull'intelligenza artificiale agli utenti di Windchill in un ambiente locale.
Il plug-in utilizza i seguenti servizi di Azure:
• Azure AI Search - Per l'indicizzazione e la ricerca di documenti
• Azure AI Foundry - Per il completamento della chat e la vettorizzazione dei documenti
• Archiviazione di Azure - Per l'inserimento temporaneo di documenti
• Azure Entra ID - Per la gestione delle entità servizio e il controllo degli accessi in base al ruolo.
• Script di distribuzione di Azure - Per il provisioning automatizzato dell'infrastruttura
Tutti i servizi di Azure necessari vengono definiti e distribuiti utilizzando IaC (Infrastructure as Code) tramite modelli di ARM (Azure Resource Manager).
Il plug-in esegue l'autenticazione con gli endpoint di Azure AI Search, Azure AI Foundry e Archiviazione di Azure tramite le entità servizio di Azure Entra ID. L'autorizzazione viene applicata tramite il controllo degli accessi in base al ruolo.
Gli account Azure AI Search, Azure AI Foundry e Archiviazione di Azure vengono distribuiti con endpoint pubblici, protetti da regole di firewall basate su IP configurabili. L'accesso alla rete può essere limitato agli intervalli di IP client approvati.
È responsabilità del proprietario della distribuzione esaminare e configurare questi controlli di accesso alla rete in conformità ai requisiti di sicurezza e conformità dell'organizzazione.
Prerequisiti
Prima di distribuire le risorse di Azure per il plug-in Windchill AI Assistant, assicurarsi che siano soddisfatti i prerequisiti riportati di seguito.
• Python 3.10.0 o versione successiva viene installato nel sistema utilizzato per la distribuzione.
• È stato scaricato il file AI_Assistant_Plugin_Azure_IaC.zip, disponibile nella parte inferiore della finestra Configurazione di Windchill AI Assistant.
◦ In Gestione plug-in, fare clic con il pulsante destro del mouse su Windchill AI Assistant e selezionare Configura plug-in.
 | Le risorse di Azure create utilizzando questa procedura devono essere utilizzate esclusivamente per il plug-in Windchill AI Assistant. |
Procedura
Per creare le risorse di Azure necessarie, attenersi ai seguenti passi:
N. passo | Task |
|---|---|
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 |
Passo 1: installare l'interfaccia della riga di comando di Azure e verificare Python
Installare l'interfaccia della riga di comando di Azure e assicurarsi che nel sistema di distribuzione sia disponibile Python 3.10 o versione successiva.
• Il comando az viene utilizzato per comunicare con Azure durante la distribuzione.
• Il comando python3 viene utilizzato per eseguire lo script di supporto per la distribuzione.
Per le istruzioni di installazione specifiche del sistema operativo in uso, fare riferimento alla documentazione ufficiale dell'interfaccia della riga di comando di Azure.
Passo 2: creare un gruppo di risorse di Azure
Creare un nuovo gruppo di risorse di Azure per ospitare le risorse di Windchill AI Assistant. Per ulteriori informazioni, vedere Manage Resource Groups.
 | Il modello di Azure Resource Manager (ARM) viene distribuito in questo gruppo di risorse. |
Passo 3: creare un'entità servizio
Creare un'entità servizio di Azure Entra ID per l'autenticazione del plug-in per le risorse di Azure.
1. Aprire un terminale o un prompt dei comandi su un sistema in cui è installata l'interfaccia della riga di comando di Azure.
2. Accedere utilizzando un identificativo in grado di creare entità servizio di Entra ID.
3. Per creare una nuova entità servizio, eseguire il comando seguente:
az ad sp create-for-rbac \
--display-name "<Display name>"
--display-name "<Display name>"
In <Display name> specificare il nome visualizzato richiesto. ad esempio wcaiassistant-onprem-sp.
Il comando genera valori simili ai seguenti:
{
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
Archiviare in modo sicuro client ID, client secret e tenant ID.
Questi valori sono richiesti in un secondo momento durante la configurazione del plug-in.
Ottenere l'ID oggetto dell'entità servizio eseguendo il comando seguente:
az ad sp show --id <client-id> --query id -o tsv
L'ID oggetto sarà richiesto in un secondo momento durante la configurazione di IaC.
Passo 4: accedere utilizzando l'interfaccia della riga di comando di Azure e verificare i ruoli obbligatori
1. Aprire un terminale o un prompt dei comandi in cui è installata l'interfaccia della riga di comando di Azure.
3. Assicurarsi che l'utente che ha effettuato l'accesso o l'entità servizio disponga del ruolo Contributore o almeno dei seguenti ruoli assegnati nel gruppo di risorse:
◦ Collaboratore Servizi cognitivi
◦ Utente OpenAI di Servizi cognitivi
◦ Collaboratore Servizio di ricerca
◦ Collaboratore Account di archiviazione
◦ Un ruolo personalizzato che consente le azioni seguenti:
▪ Microsoft.Resources/deploymentScripts/read
▪ Microsoft.Resources/deploymentScripts/write
4. Assicurarsi che all'utente che ha effettuato l'accesso o all'entità servizio sia assegnato il ruolo di amministratore Controllo degli accessi in base al ruolo per il gruppo di risorse.
Passo 5: preparare il modello di ARM e il file di parametri
1. Copiare i file seguenti in una directory di lavoro locale:
◦ wcaia.json (file del modello di ARM)
◦ wcaia.parameters.json (file di parametri)
◦ deploy-wcaia.py (script di supporto per la distribuzione)
2. Modificare il file wcaia.parameters.json e specificare i valori per i parametri obbligatori.
 | Non completare i parametri correlati al token (ad esempio management_token, management_token_expires_on, search_token e search_token_expires_on). Questi valori vengono impostati automaticamente dallo script di supporto per la distribuzione. |
a. Specificare location delle seguenti regioni di Azure supportate:
▪ australiaeast
▪ brazilsouth
▪ canadaeast
▪ eastus
▪ eastus2
▪ francecentral
▪ germanywestcentral
▪ italynorth
▪ japaneast
▪ koreacentral
▪ northcentralus
▪ polandcentral
▪ southafricanorth
▪ southcentralus
▪ spaincentral
▪ swedencentral
▪ switzerlandnorth
▪ uaenorth
▪ uksouth
▪ westus
▪ westus3
| | Per informazioni sulle limitazioni specifiche della regione, come quelle di seguito riportate, consultare la documentazione di Microsoft sulle regioni supportate di Azure AI Search. • Vincoli di capacità che possono causare errori di distribuzione. • Limiti di archiviazione ridotta (ad esempio 25 GB anziché 160 GB), che potrebbero impedire l'indicizzazione di alcuni dati. • Mancanza di zone di disponibilità, che potrebbe ridurre le garanzie di disponibilità. |
b. (Facoltativo) Specificare i tag delle risorse in common_tags.
Se l'organizzazione applica una regola di assegnazione tag, la mancanza di tag obbligatori può causare un errore RequestDisallowedByPolicy durante la creazione della risorsa.
c. Impostare service_principal_id sull'ID oggetto (detto anche ID utente/gruppo/ruolo) dell'entità servizio creata in Passo 3: creare un'entità servizio.
| | Questo valore non è l'ID client dell'entità servizio. L'ID oggetto può essere recuperato dall'ID client eseguendo il comando seguente: az ad sp show --id <client-id> --query id -o tsv |
d. Completare allowed_ips con un elenco di indirizzi IPv4 o intervalli CIDR che possono accedere alle risorse di Azure.
▪ Aggiungere gli indirizzi IP di tutti gli host che eseguono il plug-in.
▪ Se si lascia l'elenco vuoto ([]), il firewall è disattivato.
| | Le risorse di Azure sono esposte in intervalli di indirizzi Internet pubblici. Per gli host in reti interne (protetti da NAT), specificare l'indirizzo IP in uscita pubblica (gateway NAT) o l'intervallo CIDR. |
e. Impostare ai_search_partition_count sul numero richiesto di partizioni Standard S1 di Azure AI Search. Per ulteriori informazioni, vedere Stima del numero di partizioni di AI Search.
f. (Facoltativo) Impostare il parametro text_embedding_capacity su un valore inferiore al valore di default di 4000 unità di capacità (4 milioni di token al minuto) solo se la capacità sufficiente per il modello di embedding del testo non è disponibile nella regione di AI Foundry distribuita.
| | La velocità di indicizzazione dipende dalla capacità disponibile di embedding del testo. Se il valore configurato supera i limiti disponibili, lo script di supporto per la distribuzione segnala la capacità effettiva disponibile. |
g. (Facoltativo) Per default, la configurazione di ridondanza dell'account di archiviazione di Azure storage_sku_name è impostata su Standard_LRS (archiviazione con ridondanza locale). È possibile modificare questo valore impostando un livello di ridondanza diverso nelle regioni in cui sono supportate opzioni aggiuntive.
| | Archiviare tutte le credenziali in modo sicuro nell'archivio di protezione aziendale per garantire un accesso affidabile quando necessario. |
Esempio di file di parametri:
{
"$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”
} }
}
Passo 6: definire un nome di distribuzione univoco
Definire un nome di distribuzione globalmente univoco. Il nome della distribuzione viene utilizzato come prefisso per i nomi delle risorse di Azure.
Il nome della distribuzione deve soddisfare i requisiti riportati di seguito.
• Deve contenere solo lettere minuscole e numeri.
• Non deve superare i 20 caratteri.
Esempi
• acmeaidev
• companywcaiprod
• ai2025subscracme
Passo 7: creare risorse di Azure
Eseguire il comando seguente dalla directory contenente i file del modello di ARM e lo script di supporto per la distribuzione per creare le risorse di Azure necessarie:
python3 deploy-wcaia.py
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
dove:
• ${RESOURCE_GROUP} è il nome del gruppo di risorse di Azure.
• ${DEPLOYMENT_NAME} è il nome univoco di distribuzione del modello.
Output di configurazione dello script di supporto per la distribuzione
Al termine della distribuzione, lo script di supporto per la distribuzione genera i valori di configurazione necessari per connettere il plug-in Windchill AI Assistant ai relativi servizi di Azure. Questi valori devono essere immessi durante la configurazione del plug-in.
Lo script di supporto per la distribuzione fornisce i valori di configurazione per i seguenti servizi di Azure utilizzati da Windchill AI Assistant:
• Azure AI Search
• Azure OpenAI
• Archiviazione di Azure
Utilizzare i valori generati dallo script durante la configurazione del plug-in. Per la procedura di configurazione, vedere Configurazione del plug-in Windchill AI Assistant.
È inoltre possibile utilizzare lo script di supporto per la distribuzione per recuperare i valori di configurazione da una distribuzione precedente completata eseguendolo con l'opzione della riga di comando --skip-deployment.
| | • Il segreto client per l'entità servizio di Azure è disponibile solo al momento della creazione. Se il segreto client non è più disponibile, è necessario crearne uno nuovo nel portale di Azure prima di continuare con la configurazione del plug-in. • In casi rari, le condizioni di corsa temporanee interne al processo di distribuzione di Azure possono causare l'arresto dello script e la segnalazione di un errore. In tal caso, eliminare tutte le installazioni parziali e quindi eseguire di nuovo lo script di distribuzione. |
L'esempio riportato di seguito mostra un tipico output di configurazione generato dallo script di supporto per la distribuzione. I valori effettivi variano a seconda dell'ambiente.
====================================
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