CVAT项目SDK扩展：如何添加自定义API方法

前言

在使用计算机视觉标注工具CVAT时，开发者经常需要扩展其SDK功能以满足特定业务需求。本文将详细介绍如何在CVAT SDK中添加自定义API方法，实现与后端新增接口的交互。

问题背景

CVAT提供了完善的Python SDK用于与后端服务交互，但当我们需要调用自定义的后端接口时，默认的SDK可能无法满足需求。例如，当后端新增了一个用于更新项目的特定接口时，我们需要在SDK中添加对应的方法。

解决方案

1. 修改SDK源码

首先需要在CVAT SDK的core/proxies/project.py文件中添加新的方法。主要涉及两个类的修改：

ProjectsRepo类：添加一个用于检索项目并调用更新方法的新方法

def update_project_visionia(self, id: int):
    project = self.retrieve(id)
    return project.update_project_visionia()

Project类：添加实际执行API调用的方法

def update_project_visionia(self):
    (_, response) = self._client.api_client.put(
        f"/api/visionia/{self.id}/update-project/"
    )
    self.fetch()  # 刷新项目数据
    return response

2. 安装修改后的SDK

由于Python默认会使用已安装的包，我们需要先卸载原有的SDK，然后以开发模式安装修改后的版本：

pip uninstall cvat-sdk
cd /cvat/cvat-sdk
pip install -e .

这种开发模式安装会创建一个指向本地源码的链接，使得修改能够立即生效。

技术细节

后端接口设计

后端通常需要提供RESTful风格的接口，例如：

@action(detail=True, methods=['PUT'], url_path='update-project')
def update_project_visionia(self, request, pk=None):
    # 实现具体的业务逻辑
    pass

对应的URL配置：

path('api/visionia/<int:pk>/update-project/',
     VisioniaViewSet.as_view({'put': 'update_project_visionia'}),
     name='project_update'),

客户端调用

在客户端代码中，可以这样使用新添加的方法：

def update_project_visionia(self):
    try:
        with make_client(self.host, port=self.port, 
                        credentials=(self.username, self.password)) as client:
            project = client.projects.retrieve(self.id)
            return project.update_project_visionia()
    except exceptions.ApiException as e:
        print(f'Exception on API call for update_project_visionia: {e}')
        raise

注意事项

1. 版本控制：修改SDK源码后，应当做好版本标记，避免与其他开发者或部署环境产生冲突。

2. 错误处理：自定义方法应当包含完善的错误处理机制，特别是网络请求和响应解析部分。

3. 文档更新：添加新方法后，应当同步更新项目文档，方便团队其他成员使用。

4. 测试验证：新方法应当编写单元测试和集成测试，确保功能正常。

总结

通过本文介绍的方法，开发者可以灵活扩展CVAT SDK的功能，满足特定的业务需求。关键在于理解SDK的结构和工作原理，以及如何正确安装修改后的版本。这种扩展方式不仅适用于项目更新操作，也可以应用于其他各种自定义API接口的调用场景。

对于需要长期维护的项目，建议考虑将这些自定义方法封装为独立的扩展模块，而不是直接修改SDK源码，这样可以更方便地进行版本管理和升级。