온프레미스 환경을 위한 Azure 리소스 작성
이 항목은 Windchill 온프레미스 시스템 관리자를 대상으로 합니다.
개요
Windchill AI Assistant 플러그 인이 온프레미스 환경에서 Windchill 사용자에게 AI 기반 기능을 제공하려면 Microsoft Azure 서비스가 여러 개 필요합니다.
플러그 인은 다음 Azure 서비스를 사용합니다.
• Azure AI Search - 문서 인덱싱 및 검색용
• Azure AI Foundry - 채팅 완료 및 문서 벡터화용
• Azure Storage - 문서 임시 수집용
• Azure Entra ID - 서비스 사용자 관리 및 RBAC(역할 기반 액세스 제어)용
• Azure 배포 스크립트 - 자동화된 인프라 프로비저닝용
모든 필수 Azure 서비스는 ARM(Azure Resource Manager) 템플릿을 통한 IaC(Infrastructure as Code)를 사용하여 정의 및 배포됩니다.
플러그 인은 Azure Entra ID 서비스 사용자를 사용하여 Azure AI Search, Azure AI Foundry 및 Azure Storage 엔드포인트에 대한 인증을 수행합니다. 권한 부여는 RBAC(역할 기반 액세스 제어)를 통해 적용됩니다.
Azure AI Search, Azure AI Foundry 및 Azure Storage 계정은 구성 가능한 IP 기반 방화벽 규칙으로 보호되는 공용 엔드포인트와 함께 배포됩니다. 네트워크 액세스는 승인된 클라이언트 IP 범위로 제한할 수 있습니다.
조직의 보안 및 규제 준수 요구 사항에 따라 이러한 네트워크 액세스 제어를 검토하고 구성하는 것은 배포 소유자의 책임입니다.
필수조건
Windchill AI Assistant 플러그 인에 필요한 Azure 리소스를 배포하기 전에 다음 필수조건을 충족하는지 확인하십시오.
• 배포에 사용되는 시스템에 Python 3.10.0 이상이 설치되어 있습니다.
• Windchill AI Assistant 구성 창 하단에 있는 AI_Assistant_Plugin_Azure_IaC.zip 파일을 다운로드했습니다.
◦ 플러그 인 관리자에서 Windchill AI Assistant를 마우스 오른쪽 버튼으로 클릭하고 플러그 인 구성을 선택합니다.
 | 이 절차에 따라 작성된 Azure 리소스는 Windchill AI Assistant 플러그 인 전용으로만 사용해야 합니다. |
절차
다음 단계에 따라 필요한 Azure 리소스를 작성합니다.
단계 번호 | 임무 |
|---|---|
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 |
1단계: Azure CLI 설치 및 Python 확인
Azure CLI(명령줄 인터페이스)를 설치하고 배포 시스템에서 Python 3.10 이상을 사용할 수 있는지 확인합니다.
• az 명령은 배포 중 Azure와 통신하는 데 사용됩니다.
• python3 명령은 배포 도우미 스크립트를 실행하는 데 사용됩니다.
운영 체제와 관련된 설치 지침은 공식 Azure CLI(Command-Line Interface) 설명서를 참조하십시오.
2단계: Azure 리소스 그룹 작성
Windchill AI Assistant 리소스를 호스트하기 위한 새 Azure 리소스 그룹을 작성합니다. 자세한 내용은 리소스 그룹 관리를 참조하십시오.
 | ARM(Azure Resource Manager) 템플릿이 이 리소스 그룹에 배포됩니다. |
3단계: 서비스 사용자 작성
Azure 리소스에 대한 플러그 인 인증을 위해 Azure Entra ID 서비스 사용자를 작성합니다.
1. Azure CLI가 설치된 시스템에서 터미널 또는 명령 프롬프트를 엽니다.
2. Entra ID 서비스 사용자를 작성할 수 있는 ID를 사용하여 로그인합니다.
3. 다음 명령을 실행하여 새 서비스 사용자를 작성합니다.
az ad sp create-for-rbac \
--display-name "<Display name>"
--display-name "<Display name>"
<Display name>에서 필요한 디스플레이 이름을 지정합니다. 예: wcaiassistant-onprem-sp.
이 명령은 다음과 유사한 값을 출력합니다.
{
.."appId": "<client-id>",
.."password": "<client-secret>",
.."tenant": "<tenant-id>"
}
.."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
객체 ID는 나중에 IaC 구성 중에 필요합니다.
4단계: Azure CLI를 사용하여 로그인 및 필수 역할 확인
1. Azure CLI가 설치된 터미널 또는 명령 프롬프트를 엽니다.
3. 로그인한 사용자 또는 서비스 사용자에게 참가자 역할이 있거나 리소스 그룹에서 최소한 다음 역할이 할당되어 있는지 확인합니다.
◦ Cognitive Services 참가자
◦ Cognitive Services 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 파일을 편집하여 필수 매개변수의 값을 제공합니다.
 | 토큰 관련 매개 변수(예: management_token, management_token_expires_on, search_token 및 search_token_expires_on)는 채우지 마십시오. 이러한 값은 배포 도우미 스크립트에 따라 자동으로 설정됩니다. |
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 Search 지원 지역 문서를 검토하여 다음과 같은 지역별 제한 사항을 확인합니다. • 용량 제약. 배포 실패를 일으킬 수 있습니다. • 저장소 제한 감소(예: 160GB 대신 25GB). 일부 데이터를 인덱싱하지 못할 수 있습니다. • 가용성 영역 부족. 가용성 보장이 줄어들 수 있습니다. |
b. (선택 사항) common_tags에서 리소스 태그를 지정합니다.
조직에서 태그 지정 정책을 적용하는 경우 필수 태그가 누락되면 리소스를 작성하는 동안 RequestDisallowedByPolicy 오류가 발생할 수 있습니다.
| | 이 값은 서비스 사용자 클라이언트 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 Search Standard S1 파티션 수로 설정합니다. 자세한 내용은 AI 검색 파티션 수 산정을 참조하십시오.
f. (선택 사항) 배포된 AI Foundry 영역에서 텍스트 포함 모델에 충분한 용량을 사용할 수 없는 경우에만 매개변수 text_embedding_capacity를 기본값인 4000 용량 단위(분당 400만 토큰)보다 낮은 값으로 설정합니다.
| | 인덱싱 속도는 사용 가능한 텍스트 임베딩 용량에 따라 달라집니다. 구성된 값이 사용 가능한 제한을 초과하는 경우 배포 도우미 스크립트는 사용 가능한 실제 용량을 보고합니다. |
g. (선택 사항) 기본적으로 Azure Storage 계정 중복성 구성 storage_sku_name은 Standard_LRS(로컬 중복 스토리지)로 설정됩니다. 추가 옵션이 지원되는 영역에서는 이 값을 다른 중복 수준으로 변경할 수 있습니다.
h. (선택 사항) 인덱스 이름을 지정하거나 index_names 목록에서 기본값(default)을 유지합니다.
| | 여러 Windchill 인스턴스가 동일한 Azure 리소스(AI Foundry, Azure AI Search 및 Storage 계정)를 공유할 수 있습니다. 그러나 각 인스턴스는 고유 인덱스를 사용해야 합니다. 시간이 지남에 따라 index_names 목록을 확장하여 동일한 배포에 추가 인덱스를 추가할 수 있습니다. 재호스팅 또는 재인덱싱할 때 추가 인덱스가 필요할 수 있습니다. 자세한 내용은 AI Assistant 플러그 인이 설치된 온프레미스 환경에 대한 서버 재호스팅 및 재인덱싱을 참조하십시오. |
| | 필요할 때 안정적으로 액세스할 수 있도록 모든 자격 증명을 회사 보안 보관소에 안전하게 저장합니다. |
예제 매개 변수 파일:
{
"$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”
} }
}
6단계: 고유한 배포 이름 정의
전역적으로 고유한 배포 이름을 정의합니다. 배포 이름은 Azure 리소스 이름의 접두사로 사용됩니다.
배포 이름은 다음 요구 사항을 충족해야 합니다.
• 소문자와 숫자만 포함해야 합니다.
• 20자를 초과할 수 없습니다.
예제:
• acmeaidev
• companywcaiprod
• ai2025subscracme
7단계: Azure 리소스 작성
ARM 템플릿 파일 및 배포 도우미 스크립트가 포함된 디렉터리에서 다음 명령을 실행하여 필요한 Azure 리소스를 작성합니다.
python3 deploy-wcaia.py
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
--resource-group ${RESOURCE_GROUP}
--deployment-name ${DEPLOYMENT_NAME}
설명:
• ${RESOURCE_GROUP}은 Azure 리소스 그룹의 이름입니다.
• ${DEPLOYMENT_NAME}은 고유한 템플릿 배포 이름입니다.
배포 도우미 스크립트의 구성 출력
성공적으로 배포하면 배포 도우미 스크립트는 Windchill AI Assistant 플러그 인을 Azure 서비스에 연결하는 데 필요한 구성 값을 생성합니다. 이러한 값은 플러그 인 구성 중 입력되어야 합니다.
배포 도우미 스크립트는 Windchill AI Assistant에서 사용하는 다음 Azure 서비스에 대한 구성 값을 제공합니다.
• Azure AI Search
• Azure OpenAI
• Azure Storage
플러그 인을 구성할 때 스크립트에서 생성한 값을 사용합니다. 구성 단계는 Windchill AI Assistant 플러그 인 구성을 참조하십시오.
배포 도우미 스크립트를 --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
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
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