OpenCV/CVAT 低层级API开发指南-优快云博客

OpenCV/CVAT 低层级API开发指南

cvat Annotate better with CVAT, the industry-leading data engine for machine learning. Used and trusted by teams at any scale, for data of any scale. 项目地址: https://gitcode.com/gh_mirrors/cv/cvat

概述

在计算机视觉标注工具CVAT的开发中，低层级API为开发者提供了直接与REST API交互的能力，同时保留了代码编辑器的数据验证和语法辅助功能。本文将深入解析CVAT低层级API的核心概念和使用方法。

低层级API的优势与应用场景

低层级API主要适用于以下场景：

需要对API调用进行精细控制
需要直接处理原始HTTP请求和响应
开发高级功能或定制化解决方案
构建自动化工作流程

核心组件解析

1. ApiClient类

ApiClient是低层级API的核心入口点，它封装了以下功能：

会话和连接管理
请求头和Cookie处理
提供对各类API的访问

from cvat_sdk.api_client import ApiClient, Configuration

# 基本配置示例
configuration = Configuration(
    host="http://localhost",
    username='用户名',
    password='密码',
)

# 使用上下文管理器创建ApiClient实例
with ApiClient(configuration) as api_client:
    # API操作代码

2. 认证机制

CVAT支持两种认证方式：

基础认证（用户名/密码）

configuration = Configuration(
    username='用户名',
    password='密码',
)

Token认证

configuration = Configuration(
    api_key={
        "sessionAuth": "会话ID值",
        "csrfAuth": "CSRF令牌值",
        "tokenAuth": "Token 认证密钥值",
    }
)

3. API包装器

API端点按功能分组为不同的类，可以通过两种方式访问：

# 方式一：通过ApiClient成员访问
api_client.tasks_api.create(...)

# 方式二：直接实例化API类
from cvat_sdk.api_client import apis
tasks_api = apis.TasksApi(api_client)
tasks_api.create(...)

实战示例：创建标注任务

下面我们通过一个完整示例展示如何使用低层级API创建标注任务：

from time import sleep
from cvat_sdk.api_client import Configuration, ApiClient, models, exceptions

# 1. 配置客户端
config = Configuration(
    host="http://localhost",
    username='用户名',
    password='密码',
)

# 2. 创建API客户端
with ApiClient(config) as api_client:
    # 3. 定义任务规范
    task_spec = {
        'name': '汽车标注任务',
        "labels": [{
            "name": "car",
            "color": "#ff00ff",
            "attributes": [
                {
                    "name": "车型",
                    "mutable": True,
                    "input_type": "select",
                    "default_value": "SUV",
                    "values": ["SUV", "轿车", "卡车"]
                }
            ]
        }],
    }

    # 4. 创建任务
    try:
        task, _ = api_client.tasks_api.create(task_spec)
    except exceptions.ApiException as e:
        print(f"创建任务失败: {e}")
        raise

    # 5. 上传任务数据
    task_data = models.DataRequest(
        image_quality=75,
        client_files=[
            open('汽车1.jpg', 'rb'),
            open('汽车2.jpg', 'rb'),
        ],
    )

    # 6. 提交数据（注意设置内容类型）
    result, response = api_client.tasks_api.create_data(
        task.id,
        data_request=task_data,
        _content_type="multipart/form-data",
        _check_status=False
    )
    
    # 7. 检查处理状态
    for _ in range(100):
        request_details, _ = api_client.requests_api.retrieve(result.rq_id)
        if request_details.status.value in {'finished', 'failed'}:
            break
        sleep(0.1)
    
    # 8. 验证任务
    task, _ = api_client.tasks_api.retrieve(task.id)
    print(f"任务创建成功，包含{task.size}张图片")

高级特性详解

1. 模型处理

CVAT API中的请求和响应使用分离的模型：

请求模型：以Request为后缀（如TaskWriteRequest）
响应模型：无后缀（如Task）

模型可以以下列形式使用：

# 方式一：使用模型类
task_spec = models.TaskWriteRequest(name="任务名称")

# 方式二：使用字典
task_spec = {'name': '任务名称'}

# 混合使用
api_client.tasks_api.create({
    'name': '混合示例',
    'labels': [models.PatchedLabelRequest(name="标签")]
})

2. 二进制数据处理

处理文件上传时需要特别注意：

# 文件上传必须指定内容类型
api_client.tasks_api.create_data(
    id=42,
    data_request=models.DataRequest(
        client_files=[open("image.jpg", 'rb')]
    ),
    _content_type="multipart/form-data"
)

# 复杂数据需要分步上传
# 第一步：初始化上传
api_client.tasks_api.create_data(
    id=42,
    data_request=models.DataRequest(image_quality=70),
    upload_start=True
)

# 第二步：上传文件
api_client.tasks_api.create_data(
    id=42,
    data_request=models.DataRequest(
        client_files=[open("image.jpg", 'rb')]
    ),
    upload_multiple=True,
    _content_type="multipart/form-data"
)

# 第三步：完成上传
api_client.tasks_api.create_data(
    id=42,
    data_request=models.DataRequest(job_file_mapping=[...]),
    upload_finish=True
)

3. 分页响应处理

对于返回大量数据的端点，CVAT使用分页响应。可以使用辅助函数获取完整数据：

from cvat_sdk.core.helpers import get_paginated_collection

project_tasks = get_paginated_collection(
    api_client.projects_api.list_tasks_endpoint,
    id=project_id
)

最佳实践与调试技巧

错误处理：始终检查响应状态，捕获ApiException异常
超时控制：使用_request_timeout参数设置合理的超时时间
响应解析：遇到解析问题时尝试_parse_response=False
类型验证：可通过_validate_inputs和_validate_outputs控制类型检查
组织上下文：在组织内创建资源时使用org或org_id参数

# 带组织上下文的创建示例
api_client.tasks_api.create(task_spec, org_id=org_id)

总结

CVAT的低层级API为开发者提供了强大的灵活性和控制能力。通过本文的介绍，您应该已经掌握了：

如何配置和使用ApiClient
各种认证方式的选择
模型的定义和使用方法
文件上传等高级功能的实现
常见问题的解决方案

在实际开发中，建议结合项目需求选择合适的API层级，低层级API虽然复杂但能提供最大的灵活性，适合需要精细控制的场景。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考