API for Specifying an Instance Role v1

Function

Specifies an instance role.

Format

Operation type: POST

URL: https://{ip}:{port}/v1/role/{role}

The {ip} field prioritizes reading the environment variable MIES_CONTAINER_MANAGEMENT_IP. If the environment variable does not exist, managementIpAddress in the configuration file is used. If managementIpAddress does not exist in the configuration file, ipAddress in the configuration file is used.
The {port} field prioritizes reading the managementPort parameter in the configuration file. If the configuration file does not contain the managementPort parameter, the port parameter in the configuration file is used.

Request Parameters

**Table 1** URL field description
Field	Mandatory/Optional	Type	Description
role	Mandatory	String	Specifies an instance role. Possible values: prefill decode

**Table 2** Body field description
Field	Mandatory/Optional	Type	Description
local	Mandatory	Structure	Instance information.
local.server_ip	Mandatory	String	IP address of the local node.
local.device	Mandatory	Structure array	NPU information of the local node. Multiple NPUs may exist.
local.device[].device_logical_id	Mandatory	Integer string	Logical ID of an NPU.
local.device[].device_ip	Mandatory	String	IP address of an NPU.
peers	Optional	Structure array	List of objects to be connected. Each instance sees only the instances related to itself. For a decode instance, it corresponds to a prefill instance that needs to be connected. For a prefill instance, it corresponds to a decode instance that needs to be connected.
peers[].server_ip	Optional	String	IP address of the peer node.
peers[].device	Optional	Structure array	NPU information of the peer node. Multiple NPUs may exist. The number of NPUs must be the same as that of NPUs on the local node.
peers[].device[].device_logical_id	Optional	Integer string	Logical ID of an NPU.
peers[].device[].device_ip	Optional	String	IP address of an NPU.

Usage Example

Request example:

POST https://{ip}:{port}/v1/role/prefill

Request body:

{
  "local": {
    "server_ip": "1.2.3.4",
    "device": [{
        "device_ip": "xxx.xxx.xxx.xxx",
        "device_logical_id": "0"
      },
      {
        "device_ip": "xxx.xxx.xxx.xxx",
        "device_logical_id": "1"
      }
    ]
  },
  "peers": [{
    "server_ip": "5.6.7.8",
    "device": [{
        "device_ip": "xxx.xxx.xxx.xxx",
        "device_logical_id": "0"
      },
      {
        "device_ip": "xxx.xxx.xxx.xxx",
        "device_logical_id": "0"
      }
    ]
  }]
}

Response example:

Success
```
{
    "result": "OK"
}
```

Failure

{
"error": "xxx",
"error_type": "xxxxx"
}

Response status code:

200: success
400: request error
422: The request body does not meet the specifications.

Output Description

Field	Type	Description
result	String	Success.
error	String	Error message.
error_type	String	Error type.

Parent topic: Prefill-Decode Disaggregation APIs