Label Studio guide-PolarDB(PolarDB)-阿里云帮助中心

Overview

Label Studio is a versatile, open-source data labeling platform that supports various task types, such as image classification, object detection, and text annotation. It provides an intuitive web interface to create high-quality labels for machine learning training data.

PolarDB for AI integrates the deployment capabilities of Label Studio into the AI node and enables two-way data synchronization with the database. When you deploy the service, the system automatically loads image data from a database table that you specify. After you submit an annotation in the web interface, the result is written back to the corresponding field in the table in JSON format in real time.

Benefits

Automated data flow: Automatically load images from a specified data table and write annotation results back to the database in real time, eliminating the need for manual import and export.
Simplified operations: Deploy, manage, and clean up services entirely through the SQL interface, eliminating the need to manage extra servers.
Concurrent projects: Deploy and manage multiple independent annotation projects on demand by using SQL commands. Each project has its own service and access endpoint.
Built-in security: An IP address whitelist and automatically generated initial credentials ensure secure data access.

GPU specifications

Before you begin, ensure that the following prerequisites are met:

Node: Add an AI node with GPU specifications and set a database account for the AI node. For more information, see Add and manage AI nodes.
Note
- If you added an AI node when you created the cluster, you can directly set the database account for the AI node.
- The database account for the AI node must have read and write permissions to access the target database.
Endpoint: Use the cluster endpoint to connect to the PolarDB cluster.

Prepare the environment and data

Before you deploy the service, prepare the data table and the data to be annotated.

Step 1: Install extension and set credentials

Log on to the cluster with a privileged account.
Get the node token.
Go to the PolarDB console. On the details page of your target cluster, in the Database Nodes section, find the AI node, click View Node Token, and then record the Node Token.
Create the polar_ai extension and configure the node token.
Run the following commands in your database to create the extension and set the key to access large model services.
Important
Ensure you have set a database account for the AI node.
```
-- Create the extension.
CREATE EXTENSION polar_ai;

-- Set your key. Replace sk-xxx with your key for the large model service.
SELECT polar_ai._ai_nl2sql_alter_token('sk-xxx');
```

Step 2: Create the annotation template table

This table defines the UI style and label categories for the annotation task. The table name annotation_template and its structure are fixed.

Create a table to store annotation templates.

CREATE TABLE IF NOT EXISTS public.annotation_template(
  id SERIAL NOT NULL PRIMARY KEY,              -- Template ID
  tp_name varchar(255) NOT NULL,               -- Template name
  tp_description text,                         -- Template description
  tp_schema jsonb NOT NULL,                    -- Annotation schema in JSON format
  tp_is_active boolean DEFAULT 'Y'             -- Specifies whether the template is enabled.
);
CREATE UNIQUE INDEX IF NOT EXISTS tp_name_index ON public.annotation_template USING BTREE(tp_name);

Insert two sample templates for object detection tasks.

INSERT INTO public.annotation_template (id, tp_name, tp_description, tp_schema, tp_is_active) VALUES
(1, 'schema_animal', 'Annotate animals', '{"type": "ObjectDetection", "labels": ["cat", "dog"]}', TRUE),
(2, 'schema_vehicular', 'Annotate vehicles', '{"type": "ObjectDetection", "labels": ["car", "airplane"]}', TRUE);

Description of the tp_schema field:

type: Defines the annotation task type. Currently, only ObjectDetection is supported.
labels: Defines a list of available labels. Label Studio generates the label selection checkboxes on the annotation interface based on this list.

Step 3: Prepare the image data source table

The data source table stores information about the images to be annotated. You can create different data source tables for each project, but the field names and data types are fixed.

Create a data source table to store image data.

CREATE TABLE public.polardb4ai_annotation_source_animal (
  id SERIAL NOT NULL  PRIMARY KEY,
  base64_data text,                          -- Base64-encoded string of the image
  mime_type varchar(100) NOT NULL,           -- Image MIME type, such as 'jpg'
  original_name varchar(255) NOT NULL,       -- Task name displayed in Label Studio
  created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  annotation_data jsonb DEFAULT NULL,        -- Stores the annotation result (JSON)
  annotation_create_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  annotation_update_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  annotation_count bigint DEFAULT 0 NOT NULL,
  annotation_uid varchar(255) DEFAULT NULL
);

Insert image data into the data source table. You can use the AI_LoadFile function (which requires the polar_ai_util extension to be installed), a Python script, or other tools to convert local images into Base64 strings and insert them.

INSERT INTO public.polardb4ai_annotation_source_animal 
    (id, base64_data, mime_type, original_name)
VALUES
    (1, encode(polar_ai.AI_LOADFILE('oss://<ak>:<sk>@<oss-internal-endpoint>/<bucket>/temp/animal1.jpg'), 'base64'), 'jpeg', 'animal1.jpeg'),
    (2, encode(polar_ai.AI_LOADFILE('oss://<ak>:<sk>@<oss-internal-endpoint>/<bucket>/temp/animal2.png'), 'base64'), 'png', 'animal2.png');

Python script example

import os
import base64
# The psycopg2 library is required. Example: pip install psycopg2-binary
import psycopg2

# Database configuration (modify based on your environment)
DB_CONFIG = {
    'host': '<your_polardb_host>',
    'port': 5432,
    'user': '<your_polardb_username>',
    'password': '<your_polardb_user_password>',
    'database': '<your_polardb_database>'
}

# Image folder path (modify to your folder path). The script uploads all images in the folder.
IMAGE_DIR = '<your_pic_path>'
# Enter the target table name, for example, polardb4ai_annotation_source_animal.
target_table = '<your_table_name>'

def get_mime_type(filename):
    """Returns the MIME type based on the file extension."""
    ext = filename.lower().split('.')[-1]
    if ext in ['jpg', 'jpeg']:
        return 'jpeg'
    elif ext == 'png':
        return 'png'
    else:
        raise ValueError(f"Unsupported file type: {ext}")

def insert_images_to_db(image_dir):
    connection = psycopg2.connect(**DB_CONFIG)
    cursor = connection.cursor()
    id_counter = 1
    for filename in os.listdir(image_dir):
        file_path = os.path.join(image_dir, filename)
        if not filename.lower().endswith(('.jpg', '.jpeg', '.png')):
            continue
        try:
            with open(file_path, 'rb') as f:
                image_data = f.read()
            base64_str = base64.b64encode(image_data).decode('utf-8')
            mime_type = get_mime_type(filename)
            original_name = filename
            sql = f"""
                INSERT INTO {target_table}
                (id, base64_data, mime_type, original_name)
                VALUES (%s, %s, %s, %s)
            """
            cursor.execute(sql, (id_counter, base64_str, mime_type, original_name))
            print(f"Inserted: {filename} (ID: {id_counter})")
            id_counter += 1
        except Exception as e:
            print(f"Error processing {filename}: {e}")
            break
    connection.commit()
    cursor.close()
    connection.close()

if __name__ == "__main__":
    insert_images_to_db(IMAGE_DIR)

Deploy and access Label Studio

After preparing the data, you can deploy the service.

Step 1: Deploy the service

Grant permissions on the business tables to the database account used by the AI node.

For example, if the database account that you configured for the AI node is polarai_user, you must grant permissions on the annotation_template and polardb4ai_annotation_source_animal tables to polarai_user.

Note
In a production environment, make sure that the database account used by the AI node has permissions on the relevant business tables.
```
-- Grant permissions.
GRANT ALL PRIVILEGES ON TABLE public.annotation_template TO polarai_user;
GRANT ALL PRIVILEGES ON TABLE public.polardb4ai_annotation_source_animal TO polarai_user;
```

Start the Label Studio service by using an SQL command.

SELECT polar_ai.ai_nl2sql_deployModel(
  'Label-Studio',    -- A fixed keyword indicating a Label Studio deployment.
  'mark_animal',     -- A custom deployment name to distinguish between services. The name must be unique.
  '{"annotation_template_id":"1","annotation_source":"polardb4ai_annotation_source_animal"}'
);

Parameters

Parameter	Required	Description
`annotation_template_id`	Yes	Corresponds to the `id` in the `annotation_template` table. This parameter specifies the annotation template to use for the task.
`annotation_source`	Yes	The name of the data source table. The service loads data from this table.

Step 2: Check status and get credentials

Check the deployment status of the service, and get the public endpoint and login credentials.

SELECT * FROM polar_ai.ai_nl2sql_showDeployment('mark_animal');

The command returns the following output:

  model_name  | deployment_name | deployment_status |     start_time      |     ready_time      |  request_path  |   username   |  password  | white_ip_name 
--------------+-----------------+-------------------+---------------------+---------------------+----------------+--------------+------------+------------------
 Label-Studio | mark_animal     | Deploying         | 2026-01-29 14:38:44 | 2026-01-29 14:40:45 | 39.105.119.xxx | xxxx@xxx.com |   xxxxxxx  | model_mark_animal

Key returned fields

Field	Description
`deployment_status`	The status of the service. Deploying: The service is being deployed. Please wait. Serving: The service is ready and running properly. Note When the service starts, the system automatically imports image data to Label Studio. The time required varies depending on the number of images.
`request_path`	The public endpoint for Label Studio.
`username`	The initial login username.
`password`	The initial login password, which is randomly generated.
`white_ip_name`	The name of the IP address whitelist group associated with the service. This is used to configure access control.

Step 3: Configure the IP address whitelist

For security, the service blocks access from all external IP addresses by default. You must add the public IP address of your client to the service's IP address whitelist.

Add a public IP address to the whitelist.
```
SELECT polar_ai.ai_updateModelWhiteIps('model_mark_animal', '118.178.XXX.XXX, 192.168.100.0/24');
```
Note
- Replace model_mark_animal with the white_ip_name value returned by the polar_ai.ai_nl2sql_showDeployment command.
- Replace 118.178.XXX.XXX with the actual public IP address of the client.
- The whitelist supports multiple IP addresses separated by commas (,) and IP address ranges in CIDR format, such as 192.168.100.0/24.

(Optional) View the current whitelist configuration.

SELECT polar_ai.ai_showModelWhiteIps('model_mark_animal');

Step 4: Log in and start labeling

Access the Label Studio interface and log in: In a browser, open the request_path URL returned by the polar_ai.ai_nl2sql_showDeployment command and log in with the returned username and password.

Note
The current version does not support registering new accounts. You can only log in with the initial account.

The login page displays fields for Email Address and Password. Enter your credentials and click Log in.
Annotate the images and submit the annotations.
1. After you log on, click the project, which is my_project by default. The project page displays all images loaded from the polardb4ai_annotation_source_animal table. On the homepage, you can find the my_project project in the Recent Projects section. The task list is displayed in a table and shows the annotation status of each image. At the top of the page, the Label All Tasks feature for batch annotation and the Export feature are available.
2. Click any image to open the annotation interface.
3. Click a label at the bottom, such as cat or dog, and use the rectangle tool to draw a box around the target object. Then, click Submit. The Selection Details panel on the right displays the coordinates and label information of the selected annotation box. The Regions panel lists all annotated areas.

Step 5: View the annotation results

Verifying the annotation results in the database: After you submit an annotation in the Label Studio interface, the result is written in real time to the annotation_data field in the polardb4ai_annotation_source_animal data source table in JSON format. You can query this table at any time to get the latest annotation data.

SELECT id, original_name, annotation_data FROM polardb4ai_annotation_source_animal;

The following result is returned:

+----+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| id | original_name    | annotation_data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+----+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  1 | animal1.jpeg     | [{"id": "937YIRGx5v", "type": "rectanglelabels", "value": {"x": 43.00291545189505, "y": 12.973760932944606, "width": 49.8542274052478, "height": 33.673469387755105, "rotation": 0, "rectanglelabels": ["dog"]}, "origin": "manual", "to_name": "image", "from_name": "label", "image_rotation": 0, "original_width": 1328, "original_height": 1328}, {"id": "nu8ZcTbIfM", "type": "rectanglelabels", "value": {"x": 16.18075801749271, "y": 27.1137026239067, "width": 25.801749271137027, "height": 25.80174927113703, "rotation": 0, "rectanglelabels": ["cat"]}, "origin": "manual", "to_name": "image", "from_name": "label", "image_rotation": 0, "original_width": 1328, "original_height": 1328}] |
+----+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Clean up the service

The deployed Label Studio service continuously consumes AI node resources, which incurs costs. To avoid unnecessary charges, delete the service after you complete the annotation task.

SELECT polar_ai.ai_nl2sql_dropDeployment('mark_animal');

Note

After you delete the service:

The public access link becomes invalid.
The associated IP address whitelist is automatically cleared.
The data source table and existing annotation data are retained in the database and are not affected.

FAQ

Multiple annotation projects

Execute the polar_ai.ai_nl2sql_deployModel command multiple times to deploy a service, using a different deployment_name, annotation_template_id, and annotation_source for each project.

Update data and templates

The Label Studio service performs a full data load only at startup. If you modify the template or add data while the service is running, you must delete the existing service by using polar_ai.ai_nl2sql_dropDeployment and then redeploy it with polar_ai.ai_nl2sql_deployModel to apply the changes.

Data persistence

No. All annotation results are persisted in real time to the data source table that you specified. Data is not lost even if the service is interrupted. You can deploy the service again by using the same data source table, and existing annotations will be synchronized to the interface.

Supported file formats

Currently, major image formats such as JPEG and PNG are supported, as indicated by the mime_type field.

Bulk image import

Yes. You can bulk-insert Base64 data into the data source table. You can automate this process by using the AI_LoadFile function or an application script.