SQL部署Label Studio实现图片数据标注-云原生数据库 PolarDB-阿里云

PolarDB for AI已集成开源数据标注工具Label Studio，为您提供了一站式解决方案。您仅需通过SQL命令即可快速部署一个功能完善的标注服务，实现图片数据从数据库到标注界面的自动加载，以及标注结果的实时回写。无需管理额外服务器或数据流转，即可构建高效、安全的数据标注工作流。

功能简介

Label Studio是一款开源的多功能数据标注平台，支持图像分类、目标检测、文本标注等多种任务类型。它提供了一个直观的Web界面，便于人工对机器学习的训练数据进行高质量标注。

PolarDB for AI在AI节点中集成了Label Studio的部署能力，并实现了与数据库的双向数据同步。当您部署服务时，系统会自动从您指定的数据库表中加载图片数据，当您在Web界面提交标注后，标注结果会以JSON格式实时写回该表的相应字段中。

优势

自动化数据流转：自动从指定数据表加载图片，标注结果实时回写至数据库，无需手动导入导出。
简化运维：全程通过SQL接口完成服务的部署、管理和清理，无需操作和维护额外的服务器。
多项目并发：通过SQL命令按需部署和管理多个独立的标注项目，每个项目拥有独立的服务和访问地址。
内置安全保障：通过IP白名单和自动生成的初始随机凭证，确保您的数据访问安全。

适用范围

开始前，请确保已完成以下准备：

节点：增加GPU规格的AI节点，并设置AI节点的连接数据库账号：添加与管理AI节点
说明
- 若您在购买集群时已添加AI节点，则可以直接为AI节点设置连接数据库的账号。
- AI节点的连接数据库账号需具有读写权限，以确保能够顺利读取和写入目标数据库。
访问地址：使用集群地址连接PolarDB集群。

准备环境与数据

部署服务前，需准备数据表及待标注数据。

步骤一：安装扩展与设置访问凭证

使用高权限账号登录集群。
获取节点Token。
请前往PolarDB控制台，目标集群详情页中数据库节点区域，找到AI节点，并单击查看记录节点Token。
创建polar_ai扩展并配置节点Token。
在数据库中执行以下命令，创建功能扩展并设置访问大模型服务所需的密钥。
重要
请确认您已为AI节点设置了连接数据库账号。
```
-- 创建扩展
CREATE EXTENSION polar_ai;

-- 设置您的密钥
SELECT polar_ai._ai_nl2sql_alter_token('sk-xxx');
```

步骤二：创建标注模板表

此表用于定义标注任务的界面样式和标签类别。表名annotation_template和表结构为固定设计，不可修改。

创建用于存储标注模板的表。

CREATE TABLE IF NOT EXISTS public.annotation_template(
  id SERIAL NOT NULL PRIMARY KEY,              -- 模板ID
  tp_name varchar(255) NOT NULL,               -- 模板名称
  tp_description text,                         -- 模板描述
  tp_schema jsonb NOT NULL,                    -- JSON 格式的标注 schema
  tp_is_active boolean DEFAULT 'Y'             -- 是否启用
);
CREATE UNIQUE INDEX IF NOT EXISTS tp_name_index ON public.annotation_template USING BTREE(tp_name);

插入两个物体识别（Object Detection）任务的模板样例。

INSERT INTO public.annotation_template (id, tp_name, tp_description, tp_schema, tp_is_active) VALUES
(1, 'schema_animal', '标注动物', '{"type": "ObjectDetection", "labels": ["cat", "dog"]}', TRUE),
(2, 'schema_vehicular', '标注交通工具', '{"type": "ObjectDetection", "labels": ["car", "airplane"]}', TRUE);

tp_schema字段说明：

type：定义标注任务类型。当前仅支持ObjectDetection（目标检测）。
labels：定义可选的标签列表。Label Studio将根据此列表生成标注界面上的标签可选框。

步骤三：准备图片数据源表

数据源表用于存放待标注图片的信息。您可以为每个项目创建不同的数据源表，但表的字段名和类型为固定设计，不可修改。

创建用于存储图片URL的数据源表。

CREATE TABLE public.polardb4ai_annotation_source_animal (
  id SERIAL NOT NULL  PRIMARY KEY,
  base64_data text,                          -- 图片的 Base64 编码字符串
  mime_type varchar(100) NOT NULL,           -- 图片 MIME 类型，如 'jpg'
  original_name varchar(255) NOT NULL,       -- 显示在Label Studio中的任务名称
  created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  annotation_data jsonb DEFAULT NULL,        -- 存储标注结果（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
);

向数据源表中插入图片数据。您可通过AI_LoadFile（需要安装polar_ai_util扩展）函数、Python脚本以及其他工具将本地图片转为Base64字符串插入。

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脚本示例

import os
import base64
# 需安装psycopg2库，安装命令示例pip install psycopg2-binary
import psycopg2

# 数据库配置（请根据你的环境修改）
DB_CONFIG = {
    'host': '<your_polardb_host>',
    'port': 5432,
    'user': '<your_polardb_username>',
    'password': '<your_polardb_user_password>',
    'database': '<your_polardb_database>'
}

# 图片文件夹路径（请修改为你的文件夹路径，脚本将上传文件夹下所有图片）
IMAGE_DIR = '<your_pic_path>'
# 输入写入的表名，例如polardb4ai_annotation_source_animal
target_table = '<your_table_name>'

def get_mime_type(filename):
    """根据文件扩展名返回 MIME 类型"""
    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)

部署和访问Label Studio服务

完成数据准备后，即可部署服务。

步骤一：部署服务

授权业务表权限给AI节点的数据库账号。
例如，若您为AI节点配置的数据库连接账号为polarai_user，则需将annotation_template与polardb4ai_annotation_source_animal表的权限授予polarai_user。
说明
在应用于业务环境时，请确保所设置的AI节点数据库账号具备相关业务表的权限。
```
-- 授权
GRANT ALL PRIVILEGES ON TABLE public.annotation_template TO polarai_user;
GRANT ALL PRIVILEGES ON TABLE public.polardb4ai_annotation_source_animal TO polarai_user;
```

使用SQL命令启动Label Studio服务。

SELECT polar_ai.ai_nl2sql_deployModel(
  'Label-Studio',    -- 固定关键字，表示部署Label Studio服务。
  'mark_animal',     -- 自定义部署名称，用于区分多个服务，且不可重复。
  '{"annotation_template_id":"1","annotation_source":"polardb4ai_annotation_source_animal"}'
);

参数说明

参数	是否必须	说明
`annotation_template_id`	是	对应`annotation_template`表中的 `id`，用于指定本次任务使用的标注模板。
`annotation_source`	是	数据源表名，服务将从此表加载数据。

步骤二：查看服务状态并获取凭证

确认服务部署状态，并获取访问地址和登录凭证。

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

返回结果如下：

  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 | 2025-12-11 11:40:45 | 39.105.119.xxx | xxxx@xxx.com |   xxxxxxx  | model_mark_animal

关键返回字段说明

字段	说明
`deployment_status`	服务状态。 Deploying：服务正在部署中，请耐心等待。 Serving：表示服务已就绪并正常运行。说明启动服务时，系统将自动导入图片数据至Label Studio，具体耗时与图片数量相关。
`request_path`	Label Studio的公网访问地址。
`username`	初始登录用户名。
`password`	初始登录密码（随机生成）。
`white_ip_name`	与此服务绑定的IP白名单组名称，用于配置访问控制。

步骤三：配置网络访问白名单

为保障安全，服务默认禁止所有外部IP访问。需将客户端的公网IP地址添加至服务白名单。

添加公网IP到白名单。
```
SELECT polar_ai.ai_updateModelWhiteIps('model_mark_animal', '118.178.XXX.XXX, 192.168.100.0/24');
```
说明
- model_mark_animal需替换为polar_ai.ai_nl2sql_showDeployment命令返回的white_ip_name值。
- 118.178.XXX.XXX需替换为实际客户端公网IP地址。
- 白名单支持配置多个 IP（使用英文逗号,分隔）以及CIDR格式的IP网段（如192.168.100.0/24）。

（可选）查看当前白名单配置。

SELECT polar_ai.ai_showModelWhiteIps('model_mark_animal');

步骤四：登录并开始标注

访问Label Studio界面并登录：在浏览器中打开polar_ai.ai_nl2sql_showDeployment命令返回的request_path地址，使用返回的username和password进行登录。
说明
当前版本不支持自行注册新账号，仅可使用初始生成的账号登录。
对图片进行标注并提交。
1. 登录后，单击项目（默认为my_project），进入项目页面将显示从polardb4ai_annotation_source_animal表中加载的所有图片。
2. 点击任意图片进入标注界面。
3. 单击下方标签（如cat或dog），并使用矩形框工具框选目标对象。随后单击Submit提交标注。

步骤五：查看标注结果

验证标注结果已写回数据库：在Label Studio界面提交标注后，结果会以JSON格式实时写入数据源表polardb4ai_annotation_source_animal的annotation_data字段。可随时查询该表获取最新标注数据。

SELECT id, original_name, annotation_data FROM polardb4ai_annotation_source_animal;

返回结果如下：

+----+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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}] |
+----+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

清理与删除服务

部署的Label Studio服务会持续占用AI节点资源并产生费用。为避免产生不必要的成本，建议您在完成标注任务后，及时删除服务与释放AI节点资源。

SELECT polar_ai.ai_nl2sql_dropDeployment('mark_animal');

说明

删除服务后：

外网访问链接将失效。
关联的IP白名单将自动清除。
数据源表和已有的标注数据将保留在数据库中，不受影响。

常见问题

如何部署多个不同的标注项目？

多次执行polar_ai.ai_nl2sql_deployModel命令部署服务，为每个项目使用不同的deployment_name、annotation_template_id 和 annotation_source。

如果修改了模板表或者向数据源表添加了新图片，如何让服务生效？

Label Studio服务在启动时进行一次全量数据加载。若在服务运行期间修改了模板或添加了新数据，需要先执行polar_ai.ai_nl2sql_dropDeployment删除旧服务，然后重新执行polar_ai.ai_nl2sql_deployModel来加载最新数据和配置。

标注的数据会不会丢失？

不会。所有标注结果都实时持久化到您指定的数据源表中，即使服务中断也不会丢失。您可以重新指定相同的数据源表再次部署，此时历史图片标注的信息会同步至页面上。

支持哪些文件格式？

目前支持主流图像格式，包括JPEG与PNG等，由mime_type字段标明。

能否批量导入大量图片？

可以。只需批量插入Base64数据到数据源表即可，建议通过AI_LoadFile或应用程序脚本自动化处理。