Windchill AI 助手外掛程式 > 在內部部署環境中安裝及配置 Windchill AI 助手外掛程式 > 在內部部署環境中建立 Azure 資源
在內部部署環境中建立 Azure 資源
本主題適用於 Windchill 內部部署系統管理員。
概觀
欲將 AI 驅動的功能提供給內部部署環境中的 Windchill 使用者，Windchill AI 助手外掛程式需要數個 Microsoft Azure 服務。
外掛程式使用下列 Azure 服務：
• Azure AI 搜尋 - 用於文件索引和搜尋
• Azure AI Foundry - 用於聊天完成與文件向量化
• Azure 儲存體 - 用於暫時擷取文件
• Azure Entra ID - 用於服務主體管理和以角色為基礎的存取控制 (RBAC)
• Azure 部署指令集 - 用於自動化基礎結構佈建
所有必要的 Azure 服務都透過 Azure 資源管理員 (ARM) 範本使用基礎結構即程式碼 (IaC) 的形式定義及部署。
此外掛程式會使用 Azure Entra ID 服務主體，向 Azure AI 搜尋、Azure AI Foundry 和 Azure 儲存體端點進行 Entra ID 驗證。授權透過以角色為基礎的存取控制 (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 指令可用來執行部署 Helper 指令集。
如需特定於您作業系統的安裝指示，請參閱官方 Azure 指令行介面 (CLI) 文件集。
步驟 2：建立 Azure 資源群組
建立新的 Azure 資源群組來主控 Windchill AI 助手資源。如需詳細資訊，請參閱管理資源群組。
* 
將 Azure Resource Manager (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 (部署 Helper 指令集)
2. 編輯 wcaia.parameters.json 檔案並提供所需參數的值。
* 
請勿填入權杖相關參數 (例如 management_token、management_token_expires_on、search_token 與 search_token_expires_on)。這些值由部署 helper 指令集自動設定。
a. 從下列支援的 Azure 區域指定 location：
▪ 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. 將在步驟 3：建立服務主體中建立之服務主體的 service_principal_id 指定為物件 ID (也稱為主體 ID)。
* 
此值不是服務主體用戶端 ID。您可以執行下列指令以從用戶端 ID 擷取物件 ID：
az ad sp show --id <client-id> --query id -o tsv
d. 將可存取 Azure 資源之 IPv4 位址或 CIDR 範圍的清單填入 allowed_ips。
▪ 為執行外掛程式的所有主機新增 IP 位址。
▪ 如果將清單留空 ([])，則防火牆會被禁用。
* 
將在公用網際網路位址範圍內公開 Azure 資源。針對網際網路 (NAT 後端) 中的主機，請指定公開輸出 (NAT 閘道) IP 位址或 CIDR 範圍。
e. 將 ai_search_partition_count 設定為所需的 Azure AI 搜尋標準 S1 分割區數。如需詳細資訊，請參閱預估 AI 搜尋分割區數。
f. (選用) 僅當部署的 AI Foundry 區域中沒有足夠的文字嵌入模型容量時，才將 text_embedding_capacity 參數值設定為低於預設值 4000 個容量單位 (每分鐘 400 萬個權杖)。
* 
索引速度取決於可用的文字內嵌容量。如果配置的值超過可用限制，則部署 helper 指令碼會報告實際可用的容量。
g. (選用) 依預設，Azure 儲存體帳戶重複限制組態 storage_sku_name 會設定為 Standard_LRS (本機重複限制儲存體)。您可以在支援其他選項的區域中將此值變更為不同的重複限制層級。
h. (選用) 指定索引名稱，或保留 index_names 清單中的預設值 (default)。
* 
多個 Windchill 實例可以共用相同的 Azure 資源 (AI Foundry、Azure AI 搜尋服務與儲存帳戶)。但是，每個實例都必須使用具唯一性的索引。
您可以隨時間延伸 index_names 清單，以將其他索引新增至相同部署中。重新裝載或重新索引時可能需要其他索引。如需詳細資訊，請參閱在安裝有 AI 助手外掛程式的內部部署環境中重新裝載伺服器與重新索引。
* 
將所有認證安全地儲存在貴公司的安全儲存庫中，以確保在需要時可靠地存取。
範例參數檔案：
{
"$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 範本檔案與部署 helper 指令集的目錄中執行下列指令，以建立所需的 Azure 資源：
python3 deploy-wcaia.py
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
其中：
• ${RESOURCE_GROUP} 是 Azure 資源群組的名稱。
• ${DEPLOYMENT_NAME} 是具唯一性的範本部署名稱。
來自部署 Helper 指令集的組態輸出
成功部署之後，部署 helper 指令集會產生將 Windchill AI 助手外掛程式連線至其 Azure 服務所需的組態值。這些值必須在外掛程式組態期間輸入。
部署 Helper 指令集提供 Windchill AI 助手所使用的下列 Azure 服務的所有必要組態值：
• Azure AI 搜尋
• Azure OpenAI
• Azure 儲存體
配置外掛程式時，請使用指令集所產生的值。如需組態步驟，請參閱配置 Windchill AI 助手外掛程式。
您也可以使用 --skip-deployment 指令行選項執行指令集，來利用部署 helper 指令集從先前已完成的部署中擷取組態值。
* 
• Azure 服務主體的用戶端密碼僅在建立時可用。如果用戶端密碼不再可用，您必須在 Azure 入口網站建立新用戶端密碼，然後再繼續配置外掛程式。
• 在極少數情況下，Azure 部署程序內部的暫時性競爭條件可能會導致指令碼停止並報告錯誤。如果發生此情況，請清理所有部份安裝，然後重新執行部署指令碼。
下列範例顯示由部署 helper 指令集產生的一般組態輸出。實際值將根據您的環境而有所不同。
====================================

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
12a3b45c-1234-1a2b-ab12-1a234b5cd6ab

Client ID
12a3bc45-123d-12f3-1234-ab100126661b

Client Secret -- Only accessible after creation. Create new secret if needed.
-- Service Principal (App Registration) name: aiassistant-testapp
-- Service Principal (App Registration) ID: ab1c23d4-1abc-1a23-9f28-a12ba123cd12
-- Azure Portal: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Credentials/appId/12a3bc45-678d-11a1-1322-ab100926661b
這是否有幫助?