Application scenario: This document is for deploying and enabling the Data Agent in a FineBI project where FineChatBI has not been deployed or used. If FineChatBI has already been deployed and used, refer to Data Agent Deployment (FineChaBI Deployed/Used) for operations.
Only deployments that include the PostgreSQL component are supported, and PostgreSQL is a required component.
All images provided in this document are of the latest versions. No images of historical versions are provided.
FineBI and Data Agent must be deployed in sequence. Therefore, you need to deploy FineBI first using the O&M platform.
Requirement
Description
1
O&M Platform Deployment
Both FineBI and Data Agent rely on the O&M platform for deployment. Therefore, you need to deploy the O&M platform in advance.
If the O&M platform has not been deployed yet:
Refer to FineOps Deployment to deploy the O&M platform of the latest version.
If the O&M platform has been deployed:
Ensure that the O&M platform is of V2.36.0 or later versions. You are advised to upgrade the O&M platform to the latest version.
For details about how to upgrade the O&M platform, refer to Extranet-Based FineOps Upgrade/Intranet-Based FineOps Upgrade.
2
FineBI Deployment
You need to first deploy FineBI using the O&M platform, and then add the Data Agent to FineBI.
(1) Prepare the FineBI deployment environment.
Confirming Server Configuration of the FineBI Project
Confirming Server Network of the FineBI Project
Preparing the FineBI Mounting Directory
(2) Deploy the FineBI project of the latest version.
New Project Deployment
3
Opened AI Component Deployment Entry
The AI component deployment entry is not directly open to the public by default.
Log in to the O&M platform as the administrator, click the corresponding FineBI project, and choose Maintenance > Component Management > Add Component.
If the ai component deployment entry is not displayed in Business Service, contact FanRuan technical support or sales personnel to obtain the method for opening the entry.
Since the Data Agent requires multiple resources and may need configuration resources for future expansion, you are advised to prepare a separate server for the Data Agent and deploy the PostgreSQL component. The following lists server-related requirements.
Prepare a separate server dedicated only to AI component deployment, and deploy the PostgreSQL component. The following table lists server-related requirements.
Component Description
The following four components in total are deployed:
fine-ai
fine-chat-bi-parser
fine-ai-redis
postgresql
Processor Architecture
The following two are supported:
x86_64
ARM
Operating System
The following four are supported:
Ubuntu 18.04.4 and later versions (Ubuntu 20.04 unsupported)
CentOS 7.3 to 7.9
Red Hat 7.6 and later versions
Rocky Linux 8.8 to 9.4
System Resource
(High-End Configuration)
You are advised to prepare a server with the following resources:
CPU: 32 cores
Memory: 128 GB
Disk: 1000 GB
The following lists server resource allocation for reference:
(1) fine-ai component: 8-core CPU and 32-GB memory
(2) fine-chat-bi-parser component: 8-core CPU and 32-GB memory
(3) fine-ai-redis component: 8-core CPU and 32-GB memory
(4) postgresql component: 8-core CPU and 32-GB memory
(Mid-Range Configuration)
CPU: 16 cores
Memory: 64 GB
Disk: 500 GB
(1) fine-ai component: 4-core CPU and 16-GB memory
(2) fine-chat-bi-parser component: 4-core CPU and 16-GB memory
(3) fine-ai-redis component: 4-core CPU and 8-GB memory
(4) postgresql component: 4-core CPU and 8-GB memory
If the AI component shares a server with the FineBI project and the PostgreSQL data source component is deployed, at least the following resources need to be reserved for the FineBI project server to properly install the AI component. Only in this minimum configuration scenario do you need to set the single WORKER parameter FINE_AI_UVICORN_WORKERS for the fine-ai component.
In addition to the FineBI-related components, install the following AI-related components:
Reserved System Resource
At least the following resources are reserved for the server:
Memory: 32 GB
The following lists the reserved server resource allocation for reference:
(1) fine-ai component: 4-core CPU and 8-GB memory
(2) fine-chat-bi-parser component: 4-core CPU and 4-GB memory
(3) fine-ai-redis component: 4-core CPU and 4-GB memory
(1) Log in to the O&M platform as the administrator, select the corresponding FineBI project, and choose Maintenance > Component Management.
(2) Click Enter Developer Mode, locate the fine-ai component, and click Customize Environment Variable.
(3) In the pop-up box, set the environment variable FINE_AI_UVICORN_WORKERS to 1.
For other server content and precautions, refer to the following table.
Category
Recommended Configuration
Minimum Configuration
Applicable Scenario
FineBI Project Server Configuration Scheme Two and Scheme Four
FineBI Project Server Configuration Scheme One and Scheme Three
Basic Server Requirement
Time Consistency
The time on the Data Agent component server and other servers in the project must be consistent, with a difference not exceeding 5 seconds.
Server time inconsistency may cause problems such as scheduled task execution errors, log recording chaos, and data inconsistency.
Timezone Consistency
The timezone of the Data Agent component server must be exactly the same as that of other servers in the project.
Server timezone inconsistency may cause problems such as scheduled task execution errors, log recording chaos, and data inconsistency.
Intranet Connectivity
The Data Agent component server and other servers in the project must be interoperable via the intranet, or have open ports for access.
The following will describe the specific port opening requirements.
Virtual Machine Non-recommended
Due to the inherent characteristics of virtual machines, issues such as resource contention may occur, potentially leading to unexpected system failures. Therefore, you are not advised to deploy FanRuan applications in virtual machines.
K8s Unsupported
The Data Agent components cannot be deployed in a K8s (short for Kubernetes) environment. Do not prepare such an environment. (The FineBI service can be deployed in a K8s environment, but a non-K8S environment needs to be prepared for the Data Agent components.)
For more special server scenarios, contact FanRuan technical support for confirmation. For details about how to contact our technical support, see Technical Support Channel Introduction.
Operating System Type
Linux
Operating System Architecture
Operating System Kernel
3.10 and later versions
Operating System Software
Recommended: Ubuntu 22
Supported:
CentOS has been discontinued. Therefore, FanRuan recommends that the Ubuntu operating system be used preferentially.
When using the Ubuntu operating system, check user permissions, which are described specifically below. (The default root user is not a super administrator.)
CPU
Number of CPU Cores
32 cores
16 cores
CPU Model
High-performance server processors such as Intel Xeon Gold 6338
The Data Agent service relies on high-performance CPUs for intensive computing. Legacy or low-performance processors will cause response delays. Therefore, high-performance server processors are recommended.
/
CPU Clock Speed
2.5 GHz and above
Memory
Available Physical Memory
128 GB
32 GB
Disk
Available Disk Space
The server must have at least one partition with more than 1000 GB of available space.
The server must have at least one partition with more than 300 GB of available space.
Disk Performance
At least solid state drives (SSDs) are required.
Mounting Directory
External Mounting Directory Preparation
Automatic File System Mounting
Automatic mounting upon reboot needs to be configured for the file system corresponding to the external mounting directories.
If automatic remount on reboot is not configured, the container may not be able to access these mounting directories, leading to data loss or improper application startup.
Non-Shared Path
The external mounting directory cannot be a shared path.
A shared file system may cause performance degradation, file permission issues, and data consistency challenges, which will affect the reliability and speed of container applications.
Permission and Command
tar command
Ensure that the tar command has been installed on the server.
The tar command is a common command-line tool used to pack and compress files.
The O&M platform requires this command for file decompression.
sed command
Ensure that the sed command has been installed on the server.
The sed command is a tool to process texts.
The O&M platform requires this command for text processing.
ssh command
Ensure that you can connect to the server via the ssh command.
Ensure that your SSH connection password contains no single quotation marks. Otherwise, the permission check will fail during deployment.
sudo permission
The server users for project deployment must have related sudo permissions.
(1) You are advised to deploy and run the project as the root super administrator.
(2) If you need to deploy and run the project as a non-root super administrator,
refer to Linux User Privilege Explanation.
Port and Network
Intranet Latency
< 1ms
Component-Occupied Port
Check whether the default container mapping ports have been occupied. If they have, arrange for other available ports.
For port occupancy inspection and firewall passing methods, refer to Port Occupancy Inspection and Firewall Configuration.
FineAI (fine-ai): 7666
Semantic parsing SLM (fine-chat-bi-parser): 8666
FineAI Redis (fine-ai-redis): 6679
PostgreSQL (postgresql): 5432
Component Port Interconnectivity
The server needs to have some ports open externally to ensure proper running between components.
(1) FineAI (fine-ai)
The FanRuan intranet gateway in the FineBI project can access FineAI.
Each bi-web in the FineBI project can access FineAI.
(2) Semantic parsing SLM (fine-chat-bi-parser)
Each bi-web in the FineBI project can access the semantic parsing SLM.
(3) FineAI Redis (fine-ai-redis)
The semantic parsing SLM can access FineAI Redis.
FineAI can access FineAI Redis.
PostgreSQL can access FineAI Redis.
FineAI can access each bi-web.
(4) PostgreSQL (postgresql)
FineAI can access PostgreSQL.
(1) Download the Data Agent plugin.
Data Agent Plugin
(2) Log in to FineBI as the administrator, and choose System Management > Plugin Management > App Store.
(3) Click Local Install, select the obtained Data Agent plugin installation package, and complete the installation.
The Data Agent images cannot be pulled directly from the cloud repository, but need to be manually pushed into the repository.
1. For FineBI of the Information Technology Application Innovation Industry (ITAI) version, you can add AI services into ARM-based ITAI servers.
2. The images provided in this document are all the latest AI images. Different FineBI versions are compatible with different AI image versions. If you need images of historical versions, contact FanRuan technical support.
x86 Architecture
FineAI component image: FineAI component image
FineChatBI semantic parsing SLM image: FineChatBI semantic parsing SLM image
ARM Architecture
Log in to the O&M platform as the administrator and choose O&M Platform > Platform Management > O&M Component.
Click Export Deployment Information. After deployment information is exported successfully, the address of the exported file will be prompted.
Go to the server where the O&M platform is located. At the same directory level as the logs directory where the exported file is located, there is a resources folder, which is the image upload location.
For example, in this example, the path where the exported file is located is /home/ops/fanruan_5d15bea4/ops/logs, so the image upload location is /home/ops/fanruan_5d15bea4/ops/resources.
Upload the two .tar.gz image files downloaded in the previous step to the resources folder.
Log in to the O&M platform as the administrator, choose Maintenance Center > Image Management, and click Load Image.
You can then select the two AI image files in the resources folder to load them. After being loaded successfully, the image files in the resources folder will be deleted.
After the images are pushed successfully, log in to the O&M platform as the administrator and choose Maintenance Center > Image Management to view the new images pushed to the repository.
Find the newly pushed fine-ai-bi7 and fine-chat-bi-parser-bi7 images, and remember their version numbers.
Log in to the O&M platform as the administrator, and choose O&M Platform > Platform Management > Update & Upgrade > Deployment List > Manual Change.
Manually modify the image version numbers of the two AI-related components to ensure that they are exactly the same as the image version numbers in Image Management. Only in this case will the O&M platform read the image versions to be updated.
The FineAI Redis component is the redis component in the image repository.
Log in to the O&M platform as the administrator, choose Maintenance Center > Image Management, and check whether the redis image exists in the current image repository.
Ensure that the redis image of v20.3.0-6.2.17 or later versions exists. If no redis image meeting the version requirements exists, ensure that the image repository can connect to the FanRuan cloud repository.
Log in to the O&M platform as the administrator, select the corresponding FineBI project, and choose Maintenance > Component Management.
Click Add Component and choose Business Service > AI to add the AI components.
If a new server has been prepared for the AI components, you need to add this server to the project nodes first.
Click the Add Node button, enter the server information, click Add Node below, and wait for the node to be added.
The following table describes specific settings.
Node Setting
Node Type
Select Component.
Host
Enter the node host IP address (intranet IP address).
Port
Enter the node port number, which is 22 by default.
Username
Enter the server username with sudo permissions.
Verification Method
Password and Public Key are supported.
1. The password/key is only used for project deployment and is not required after deployment is complete. The connection between the project and the O&M platform relies on platform configuration.
Therefore, subsequent changes to the server password will not affect O&M monitoring.
2. If you set Verification Method to Public Key:
Upload a private key file with the name extension .key, .pem, or .crt (for example, id_rsa.key).
Do not upload private key files with other name extensions, and do not upload public key files (for example, id_rsa.pub).
Mounting Path
Enter the server path of the node installation directory, which is the mounting directory set in the "Data Agent Server Preparation" section of this document.
The default path is ~/data, where ~ represents the home directory of the used server user.
Extranet IP
Optional
If the server does not support intranet access and only supports extranet mapping, you can enter an accessible extranet IP address.
Select the project node to be used for deploying the AI components.
The minimum node configuration is a 16-core CPU, 32-GB available memory, and 500-GB available disk space. Any node below this configuration will be grayed out (unavailable).
Adjust the ports for each component according to the available ports prepared in the "Data Agent Server Preparation" section of this document.
(1) You must change the passwords for the FineAI Redis component and the PostgreSQL component. The default component passwords are randomly generated and cannot be modified after deployment.
(2) The postgresql component username is fine_ai_checkpoint_user.
Click the Start Deployment button to automatically deploy AI-related components on the selected node. If the deployment fails, the failure reason will be displayed.
For Data Agent-related authorization, contact FanRuan sales personnel.
Authorization installation method: Depending on the network environment, public cloud authentication (extranet) and new project registration (intranet) are recommended.
After you have completed the above Data Agent configuration and successfully installed the Data Agent-related authorization, the Data Agent button will appear in the upper right corner of FineBI. At this point, only the basic configuration is complete. Continue with the following operations in this document.
Ensure that the Elasticsearch component has been upgraded to v20.4.5-8.17.3 or later versions and is in a running state.
For details, refer to Intranet-Based O&M Project Upgrade.
Customize the environment variable of the Elasticsearch component through the developer mode, that is, setting INSTALL_FINE_PLUGIN to yes. For details, refer to Developer Mode.
After all the above operations are completed, Data Agent will be deployed successfully for you to enter. Before formally using the Data Agent platform, you need to perform platform and model connection tests as the administrator.
Enter Data Agent, choose Admin Console > App Connection, and complete the following two operations:
(1) In the Backend Address area, add the FineBI address where the Data Agent is currently deployed. The address format must be consistent. The IP address and domain name cannot be used interchangeably.
(2) Click Test Connection to ensure that the FineAI plugin and the FineBI platform are interoperable and have consistent versions.
Enter Data Agent, choose Admin Console > Model, and perform a connection test on the added target model to ensure that the large language model (LLM) is available.