在Azure进行部署
部署前的准备
需要提供的资源
- 一个新的专门用于部署产品的订阅，并且确保这个订阅能够创建OpenAI相关的资源。
- 一个Azure AD账号，这个账号拥有该订阅的Contributor或以上权限。
- 可以将已有AAD账号以Guest身份加入租户并授权，也可以是专门创建的用于部署的AAD账号。
- 该账号能够创建和配置AAD应用注册（例如授予：Application Developer角色）。
需要安装的工具
- 能够连接Azure SQL以及PGSQL的数据库客户端（例如：DBeaver）
- Azure Storage Explorer
- Az CLI 命令行
- 安装Terraform命令行
需要掌握的知识（建议）
- 对Azure资源有一定的了解（如：App Service、Azure SQL、Storage、Key Vault等），并且能够通过Azure Portal进行资源管理
- 对SERVICEME产品的功能和基础操作有一定了解
- 了解产品的基础功能（如Agent问答、文档上传、预处理、文档翻译等）
- 了解用户、组织、角色的创建、配置，用户密码重置
- 了解Agent的创建、授权、配置
- 了解空间的创建、授权、配置
- https://docs.serviceme.com/
- 对Terraform有一定了解，完成官方的azure-get-started教程
产品部署架构及资源清单
我们在Terraform脚本中提供了两种部署选项，可根据需要进行选择。
标准部署架构
Private Endpoint部署架构，通过Private Endpoint/Vnet实现内部资源的网络隔离，进一步提高安全性。
使用Private Endpoint时，除了基础的按数量计费外，还会产生额外的网络流量费用。
各组件用途说明
| 类型 | 自定义名称 | 用途说明 |
|---|---|---|
| Azure Front Door | CDN | (可选的) 内容分发网络，用于加速静态资源的访问 |
| Azure Front Door | API Acceleration | (可选的) API 加速，用于加速API的访问 |
| API Management | API Endpoint | API 管理终端，用于管理API |
| App Service | API Service | API 服务，用于处理API请求 |
| App Service | Job Service | 作业服务，用于处理高负载的任务，定时任务的执行 |
| Azure OpenAI Service | LLM-Primary | 主要大语言模型，用于Agent问答的主模型（例如gpt-4o） |
| Azure OpenAI Service | LLM-Secondary | 备用大语言模型，用于文档处理的辅助模型（例如gpt-4o-mini） |
| Azure OpenAI Service | Embedding | 向量嵌入，用于处理向量数据 |
| Azure OpenAI Service | Text to Image | 文本生成图像，用于处理文本生成图像的任务 |
| Azure OpenAI Service | Whisper | 语音识别，用于处理语音识别的任务 |
| Azure AI Document Intelligence | Document OCR | 文档OCR识别，用于处理文档OCR识别的任务 |
| Azure AI services | Document Translate | 文档翻译，用于处理文档翻译的任务 |
| Azure SQL Database | Data | 数据存储，主数据库，系统大部分的数据存储于此 |
| Azure Database for PostgreSQL | Index | 索引数据库，主要存储文档相关的索引数据 |
| Azure Cache for Redis | Cache | 缓存服务，用于缓存数据 |
| Storage Accounts | Files | 文件存储，用于存储用户上传的文件 |
| Key Vault | - | 密钥管理，用于存储密钥 |
| Azure Monitor | - | (可选的) 资源监控服务，收集和分析资源的指标信息 |
| Application Insights | - | (可选的) 应用监控服务，用于应用性能监控，问题诊断 |
| Vnet/Subnet | - | (可选的) 定义Azure资源的逻辑隔离网络和子网 |
| Private Endpoint | - | (可选的) 通过私有IP安全地连接到Azure服务 |
| Private DNS Zone | - | (可选的) 私有DNS，将服务的FQDN解析为私有IP |
| Managed Identity | - | (可选的) 托管标识，资源间通信的凭证 |
| Public IP | - | (可选的) 公网IP地址，在使用Private Endpoint部署架构时，Standard tier的API Management需要配置公网IP |
| Network Security Group | - | (可选的) 网络安全组，用于控制资源的网络访问 |
参考配置
- 500 用户配置
- 3000 用户配置
- 3000 以上用户配置
- Private Endpoint配置
以上配置仅供参考，需要根据实际的负载情况进行调整
进行产品部署
部署流程
- 执行部署
- 创建AAD应用注册
- 部署包准备
- Azure账号登录，订阅切换
- 执行部署
- 更新AAD应用注册
- 资源包上传，系统启动
- 安装前端部署包、字体包、图标资源
- 安装License
- 启动系统，检查是否启动成功
- 系统检查
- 管理员登录系统
- 测试系统功能是否正常
- 完善配置
- 系统设置修改
- Agent设置
- 空间设置
- 测试文档上传
Terraform部署
创建AAD应用注册
在Azure Entra ID中创建AAD应用注册，获取client_id
命名规则：appreg-[app-name]-[environment]
eg. appreg-serviceme-trial
部署包准备
请联系产品团队获取最新的部署包（包含Terraform部署包、字体包、图标资源、Web前端部署包、移动端部署包、浏览器插件包）
请参考Terraform部署包中的README.md文件，按照其中的说明配置variables.tf文件中的各项参数
如需启用 Private Endpoint 功能，请在 variables.tf 文件中将 deploy_private_network 变量设置为 true。Vnet 和 subnet 的 IP 地址配置请在 network.tf 文件中进行设置。
关于 enable_public_network_access 变量：
- 该变量用于控制除 APIM 外所有资源的公网访问权限
- 建议在所有部署完成后再将此选项设置为
false - 如果提前关闭，可能会影响 Terraform 脚本的正常执行
- 一旦关闭，将无法在vnet以外的网络访问包括keyvault、数据库在内的资源，需要部署VPN Gateway或是跳板机
Azure账号登录，订阅切换
在部署包的工作目录中打开powershell，执行以下命令登录Azure，TENANT_ID是客户提供的租户ID
Global Cloud 登录命令
az login --tenant TENANT_ID
如果是非Global cloud，请指定--cloud参数，例如：
China Cloud 登录命令
az login --tenant TENANT_ID --cloud AzureChinaCloud
设置订阅ID，[subscriptionId]是客户提供的订阅ID
az account set --subscription "[subscriptionId]"
查看当前订阅，确保已经登录到正确的订阅
az account show
执行部署
首先检查即将执行的变更是否符合预期
terraform plan
+ 代表新增资源
- 代表删除资源
~ 代表更新资源
如无问题，正式应用这些变更，注意Terraform会再次检查和输出变更内容，查看后需要输入yes进行确认
terraform apply
等待部署完成（大约需要20~60分钟，其中APIM的部署时间较长）
如果没有发生报错，Terraform将会提示创建了多少资源，部署成功。
如果出现错误，需要根据错误提示进行排查，常见问题如下：
- 执行过程中发生network error、request timeout之类的错误
- 重新执行Terraform apply一般就可以解决
- 执行过程中发生Resource already exists之类的错误
- 通过Azure Portal检查相应的资源是否已经存在，如果已经存在通过Azure Portal进行删除。（部分资源有Purge Protection，可能需要通过专门的az cli命令进行删除）
- OpenAI资源创建失败，提示quota不足
- 请检查OpenAI资源在该Region的限额是否足够，如果不足，请改换其他区域
更新AAD应用注册
将APIM的URL更新至AAD应用注册中（规则：$APIM_GATEWAY_URL + "/"，eg. https://xxx-apim.azure-api.net/ )，注意勾选access token，ID token
资源包上传，系统启动
安装前端部署包、字体包、图标资源
将以下资源上传至Azure Storage Account的对应容器中，可通过Azure Storage Explorer或是az cli命令进行上传
- 将字体包上传至
backend-core-fonts容器 - 将图标资源上传至
icons容器 - 将Web前端部署包上传至
static-site容器（请勿覆盖现有的config.js文件） - 将浏览器插件部署包上传至
extension容器（如果没有请手动创建） - 如需部署移动端，请在
static-site容器中创建mobile文件夹，配置好移动端部署包中的config.js后上传至该文件夹
安装License
将License文件上传至Azure Storage Account的static-site容器中
启动系统并验证部署状态
-
修改配置启用应用服务
- 打开
variables.tf文件 - 将
enable_app_service变量值更新为true
- 打开
-
应用配置变更
- 执行
terraform apply命令 - 等待部署完成
- 执行
-
检查服务运行状态
- 登录 Azure Portal
- 分别检查以下服务的 Monitor 日志：
- api_app_service
- scheduler_app_service
- pythoncore_app_service
- 确认所有服务均正常启动运行
如发现服务启动异常，请仔细查看错误日志信息，根据具体错误进行排查和修复。
对于采用 Private Endpoint 部署的环境，请注意以下几点：
- 部署完成后，如需限制公网访问，可将
enable_public_network_access变量设置为false - 此设置将关闭除 APIM 外所有资源的公网访问权限，提高系统安全性
- 需要注意的是，关闭公网访问后：
- Terraform 将无法直接访问 keyvault 和 Storage 资源
- 可能导致后续的 terraform apply 操作失败
- 解决方案：
- 方案一：临时启用公网访问，执行完 terraform apply 后再关闭
- 方案二：通过跳板机或 VPN Gateway 连接到 vnet 执行脚本
系统检查
管理员登录系统
通过APIM的URL登录系统，默认管理员账号为servicemeadmin，默认密码在部署包的README.md文件中。
测试系统功能是否正常
完善配置
Agent设置
Agent的问答的准确度以及回复内容的形式，很大程度受到Prompt以及相关参数的影响。
以下链接提供了一些Agent设置的示例，可以在这个基础上根据客户的场景进行修改。
在Agent提供给最终用户使用之前，需要进行充分的测试，以确保相关的技能能够被正确调用，问答的准确度以及回复内容的形式能够满足用户的需求。
参考系统设置最佳实践
空间设置
空间和文档属性中的设置将会影响到文档在预处理阶段的分段策略，请根据不同情况选择最合适的设置，以达到更好的文档准确度。
设置调整以后，请记得对相关文档重新生成索引，否则设置只会对新上传的文档生效。
参考系统设置最佳实践
测试文档上传
可以将一些示例文档或是客户提供的文档上传至系统，在完成预处理后，通过Agent问答进行测试。
系统设置修改
根据需要对系统的LOGO、系统标题进行修改。
