Windchill AI 助手插件 > 在本地环境中安装和配置 Windchill AI 助手插件 > 为本地环境创建 Azure 资源
为本地环境创建 Azure 资源
本主题适用于 Windchill 本地系统管理员。
概述
Windchill AI 助手插件需要多项 Microsoft Azure 服务才能在本地环境中为 Windchill 用户提供 AI 驱动的功能。
该插件利用以下 Azure 服务：
• Azure AI 搜索 - 用于文档索引和搜索
• Azure AI Foundry - 用于聊天补全和文档矢量化
• Azure 存储 - 用于临时提取文档
• Azure Entra ID - 用于服务主体管理和基于角色的访问控制 (RBAC)
• Azure 部署脚本 - 用于自动搭建基础设施
所有必需的 Azure 服务均使用基础设施即代码 (IaC) 通过 Azure 资源管理器 (ARM) 模板进行定义和部署。
该插件使用 Azure Entra ID 服务主体向 Azure AI 搜索、Azure AI Foundry 和 Azure 存储端点进行身份验证。授权是通过基于角色的访问控制 (RBAC) 强制执行的。
Azure AI 搜索、Azure AI Foundry 和 Azure 存储帐户均部署了公共端点，并受到基于 IP 的可配置防火墙规则的保护。可将网络访问限制为已批准的客户端 IP 地址范围。
部署负责人负责根据其组织的安全性和合规性要求审阅和配置这些网络访问控制。
先决条件
在为 Windchill AI 助手插件部署 Azure 资源之前，请确保满足以下先决条件：
• 用于部署的系统上已安装 Python 3.10.0 或更高版本。
• 已下载 AI_Assistant_Plugin_Azure_IaC.zip 文件，该文件位于“Windchill AI 助手 - 配置”窗口的底部。
◦ 在“插件管理器”中，右键单击“Windchill AI 助手”，然后选择“配置插件”。
* 
通过此过程创建的所有 Azure 资源必须专用于 Windchill AI 助手插件。
过程
按照以下步骤创建所需的 Azure 资源：
步骤编号
任务
1
2
3
4
5
6
7
步骤 1：安装 Azure CLI 和验证 Python
安装 Azure 命令行接口 (CLI)，并确保部署系统上安装有 Python 3.10 或更高版本。
• az 命令用于在部署期间与 Azure 进行通信。
• python3 命令用于运行部署帮助脚本。
有关操作系统特定安装说明，请参阅官方 Azure Command-Line Interface (CLI) 文档。
步骤 2：创建 Azure 资源组
创建一个新 Azure 资源组来托管 Windchill AI 助手资源。有关详情，请参阅 Manage resource groups。
* 
将 Azure 资源管理器 (ARM) 模板部署到此资源组。
步骤 3：创建服务主体
创建 Azure Entra ID 服务主体，以供插件对 Azure 资源进行身份验证。
1. 在安装有 Azure CLI 的系统上打开终端或命令提示符。
2. 使用可以创建 Entra ID 服务主体的标识进行登录。
3. 运行以下命令来创建新的服务主体：
az ad sp create-for-rbac \
--display-name "<Display name>"
在 <Display name> 中，指定所需的显示名称。例如，wcaiassistant-onprem-sp。
命令输出值如下：
{
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
请妥善存储 client ID、client secret 和 tenant ID。
这些值在稍后的插件配置过程中需要用到。
通过执行以下命令获取服务主体对象 ID：
az ad sp show --id <client-id> --query id -o tsv
稍后的 IaC 配置过程中将需要该对象 ID。
步骤 4：使用 Azure CLI 登录并验证所需角色
1. 打开安装了 Azure CLI 的终端或命令提示符。
2. 使用 az login 命令 (以用户或 服务主体身份) 进行登录。
3. 确保登录的用户或服务主体具有“参与创作者”角色，或至少在资源组中分配了以下角色：
◦ 认知服务参与创作者
◦ 认知服务 OpenAI 用户
◦ 搜索服务参与创作者
◦ 存储帐户参与创作者
◦ 自定义角色 - 允许执行以下操作：
▪ Microsoft.Resources/deploymentScripts/read
▪ Microsoft.Resources/deploymentScripts/write
4. 对于已登录用户或服务主体，确保为其分配资源组的基于角色的访问控制管理员角色。
步骤 5：准备 ARM 模板和参数文件
1. 将以下文件复制到本地工作目录：
◦ wcaia.json (ARM 模板文件)
◦ wcaia.parameters.json (参数文件)
◦ deploy-wcaia.py (部署帮助脚本)
2. 编辑 wcaia.parameters.json 文件，并为必需的参数指定值。
* 
请不要填充 token 相关参数 (例如，management_token、management_token_expires_on、search_token 和 search_token_expires_on)。这些值由部署帮助脚本自动设置。
a. 指定 location，可选择以下受支持的 Azure 区域：
▪ australiaeast
▪ brazilsouth
▪ canadaeast
▪ eastus
▪ eastus2
▪ francecentral
▪ germanywestcentral
▪ italynorth
▪ japaneast
▪ koreacentral
▪ northcentralus
▪ polandcentral
▪ southafricanorth
▪ southcentralus
▪ spaincentral
▪ swedencentral
▪ switzerlandnorth
▪ uaenorth
▪ uksouth
▪ westus
▪ westus3
* 
查阅 Microsoft 的 Azure AI 搜索支持的区域文档，了解区域特定限制，例如：
• 容量限制 - 这可能会导致部署失败。
• 降低的存储限制 (例如，25 GB 而非 160 GB) - 这可能会阻止对某些数据进行索引。
• 可用区不足 - 这可能会降低可用性保证。
b. (可选) 在 common_tags 中指定资源标签。
如果您的组织强制实施标签策略，则在资源创建过程中，缺少必需标签可能会导致 RequestDisallowedByPolicy 错误。
c. 将 service_principal_id 设置为步骤 3：创建服务主体中所创建服务主体的对象 ID (也称为“主体 ID”)。
* 
此值不是服务主体客户端 ID。要从客户端 ID 中检索对象 ID，可运行以下命令：
az ad sp show --id <client-id> --query id -o tsv
d. 使用可以访问 Azure 资源的 IPv4 地址或 CIDR 范围的列表来填充 allowed_ips。
▪ 添加运行该插件的所有主机的 IP 地址。
▪ 如果将列表留空 ([])，则防火墙将被禁用。
* 
Azure 资源被公开在公共 Internet 地址范围内。对于内部网络中 (位于 NAT 后面) 的主机，请指定公共出口 (NAT 网关) IP 地址或 CIDR 范围。
e. 将 ai_search_partition_count 设置为所需的 Azure AI 搜索标准 S1 分区数。有关详情，请参阅估计 AI 搜索分区数。
f. (可选) 将 text_embedding_capacity 参数的值设置为低于默认值 4000 个容量单位 (每分钟 400 万个令牌)，这仅在部署的 AI Foundry 区域中文本嵌入模型容量不足时适用。
* 
索引速度取决于可用的文本嵌入容量。如果配置的值超出可用容量限制，则部署帮助脚本将报告实际可用容量。
g. (可选) 默认情况下，Azure 存储帐户冗余配置 storage_sku_name 设置为 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”
} }
}
步骤 6：定义唯一部署名称
定义全局唯一部署名称。部署名称用作 Azure 资源名称的前缀。
部署名称必须满足以下要求：
• 仅包含小写字母和数字。
• 不能超过 20 个字符。
示例：
• acmeaidev
• companywcaiprod
• ai2025subscracme
步骤 7：创建 Azure 资源
从包含 ARM 模板文件和部署帮助脚本的目录运行以下命令，以创建所需的 Azure 资源：
python3 deploy-wcaia.py
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
其中：
• ${RESOURCE_GROUP} 是 Azure 资源组的名称。
• ${DEPLOYMENT_NAME} 是唯一的模板部署名称。
部署帮助脚本的配置输出
成功部署后，部署帮助脚本会生成将 Windchill AI 助手插件连接到其 Azure 服务所需的配置值。这些值必须在插件配置期间输入。
部署帮助脚本将为 Windchill AI 助手所使用的以下 Azure 服务提供配置值。
• Azure AI 搜索
• Azure OpenAI
• Azure 存储
配置该插件时，请使用该脚本生成的值。有关配置步骤，请参阅配置 Windchill AI 助手插件。
也可以使用部署帮助脚本从先前完成的部署中检索配置值，方法是使用 --skip-deployment 命令行选项运行该脚本。
* 
• Azure 服务主体的客户端密钥仅在创建时可用。如果客户端密钥不再可用，则必须在 Azure 门户中创建一个新的客户端密钥，然后才能继续配置该插件。
• 在极少数情况下，Azure 部署进程内部的瞬态争用条件可能会导致脚本停止并报告错误。如果发生这种情况，请清理所有部分安装，然后重新运行部署脚本。
以下示例显示由部署帮助脚本生成的典型配置输出。实际值将因环境而异。
====================================

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
这对您有帮助吗?