# 批量添加样本 #### 功能介绍 批量添加样本。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/ModelArts/doc?api=UploadSamplesJson)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### URI POST /v2/{project_id}/datasets/{dataset_id}/data-annotations/samples 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | dataset_id | 是 | String | 数据集ID。 | | project_id | 是 | String | 用户项目ID。获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-modelarts/modelarts_03_0147.html)。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | final_annotation | 否 | Boolean | 是否直接导入到最终结果。可选值如下： - true：标签导入到已标注（默认值） - false：标签导入到待确认，导入到待确认状态目前仅支持的数据集类型为图像分类和物体检测。 | | label_format | 否 | [LabelFormat] object | 标签格式，此参数仅文本类数据集使用。 | | samples | 否 | Array of [Sample] objects | 样本列表。 | 表3LabelFormat | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | label_type | 否 | String | 文本分类的标签类型。可选值如下： - 0：标签和文本分离，以固定后缀"_result"区分。如：文本文件是"abc.txt"，标签文件是"abc_result.txt"。 - 1：默认值，标签和文本在一个文件内，以分隔符分离。文本与标签，标签与标签之间的分隔符可通过text_sample_separator和text_label_separator指定。 | | text_label_separator | 否 | String | 标签与标签之间的分隔符，默认为逗号分隔，分隔符需转义。分隔符仅支持一个字符，必须为大小写字母，数字和"!@#$%\^\&\*_=\|?/':.;,"其中的某一字符。 | | text_sample_separator | 否 | String | 文本与标签之间的分隔符，默认为Tab键分隔，分隔符需转义。分隔符仅支持一个字符，必须为大小写字母，数字和"!@#$%\^\&\*_=\|?/':.;,"其中的某一字符。 | 表4Sample | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | data | 否 | Object | 样本文件的字节数据。类型为java.nio.ByteBuffer，前台调用时传字节数据转换后的字符串。 | | data_source | 否 | [DataSource] object | 数据来源。 | | encoding | 否 | String | 样本文件的编码类型，用于文本类型（txt/csv）的文件上传。取值有UTF-8、GBK、GB2312等，默认为UTF-8编码。 | | labels | 否 | Array of [SampleLabel] objects | 样本标签列表。 | | metadata | 否 | [SampleMetadata] object | 样本metadata属性键值对。 | | name | 否 | String | 样本文件名称，名称不能包含!\<\>=\&"'特殊字符，长度为0-1024位。 | | sample_type | 否 | Integer | 样本类型。可选值如下： - 0：图像 - 1：文本 - 2：语音 - 4：表格 - 6：视频 - 9：自由格式 | 表5DataSource | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | data_path | 否 | String | 数据源所在路径。 | | data_type | 否 | Integer | 数据类型。可选值如下： - 0：OBS桶（默认值） - 1：GaussDB(DWS)服务 - 2：DLI服务 - 3：RDS服务 - 4：MRS服务 - 5：AI Gallery - 6：推理服务 | | schema_maps | 否 | Array of [SchemaMap] objects | 表格数据对应的schema映射信息。 | | source_info | 否 | [SourceInfo] object | 导入表格数据源所需的信息。 | | with_column_header | 否 | Boolean | 文件中首行是否是列名，用于表格数据集。可选值如下： - true：文件首行为列名 - false：文件首行不为列名 | 表6SchemaMap | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | dest_name | 否 | String | 目的方的列名。 | | src_name | 否 | String | 来源方的列名。 | 表7SourceInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | cluster_id | 否 | String | MRS集群ID。可登录MRS控制台查看。 | | cluster_mode | 否 | String | MRS集群运行模式。可选值如下： - 0：普通集群 - 1：安全集群 | | cluster_name | 否 | String | MRS集群名称。可登录MRS控制台查看。 | | database_name | 否 | String | 导入表格数据集，数据库名字。 | | input | 否 | String | 表格数据集，HDFS路径。例如/datasets/demo。 | | ip | 否 | String | 用户GaussDB(DWS)集群的IP地址。 | | port | 否 | String | 用户GaussDB(DWS)集群的端口。 | | queue_name | 否 | String | 表格数据集，DLI队列名。 | | subnet_id | 否 | String | MRS集群的子网ID。 | | table_name | 否 | String | 导入表格数据集，表名。 | | user_name | 否 | String | 用户名，GaussDB(DWS)数据需提供此参数。 | | user_password | 否 | String | 用户密码，GaussDB(DWS)数据需提供此参数。 | | vpc_id | 否 | String | MRS集群所在的vpc的ID。 | 表8SampleLabel | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | annotated_by | 否 | String | 视频标注途径，用于区分标签是人工标注的还是自动标注的。可选值如下： - human：人工标注 - auto：自动标注 | | id | 否 | String | 标签ID。 | | name | 否 | String | 标签名。 | | property | 否 | [SampleLabelProperty] object | 样本标签的属性键值对，如物体形状、形状特征等。 | | score | 否 | Float | 置信度，取值范围为\[0,1\] | | type | 否 | Integer | 标签类型。可选值如下： - 0：图像分类 - 1：物体检测 - 3: 图像分割 - 100：文本分类 - 101：命名实体 - 102：文本三元组关系标签 - 103：文本三元组实体标签 - 200：语音分类 - 201：语音内容 - 202：语音分割 - 600：视频标注 | 表9SampleLabelProperty | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | @modelarts:content | 否 | String | 语音标签（包含语音内容和语音起止点）专用内置属性：语音文本内容。 | | @modelarts:end_index | 否 | Integer | 命名实体标签专用内置属性：文本的结束位置，但不包括end_index所指的字符。例如： - 文本内容为"Barack Hussein Obama II (born August 4, 1961) is a attorney and politician."，则其中人名"Barack Hussein Obama II"的start_index为0，end_index为23。 - 文本内容为"截止到2018年底，本公司人员规模已经超过100"，则其中时间"2018年底"的start_index为3，end_index为9。 | | @modelarts:end_time | 否 | String | 语音起止点标签专用内置属性：语音的结束时间，格式"hh:mm:ss.SSS"(其中hh表示小时，mm表示分钟，ss表示秒，SSS表示毫秒)。 | | @modelarts:feature | 否 | Object | 物体检测标签专用内置属性：形状特征，类型为List。以图片的左上角为坐标原点\[0, 0\]，每个坐标点的表示方法为\[x, y\]，x表示横坐标，y表示纵坐标(x和y均\>=0)。每种形状的格式如下： - bndbox \[\[0,10\],\[50,95\]\] 两个点组成，矩形的左上角为第一个点，矩形的右下角为第二个点(即第一个点x坐标一定小于第二个点的x坐标，第一个点y坐标一定小于第二个点的y坐标)。 - polygon \[\[0,100\],\[50,95\],\[10,60\],\[500,400\]\] 多个点组成，按顺序连接成一个多边形。 - circle \[\[100,100\],\[50\]\] 一个圆心点和半径组成。 - line \[\[0,100\],\[50,95\]\] 两个点组成，第一个点起始点，第二个点为终止点。 - dashed \[\[0,100\],\[50,95\]\] 两个点组成，第一个点起始点，第二个点为终止点。 - point \[\[0,100\]\] 一个点组成。 - polyline \[\[0,100\],\[50,95\],\[10,60\],\[500,400\]\] 折线，多个点组成。 | | @modelarts:from | 否 | String | 三元组关系标签专用内置属性：三元组关系标签的起始实体ID。 | | @modelarts:hard | 否 | String | 内置属性：标签级别是否难例。可选值为： - 0/false：非难例 - 1/true：难例 | | @modelarts:hard_coefficient | 否 | String | 内置属性：标签级别难度系数。范围为\[0,1\]。 | | @modelarts:hard_reasons | 否 | String | 内置属性：标签级别难例原因。通过中划线间隔单个难例原因ID，例如："3-20-21-19"。难例原因ID可选值如下： - 0：未识别出任何目标物体。 - 1：置信度偏低。 - 2：基于训练数据集的聚类结果和预测结果不一致。 - 3：预测结果和训练集同类别数据差异较大。 - 4：连续多张相似图片的预测结果不一致。 - 5：图像的分辨率与训练数据集的特征分布存在较大偏移。 - 6：图像的高宽比与训练数据集的特征分布存在较大偏移。 - 7：图像的亮度与训练数据集的特征分布存在较大偏移。 - 8：图像的饱和度与训练数据集的特征分布存在较大偏移。 - 9：图像的色彩丰富程度与训练数据集的特征分布存在较大偏移。 - 10：图像的清晰度与训练数据集的特征分布存在较大偏移。 - 11：图像的目标框数量与训练数据集的特征分布存在较大偏移。 - 12：图像中目标框的面积标准差与训练数据集的特征分布存在较大偏移。 - 13：图像中目标框的高宽比与训练数据集的特征分布存在较大偏移。 - 14：图像中目标框的面积占比与训练数据集的特征分布存在较大偏移。 - 15：图像中目标框的边缘化程度与训练数据集的特征分布存在较大偏移。 - 16：图像中目标框的亮度与训练数据集的特征分布存在较大偏移。 - 17：图像中目标框的清晰度与训练数据集的特征分布存在较大偏移。 - 18：图像中目标框的堆叠程度与训练数据集的特征分布存在较大偏移。 - 19：基于gaussianblur的数据增强与原图预测结果不一致。 - 20：基于fliplr的数据增强与原图预测结果不一致。 - 21：基于crop的数据增强与原图预测结果不一致。 - 22：基于flipud的数据增强与原图预测结果不一致。 - 23：基于scale的数据增强与原图预测结果不一致。 - 24：基于translate的数据增强与原图预测结果不一致。 - 25：基于shear的数据增强与原图预测结果不一致。 - 26：基于superpixels的数据增强与原图预测结果不一致。 - 27：基于sharpen的数据增强与原图预测结果不一致。 - 28：基于add的数据增强与原图预测结果不一致。 - 29：基于invert的数据增强与原图预测结果不一致。 - 30：数据被预测为异常点。 | | @modelarts:shape | 否 | String | 物体检测标签专用内置属性：物体形状，默认为空。可选值如下： - bndbox：矩形。 - polygon：多边形。 - circle：圆形。 - line：直线。 - dashed：虚线。 - point：点。 - polyline：折线。 | | @modelarts:source | 否 | String | 语音起止点标签专用内置属性：语音来源(例如说话人/旁白等)。 | | @modelarts:start_index | 否 | Integer | 命名实体标签专用内置属性：文本的起始位置，值从0开始，包括start_index所指的字符。 | | @modelarts:start_time | 否 | String | 语音起止点标签专用内置属性：语音的起始时间，格式"hh:mm:ss.SSS"(其中hh表示小时，mm表示分钟，ss表示秒，SSS表示毫秒)。 | | @modelarts:to | 否 | String | 三元组关系标签专用内置属性：三元组关系标签的指向实体ID。 | 表10SampleMetadata | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | @modelarts:import_origin | 否 | Integer | 内置属性：样本来源。 | | @modelarts:hard | 否 | Double | 内置属性：样本级别是否难例。可选值为： - 0：非难例 - 1：难例 | | @modelarts:hard_coefficient | 否 | Double | 内置属性：样本级别难度系数。范围为\[0,1\]。 | | @modelarts:hard_reasons | 否 | Array of integers | 内置属性：样本级别难例原因ID列表。难例原因ID可选值如下： - 0：未识别出任何目标物体。 - 1：置信度偏低。 - 2：基于训练数据集的聚类结果和预测结果不一致。 - 3：预测结果和训练集同类别数据差异较大。 - 4：连续多张相似图片的预测结果不一致。 - 5：图像的分辨率与训练数据集的特征分布存在较大偏移。 - 6：图像的高宽比与训练数据集的特征分布存在较大偏移。 - 7：图像的亮度与训练数据集的特征分布存在较大偏移。 - 8：图像的饱和度与训练数据集的特征分布存在较大偏移。 - 9：图像的色彩丰富程度与训练数据集的特征分布存在较大偏移。 - 10：图像的清晰度与训练数据集的特征分布存在较大偏移。 - 11：图像的目标框数量与训练数据集的特征分布存在较大偏移。 - 12：图像中目标框的面积标准差与训练数据集的特征分布存在较大偏移。 - 13：图像中目标框的高宽比与训练数据集的特征分布存在较大偏移。 - 14：图像中目标框的面积占比与训练数据集的特征分布存在较大偏移。 - 15：图像中目标框的边缘化程度与训练数据集的特征分布存在较大偏移。 - 16：图像中目标框的亮度与训练数据集的特征分布存在较大偏移。 - 17：图像中目标框的清晰度与训练数据集的特征分布存在较大偏移。 - 18：图像中目标框的堆叠程度与训练数据集的特征分布存在较大偏移。 - 19：基于gaussianblur的数据增强与原图预测结果不一致。 - 20：基于fliplr的数据增强与原图预测结果不一致。 - 21：基于crop的数据增强与原图预测结果不一致。 - 22：基于flipud的数据增强与原图预测结果不一致。 - 23：基于scale的数据增强与原图预测结果不一致。 - 24：基于translate的数据增强与原图预测结果不一致。 - 25：基于shear的数据增强与原图预测结果不一致。 - 26：基于superpixels的数据增强与原图预测结果不一致。 - 27：基于sharpen的数据增强与原图预测结果不一致。 - 28：基于add的数据增强与原图预测结果不一致。 - 29：基于invert的数据增强与原图预测结果不一致。 - 30：数据被预测为异常点。 | | @modelarts:size | 否 | Array of objects | 内置属性：图像尺寸（图像的宽度、高度、深度），类型为List\[/topic/body/section/table/tgroup/tbody/row/entry/p/br {""}) (br\]。列表中的第一个数字为宽度(像素)，第二个数字为高度(像素)，第三个数字为深度(深度可以没有，默认为3)，如\[100,200,3\]和\[100,200\]均合法。 说明：只有当样本的标签列表包含物体检测标签时，此字段必选。 | #### 响应参数 **状态码： 200** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 操作失败的错误码。 | | error_msg | String | 操作失败的错误信息。 | | results | Array of [UploadSampleResp] objects | 批量添加样本的响应列表。 | | success | Boolean | 操作是否执行成功。可选值如下： - true：执行成功 - false：执行失败 | 表12UploadSampleResp | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 操作失败的错误码。 | | error_msg | String | 操作失败的错误信息。 | | info | String | 描述信息。 | | name | String | 样本文件名。 | | success | Boolean | 操作是否执行成功。可选值如下： - true：执行成功 - false：执行失败 | #### 请求示例 批量添加样本 ``` { "samples" : [ { "name" : "2.jpg", "data" : "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAA1AJUDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL" } ] } ``` #### 响应示例 **状态码： 200** OK ``` { "success" : true, "results" : [ { "success" : true, "name" : "/test-obs/classify/input/animals/2.jpg", "info" : "960585877c92d63911ba555ab3129d36" } ] } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | OK | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-modelarts/modelarts_03_0095.html)。