Deploying AI-ML in Microsoft Windows

To deploy AI-ML component in Microsoft Windows, complete the following procedures:

Configuring Python files

Procedure

  1. Access the Python3.11.7 folder available under Platform/ML directory.
  2. In the Platform/ML/startup.bat file, replace the placeholder [PYTHON_BASE_LOCATION] with the absolute path to Python3.11.7 directory.
  3. In the Platform/ML/lib directory, access the site-packages folder.
  4. In the Platform/ML/startup.bat file, replace the placeholder [replace_with_the_sitepackages_path] with the absolute path to site-packages directory.

Configuring the conf.ini document

About this task

The conf.ini file has the following format:

[server]
# Hostname or IP address of the machine hosting the ML service
host = 127.0.0.1

# Port number for the ML service
port = 8000

[security]
# API security token for the ML service
api-token =

# To enable TLS/SSL deployment, set this to "yes"
use-ssl = no

# Absolute path to the TLS/SSL private key
ssl-keyfile = key.pem

# TLS/SSL keyfile password. If required, you can leave the password unspecified and provide the password during server startup.
ssl-keyfile-password =

# Absolute path to the TLS/SSL certificate
ssl-certfile = cert.pem

[others]
# Number of requests retained in segment suggestion history for each user (for optimal experience, provide a value between 5 and 20).
segmentation.request.history.max-limit = 10

# Maximum allowed CPU capacity for ML service. Valid values are 0 and 1, where 1 represents 100% capacity.
cpu.utilization.max-limit = 0.8

# Maximum allowed memory utilization for ML service. Valid values are 0 and 1, where 1 represents 100% capacity.
memory.utilization.max-limit = 0.8

# Maximum number of CPU cores permitted for the ML service.
cpu.jobs.max-cores = 4

# Batch size for audience segmentation. Valid values are 16, 32, 64, 128, 256, and so on. For optimal performance, keep the batch size low.
memory.segmentation.batch-size = 64

# The Clustering algorithm that is to be used for audience segmentation. Only "hdbscan" is supported.
segmentation.algorithm = hdbscan

[hdbscan]
# Default minimum segment size, in percentage, of the total filtered audiences (0.01 represents 1% of total filtered audiences).
minimum-cluster-ratio = 0.0001
 
# Maximum number of workers for parallel segmentation processing. Performance is dependent on the allocated CPU and memory.
max-workers = 8


algorithm = best
min-samples = 5
leaf-size = 40

To configure the conf.ini file, complete the following steps:

Procedure

  1. From the Platform/ML/conf folder, access the conf.ini file.
  2. Configure the following fields in the [server] section of the file:
    host The host name or the IP address on which you want to run the ML service.
    port The port on which you want to run the ML service.
  3. Configure the following fields in the [security] section of the file:
    api-token The API security token referenced in this context is a prerequisite for clients accessing the ML service. It is imperative to configure this token consistently, ensuring that the same token is utilized as the datasource password in Configuration > Platform > ML > navigation. Verify that the tokens match precisely in both settings, as any discrepancies will result in an error.
    use-ssl If you are using SSL (i.e HTTPS), set it to yes and generate the keyfile and the certificate file (use a tool of your choice to generate the private key and the certificate file). If you set use-ssl to yes, you must configure ssl-keyfile and ssl-certfile. If you are not using SSL (i.e HTTP), set it to no. If you set use-ssl to no, ignore ssl-keyfile and ssl-certfile.
    Note: It is strongly recommended to operate ML service over a TLS/SSL connection to enhance the security of API access. If TLS/SSL is disabled, generate a symmetric encryption key and insert it into the designated files listed below:

    Under ML service - conf/security/decryption.key

    Under Segment Central - conf/security/encryption.key

    This extra measure ensures the minimum necessary security for the system.
    ssl-keyfile The location of private key file generated with its name and extension. Example: D:\HCL\unica\key.pem.
    ssl-certfile The location of the TLS certificate generated with its name and extension. Example D:\HCL\unica\cert.pem.
  4. Configure the following fields in the [others] section of the file:
    segmentation.request.history.max-limit = 10 This is the recent number of suggestion requests to be shown on the suggestion screen. Increasing it will show more suggestion history for the particular user.
    Note: Suggestions more than the suggested limit (either pending, successfully done, or failed) are removed from the system and cannot be recovered.
    cpu.utilization.max-limit = 0.8 Specify the desired CPU capacity for the ML service by assigning a value within the range of 0 to 1, where 1 corresponds to 100% CPU utilization.
    memory.utilization.max-limit = 0.8 Specify the desired memory utilization for the ML service by assigning a value within the range of 0 to 1, where 1 corresponds to 100% RAM utilization.
    Note: We recommend that you refrain from setting the memory limit to 1. Assigning 1 to this property results in the system utilizing the entire system memory, potentially causing disruptions to other processes, leading to improper functionality or halting altogether.
    cpu.jobs.max-cores = 4 Specify the maximum number of CPU cores allocated to the ML service. Additionally, controls the overall capacity across all assigned cores by configuring cpu.utilization.max-limit. It is advisable to limit this number to half or a quarter of the total available cores to optimize performance and resource utilization.
    memory.segmentation.batch-size=64 Specify the data partition size in megabytes (MB). It is advisable to maintain a lower value, such as 32, 64, 128, 256, 512, and so forth. This practice facilitates the smooth processing of large datasets within limited memory space. If you encounter memory errors in the logs, consider reducing the configured value accordingly.
    segmentation.algorithm = hdbscan Presently, only hdbscan is supported.
  5. Configure the following fields in the [hbdscan] section of the file:
    minimum-cluster-ratio = 0.0001 The default minimum cluster size is applied if it is not explicitly specified while requesting the segment suggestions in Segment Central. When providing a ratio value, choose a lower value for larger audience datasets, as opting for a larger value may result in increased execution time while generating segment suggestions (The value 0.01 corresponds to 1% of the audience dataset size).
    max-workers = 8 Number of workers for the algorithm to process. More the number of workers, faster the execution. Avoid assigning a high value.
    algorithm = best The best algorithm (from hdbscan internals) is selected automatically. Do not change this value.
    min-samples = 5 Minimum number of samples needed for making a cluster point. Do not change this value as high values can lead to memory error.
    leaf-size = 40 Do not change this value.

Configuring encoding.ini file

About this task

Audience data may include categorical information, where the order or ranking of categories is crucial for segmentation. For example, a dataset of audiences categorized into job positions like "Junior", "Intermediate", "Senior", and "Lead." In such cases, it is essential to create segments based on the specific ranking of job positions rather than using an arbitrary order. The ML service offers a way to specify these orders in the Platform/ML/conf/encoding.ini file. If the dataset is stored in a user database table named Audiences, with job positions recorded in the job_position column, configure the encoding.ini file as shown in the following example. The ML service considers these declarations when generating segment recommendations.
[Audiences]
job_position = Junior, Intermediate, Senior, Lead
Note: This declaration does not support categories having commas in their name.

This declaration can be expanded to include other columns in the Audiences table, as well as any other database table in the same way.

[Audiences]
job_position = Junior, Intermediate, Senior, Lead
another_column_in_audiences = category1, category2, category3, category4

[some_other_audience_table]
column_name = category1, category2, category3

Starting the ML services

Procedure

  1. Open the command prompt.
  2. Change the directory to Platform/ML.
  3. To launch the ML service, run the command startup.bat.