Request service training

Available in Classic and VPC

Request that a service with a service type of batch train a one-time dataset.

Request

The following describes the request format for the endpoint. The request format is as follows:

Method	URI
POST	/services/{serviceId}

Request headers

For headers common to all AiTEMS APIs, see Common AiTEMS headers.

Request path parameters

The following describes the parameters.

Field	Type	Required	Description
`serviceId`	String	Required	Service ID Check through Get service list Only IDs of services with `type` of `batch` can be entered

Request body

The following describes the request body.

Field	Type	Required	Description
`types`	Array	Required	Training request type `personalRecommend` \| `relatedItem` \| `pop` `personalRecommend`: personalized recommendations based on customer service users' past history `relatedItem`: personalized recommendations based on an item's association history `pop`: top item recommendations by rank
`description`	String	Optional	Training description
`hpConfig`	Object	Required	Hyperparameter optimization (HPO) settings information
`hpConfig.is_enabled`	Boolean	Required	HPO configuration status `true` \| `false` `true`: HPO configured, optimal training models can be implemented `false`: HPO not configured, trained by AiTEMS' own internal algorithms
`hpConfig.{option}`	String, Long, Boolean	Optional	Configured HPO value See HPO for value details

HPO

The following describes the configurable HPO values.

Option name	Type	Required	Training type	Description
`session_max_timestamp`	Long	Optional	Personalized recommendations, related item recommendations	Maximum idle time (in seconds) between actions to consider the same session 10 - 86,400 (default: 1800) Recommended to be set to 1800 or higher
`item_top_n`	Long	Optional	Personalized recommendations, related item recommendations	Maximum number of products to be used for recommendations Utilize by popularity 1000 - 500,000 (default: 20,000)
`min_item_cut`	Long	Optional	Personalized recommendations, related item recommendations	Product minimum appearance count 1 - 1000 (default: 5)
`min_session_length`	Long	Optional	Personalized recommendations, related item recommendations	Minimum number of actions in a session 2 - 1000 (default: 2)
`max_user_recommend_top`	Long	Optional	Personalized recommendation	Maximum number of recommendations per user 1 - 1000 (default: 100)
`max_relate_recommend_top`	Long	Optional	Related item recommendation	Maximum number of related item recommendations per product 1 - 1000 (default: 100)
`remove_history_item`	Boolean	Optional	Personalized recommendations, related item recommendations	Whether to remove previously recommended products from personalized recommendations list `true` \| `false` (default) `true`: Remove previously recommended products from the recommendations list `false`: Include previously recommended products in the personalized recommendations list
`group_column`	Array	Required	Popular item recommendation	List of popular extract group columns USER_ID, ITEM_ID, and TIMESTAMP can't be selected
`target_column`	String	Optional	Popular item recommendation	Popular extract target columns USER_ID, ITEM_ID, and TIMESTAMP can't be selected Up to 100 can be entered
`max_group_recommend_top`	Long	Optional	Popular item recommendation	Maximum number of popular products per group 1 - 1000 (default: 100)

Request example

The following is a sample request.

curl --location --request POST 'https://aitems.apigw.ntruss.com/api/v1/services/xv94v******' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
    "types": [
        "personalRecommend"
    ],
    "description": "test",
    "hpConfig": {
        "is_enabled": false
    }
}'

Response

The following describes the response format.

Response body

The following describes the response body.

Field	Type	Required	Description
`serviceId`	String	-	Service ID
`name`	String	-	Service name
`description`	String	-	Service description
`status`	String	-	Service status `scheduled` \| `scheduledLearning` \| `learnable` \| `learning` \| `deleting` \| `deleted` \| `disable` \| `drafted` \| `requestLearning` \| `datasetRequired` `scheduled`: scheduled `scheduledLearning`: scheduled training in progress `learnable`: trainable `learning`: training in progress `deleting`: deleting `deleted`: deleted `disable`: training unavailable `drafted`: draft status `requestLearning`: training requested `datasetRequired`: no dataset specified after service creation
`datasets`	Array	-	Information of dataset set to service
`hpConfig`	Object	-	Hyperparameter optimization (HPO) settings information
`hpConfig.is_enabled`	Boolean	-	HPO configuration status `true` \| `false` `true`: HPO configured, optimal training models can be implemented `false`: HPO not configured, trained by AiTEMS' own internal algorithms
`hpConfig.{option}`	String, Long, Boolean	-	Configured HPO value See HPO for value details
`infers`	Array	-	Training result information Displayed only if `type` is `interval`
`createdDate`	String	-	Service creation date and time
`updatedDate`	String	-	Last update date and time of the service
`type`	String	-	Service type `batch` \| `interval` `batch`: one-time training upon execution `interval`: Retrain at regular intervals after execution
`learningInterval`	String	-	Dataset update cycle
`scheduledDate`	String	-	Dataset update scheduling time

`datasets`

The following describes datasets.

Field	Type	Required	Description
`datasetId`	String	-	Dataset ID set to the service
`type`	String	-	Dataset type set to the service `personalRecommend` \| `relatedItem` \| `pop` `personalRecommend`: personalized recommendations based on customer service users' past history `relatedItem`: personalized recommendations based on an item's association history `pop`: top item recommendations by rank
`name`	String	-	Dataset name set to the service
`schemaName`	String	-	Dataset schema name set to the service
`status`	String	-	Status of dataset set to the service `learnable` \| `disable` \| `uploading` \| `updateRequired` `learnable`: training available `disable`: training unavailable `uploading`: uploading `updatedRequired`: updated dataset registration required (automatically registered when training)
`createdDate`	String	-	Creation date and time of dataset set to the service
`updatedDate`	String	-	Last update date and time of dataset set to the service

`infers`

The following describes infers.

Field	Type	Required	Description
`dataType`	String	-	Dataset type of the training result `personalRecommend` \| `relatedItem` \| `pop` `personalRecommend`: personalized recommendations based on customer service users' past history `relatedItem`: personalized recommendations based on an item's association history `pop`: top item recommendations by rank
`trainVersion`	String	-	Training result version
`status`	String	-	Training result status `enable` \| `waiting` \| `pending` \| `processing` \| `updateFailed` \| `disable` `enable`: update available `waiting`: waiting for update `pending`: pending update `processing`: updating `updateFailed`: update failed `disable`: update unavailable
`rowCount`	String	-	Result data count
`createdDate`	String	-	Data creation date and time
`updatedDate`	String	-	Last update date and time of data

Response status codes

For response status codes common to all AiTEMS APIs, see Common AiTEMS API response status codes.

Response example

The following is a sample example.

{
    "serviceId": "xv94v******",
    "name": "service1",
    "description": "",
    "status": "learning",
    "datasets": [
        {
            "datasetId": "g8rf6******",
            "type": "item",
            "name": "item_dataset",
            "schemaName": "item_schema",
            "status": "learnable",
            "createdDate": "2024-07-29T16:46:35.968",
            "updatedDate": "2024-07-30T08:57:35.209"
        },
        {
            "datasetId": "bu457******",
            "type": "interaction",
            "name": "interaction_dataset",
            "schemaName": "interaction_schema",
            "status": "learnable",
            "createdDate": "2024-07-30T09:49:19.254",
            "updatedDate": "2024-07-30T09:49:35.364"
        },
        {
            "datasetId": "oeq4i******",
            "type": "user",
            "name": "user_dataset",
            "schemaName": "user_schema",
            "status": "learnable",
            "createdDate": "2024-07-30T08:58:00.662",
            "updatedDate": "2024-07-30T08:58:35.205"
        }
    ],
    "hpConfig": {
        "is_enabled": false
    },
    "infers": [],
    "createdDate": "2024-07-30T09:50:53.521",
    "updatedDate": "2024-07-30T10:32:00.492",
    "type": "batch"
}