Deployment on Azure

Preparation Before Deployment

Required Resources

• A new subscription dedicated to product deployment, ensuring that this subscription can create OpenAI-related resources.
• An Azure AD account with Contributor or higher permissions on the subscription.
  • You can add an existing AAD account as a Guest to the tenant and authorize it, or create a dedicated AAD account for deployment.
  • The account should be able to create and configure AAD application registrations (e.g., grant the Application Developer role).

Required Tools

• A database client that can connect to Azure SQL and PGSQL (e.g., DBeaver)
• Azure Storage Explorer
  • https://azure.microsoft.com/en-us/products/storage/storage-explorer/#Download-4
• Az CLI command line
  • https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-windows?pivots=winget
• Install Terraform command line
  • https://www.terraform.io/downloads.html

Recommended Knowledge

• A certain understanding of Azure resources (e.g., App Service, Azure SQL, Storage, Key Vault, etc.) and the ability to manage resources through the Azure Portal
  • https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resources-portal
• A certain understanding of the SERVICEME product's functions and basic operations
  • Understand the product's basic functions (e.g., Copilot Q&A, document upload, preprocessing, document translation, etc.)
  • Understand user, organization, role creation, configuration, and user password reset
  • Understand Copilot creation, authorization, configuration
  • Understand space creation, authorization, configuration
  • https://docs.serviceme.com/
• A certain understanding of Terraform, completing the official azure-get-started tutorial
  • https://developer.hashicorp.com/terraform/tutorials/azure-get-started/azure-build

Product Deployment Architecture and Resource List

Product Deployment Architecture

Resource List & Recommended Configuration

tip

Server load varies under different scenarios and usage frequencies, adjustments should be made based on actual load conditions.

• Recommended configuration for 500 users (default configuration for Trial environment)
  • https://azure.com/e/445153696b3d47d196195e5270cd58de
• Recommended configuration for 3000 users
  • https://azure.com/e/947375496b874ee2ab0ad54726397eda
• Recommended configuration for over 3000 users
  • https://azure.com/e/f58bd3ee542646d4be7d1ecb2afa453c

Usage Description

Service Type	Custom Name	Usage Description
Azure Front Door	CDN	Content Delivery Network, used to accelerate access to static resources
Azure Front Door	API Acceleration	API Acceleration, used to accelerate API access
API Management	API Endpoint	API Management Endpoint, used to manage APIs
App Service	API Service	API Service, used to handle API requests
App Service	Job Service	Job Service, used to handle high-load tasks, execute scheduled tasks
Azure OpenAI Service	LLM-Primary	Primary Large Language Model, used as the main model for Copilot Q&A (e.g., gpt-4o)
Azure OpenAI Service	LLM-Secondary	Secondary Large Language Model, used as an auxiliary model for document processing (e.g., gpt-4o-mini)
Azure OpenAI Service	Embedding	Vector Embedding, used to process vector data
Azure OpenAI Service	Text to Image	Text to Image, used to handle text-to-image tasks
Azure OpenAI Service	Whisper	Speech Recognition, used to handle speech recognition tasks
Azure AI Document Intelligence	Document OCR	Document OCR Recognition, used to handle document OCR recognition tasks
Azure AI services	Document Translate	Document Translation, used to handle document translation tasks
Azure SQL Database	Data	Data Storage, main database, most of the system data is stored here
Azure Database for PostgreSQL	Index	Index Database, mainly stores document-related index data
Azure Cache for Redis	Cache	Cache Service, used to cache data
Storage Accounts	Files	File Storage, used to store user-uploaded files
Key Vault	-	Key Management, used to store keys

Product Deployment

Deployment Process

• Execute Deployment
  • Create AAD Application Registration
  • Set Terraform Deployment Parameters
  • Azure Account Login, Subscription Switch
  • Execute Deployment
  • Update AAD Application Registration
• Upload Resource Package, Start System
  • Install Frontend Deployment Package, Font Package, Icon Resources
  • Install License
  • Start System, Check if it Starts Successfully
• System Check
  • Admin Login to System
  • Test if System Functions are Normal
• Complete Configuration
  • Modify System Settings
  • Copilot Settings
  • Space Settings
  • Test Document Upload

Terraform Deployment

Create AAD Application Registration

Create an AAD application registration in Azure Entra ID, obtain client_id

Naming Rule: appreg-[app-name]-[environment]

e.g., appreg-serviceme-trial

Set Terraform Deployment Parameters

tip

Please contact the product team to obtain the latest deployment package (including Terraform deployment package, frontend deployment package, font package, icon resources).

Set the parameters in variables.tf according to the README.md file in the Terraform deployment package.

Azure Account Login, Subscription Switch

Open PowerShell in the working directory of the deployment package, execute the following command to log in to Azure, TENANT_ID is the tenant ID provided by the customer.

Global Cloud Login Command

az login --tenant TENANT_ID

If it is not Global Cloud, specify the --cloud parameter, for example:

China Cloud Login Command

az login --tenant TENANT_ID --cloud AzureChinaCloud

Set Subscription ID, [subscriptionId] is the subscription ID provided by the customer

az account set --subscription "[subscriptionId]"

Check the current subscription to ensure you are logged into the correct subscription

az account show

Execute Deployment

First, check if the upcoming changes meet expectations

terraform plan

+ represents adding resources
- represents deleting resources
~ represents updating resources

If there are no issues, formally apply these changes. Note that Terraform will check and output the changes again, and you need to enter yes to confirm after reviewing.

terraform apply

Wait for the deployment to complete (it takes about 20-60 minutes, with APIM deployment taking longer).

If no errors occur, Terraform will indicate how many resources were created, and the deployment is successful.

If errors occur, troubleshoot based on the error messages. Common issues include:

• Network error, request timeout errors during execution
  • Re-executing Terraform apply usually resolves the issue
• Resource already exists errors during execution
  • Check if the corresponding resources already exist through the Azure Portal, if they do, delete them through the Azure Portal (some resources have Purge Protection and may need to be deleted using specific az cli commands)
• OpenAI resource creation failure due to insufficient quota
  • Check if the OpenAI resource quota in the region is sufficient, if not, switch to another region

Update AAD Application Registration

Update the APIM URL in the AAD application registration (rule: $APIM_GATEWAY_URL + "/", e.g., https://xxx-apim.azure-api.net/), make sure to check access token and ID token.

Upload Resource Package, Start System

Install Frontend Deployment Package, Font Package, Icon Resources

Upload the following resources to the corresponding containers in the Azure Storage Account, either through Azure Storage Explorer or az cli commands.

• Frontend deployment package, upload to the static-site container, be careful not to overwrite the config.js file in it
• Font package, upload to the backend-core-fonts container
• Icon resources, upload to the icons container

Install License

Upload the License file to the static-site container in the Azure Storage Account.

Start System, Check if it Starts Successfully

Update the enable_app_service variable to true in the variables.tf file.

Re-execute the terraform apply command to enable the application service.

Check the Monitor logs of api_app_service, scheduler_app_service, and pythoncore_app_service to confirm if they start normally.

tip

If the startup fails, troubleshoot based on the information in the error logs.

System Check

Admin Login to System

Log in to the system through the APIM URL, the default admin account is servicemeadmin, and the default password is in the README.md file of the deployment package.

Test if System Functions are Normal

• Test ChatX Q&A
• Test Document Upload and Preprocessing
• Test Document Translation

Complete Configuration

Copilot Settings

The accuracy of Copilot Q&A and the form of response content are greatly influenced by the Prompt and related parameters.

The following links provide some examples of Copilot settings, which can be modified based on the customer's scenario.

Before providing Copilot to end users, thorough testing is required to ensure that the relevant skills can be correctly invoked, and the accuracy and form of the Q&A content meet user needs.

Refer to System Configuration Best Practices

Space Settings

The settings in space and document properties will affect the segmentation strategy during the preprocessing stage. Choose the most appropriate settings based on different situations to achieve better document accuracy.

tip

After adjusting the settings, remember to regenerate the index for the relevant documents, otherwise, the settings will only take effect for newly uploaded documents.

Refer to System Configuration Best Practices

Test Document Upload

You can upload some sample documents or customer-provided documents to the system. After preprocessing, test through Copilot Q&A.

Modify System Settings

Modify the system's LOGO and system title as needed.