这是本节的多页打印视图。点击此处打印.

API 参考

DataMate API 文档

1: 数据管理 API

DataMate 提供完整的 REST API，支持所有核心功能的编程访问。

API 概述

DataMate API 基于 REST 架构设计，提供以下服务：

数据管理 API：数据集和文件管理
数据清洗 API：数据清洗任务管理
数据采集 API：数据采集任务管理
数据标注 API：数据标注任务管理
数据合成 API：数据合成任务管理
数据评估 API：数据评估任务管理
算子市场 API：算子管理
RAG 索引 API：知识库和向量检索
流水线编排 API：流程编排管理

认证方式

DataMate 支持两种认证方式：

JWT 认证（推荐）

GET /api/v1/data-management/datasets
Authorization: Bearer <your-jwt-token>

获取 JWT Token：

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

响应：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

API Key 认证

GET /api/v1/data-management/datasets
X-API-Key: <your-api-key>

通用响应格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    // 响应数据
  }
}

错误响应

{
  "code": 400,
  "message": "Bad Request",
  "error": "Invalid parameter: datasetId",
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/v1/data-management/datasets"
}

分页响应

{
  "content": [],
  "page": 0,
  "size": 20,
  "totalElements": 100,
  "totalPages": 5,
  "first": true,
  "last": false
}

API 端点

数据管理

端点	方法	描述
`/data-management/datasets`	GET	获取数据集列表
`/data-management/datasets`	POST	创建数据集
`/data-management/datasets/{id}`	GET	获取数据集详情
`/data-management/datasets/{id}`	PUT	更新数据集
`/data-management/datasets/{id}`	DELETE	删除数据集
`/data-management/datasets/{id}/files`	GET	获取文件列表
`/data-management/datasets/{id}/files/upload`	POST	上传文件

详细文档：数据管理 API

数据清洗

端点	方法	描述
`/data-cleaning/tasks`	GET	获取清洗任务列表
`/data-cleaning/tasks`	POST	创建清洗任务
`/data-cleaning/tasks/{id}`	GET	获取任务详情
`/data-cleaning/tasks/{id}`	PUT	更新任务
`/data-cleaning/tasks/{id}`	DELETE	删除任务
`/data-cleaning/tasks/{id}/execute`	POST	执行任务

详细文档：数据清洗 API

数据采集

端点	方法	描述
`/data-collection/tasks`	GET	获取采集任务列表
`/data-collection/tasks`	POST	创建采集任务
`/data-collection/tasks/{id}`	GET	获取任务详情
`/data-collection/tasks/{id}/execute`	POST	执行采集任务

详细文档：数据采集 API

数据合成

端点	方法	描述
`/data-synthesis/tasks`	GET	获取合成任务列表
`/data-synthesis/tasks`	POST	创建合成任务
`/data-synthesis/templates`	GET	获取指令模板列表
`/data-synthesis/templates`	POST	创建指令模板

详细文档：数据合成 API

算子市场

端点	方法	描述
`/operator-market/operators`	GET	获取算子列表
`/operator-market/operators`	POST	发布算子
`/operator-market/operators/{id}`	GET	获取算子详情
`/operator-market/operators/{id}/install`	POST	安装算子

详细文档：算子市场 API

RAG 索引

端点	方法	描述
`/rag/knowledge-bases`	GET	获取知识库列表
`/rag/knowledge-bases`	POST	创建知识库
`/rag/knowledge-bases/{id}/documents`	POST	上传文档
`/rag/knowledge-bases/{id}/search`	POST	向量检索

详细文档：RAG 索引 API

SDK 和客户端

DataMate 提供多种语言的 SDK：

Python SDK

from datamate import DataMateClient

# 初始化客户端
client = DataMateClient(
    base_url="http://localhost:8080",
    api_key="your-api-key"
)

# 获取数据集列表
datasets = client.data_management.get_datasets()

# 创建数据集
dataset = client.data_management.create_dataset(
    name="my_dataset",
    type="text",
    description="My dataset"
)

# 上传文件
client.data_management.upload_file(
    dataset_id=dataset.id,
    file_path="/path/to/file.txt"
)

JavaScript SDK

import { DataMateClient } from '@datamate/sdk';

// 初始化客户端
const client = new DataMateClient({
  baseURL: 'http://localhost:8080',
  apiKey: 'your-api-key'
});

// 获取数据集列表
const datasets = await client.dataManagement.getDatasets();

// 创建数据集
const dataset = await client.dataManagement.createDataset({
  name: 'my_dataset',
  type: 'text',
  description: 'My dataset'
});

// 上传文件
await client.dataManagement.uploadFile(
  dataset.id,
  '/path/to/file.txt'
);

错误码

错误码	说明
200	成功
201	创建成功
400	请求参数错误
401	未认证
403	无权限
404	资源不存在
409	资源冲突
500	服务器内部错误

速率限制

API 调用速率限制：

默认限制：1000 次/小时
突发限制：100 次/分钟

超过限制返回 429 Too Many Requests。

响应头包含速率限制信息：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642252800

版本管理

API 版本通过 URL 路径指定：

当前版本：/api/v1/
未来版本：/api/v2/

1 - 数据管理 API

数据集和文件管理 API

数据管理 API 提供数据集和文件的创建、查询、更新和删除功能。

基础信息

Base URL: http://localhost:8092/api/v1/data-management
认证方式: JWT / API Key
Content-Type: application/json

数据集管理

获取数据集列表

GET /data-management/datasets?page=0&size=20&type=text&status=ACTIVE

查询参数:

参数	类型	必填	说明
page	integer	否	页码，从 0 开始，默认 0
size	integer	否	每页大小，默认 20
type	string	否	数据集类型过滤
tags	string	否	标签过滤，逗号分隔
keyword	string	否	关键词搜索
status	string	否	状态过滤

响应示例:

{
  "content": [
    {
      "id": "dataset-001",
      "name": "text_dataset",
      "description": "文本数据集",
      "type": {
        "code": "TEXT",
        "name": "文本",
        "supportedFormats": ["txt", "md", "json"]
      },
      "status": "ACTIVE",
      "tags": [
        {"id": "tag-001", "name": "training", "color": "#FF0000"}
      ],
      "fileCount": 1000,
      "totalSize": 1073741824,
      "completionRate": 85.5,
      "createdAt": "2024-01-15T10:00:00Z",
      "createdBy": "admin"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "last": true
}

创建数据集

POST /data-management/datasets
Content-Type: application/json

{
  "name": "my_dataset",
  "description": "My dataset description",
  "type": "TEXT",
  "tags": ["training", "nlp"],
  "dataSource": "/data/input",
  "targetLocation": "/data/output"
}

请求体参数:

参数	类型	必填	说明
name	string	是	数据集名称，1-100 字符
description	string	否	数据集描述，最多 500 字符
type	string	是	数据集类型代码
tags	array	否	标签列表
dataSource	string	否	数据源
targetLocation	string	否	目标位置

响应示例:

{
  "id": "dataset-002",
  "name": "my_dataset",
  "description": "My dataset description",
  "type": {
    "code": "TEXT",
    "name": "文本"
  },
  "status": "ACTIVE",
  "tags": [],
  "fileCount": 0,
  "totalSize": 0,
  "completionRate": 0,
  "createdAt": "2024-01-15T11:00:00Z",
  "createdBy": "admin"
}

获取数据集详情

GET /data-management/datasets/{datasetId}

路径参数:

参数	类型	必填	说明
datasetId	string	是	数据集 ID

响应: 同创建数据集响应

更新数据集

PUT /data-management/datasets/{datasetId}
Content-Type: application/json

{
  "name": "updated_dataset",
  "description": "Updated description",
  "tags": ["training", "updated"]
}

请求体参数:

参数	类型	必填	说明
name	string	否	数据集名称
description	string	否	数据集描述
tags	array	否	标签列表
status	string	否	数据集状态

删除数据集

DELETE /data-management/datasets/{datasetId}

响应: 204 No Content

文件管理

获取文件列表

GET /data-management/datasets/{datasetId}/files?page=0&size=20

查询参数:

参数	类型	必填	说明
page	integer	否	页码，从 0 开始
size	integer	否	每页大小
fileType	string	否	文件类型过滤
status	string	否	状态过滤

响应示例:

{
  "content": [
    {
      "id": "file-001",
      "fileName": "document.txt",
      "originalName": "document.txt",
      "fileType": "txt",
      "fileSize": 1024,
      "status": "COMPLETED",
      "filePath": "/dataset-001/document.txt",
      "uploadTime": "2024-01-15T10:30:00Z",
      "uploadedBy": "admin"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

上传文件（预上传）

POST /data-management/datasets/{datasetId}/files/upload/pre-upload
Content-Type: application/json

{
  "hasArchive": false,
  "totalFileNum": 1,
  "totalSize": 1024,
  "prefix": "documents/"
}

请求体参数:

参数	类型	必填	说明
hasArchive	boolean	否	是否为压缩包
totalFileNum	integer	是	总文件数
totalSize	integer	是	总文件大小（字节）
prefix	string	否	目标子目录前缀

响应: 请求 ID (string)

上传文件（分片上传）

POST /data-management/datasets/{datasetId}/files/upload/chunk
Content-Type: multipart/form-data

reqId: <pre-upload-request-id>
fileNo: 1
fileName: document.txt
totalChunkNum: 3
chunkNo: 1
file: <binary-data>
checkSumHex: <checksum>

表单参数:

参数	类型	必填	说明
reqId	string	是	预上传请求 ID
fileNo	integer	是	文件编号
fileName	string	是	文件名
totalChunkNum	integer	是	总分片数
chunkNo	integer	是	当前分片编号（从 1 开始）
file	file	是	分片二进制数据
checkSumHex	string	否	分片校验和

下载文件

GET /data-management/datasets/{datasetId}/files/{fileId}/download

响应: 文件二进制内容

批量下载文件（ZIP）

GET /data-management/datasets/{datasetId}/files/download

响应: ZIP 压缩包

删除文件

DELETE /data-management/datasets/{datasetId}/files/{fileId}

响应: 204 No Content

创建目录

POST /data-management/datasets/{datasetId}/files/directories
Content-Type: application/json

{
  "parentPrefix": "documents/",
  "directoryName": "subfolder"
}

数据集类型

获取数据集类型列表

GET /data-management/dataset-types

响应示例:

[
  {
    "code": "TEXT",
    "name": "文本",
    "description": "文本数据集",
    "supportedFormats": ["txt", "md", "json", "csv"],
    "icon": "file-text"
  },
  {
    "code": "IMAGE",
    "name": "图像",
    "description": "图像数据集",
    "supportedFormats": ["jpg", "png", "gif", "bmp"],
    "icon": "file-image"
  }
]

标签管理

获取标签列表

GET /data-management/tags?keyword=training

查询参数:

参数	类型	必填	说明
keyword	string	否	标签名称关键词

响应示例:

[
  {
    "id": "tag-001",
    "name": "training",
    "color": "#FF0000",
    "description": "训练数据",
    "usageCount": 15
  }
]

创建标签

POST /data-management/tags
Content-Type: application/json

{
  "name": "validation",
  "color": "#00FF00",
  "description": "验证数据"
}

请求体参数:

参数	类型	必填	说明
name	string	是	标签名称，1-50 字符
color	string	否	标签颜色，十六进制
description	string	否	标签描述，最多 200 字符

统计信息

获取数据集统计

GET /data-management/datasets/{datasetId}/statistics

响应示例:

{
  "totalFiles": 1000,
  "completedFiles": 850,
  "totalSize": 1073741824,
  "completionRate": 85.0,
  "fileTypeDistribution": {
    "txt": 600,
    "md": 250,
    "json": 150
  },
  "statusDistribution": {
    "COMPLETED": 850,
    "PROCESSING": 100,
    "ERROR": 50
  }
}

错误响应

400 Bad Request

{
  "error": "INVALID_PARAMETER",
  "message": "Invalid parameter: datasetId",
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/v1/data-management/datasets"
}

404 Not Found

{
  "error": "DATASET_NOT_FOUND",
  "message": "Dataset not found: dataset-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/v1/data-management/datasets/dataset-001"
}

SDK 使用示例

Python

from datamate import DataMateClient

client = DataMateClient(
    base_url="http://localhost:8080",
    api_key="your-api-key"
)

# 获取数据集列表
datasets = client.data_management.get_datasets(
    type="TEXT",
    status="ACTIVE"
)

# 创建数据集
dataset = client.data_management.create_dataset(
    name="my_dataset",
    type="TEXT",
    description="My dataset"
)

# 上传文件
with open("document.txt", "rb") as f:
    client.data_management.upload_file(
        dataset_id=dataset.id,
        file=f,
        file_name="document.txt"
    )

JavaScript

import { DataMateClient } from '@datamate/sdk';

const client = new DataMateClient({
  baseURL: 'http://localhost:8080',
  apiKey: 'your-api-key'
});

// 获取数据集列表
const datasets = await client.dataManagement.getDatasets({
  type: 'TEXT',
  status: 'ACTIVE'
});

// 创建数据集
const dataset = await client.dataManagement.createDataset({
  name: 'my_dataset',
  type: 'TEXT',
  description: 'My dataset'
});

// 上传文件
await client.dataManagement.uploadFile(
  dataset.id,
  'document.txt',
  fileData
);

cURL

# 获取数据集列表
curl -X GET "http://localhost:8092/api/v1/data-management/datasets?page=0&size=20" \
  -H "Authorization: Bearer your-jwt-token"

# 创建数据集
curl -X POST "http://localhost:8092/api/v1/data-management/datasets" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_dataset",
    "type": "TEXT",
    "description": "My dataset"
  }'

API 参考

API 概述

认证方式

JWT 认证（推荐）

API Key 认证

通用响应格式

成功响应

错误响应

分页响应

API 端点

数据管理

数据清洗

数据采集

数据合成

算子市场

RAG 索引

SDK 和客户端

Python SDK

JavaScript SDK

错误码

速率限制

版本管理

相关文档

1 - 数据管理 API

基础信息

数据集管理

获取数据集列表

创建数据集

获取数据集详情

更新数据集

删除数据集

文件管理

获取文件列表

上传文件（预上传）

上传文件（分片上传）

下载文件

批量下载文件（ZIP）

删除文件

创建目录

数据集类型

获取数据集类型列表

标签管理

获取标签列表

创建标签

统计信息

获取数据集统计

错误响应

400 Bad Request

404 Not Found

SDK 使用示例

Python

JavaScript

cURL

相关文档