设计文档提交

文档/API接口设计文档/标注-样本中心联动接口.md

@@ -0,0 +1,621 @@
+# 标注平台对外API接口文档
+
+## 概述
+
+本文档描述了标注平台提供给外部系统（如样本中心）调用的API接口。通过这些接口，外部系统可以：
+
+1. 创建标注项目并导入任务数据
+2. 查询项目标注进度
+3. 导出标注完成的数据
+
+## 认证方式
+
+所有API请求需要在HTTP Header中携带管理员Token进行身份验证：
+
+```
+Authorization: Bearer <admin_token>
+```
+
+**注意**：Token由标注平台管理员提供，具有长期有效性。
+
+## 基础URL
+
+```
+生产环境: https://your-domain.com/api/external
+开发环境: http://localhost:8003/api/external
+```
+
+## 接口列表
+
+### 1. 项目初始化接口
+
+创建新的标注项目并批量导入任务数据。
+
+**请求**
+
+```
+POST /api/external/projects/init
+```
+
+**请求头**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| Authorization | string | 是 | Bearer Token |
+| Content-Type | string | 是 | application/json |
+
+**请求体**
+
+```json
+{
+  "name": "图像分类项目-批次001",
+  "description": "对商品图片进行分类标注",
+  "task_type": "image_classification",
+  "data": [
+    {
+      "id": "ext_001",
+      "content": "https://example.com/images/product1.jpg",
+      "metadata": {
+        "batch": "001",
+        "source": "商品库"
+      }
+    },
+    {
+      "id": "ext_002",
+      "content": "https://example.com/images/product2.jpg",
+      "metadata": {
+        "batch": "001",
+        "source": "商品库"
+      }
+    }
+  ],
+  "external_id": "sample_center_proj_001",
+  "tags": [
+    {"tag": "猫猫", "color": "#FF5733"},
+    {"tag": "狗狗", "color": "#33FF57"},
+    {"tag": "其他"}
+  ]
+}
+```
+
+**请求参数说明**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | 项目名称 |
+| description | string | 否 | 项目描述 |
+| task_type | string | 是 | 任务类型，见下方支持的类型 |
+| data | array | 是 | 任务数据列表 |
+| data[].id | string | 否 | 外部系统的数据ID，用于关联 |
+| data[].content | string | 是 | 数据内容（文本或图像URL） |
+| data[].metadata | object | 否 | 额外元数据 |
+| external_id | string | 否 | 外部系统的项目ID，用于关联查询 |
+| tags | array | 否 | 标签列表，用于预定义标注选项 |
+| tags[].tag | string | 是 | 标签名称 |
+| tags[].color | string | 否 | 标签颜色，格式: #RRGGBB，不传则自动生成 |
+
+**注意**：
+- 如果传入 `tags` 参数，系统会自动根据标签生成对应的XML配置
+- 如果不传 `tags` 参数，标签由标注平台管理员在项目配置阶段设置
+
+**支持的任务类型**
+
+| task_type | 说明 | data.content 格式 |
+|-----------|------|-------------------|
+| text_classification | 文本分类 | 文本内容 |
+| image_classification | 图像分类 | 图像URL |
+| object_detection | 目标检测（矩形框） | 图像URL |
+| ner | 命名实体识别 | 文本内容 |
+| polygon | 多边形标注 | 图像URL |
+
+**响应**
+
+```json
+{
+  "project_id": "proj_abc123def456",
+  "project_name": "图像分类项目-批次001",
+  "task_count": 2,
+  "status": "draft",
+  "created_at": "2026-02-03T10:30:00Z",
+  "config": "<View>...</View>",
+  "external_id": "sample_center_proj_001"
+}
+```
+
+**响应参数说明**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| project_id | string | **标注平台项目ID，样本中心必须保存此ID用于后续进度查询和数据导出** |
+| project_name | string | 项目名称 |
+| task_count | int | 创建的任务数量 |
+| status | string | 项目状态（draft=草稿，等待管理员配置） |
+| created_at | string | 创建时间（ISO 8601格式） |
+| config | string | 实际使用的XML配置模板 |
+| external_id | string | 样本中心传入的外部ID（如有） |
+
+**重要**：`project_id` 是标注平台生成的唯一标识符，样本中心需要保存此ID用于后续的进度查询和数据导出接口调用。
+
+---
+
+### 2. 项目进度查询接口
+
+查询指定项目的标注进度和人员完成情况。
+
+**请求**
+
+```
+GET /api/external/projects/{project_id}/progress
+```
+
+**路径参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | 是 | 项目ID |
+
+**响应**
+
+```json
+{
+  "project_id": "proj_abc123def456",
+  "project_name": "图像分类项目-批次001",
+  "status": "in_progress",
+  "total_tasks": 100,
+  "completed_tasks": 45,
+  "in_progress_tasks": 30,
+  "pending_tasks": 25,
+  "completion_percentage": 45.0,
+  "annotators": [
+    {
+      "user_id": "user_001",
+      "username": "annotator1",
+      "assigned_count": 50,
+      "completed_count": 25,
+      "in_progress_count": 15,
+      "completion_rate": 50.0
+    },
+    {
+      "user_id": "user_002",
+      "username": "annotator2",
+      "assigned_count": 50,
+      "completed_count": 20,
+      "in_progress_count": 15,
+      "completion_rate": 40.0
+    }
+  ],
+  "last_updated": "2026-02-03T15:30:00Z"
+}
+```
+
+**响应参数说明**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| project_id | string | 项目ID |
+| project_name | string | 项目名称 |
+| status | string | 项目状态 |
+| total_tasks | int | 总任务数 |
+| completed_tasks | int | 已完成任务数 |
+| in_progress_tasks | int | 进行中任务数 |
+| pending_tasks | int | 待处理任务数 |
+| completion_percentage | float | 完成百分比（0-100） |
+| annotators | array | 标注人员列表 |
+| annotators[].user_id | string | 用户ID |
+| annotators[].username | string | 用户名 |
+| annotators[].assigned_count | int | 分配的任务数 |
+| annotators[].completed_count | int | 已完成数 |
+| annotators[].in_progress_count | int | 进行中数 |
+| annotators[].completion_rate | float | 个人完成率（0-100） |
+| last_updated | string | 最后更新时间 |
+
+**项目状态说明**
+
+| status | 说明 |
+|--------|------|
+| draft | 草稿，等待管理员配置 |
+| configuring | 配置中 |
+| ready | 就绪，等待分发任务 |
+| in_progress | 进行中，标注人员正在工作 |
+| completed | 已完成 |
+
+---
+
+### 3. 数据导出接口
+
+导出项目的标注数据，支持多种导出格式，以文件形式返回。
+
+**请求**
+
+```
+POST /api/external/projects/{project_id}/export
+```
+
+**路径参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | 是 | 标注平台项目ID（创建项目时返回的project_id） |
+
+**请求体**
+
+```json
+{
+  "format": "sharegpt",
+  "completed_only": true,
+  "callback_url": "https://sample-center.example.com/api/callback/export"
+}
+```
+
+**请求参数说明**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| format | string | 否 | json | 导出格式，见下方支持的格式 |
+| completed_only | bool | 否 | true | 是否只导出已完成的任务 |
+| callback_url | string | 否 | null | 回调URL，导出完成后通知样本中心 |
+
+**支持的导出格式**
+
+| format | 说明 | 适用场景 |
+|--------|------|----------|
+| json | 通用JSON格式 | 通用数据交换 |
+| csv | CSV表格格式 | Excel处理 |
+| sharegpt | ShareGPT对话格式 | 对话模型训练 |
+| yolo | YOLO目标检测格式 | YOLO模型训练 |
+| coco | COCO数据集格式 | 目标检测/分割模型训练 |
+| alpaca | Alpaca指令微调格式 | LLM指令微调 |
+| pascal_voc | PascalVOC XML格式 | 经典目标检测模型训练 |
+
+**响应**
+
+```json
+{
+  "project_id": "proj_abc123def456",
+  "format": "sharegpt",
+  "total_exported": 45,
+  "file_url": "/api/exports/export_789/download",
+  "file_name": "export_proj_abc123_sharegpt_20260203.json",
+  "file_size": 1024000,
+  "expires_at": "2026-02-10T10:30:00Z"
+}
+```
+
+**响应参数说明**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| project_id | string | 项目ID |
+| format | string | 导出格式 |
+| total_exported | int | 导出的任务数量 |
+| file_url | string | 文件下载URL |
+| file_name | string | 文件名 |
+| file_size | int | 文件大小（字节） |
+| expires_at | string | 下载链接过期时间 |
+
+**回调通知**
+
+如果提供了 `callback_url`，导出完成后系统会向该URL发送POST请求：
+
+```json
+{
+  "project_id": "proj_abc123def456",
+  "export_id": "export_789",
+  "status": "completed",
+  "format": "sharegpt",
+  "total_exported": 45,
+  "file_url": "https://annotation-platform.example.com/api/exports/export_789/download",
+  "file_name": "export_proj_abc123_sharegpt_20260203.json",
+  "file_size": 1024000,
+  "error_message": null
+}
+```
+
+**导出格式示例**
+
+**ShareGPT格式**：
+```json
+[
+  {
+    "conversations": [
+      {"from": "human", "value": "请对这段文本进行分类"},
+      {"from": "gpt", "value": "这是一段正面评价"}
+    ]
+  }
+]
+```
+
+**YOLO格式**：
+```
+# image1.txt
+0 0.5 0.5 0.2 0.3
+1 0.3 0.4 0.1 0.2
+```
+
+**COCO格式**：
+```json
+{
+  "images": [...],
+  "annotations": [...],
+  "categories": [...]
+}
+```
+
+**Alpaca格式**：
+```json
+[
+  {
+    "instruction": "对以下文本进行情感分类",
+    "input": "这个产品非常好用！",
+    "output": "正面"
+  }
+]
+```
+
+**PascalVOC格式**：
+```json
+[
+  {
+    "image": "https://example.com/img1.jpg",
+    "filename": "img1.jpg",
+    "xml_content": "<?xml version=\"1.0\"?>...",
+    "objects": [
+      {
+        "name": "cat",
+        "bndbox": {"xmin": 100, "ymin": 50, "xmax": 300, "ymax": 250}
+      }
+    ]
+  }
+]
+```
+
+---
+
+## 错误响应
+
+所有接口在发生错误时返回统一格式的错误响应：
+
+```json
+{
+  "error_code": "PROJECT_NOT_FOUND",
+  "message": "项目不存在",
+  "details": {
+    "project_id": "proj_invalid"
+  }
+}
+```
+
+**错误码说明**
+
+| error_code | HTTP状态码 | 说明 |
+|------------|-----------|------|
+| INVALID_TOKEN | 401 | Token无效或已过期 |
+| PERMISSION_DENIED | 403 | 权限不足，需要管理员权限 |
+| PROJECT_NOT_FOUND | 404 | 项目不存在 |
+| INVALID_REQUEST | 400 | 请求参数无效 |
+| INVALID_TASK_TYPE | 400 | 不支持的任务类型 |
+| EXPORT_FAILED | 500 | 导出失败 |
+| INTERNAL_ERROR | 500 | 内部服务器错误 |
+
+---
+
+## 使用示例
+
+### Python 示例
+
+```python
+import requests
+
+BASE_URL = "http://localhost:8003/api/external"
+ADMIN_TOKEN = "your_admin_token_here"
+
+headers = {
+    "Authorization": f"Bearer {ADMIN_TOKEN}",
+    "Content-Type": "application/json"
+}
+
+# 1. 创建项目（带标签）
+init_data = {
+    "name": "文本分类项目",
+    "description": "对用户评论进行情感分类",
+    "task_type": "text_classification",
+    "data": [
+        {"id": "1", "content": "这个产品非常好用！"},
+        {"id": "2", "content": "质量太差了，不推荐"},
+        {"id": "3", "content": "一般般，没什么特别的"}
+    ],
+    "external_id": "sample_center_001",
+    "tags": [
+        {"tag": "正面", "color": "#4CAF50"},
+        {"tag": "负面", "color": "#F44336"},
+        {"tag": "中性"}  # 不指定颜色，系统自动生成
+    ]
+}
+
+response = requests.post(
+    f"{BASE_URL}/projects/init",
+    json=init_data,
+    headers=headers
+)
+project = response.json()
+project_id = project["project_id"]
+print(f"项目创建成功: {project_id}")
+
+# 2. 创建多边形标注项目
+polygon_data = {
+    "name": "多边形标注项目",
+    "description": "标注图像中的不规则区域",
+    "task_type": "polygon",
+    "data": [
+        {"id": "1", "content": "https://example.com/img1.jpg"},
+        {"id": "2", "content": "https://example.com/img2.jpg"}
+    ],
+    "tags": [
+        {"tag": "区域A", "color": "#FF5722"},
+        {"tag": "区域B", "color": "#607D8B"}
+    ]
+}
+
+response = requests.post(
+    f"{BASE_URL}/projects/init",
+    json=polygon_data,
+    headers=headers
+)
+polygon_project = response.json()
+print(f"多边形项目创建成功: {polygon_project['project_id']}")
+
+# 3. 查询进度
+response = requests.get(
+    f"{BASE_URL}/projects/{project_id}/progress",
+    headers=headers
+)
+progress = response.json()
+print(f"完成进度: {progress['completion_percentage']}%")
+
+# 4. 导出数据（ShareGPT格式）
+export_data = {
+    "format": "sharegpt",
+    "completed_only": True,
+    "callback_url": "https://sample-center.example.com/api/callback"
+}
+
+response = requests.post(
+    f"{BASE_URL}/projects/{project_id}/export",
+    json=export_data,
+    headers=headers
+)
+export_result = response.json()
+print(f"导出任务数: {export_result['total_exported']}")
+print(f"下载链接: {export_result['file_url']}")
+
+# 下载导出文件
+file_response = requests.get(
+    f"http://localhost:8003{export_result['file_url']}",
+    headers=headers
+)
+with open(export_result['file_name'], 'wb') as f:
+    f.write(file_response.content)
+print(f"文件已保存: {export_result['file_name']}")
+```
+
+### cURL 示例
+
+```bash
+# 1. 创建项目（带标签）
+curl -X POST "http://localhost:8003/api/external/projects/init" \
+  -H "Authorization: Bearer your_admin_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "图像分类项目",
+    "task_type": "image_classification",
+    "data": [
+      {"id": "1", "content": "https://example.com/img1.jpg"},
+      {"id": "2", "content": "https://example.com/img2.jpg"}
+    ],
+    "external_id": "sample_center_proj_001",
+    "tags": [
+      {"tag": "猫猫", "color": "#FF9800"},
+      {"tag": "狗狗", "color": "#2196F3"}
+    ]
+  }'
+
+# 2. 创建多边形标注项目
+curl -X POST "http://localhost:8003/api/external/projects/init" \
+  -H "Authorization: Bearer your_admin_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "多边形标注项目",
+    "task_type": "polygon",
+    "data": [
+      {"id": "1", "content": "https://example.com/img1.jpg"}
+    ],
+    "tags": [
+      {"tag": "区域A", "color": "#FF5722"},
+      {"tag": "区域B"}
+    ]
+  }'
+
+# 3. 查询进度
+curl -X GET "http://localhost:8003/api/external/projects/proj_xxx/progress" \
+  -H "Authorization: Bearer your_admin_token"
+
+# 4. 导出数据（YOLO格式）
+curl -X POST "http://localhost:8003/api/external/projects/proj_xxx/export" \
+  -H "Authorization: Bearer your_admin_token" \
+  -H "Content-Type: application/json" \
+  -d '{"format": "yolo", "completed_only": true}'
+
+# 5. 下载导出文件
+curl -X GET "http://localhost:8003/api/exports/export_xxx/download" \
+  -H "Authorization: Bearer your_admin_token" \
+  -o exported_data.zip
+```
+
+---
+
+## 工作流程说明
+
+```
+样本中心                          标注平台
+   |                                 |
+   |  1. POST /projects/init         |
+   |-------------------------------->|
+   |  返回 project_id, status=draft  |
+   |<--------------------------------|
+   |                                 |
+   |                                 | 管理员配置项目
+   |                                 | (配置标签、XML等)
+   |                                 |
+   |                                 | 管理员分发任务
+   |                                 | (选择标注人员)
+   |                                 |
+   |  2. GET /projects/{id}/progress |
+   |-------------------------------->|
+   |  返回进度信息                    |
+   |<--------------------------------|
+   |                                 |
+   |  (轮询查询进度...)               |
+   |                                 |
+   |  3. POST /projects/{id}/export  |
+   |-------------------------------->|
+   |  返回标注数据                    |
+   |<--------------------------------|
+   |                                 |
+```
+
+---
+
+## 注意事项
+
+1. **项目状态**：外部系统创建的项目初始状态为 `draft`，需要标注平台管理员完成配置（设置标签等）和任务分发后才会进入 `in_progress` 状态。
+
+2. **标签配置**：
+   - 如果在创建项目时传入 `tags` 参数，系统会自动生成包含这些标签的XML配置
+   - 如果不传 `tags` 参数，标签由标注平台管理员在项目配置阶段设置
+   - 管理员可以在配置阶段修改已传入的标签名称和颜色
+
+3. **颜色格式**：
+   - 颜色使用 `#RRGGBB` 格式（如 `#FF5733`）
+   - 如果不指定颜色，系统会自动生成随机颜色
+
+4. **数据格式**：
+   - 文本类任务（text_classification, ner）：`content` 字段为文本内容
+   - 图像类任务（image_classification, object_detection, polygon）：`content` 字段为图像URL
+
+5. **外部ID关联**：建议在创建项目时提供 `external_id`，方便后续在样本中心系统中关联查询。
+
+6. **导出时机**：建议在项目状态为 `completed` 或 `completion_percentage` 达到预期值时再进行数据导出。
+
+7. **Token安全**：请妥善保管管理员Token，不要在客户端代码中暴露。
+
+8. **多边形标注**：polygon 类型支持标注不规则形状区域，导出时支持 COCO 和 YOLO 格式。
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| 1.2.0 | 2026-02-06 | 添加PascalVOC导出格式支持 |
+| 1.1.0 | 2026-02-05 | 添加tags参数支持、新增polygon任务类型 |
+| 1.0.0 | 2026-02-03 | 初始版本 |