Label Studio 配置 Redis 数据库作为标注任务源存储与目标存储Source/Target Storage实战指南【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio本篇技术指南以 Label Studio 的 Redis 存储连接为主题讲解如何将任务Source Storage与标注结果Target Storage直接存放在 Redis 数据库中替代基于文件对象的云存储连接从而获得更快的任务读写速度。读完本文你将掌握Redis 中任务数据的存放格式、在 Label Studio 界面中创建源存储与目标存储的完整字段含义、底层同步与导出机制的原理以及如何通过 REST API 程序化创建和管理 Redis 存储连接。文中所有参数与行为均以本仓库label-studio当前代码为准并给出对应源码位置供深入查验。Redis 存储的定位与适用前提在 Label Studio 中任务和标注既可以存放在 S3、GCS、Azure Blob 等文件型云存储中也可以直接存放在 Redis 数据库 中。当数据集较大、依赖文件型云存储连接显得缓慢时Redis 的内存读写特性是一个值得考虑的替代方案。使用 Redis 存储需要明确以下几个前提与限制源自 storage_redis.md任务与标注必须存放在不同的数据库db中源存储默认使用db1目标存储默认使用db2二者不能共用同一个数据库以免互相覆盖。仅支持默认模式、默认 IP 地址部署的 Redis文档明确说明当前仅支持以默认模式、默认 IP 地址自建托管的 Redis 实例。Label Studio 不负责管理 Redis 实例Redis 的安装、启动、监控需要自行维护。Redis 是内存数据库数据默认不持久化为避免数据丢失需要自行配置 Redis 持久化RDB/AOF或使用云托管的 Redis 服务如 Azure Cache、AWS 的 Redis 服务。从源码层面看“任务与标注必须分库”是一条被强制执行的约束RedisStorageMixin.get_redis_connection 中db参数默认值为None一旦未显式传入 db 编号会直接抛出ValueError(Please explicitly pass a redis db id to prevent accidentally overwriting existing database!)其目的就是防止误选默认库导致已有数据库被意外覆盖。源存储的任务数据格式字符串即任务Label Studio 的 Redis 源存储只支持字符串类型的键值对每个字符串的值必须是 JSON 格式的 Label Studio 任务。键名相当于“文件名”值是任务的 JSON 定义。以两张图片任务为例键值结构如下ls-task-1: {image: http://example.com/1.jpg} ls-task-2: {image: http://example.com/2.jpg} ...可以通过redis-cli写入并验证 redis-cli -n 1 127.0.0.1:6379[1] SET ls-task-1 {image: http://example.com/1.jpg} OK 127.0.0.1:6379[1] GET ls-task-1 {\image\: \http://example.com/1.jpg\} 127.0.0.1:6379[1] TYPE ls-task-1 string注意-n 1表示选用数据库 1与源存储默认 db 一致。从源码看导入时每个键的值会经过 get_data 读取后交给 load_tasks_json 解析该解析器load_tasks_json_lso支持三种形态单个 JSON 对象{data: {...}}JSON 数组[{data: {...}}, {data: {...}}, ...]流式解析适合大文件JSONL 多行 JSON每行一个任务。因此一个 Redis 键的 JSON 值中也可以包含多个任务数组或 JSONL 形式导入时会被展开为多条任务记录。创建源存储连接Source Storage在 Label Studio 中打开项目进入Settings Cloud Storage Add Source Storage选择Redis Storage并点击Next即可进入三步骤配置流程。第一步配置连接Configure Connection字段说明Storage Title为存储连接设置一个便于识别的名称Host数据库所在服务器的 IP 地址或localhostPort访问数据库的端口默认6379Database Number (db)要使用的数据库编号默认1Password可选。若 Redis 实例需要认证填写服务器密码填写完成后点击Test connection验证连通性。界面上对应表单由 form_layout.yml 定义其中 Host 的占位提示为localhost、db 占位提示为1并专门将 Password 声明为密码输入框autoComplete: new-password。第二步导入设置与预览Import Settings Preview字段说明Path to files可选。数据库路径实际用作键名前缀keys prefix此前缀下的键会被扫描为任务Import Method选择每个对象创建一个任务还是用 JSON/JSONL/Parquet 文件来定义每个任务的数据File Name Filter正则表达式用于过滤数据库对象使用.*收集全部对象Scan all sub-folders开启后对数据库内子目录进行递归扫描点击Load preview可确认将要同步的数据是否正确。界面上 Import Method 对应模型字段 use_blob_urls选择“Files”时值为true每个存储对象自动创建一个任务如 JPG、MP3、TXT选择“Tasks”时值为false将每个 JSON/JSONL 文件视为任务定义一个文件可包含一个或多个任务。File Name Filter 对应regex_filter字段form_layout.yml 中给出的示例正则如.*csv or .*(jpe?g|png|tiff) or .\w-\d.text。需要说明的是Redis 的键是扁平字符串没有真正的文件夹层级。从源码看扫描逻辑 iter_objects 实际执行的是client.keys(path *)的模式匹配——“Path”作为键前缀*通配其后所有内容因此文档中的“子文件夹/递归”概念在 Redis 场景下映射为键名前缀与*通配模式的组合。预览功能则调用POST /api/storages/redis/files接口ImportStorageListFilesAPI它遍历iter_objects()并返回每个键的元数据key、last_modified、size同时有默认条数限制DEFAULT_STORAGE_LIST_LIMIT和 30 秒扫描超时保护。第三步确认与同步Review Confirm点击Save Sync保存设置并立即触发同步点击Save仅保存设置稍后再手动同步。同步接口为POST /api/storages/redis/pk/sync。创建目标存储连接Target Storage进入Settings Cloud Storage Add Target Storage选择Redis Storage并点击Next填写以下字段字段说明Storage Title为存储连接设置一个便于识别的名称Path可选。数据库路径用作导出标注的键名前缀Host数据库所在服务器的 IP 地址或localhostPort访问数据库的端口默认6379Database Number (db)要使用的数据库编号默认2。必须与源存储使用不同的数据库编号Password可选。若 Redis 实例需要认证填写服务器密码添加完成后点击Sync执行一次全量导出同步。目标存储的同步接口为POST /api/storages/export/redis/pk/sync。从模型定义看源存储与目标存储的 db 默认值正是 1 和 2RedisImportStorageBase.db 默认1RedisExportStorage.db 默认2。底层同步与导出机制连接验证Ping 即真相无论是界面上的 Test connection、创建连接时序列化器的校验还是同步前的预检最终都归结为一次 Redisping()。RedisStorageMixin.get_redis_connection 使用redis.StrictRedis(dbdb, charsetutf-8, decode_responsesTrue)建立连接并调用r.ping()若无法连接会抛出redis.exceptions.ConnectionError。序列化器层serializers.py在 validate 阶段也会调用storage.validate_connection()失败时统一抛出Cant connect to Redis server.。另外出于安全考虑API 返回的连接对象中密码字段会被移除result.pop(password)密码只在写入时提交、永不回显。导入同步链路POST .../sync入口在 ImportStorageSyncAPI.post先检查synchronizable标记然后validate_connection()并调用storage.sync()。sync 会根据 Label Studio 自身的 RQ 任务队列 Redis 是否可用决定将同步作为后台任务low队列RQ_LONG_JOB_TIMEOUT异步执行还是同步执行。注意这里的“RQ 队列 Redis”是 Label Studio 应用自身的任务队列与本次配置的存储 Redis 是两套独立的连接不要混淆。后台任务最终执行 scan_and_create_links → _scan_and_create_links核心流程为将存储状态置为in_progress通过iter_keys()内部即keys(path *)枚举所有候选键并去重通过RedisImportStorageLink.exists()跳过已同步过的键断点续传避免重复建任务对每个新键调用get_data(key)读取 JSON 值并解析出StorageObject逐个调用 add_task 创建任务支持同步导入 predictions 与 annotations并创建RedisImportStorageLink记录键与任务的映射同步过程中批量发送TASKS_CREATEDWebhook最后回填任务 FSM 状态并更新项目任务计数。整个过程的进度与结果状态initialized/queued/in_progress/failed/completed/completed_with_errors记录在 StorageInfo 模型中包含 last_sync、last_sync_count、traceback 等字段若任务进程因 OOM 或重部署意外终止health_check 也会把状态修正为failed。标注导出链路目标存储的导出由两类入口驱动手动同步调用POST /api/storages/export/redis/pk/sync触发 save_all_annotations 将项目全部标注写入 Redis自动实时导出模型注册了Annotation的 post_save 信号 export_annotation_to_redis_storages每次标注保存后会自动将该标注写入项目关联的所有 Redis 目标存储。每条标注的写入实现在 RedisExportStorage.save_annotation先把标注序列化为 JSON默认导出标注本体若启用FUTURE_SAVE_TASK_TO_STORAGE特性则会连带导出任务与标注再用RedisExportStorageLink.get_key(annotation)计算键名执行client.set(key, json.dumps(...))最后创建RedisExportStorageLink建立标注与键的映射。批量同步save_annotations会依据 CPU 核心数使用最多 8 个线程并发写入并分批更新进度。使用 Label Studio API 程序化创建连接除界面外Redis 存储的全部能力都可通过 REST API 使用。接口路由定义在 io_storages/urls.py完整端点如下方法路径用途GET / POST/api/storages/redis/列出 / 创建 Redis 源存储连接GET / PATCH / DELETE/api/storages/redis/pk查看 / 更新 / 删除指定源存储POST/api/storages/redis/pk/sync触发源存储同步POST/api/storages/redis/validate校验连接参数POST/api/storages/redis/files预览存储中的对象列表GET/api/storages/redis/form获取源存储表单布局GET / POST/api/storages/export/redis列出 / 创建 Redis 目标存储连接GET / PATCH / DELETE/api/storages/export/redis/pk查看 / 更新 / 删除指定目标存储POST/api/storages/export/redis/pk/sync触发目标存储导出同步POST/api/storages/export/redis/validate校验目标连接参数GET/api/storages/export/redis/form获取目标存储表单布局以创建源存储为例请求体字段为title、host、port、db、path、password、regex_filter、use_blob_urls以及必填的project项目 IDcurl -X POST https://your-label-studio/api/storages/redis/ \ -H Authorization: Token your-api-token \ -H Content-Type: application/json \ -d { project: 1, title: my-redis-source, host: localhost, port: 6379, db: 1, path: ls-task-, regex_filter: .*, use_blob_urls: false }创建目标存储时请求/api/storages/export/redis/将db改为2即可。创建后若需立即同步调用对应的pk/sync端点。各端点的 OpenAPI 描述如Sync tasks from a Redis import storage connection定义在 redis/api.py 中可作为接口语义的权威参考。注意事项与最佳实践源库与目标库严格分离源存储 db 默认 1、目标存储 db 默认 2且代码强制要求显式传入 db切勿让二者指向同一库否则任务与标注会互相覆盖。务必配置 Redis 持久化Redis 是内存数据库重启即丢数据。生产环境请开启 RDB/AOF 持久化或直接选用带持久化的云托管 Redis。区分两种导入方法若 Redis 值里存的是 JSON 任务定义use_blob_urls应为falseTasks 方式若要导入图片、音频等二进制对象的原始文件并让 Label Studio 为每个对象自动建任务则应设为trueFiles 方式。同步时若开启扩展名校验特性非.json/.jsonl/.parquet后缀的键会被拒绝导入base_models.py并给出明确提示要求切换导入方式。键前缀即过滤手段Path字段在导入时作为键前缀keys(path *)导出时作为标注键前缀配合regex_filter可以精确圈定要同步的键范围。存储连接可复用与回读can_resolve_schemebase_models.py支持用存储的path匹配 URI便于在任务数据中引用 Redis 存储内的资源并通过代理 URL 回读。验证与测试参考仓库测试 test_multitask_import.py 提供了 Redis 导入的集成测试用例test_import_multiple_tasks_redis使用redis_client_mock模拟 Redis 客户端向test.json键写入任务 JSON通过RedisImportStorageFactory定义于 factories.py创建存储并触发同步最后断言/api/tasks中任务被正确导入。读者可据此在本地复现完整的 Redis 导入链路。深入阅读storage_redis.md本文对应的官方指南原文storage.md云存储Source/Target Storage总览task_format.md任务 JSON 格式规范redis/models.pyRedis 存储模型、连接与导入导出实现redis/serializers.pyAPI 序列化与连接校验redis/api.pyRedis 存储 REST API 端点redis/form_layout.yml界面表单布局定义base_models.py同步状态机与通用导入导出链路【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考