Creación de recursos de Azure para el entorno local
Este tema está dirigido al administrador del sistema local de Windchill.
Resumen
El plug-in Windchill AI Assistant requiere varios servicios de Microsoft Azure para ofrecer funciones basadas en IA a los usuarios de Windchill en un entorno local.
El plug-in utiliza los siguientes servicios de Azure:
• Azure AI Search: para indexación y búsqueda de documentos
• Azure AI Foundry: para la finalización de chats y la vectorización de documentos
• Azure Storage: para la ingesta temporal de documentos
• Azure Entra ID: para la administración de entidades de servicio y el control de acceso basado en roles (RBAC)
• Azure Deployment Scripts: para el aprovisionamiento de infraestructura automatizado
Todos los servicios de Azure necesarios se definen e implementan mediante infraestructura como código (IaC) a través de plantillas de Azure Resource Manager (ARM).
El plug-in se autentica con puntos de conexión de Azure AI Search, Azure AI Foundry y Azure Storage mediante entidades de servicio de Azure Entra ID. La autorización se aplica a través del control de acceso basado en roles (RBAC).
Las cuentas de Azure AI Search, Azure AI Foundry y Azure Storage se implementan con puntos de conexión públicos, protegidos por reglas de firewall configurables basadas en IP. El acceso a la red se puede restringir a rangos de IP de cliente aprobados.
Es responsabilidad del propietario de la implementación revisar y configurar estos controles de acceso a la red de acuerdo con los requisitos de seguridad y cumplimiento de su organización.
Requisitos previos
Antes de implementar recursos de Azure para el plug-in Windchill AI Assistant, asegúrese de que se cumplen los requisitos previos siguientes:
• Python 3.10.0 o posterior está instalado en el sistema utilizado para la implementación.
• Ha descargado el fichero AI_Assistant_Plugin_Azure_IaC.zip, que está disponible en la parte inferior de la ventana Configuración de Windchill AI Assistant.
◦ En Administrador de plug-ins, pulse con el botón derecho del ratón en Windchill AI Assistant y seleccione Configurar plug-in.
 | Los recursos de Azure creados mediante este procedimiento se deben utilizar exclusivamente para el plug-in Windchill AI Assistant. |
Procedimiento
Siga estos pasos para crear los recursos de Azure necesarios:
N.º paso | Tarea |
|---|---|
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 |
Paso 1: Instalación de la línea de comandos de Azure y verificación de Python
Instale la interfaz de línea de comandos (CLI) de Azure y asegúrese de que Python 3.10 o posterior esté disponible en el sistema de implementación.
• El comando az se utiliza para comunicarse con Azure durante la implementación.
• El comando python3 se utiliza para ejecutar el script del asistente de implementación.
Para obtener instrucciones de instalación específicas de su sistema operativo, consulte la documentación oficial de la línea de comandos (CLI) de Azure.
Paso 2: Creación de un grupo de recursos de Azure
Cree un nuevo grupo de recursos de Azure para alojar los recursos de Windchill AI Assistant. Para obtener más información, consulte Manage Resource Groups.
 | La plantilla de Azure Resource Manager (ARM) se implementa en este grupo de recursos. |
Paso 3: Creación de una entidad de servicio
Cree una entidad de servicio de Azure Entra ID para la autenticación del plug-in en recursos de Azure.
1. Abra un terminal o símbolo del sistema en un sistema donde esté instalada la línea de comandos de Azure.
2. Inicie sesión con una identidad que pueda crear entidades de servicio de Entra ID.
3. Ejecute el siguiente comando para crear una nueva entidad de servicio:
az ad sp create-for-rbac \
--display-name "<Display name>"
--display-name "<Display name>"
En <Display name>, especifique el nombre mostrado requerido. Por ejemplo, wcaiassistant-onprem-sp.
El comando emite valores similares a los siguientes:
{
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
Almacene con seguridad client ID, client secret y tenant ID.
Estos valores son necesarios más adelante durante la configuración del plug-in.
Para obtener el ID de objeto de la entidad de servicio, ejecute el siguiente comando:
az ad sp show --id <client-id> --query id -o tsv
El ID de objeto será necesario más adelante durante la configuración de IaC.
Paso 4: Inicio de sesión con la línea de comandos de Azure y verificación de los roles obligatorios
1. Abra un terminal o símbolo del sistema donde esté instalada Azure CLI.
3. Asegúrese de que el usuario o la entidad de servicio que ha iniciado la sesión tenga el rol de colaborador o, como mínimo, los siguientes roles asignados en el grupo de recursos:
◦ Colaborador de Cognitive Services
◦ Usuario de OpenAI de Cognitive Services
◦ Colaborador de servicio de búsqueda
◦ Colaborador de cuenta de almacenamiento
◦ Un rol personalizado que permite las siguientes acciones:
▪ Microsoft.Resources/deploymentScripts/read
▪ Microsoft.Resources/deploymentScripts/write
4. Asegúrese de que el usuario o la entidad de servicio que ha iniciado sesión tiene asignado el rol de administrador de control de acceso basado en roles para el grupo de recursos.
Paso 5: Preparación de la plantilla de ARM y el fichero de parámetros
1. Copie los siguientes ficheros en un directorio de trabajo local:
◦ wcaia.json (fichero de plantilla de ARM)
◦ wcaia.parameters.json (fichero de parámetros)
◦ deploy-wcaia.py (script del asistente de implementación)
2. Edite el fichero wcaia.parameters.json y proporcione los valores de los parámetros necesarios.
 | No rellene los parámetros relacionados con tokens (por ejemplo, management_token, management_token_expires_on, search_token y search_token_expires_on). El script de asistente de implementación define automáticamente estos valores. |
a. Especifique location entre las siguientes regiones de Azure soportadas:
▪ australiaeast
▪ brazilsouth
▪ canadaeast
▪ eastus
▪ eastus2
▪ francecentral
▪ germanywestcentral
▪ italynorth
▪ japaneast
▪ koreacentral
▪ northcentralus
▪ polandcentral
▪ southafricanorth
▪ southcentralus
▪ spaincentral
▪ swedencentral
▪ switzerlandnorth
▪ uaenorth
▪ uksouth
▪ westus
▪ westus3
| | Revise la documentación de regiones soportadas de Azure AI Search de Microsoft para conocer las limitaciones específicas de cada región, tales como: • Restricciones de capacidad que pueden provocar fallos de implementación. • Límites de almacenamiento reducidos (por ejemplo, 25 GB en lugar de 160 GB), que pueden impedir la indexación de algunos datos. • Falta de zonas de disponibilidad, lo que puede reducir las garantías de disponibilidad. |
b. (Opcionalmente) Especifique las etiquetas de recurso en common_tags.
Si su organización aplica una directiva de etiquetado, la falta de etiquetas obligatorias puede provocar un error RequestDisallowedByPolicy durante la creación del recurso.
c. Defina service_principal_id en el ID de objeto (también denominado ID del principal) de la entidad de servicio creada en el Paso 3: Creación de una entidad de servicio.
| | Este valor no es el ID de cliente de la entidad de servicio. El ID de objeto se puede recuperar del ID de cliente ejecutando el siguiente comando: az ad sp show --id <client-id> --query id -o tsv |
d. Rellene allowed_ips con una lista de direcciones IPv4 o rangos de CIDR que pueden acceder a los recursos de Azure.
▪ Añada las direcciones IP de todos los hosts que ejecutan el plug-in.
▪ Si deja la lista vacía ([]), el cortafuegos está desactivado.
| | Los recursos de Azure se exponen en rangos de direcciones públicas de Internet. En el caso de redes internas (detrás de una NAT), especifique la dirección IP de salida pública (gateway NAT) o el rango de CIDR. |
e. Defina ai_search_partition_count en el número necesario de particiones Standard S1 de Azure AI Search. Para obtener más información, consulte Estimación del número de particiones de búsqueda de IA.
f. (Opcional) Defina el parámetro text_embedding_capacity en un valor inferior al valor predeterminado de 4.000 unidades de capacidad (4 millones de tokens por minuto) solo si no hay suficiente capacidad disponible para el modelo de integración de texto en la región de AI Foundry implementada.
| | La velocidad de indexación depende de la capacidad de incrustación de texto disponible. Si el valor configurado supera los límites disponibles, el script del asistente de implementación informa de la capacidad real disponible. |
g. (Opcional) De forma predeterminada, la configuración de redundancia de la cuenta de Azure Storage storage_sku_name se define en Standard_LRS (almacenamiento con redundancia local). Puede cambiar este valor a un nivel de redundancia diferente en las regiones donde se soportan opciones adicionales.
| | Almacene todas las credenciales de forma segura en su depósito de seguridad corporativo para garantizar un acceso fiable cuando sea necesario. |
Fichero de parámetros de ejemplo:
{
"$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”
} }
}
Paso 6: Definición de un nombre de implementación único
Defina un nombre de implementación globalmente único. El nombre de implementación se utiliza como prefijo para los nombres de recursos de Azure.
El nombre de implementación debe cumplir los siguientes requisitos:
• Contiene solo letras minúsculas y números.
• No excede los 20 caracteres.
Ejemplos:
• acmeaidev
• companywcaiprod
• ai2025subscracme
Paso 7: Creación de recursos de Azure
Ejecute el siguiente comando desde el directorio que contiene los ficheros de plantilla de ARM y el script de asistente de implementación para crear los recursos de Azure necesarios:
python3 deploy-wcaia.py
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
Donde:
• ${RESOURCE_GROUP} es el nombre del grupo de recursos de Azure.
• ${DEPLOYMENT_NAME} es el nombre único de implementación de la plantilla.
Salida de configuración desde el script del asistente de implementación
Después de una implementación correcta, el script del asistente de implementación genera los valores de configuración necesarios para conectar el plug-in Windchill AI Assistant a sus servicios de Azure. Estos valores se deben introducir durante la configuración del plug-in.
El script del asistente de implementación proporciona valores de configuración para los siguientes servicios de Azure que utiliza Windchill AI Assistant:
• Azure AI Search
• Azure OpenAI
• Azure Storage
Utilice los valores generados por el script al configurar el plug-in. Para ver los pasos de configuración, consulte Configuración del plug-in de Windchill AI Assistant.
El script del asistente de implementación también se puede utilizar para recuperar valores de configuración de una implementación completada anteriormente ejecutando el script con la opción de línea de comandos --skip-deployment.
| | • El secreto de cliente para la entidad de servicio de Azure solo está disponible en el momento de la creación. Si el secreto de cliente ya no está disponible, se debe crear un nuevo secreto de cliente en Azure Portal antes de continuar con la configuración del plug-in. • En casos poco frecuentes, las condiciones de carrera transitorias internas del proceso de implementación de Azure pueden hacer que el script se detenga e informe de un error. Si se produce esta situación, repare las instalaciones parciales y vuelva a ejecutar el script de implementación. |
En el siguiente ejemplo se muestra una salida de configuración típica generada por el script de asistente de implementación. Los valores reales variarán en función del entorno.
====================================
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