1. 概述
本文讲解如何在 FineBI 项目中部署启用 Data Agent。
2. 使用前提
FineBI 与 Data Agent 需要按顺序部署，因此用户需要先使用运维平台部署好 FineBI 。
| 要求 | 说明 | |
|---|---|---|
| 1 | 部署运维平台 | FineBI和 Data Agent 均依赖运维平台部署，因此用户需要提前部署好运维平台
请参考文档部署最新版运维平台：部署运维平台 内网环境请务必使用全量版离线安装包部署，否则无法获取 FineBI 相关组件镜像
请确保运维平台在 V2.26.0 及以上，建议升级到最新版本 |
| 2 | 部署 FineBI | 用户需要先使用运维平台部署好 FineBI，再对 FineBI 添加 Data Agent
1）准备FineBI部署环境 2）部署最新版FineBI项目
请确保 FineBI 部署方式为「运维平台部署」，不支持「非运维平台部署」 请确保 FineBI 版本在 7.0.7及以上，建议直接升级到最新版本FineBI 请参考文档升级 FineBI：外网升级运维项目、内网升级运维项目 因为下文提供的镜像均为最新 Data Agent 镜像，不同 FineBI 版本适配不同版本的 Data Agent 镜像，如为历史版本FineBI，需要联系帆软技术支持获取对应版本AI镜像。 |
3. 未部署使用过 FineChatBI 的 FineBI 工程
请先阅读第二章，确保所准备的运维平台和 FineBI 工程符合要求。
本章节面向从未部署过 FineChatBI 的 FineBI 工程。如曾经部署过 FineChatBI，请移步第四章。
3.1 准备Data Agent组件服务器
由于 Data Agent 所需资源较多，以及后期增加大模型等考虑，建议为 Data Agent 单独准备一台服务器。
服务器要求如下：
推荐配置：CPU32核、可用内存128G、可用磁盘1000G，AI组件独占服务器且部署PostgreSQL组件
最低配置：CPU16核、可用内存16G、可用磁盘500G，AI组件与FineBI项目共用服务器，且部署PostgreSQL组件（该配置为 Data Agent 可用配置，请在部署完 BI 后确认服务器是否有相关空闲可用配置，再着手部署 Data Agent ）
| 分类 | 推荐配置 | 最低配置 | |
|---|---|---|---|
| 适配场景 | FineBI项目服务器配置 方案二、方案四 | FineBI项目服务器配置 方案一、方案三 | |
| 服务器基础要求 | 时间一致 | Data Agent 组件服务器与项目其他服务器时间一致，相差不能超过5秒 服务器时间不一致，可能会导致定时任务执行错误、日志记录混乱、数据不一致等多种问题 | |
| 时区一致 | Data Agent 组件服务器与项目其他服务器时区完全一致 服务器时区不一致，可能会导致定时任务执行错误、日志记录混乱、数据不一致等多种问题 | ||
| 内网互通 | Data Agent 组件服务器与项目其他服务器内网互通，或可以开放端口访问 下文将具体讲述对应端口开放要求 | ||
| 不建议虚拟机 | 由于虚拟机自身的特性，会存在资源竞争等情况，可能导致出现预期外的系统故障，因此不建议在虚拟机中部署帆软应用 | ||
| 不支持K8S | 不支持在 Kubernetes 环境中部署 Data Agent 组件，请勿准备相关环境（FineBI 服务可部署在 K8S中，但需要为 Data Agent 组件准备非 K8S 环境） 更多特殊服务器情况请联系帆软技术支持确认。技术支持联系方式：「服务>在线支持」 | ||
| 操作系统 | 操作系统类型 | Linux | |
| 操作系统架构 | X86_64 ARM 注：FineBI 的 Data Agent 服务支持部署在 ARM 架构的信创服务器中。 | ||
| 操作系统内核 | 3.10 版本及以上 | ||
| 操作系统软件 | 推荐：Ubuntu 22 版本 支持：
注：CentOS 操作系统目前已停止服务，因此帆软优先推荐使用 Ubuntu 操作系统 使用 Ubuntu 操作系统时，请注意检查用户权限（默认 root 用户不是超管），下文已详细备注 | ||
| CPU | CPU核数 | 32核 | 16核 |
| CPU型号 | Intel Xeon Gold 6338 等高性能服务器处理器 Data Agent 服务依赖高性能 CPU 进行密集计算，老旧或低性能处理器会导致响应延迟，因此建议选用高性能服务器处理器 | - | |
| CPU主频 | 2.5GHz及以上 | ||
| 内存 | 剩余空闲 物理内存 | 128G | 16G |
| 磁盘 | 剩余空闲 磁盘大小 | 服务器中存在一个分区剩余可用空间大于1000G 注1：必须要有任一分区满足条件，不可将分区容量加和 | 服务器中存在一个分区剩余可用空间大于500G 注：必须要有任一分区满足条件，不可将分区容量加和 |
| 磁盘性能 | 最低性能要求为固态硬盘（SSD） | ||
| 外挂目录 | 准备外挂目录 | 准备FineBI项目挂载目录 注：禁止直接使用/、/usr、/root、/usr/local四个目录作为挂载目录，可在对应位置新建文件夹使用 | |
| 文件系统自动挂载 | 外挂目录对应的文件系统需要配置重启自动挂载 如果没有配置重启自动挂载，那么容器可能无法访问这些挂载目录，导致数据丢失或应用程序无法正常启动 | ||
| 非共享路径 | 外挂目录不能是一个共享路径 共享文件系统可能导致性能下降、文件权限问题和数据一致性挑战，这些问题会影响容器应用程序的可靠性和速度 | ||
| 权限与命令 | tar命令 | 确保服务器已安装tar命令 tar命令是一个用于打包和压缩文件的常用命令行工具 运维平台需要使用该命令进行文件解压 | |
| sed命令 | 确保服务器已安装sed命令 sed命令是一个用于处理文本的工具 运维平台需要使用该命令进行文本处理 | ||
| ssh | 确保用户可以通过ssh连接服务器 确保用户的ssh连接密码无英文单引号字符，否则部署时权限检查无法通过 | ||
| sudo权限 | 用于部署项目的服务器用户，必须具备相关sudo权限 1）优先推荐使用root超管用户进行项目部署和运行 2）如需使用非超管root用户进行项目的部署和运行 请参考文档：Linux用户权限说明 注：Ubuntu操作系统，默认的root用户并非超管用户，请务必再次确认所准备的用户是否满足上方超链的linux用户权限 | ||
| 端口网络 | 内网时延 | <1ms | |
| 组件占用端口 | 请确保默认的容器映射端口是否已被使用，如已被使用，请安排好其他空闲端口 端口占用检查和防火墙放行方法请参考：端口占用检查与防火墙配置
| ||
| 组件端口互通 | 服务器需要对外开放一些端口，以确保组件间正常工作 端口占用检查和防火墙放行方法请参考：端口占用检查与防火墙配置 1）FineAI（fine-ai）
2）语义解析小模型（fine-chat-bi-parser）
3）FineAI Redis（fine-ai-redis）
4）PostgreSQL（postgresql）
| ||
3.2 准备Data Agent镜像
Data Agent 镜像无法直接从云端仓库拉取，需要手动推送镜像入库。
1）获取镜像包
注1：对于信创版FineBI，支持在ARM架构的信创服务器中添加AI服务。
注2：本文提供的镜像均为最新AI镜像，不同FineBI版本适配不同版本的AI镜像。如需历史版本镜像，请联系帆软技术支持获取。
| x86 架构 |
|
|---|---|
| ARM 架构 |
|
2）上传镜像包
管理员登录运维平台，点击「运维平台管理>运维组件」。
点击「导出部署信息」，导出成功后会提示导出的文件地址。
前往运维平台所在服务器，在导出文件所在的logs目录，同级目录下，有一个resources文件夹，即为镜像上传位置。
例如本示例，导出文件所在文件夹为/home/ops/fanruan_5d15bea4/ops/logs，那么镜像上传位置为/home/ops/fanruan_5d15bea4/ops/resources
请将上一步下载的两个镜像.tar.gz文件，上传到resources文件夹中
3）推送入库
管理员登录运维平台，点击「维护中心>镜像管理」，点击「加载镜像」。
即可选择resources下的两个 AI 镜像文件进行加载，加载完成后resources下的镜像文件会被删除。
4）确认并修改部署版本
推送成功后，管理员登录运维平台，点击「维护中心>镜像管理」，查看推送到仓库的新镜像。
找到刚刚推送的 fine-ai-bi7 和 fine-chat-bi-parser-bi7 镜像，记下版本号。
管理员登录运维平台，点击「运维平台管理>更新升级>部署列表>手动修改」。
手动修改AI相关的两个组件的镜像版本号，确保与镜像管理中的镜像版本号完全一致，此时运维平台才会读取到有待更新的镜像版本。
3.3 确认存在redis镜像
FineAI Redis组件，即镜像仓库中的redis组件。
管理员登录运维平台，点击「维护中心>镜像管理」，即可查看当前镜像仓库中是否存在redis镜像。
请确保存在v20.3.0-6.2.17及以上版本的redis镜像。如不存在符合版本要求的redis镜像，请确认镜像仓库支持连接帆软云端仓库
3.4 部署Data Agent组件
1）进入添加组件界面
管理员登录运维平台，选择对应 FineBI 项目，点击「维护>组件管理」按钮。
点击「添加组件」，选择添加组件类型「业务服务>AI」
2）新增节点（选做）
如为AI组件准备了全新服务器，需要先将该服务器添加到项目节点中。
点击「新增节点」按钮，输入服务器信息，点击「新增节点」，等待添加完成即可。
具体节点设置如下表所示：
| 节点设置 | 说明 |
|---|---|
| 节点类型 | 请选择「组件」 该组件服务器上不建议部署其他工程或内容 |
| 主机 | 请输入节点主机IP（内网IP） 注：同一项目中，主机不支持重复添加多次 |
| 端口 | 请输入节点端口号，默认为22 |
| 用户名 | 请输入有sudo权限的服务器用户名 |
| 验证方法 | 支持两种：密码、公钥 注1：密码密钥仅用于部署项目，部署结束后无需使用，项目与运维平台的对接依赖平台配置。 因此后续如修改了服务器密码，不会对运维监控产生影响。 注2：如选择公钥方式验证 请上传后缀为.key / .pem / .crt的私钥文件（例如id_rsa.key） 请勿上传其他后缀格式的私钥文件，请勿上传公钥文件（例如id_rsa.pub） |
| 挂载路径 | 请输入节点安装目录的服务器路径，即 3.1 节准备环节设置的挂载目录 默认为~/data，~代表所使用的服务器用户的主目录 注：可在终端使用该用户账号访问服务器，输入echo $HOME命令查看该用户的主目录路径 |
| 外网IP | 选填项 如果服务器不支持内网访问，仅支持外网映射，可以填写可联通的外网IP |
3）选择节点
选择需要用于部署AI组件的项目节点。
节点最低配置为CPU8核、可用内存16G、可用磁盘300G。低于该配置的节点灰化不可选。
4）确认服务配置
请根据3.1节准备的可用空闲端口，对每一个组件的端口进行调整
请务必修改FineAI Redis组件的密码，组件的默认密码随机生成，部署成功后无法修改。
5）开始部署
点击「开始部署」按钮，自动在所选节点中部署AI相关组件。若部署失败则显示失败原因。
3.5 配置Data Agent插件
1）下载 Data Agent 插件
2）管理员登录FineBI，点击「管理系统>插件管理>应用商城」
3）点击「从本地安装」，选择获取的 FineChatBI 插件安装包，完成安装即可。
注：插件包较大，因此安装时间较长，请耐心等待。
3.6 获取Data Agent授权
Data Agent 相关授权，请联系帆软销售获取。
授权安装方法：根据网络环境，推荐 公有云认证 （外网）/ 注册新项目（内网）
3.7 确认配置成功
Data Agent 配置成功，且 Data Agent 相关授权安装成功后，在 FineBI 右上角出现「Data Agent」按钮，即代表 Data Agent 配置完成。
4. 部署使用过 FineChatBI 的 FineBI 工程
请先阅读第二章，确保所准备的运维平台和 FineBI 工程符合要求。
本章节面向曾经部署过 FineChatBI 的 FineBI 工程。如未部署过 FineChatBI，请移步第三章。优先建议使⽤未部署过 FineChatBI 的新 FineBI 工程，帆软不协助处理 ChatBI 升级至 Data Agent 出现的兼容问题，若部署后 Data Agent 中携带部分 ChatBI 的旧数据，请⾃⾏检查其是否可⽤，或重新进⾏配置。
4.1 卸载 FineChatBI 插件
管理员登录FineBI，点击「管理系统>插件管理>应用商城」，卸载 FineChatBI 插件。
4.2 准备Data Agent镜像
Data Agent 镜像无法直接从云端仓库拉取，需要手动推送镜像入库。
1）获取镜像包
注1：对于信创版FineBI，支持在ARM架构的信创服务器中添加AI服务。
注2：本文提供的镜像均为最新AI镜像，不同FineBI版本适配不同版本的AI镜像。如需历史版本镜像，请联系帆软技术支持获取。
| x86 架构 |
|
|---|---|
| ARM 架构 |
|
2）上传镜像包
管理员登录运维平台，点击「运维平台管理>运维组件」。
点击「导出部署信息」，导出成功后会提示导出的文件地址。
前往运维平台所在服务器，在导出文件所在的logs目录，同级目录下，有一个resources文件夹，即为镜像上传位置。
例如本示例，导出文件所在文件夹为/home/ops/fanruan_5d15bea4/ops/logs，那么镜像上传位置为/home/ops/fanruan_5d15bea4/ops/resources
请将上一步下载的两个镜像.tar.gz文件，上传到resources文件夹中
3）推送入库
管理员登录运维平台，点击「维护中心>镜像管理」，点击「加载镜像」。
即可选择resources下的两个 AI 镜像文件进行加载，加载完成后resources下的镜像文件会被删除。
4）确认并修改部署版本
推送成功后，管理员登录运维平台，点击「维护中心>镜像管理」，查看推送到仓库的新镜像。
找到刚刚推送的 fine-ai-bi7 和 fine-chat-bi-parser-bi7 镜像，记下版本号。
管理员登录运维平台，点击「运维平台管理>更新升级>部署列表>手动修改」。
手动修改AI相关的两个组件的镜像版本号，确保与镜像管理中的镜像版本号完全一致，此时运维平台才会读取到有待更新的镜像版本。
4.3 升级原 FineChatBI 组件至 Data Agent 组件版本
用户可通过「组件管理」将原 FineChatBI 组件升级至 Data Agent 组件版本，平滑使用。
4.4 配置Data Agent插件
1）下载 Data Agent 插件
2）管理员登录FineBI，点击「管理系统>插件管理>应用商城」
3）点击「从本地安装」，选择获取的 FineChatBI 插件安装包，完成安装即可。
注：插件包较大，因此安装时间较长，请耐心等待。
4.5 获取Data Agent授权
Data Agent 相关授权，请联系帆软销售获取。
授权安装方法：根据网络环境，推荐 公有云认证 （外网）/ 注册新项目（内网）
4.6 确认配置成功
Data Agent 配置成功，且 Data Agent 相关授权安装成功后，在 FineBI 右上角出现「Data Agent」按钮，即代表 Data Agent 配置完成。
5. 升级Data Agent
1）请先参考文档将 FineBI 项目升级到最新：外网升级运维项目 / 内网升级运维项目
2）参考本文 3.2 节推送最新的 AI 镜像包到运维平台仓库。
3）管理员登录运维平台，选择运维项目。点击「维护>组件管理」。找到待更新的 AI 组件，点击「更新」。
4）升级完成后请将 3.5 节安装的插件升级到最新。
6. 升级ElasticSearch 组件
6.1 确认ElasticSearch组件版本
请确保升级 ElasticSearch 组件至 v20.4.5-8.17.3 及以上版本，并确保 ElasticSearch 组件处于 running 状态。
详情请参见：内网升级运维项目。
6.2 自定义ElasticSearch 组件环境变量
请通过开发者模式，自定义 ElasticSearch 组件的环境变量，将 INSTALL_FINE_PLUGIN 的值修改为 yes。
详情请参见：开发者模式。
7. 连接测试
完成以上所有操作后，将成功部署并可进入 Data Agent 页面，在正式使用 Data Agent 平台前，管理员需进行平台和模型连接测试操作。
注：若连接测试出现报错，可前往 大模型问题排查指南 查看。
7.1 平台连接测试
前往「Data Agent 管理后台>开放集成>其他」，完成如下两个操作：
1）在后台地址中添加当前已部署 Data Agent 的 FineBI 地址，地址格式需保持统一，IP 与域名不可混用。
2）点击「连接测试」，以保证 FineAI 插件与 FineBI 平台互通且版本一致。
7.2 模型连接测试
前往「Data Agent 管理后台>模型」，对已添加的目标模型进行连接测试，保证大模型为可用状态。
