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 AiTEMS request headers.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`serviceId`	String	Required	Service ID See 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: datasets
`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: infers 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 AiTEMS 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"
}