管理 API ¶

TorchServe 提供以下 API，可讓您在運行時管理模型

註冊模型
增加/減少特定模型的 worker 數量
描述模型的狀態
取消註冊模型
列出已註冊的模型
設定模型的預設版本
刷新權杖以進行權杖授權

管理 API 在埠 8081 上監聽，預設情況下只能從 localhost 訪問。要更改預設設定，請參閱TorchServe 配置。

預設情況下，用於註冊和刪除模型的管理 API 已停用。運行 TorchServe 時，在命令列中添加 --enable-model-api 以啟用這些 API 的使用。有關更多詳細資訊和啟用方法，請參閱模型 API 控制

對於所有管理 API 請求，TorchServe 都需要包含正確的管理權杖，或者必須停用權杖授權。有關更多詳細資訊，請參閱權杖授權文檔

與推論 API 類似，管理 API 提供API 描述，以使用 OpenAPI 3.0 規範描述管理 API。

或者，如果您想使用 KServe，TorchServe 支援 v1 和 v2 API。有關更多詳細資訊，請查看此kserve 文檔

註冊模型¶

此 API 遵循 ManagementAPIsService.RegisterModel gRPC API。

在 TorchServe 啟動後使用此 API，必須啟用模型 API 控制。在啟動 TorchServe 時，在命令列中添加 --enable-model-api 以啟用此 API 的使用。有關更多詳細資訊，請參閱模型 API 控制

POST /models

url - 模型封存下載網址。支援以下位置
- 本機模型封存 (.mar)；該檔案必須位於 model_store 資料夾中（而不是子資料夾中）。
- 使用 HTTP(s) 協定的 URI。 TorchServe 可以從網際網路下載 .mar 檔案。
model_name - 模型的名稱；此名稱將在其他 API 中用作路徑的一部分的 {model_name}。如果此參數不存在，則將使用 MANIFEST.json 中的 modelName。
handler - 推論處理器進入點。如果 MANIFEST.json 中存在 handler，此值將覆蓋它。注意：請確保給定的 handler 在 PYTHONPATH 中。handler 的格式為 module_name:method_name。
runtime - 模型自訂服務程式碼的執行環境。如果 MANIFEST.json 中存在 runtime，此值將覆蓋它。預設值為 PYTHON。
batch_size - 推論批次大小。預設值為 1。
max_batch_delay - 批次聚合的最大延遲時間。預設值為 100 毫秒。
initial_workers - 要建立的初始 worker 數量。預設值為 0。在至少分配一個 worker 之前，TorchServe 將不會執行推論。
synchronous - worker 的建立是否為同步。預設值為 false。 TorchServe 將建立新的 worker，而無需等待先前 worker 上線的確認。
response_timeout - 如果模型的後端 worker 未在此逾時時間內回覆推論回應，則該 worker 將被視為沒有回應並重新啟動。單位為秒。預設值為 120 秒。
startup_timeout - 如果模型的後端 worker 未在此逾時時間內載入模型，則該 worker 將被視為沒有回應並重新啟動。單位為秒。預設值為 120 秒。

curl -X POST  "https://127.0.0.1:8081/models?url=https://torchserve.pytorch.org/mar_files/squeezenet1_1.mar"

{
  "status": "Model \"squeezenet_v1.1\" Version: 1.0 registered with 0 initial workers. Use scale workers API to add workers for the model."
}

加密模型服務¶

如果您想提供加密模型，則需要使用以下環境變數設定 S3 SSE-KMS

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION

並在 HTTP 請求中設定 "s3_sse_kms=true"。

例如：模型 squeezenet1_1 在您自己的私有帳戶下於 S3 上加密。S3 上的模型 http url 為 https://torchserve.pytorch.org/sse-test/squeezenet1_1.mar。

如果 torchserve 將在 EC2 實例上執行（例如：作業系統：ubuntu）

為 EC2 實例添加一個 IAM 角色 (AWSS3ReadOnlyAccess)
執行 ts_scripts/get_aws_credential.sh 以匯出 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY
export AWS_DEFAULT_REGION=your_s3_bucket_region
啟動 torchserve
透過在 curl 命令中設定 s3_sse_kms=true 來註冊加密模型 squeezenet1_1。

curl -X POST  "https://127.0.0.1:8081/models?url=https://torchserve.pytorch.org/sse-test/squeezenet1_1.mar&s3_sse_kms=true"

{
  "status": "Model \"squeezenet_v1.1\" Version: 1.0 registered with 0 initial workers. Use scale workers API to add workers for the model."
}

如果 torchserve 將在本地執行（例如：作業系統：macOS）

尋找您的 AWS 存取金鑰和密碼金鑰。如果您忘記了金鑰，可以重設它們。
export AWS_ACCESS_KEY_ID=your_aws_access_key
export AWS_SECRET_ACCESS_KEY=your_aws_secret_key
export AWS_DEFAULT_REGION=your_s3_bucket_region
啟動 torchserve
透過在 curl 命令中設定 s3_sse_kms=true 來註冊加密模型 squeezenet1_1（與 EC2 範例步驟 5 相同）。

您可能想在註冊期間建立 worker。由於建立初始 worker 可能需要一些時間，您可以選擇同步或非同步呼叫，以確保正確建立初始 worker。

非同步呼叫會在嘗試建立 worker 之前傳回 HTTP 代碼 202。

curl -v -X POST "https://127.0.0.1:8081/models?initial_workers=1&synchronous=false&url=https://torchserve.pytorch.org/mar_files/squeezenet1_1.mar"

< HTTP/1.1 202 Accepted
< content-type: application/json
< x-request-id: 4dc54158-c6de-42aa-b5dd-ebcb5f721043
< content-length: 47
< connection: keep-alive
<
{
  "status": "Processing worker updates..."
}

同步呼叫會在所有 worker 都已調整後傳回 HTTP 代碼 200。

curl -v -X POST "https://127.0.0.1:8081/models?initial_workers=1&synchronous=true&url=https://torchserve.pytorch.org/mar_files/squeezenet1_1.mar"

< HTTP/1.1 200 OK
< content-type: application/json
< x-request-id: ecd2e502-382f-4c3b-b425-519fbf6d3b85
< content-length: 89
< connection: keep-alive
<
{
  "status": "Model \"squeezenet1_1\" Version: 1.0 registered with 1 initial workers"
}

擴展 worker¶

此 API 遵循 ManagementAPIsService.ScaleWorker gRPC API。它傳回 ModelServer 中模型的狀態。

PUT /models/{model_name}

min_worker - （可選）最小 worker 處理程序數量。 TorchServe 將嘗試為指定的模型維持此最小值。預設值為 1。
max_worker - （可選）最大 worker 處理程序數量。 TorchServe 將為指定的模型建立不超過此數量的 worker。預設值與 min_worker 的設定相同。
synchronous - 呼叫是否為同步。預設值為 false。
timeout - worker 完成所有待處理請求的指定等待時間。如果超過，則將終止 work 處理程序。使用 0 立即終止後端 worker 處理程序。使用 -1 無限期等待。預設值為 -1。

使用 Scale Worker API 來動態調整任何版本的模型的 worker 數量，以更好地服務於不同的推論請求負載。

此 API 有兩種不同的形式：同步和非同步。

非同步呼叫將立即傳回 HTTP 代碼 202

curl -v -X PUT "https://127.0.0.1:8081/models/noop?min_worker=3"

< HTTP/1.1 202 Accepted
< content-type: application/json
< x-request-id: 42adc58e-6956-4198-ad07-db6c620c4c1e
< content-length: 47
< connection: keep-alive
<
{
  "status": "Processing worker updates..."
}

同步呼叫會在所有 worker 都已調整後傳回 HTTP 代碼 200。

curl -v -X PUT "https://127.0.0.1:8081/models/noop?min_worker=3&synchronous=true"

< HTTP/1.1 200 OK
< content-type: application/json
< x-request-id: b72b1ea0-81c6-4cce-92c4-530d3cfe5d4a
< content-length: 63
< connection: keep-alive
<
{
  "status": "Workers scaled to 3 for model: noop"
}

要擴展特定版本的模型的 worker，請使用 URI : /models/{model_name}/{version} PUT /models/{model_name}/{version}

以下同步呼叫將在模型 "noop" 的版本 "2.0" 的所有 worker 都已調整後傳回，並帶有 HTTP 代碼 200。

curl -v -X PUT "https://127.0.0.1:8081/models/noop/2.0?min_worker=3&synchronous=true"

< HTTP/1.1 200 OK
< content-type: application/json
< x-request-id: 3997ccd4-ae44-4570-b249-e361b08d3d47
< content-length: 77
< connection: keep-alive
<
{
  "status": "Workers scaled to 3 for model: noop, version: 2.0"
}

描述模型¶

此 API 遵循 ManagementAPIsService.DescribeModel gRPC API。它傳回 ModelServer 中模型的狀態。

GET /models/{model_name}

使用 Describe Model API 取得模型預設版本的詳細執行階段狀態

curl https://127.0.0.1:8081/models/noop
[
    {
      "modelName": "noop",
      "modelVersion": "1.0",
      "modelUrl": "noop.mar",
      "engine": "Torch",
      "runtime": "python",
      "minWorkers": 1,
      "maxWorkers": 1,
      "batchSize": 1,
      "maxBatchDelay": 100,
      "workers": [
        {
          "id": "9000",
          "startTime": "2018-10-02T13:44:53.034Z",
          "status": "READY",
          "gpu": false,
          "memoryUsage": 89247744
        }
      ],
      "jobQueueStatus": {
        "remainingCapacity": 100,
        "pendingRequests": 0
      }
    }
]

GET /models/{model_name}/{version}

使用 Describe Model API 取得模型特定版本的詳細執行階段狀態

curl https://127.0.0.1:8081/models/noop/2.0
[
    {
      "modelName": "noop",
      "modelVersion": "2.0",
      "modelUrl": "noop_2.mar",
      "engine": "Torch",
      "runtime": "python",
      "minWorkers": 1,
      "maxWorkers": 1,
      "batchSize": 1,
      "maxBatchDelay": 100,
      "workers": [
        {
          "id": "9000",
          "startTime": "2018-10-02T13:44:53.034Z",
          "status": "READY",
          "gpu": false,
          "memoryUsage": 89247744
        }
      ],
      "jobQueueStatus": {
        "remainingCapacity": 100,
        "pendingRequests": 0
      }
    }
]

GET /models/{model_name}/all

使用 Describe Model API 取得模型所有版本的詳細執行階段狀態

curl https://127.0.0.1:8081/models/noop/all
[
    {
      "modelName": "noop",
      "modelVersion": "1.0",
      "modelUrl": "noop.mar",
      "engine": "Torch",
      "runtime": "python",
      "minWorkers": 1,
      "maxWorkers": 1,
      "batchSize": 1,
      "maxBatchDelay": 100,
      "workers": [
        {
          "id": "9000",
          "startTime": "2018-10-02T13:44:53.034Z",
          "status": "READY",
          "gpu": false,
          "memoryUsage": 89247744
        }
      ],
      "jobQueueStatus": {
        "remainingCapacity": 100,
        "pendingRequests": 0
      }
    },
    {
      "modelName": "noop",
      "modelVersion": "2.0",
      "modelUrl": "noop_2.mar",
      "engine": "Torch",
      "runtime": "python",
      "minWorkers": 1,
      "maxWorkers": 1,
      "batchSize": 1,
      "maxBatchDelay": 100,
      "workers": [
        {
          "id": "9000",
          "startTime": "2018-10-02T13:44:53.034Z",
          "status": "READY",
          "gpu": false,
          "memoryUsage": 89247744
        }
      ],
      "jobQueueStatus": {
        "remainingCapacity": 100,
        "pendingRequests": 0
      }
    }
]

GET /models/{model_name}/{model_version}?customized=true 或 GET /models/{model_name}?customized=true

使用 Describe Model API 取得模型某個版本的詳細執行階段狀態和自訂元數據

實作函式 describe_handle。例如：

    def describe_handle(self):
        """Customized describe handler
        Returns:
            dict : A dictionary response.
        """
        output_describe = None

        logger.info("Collect customized metadata")

        return output_describe

如果 handler 不是繼承自 BaseHandler，則實作函式 _is_describe。然後，在 handle 中呼叫 _is_describe 和 describe_handle。

    def _is_describe(self):
        if self.context and self.context.get_request_header(0, "describe"):
            if self.context.get_request_header(0, "describe") == "True":
                return True
        return False

    def handle(self, data, context):
        if self._is_describe():
            output = [self.describe_handle()]
        else:
            data_preprocess = self.preprocess(data)

            if not self._is_explain():
                output = self.inference(data_preprocess)
                output = self.postprocess(output)
            else:
                output = self.explain_handle(data_preprocess, data)

        return output

在 handle 中呼叫函式 _is_describe 和 describe_handle。例如：

def handle(self, data, context):
        """Entry point for default handler. It takes the data from the input request and returns
           the predicted outcome for the input.
        Args:
            data (list): The input data that needs to be made a prediction request on.
            context (Context): It is a JSON Object containing information pertaining to
                               the model artifacts parameters.
        Returns:
            list : Returns a list of dictionary with the predicted response.
        """

        # It can be used for pre or post processing if needed as additional request
        # information is available in context
        start_time = time.time()

        self.context = context
        metrics = self.context.metrics

        is_profiler_enabled = os.environ.get("ENABLE_TORCH_PROFILER", None)
        if is_profiler_enabled:
            output, _ = self._infer_with_profiler(data=data)
        else:
            if self._is_describe():
                output = [self.describe_handle()]
            else:
                data_preprocess = self.preprocess(data)

                if not self._is_explain():
                    output = self.inference(data_preprocess)
                    output = self.postprocess(output)
                else:
                    output = self.explain_handle(data_preprocess, data)

        stop_time = time.time()
        metrics.add_time('HandlerTime', round(
            (stop_time - start_time) * 1000, 2), None, 'ms')
        return output

這是一個範例。"customizedMetadata" 顯示來自使用者模型的元數據。這些元數據可以解碼為字典。

curl https://127.0.0.1:8081/models/noop-customized/1.0?customized=true
[
    {
        "modelName": "noop-customized",
        "modelVersion": "1.0",
        "modelUrl": "noop-customized.mar",
        "runtime": "python",
        "minWorkers": 1,
        "maxWorkers": 1,
        "batchSize": 1,
        "maxBatchDelay": 100,
        "loadedAtStartup": false,
        "workers": [
          {
            "id": "9010",
            "startTime": "2022-02-08T11:03:20.974Z",
            "status": "READY",
            "memoryUsage": 0,
            "pid": 98972,
            "gpu": false,
            "gpuUsage": "N/A"
          }
        ],
        "jobQueueStatus": {
          "remainingCapacity": 100,
          "pendingRequests": 0
        },
        "customizedMetadata": "{\n  \"data1\": \"1\",\n  \"data2\": \"2\"\n}"
     }
]

在客戶端解碼 customizedMetadata。例如

import requests
import json

response = requests.get('https://127.0.0.1:8081/models/noop-customized/?customized=true').json()
customizedMetadata = response[0]['customizedMetadata']
print(customizedMetadata)

取消註冊模型¶

此 API 遵循 ManagementAPIsService.UnregisterModel gRPC API。它傳回 ModelServer 中模型的狀態。

在 TorchServe 啟動後使用此 API，必須啟用模型 API 控制。在啟動 TorchServe 時，在命令列中添加 --enable-model-api 以啟用此 API 的使用。有關更多詳細資訊，請參閱模型 API 控制

DELETE /models/{model_name}/{version}

使用取消註冊模型 API，透過從 TorchServe 取消註冊模型的特定版本來釋放系統資源。

curl -X DELETE https://127.0.0.1:8081/models/noop/1.0

{
  "status": "Model \"noop\" unregistered"
}

列出模型¶

此 API 遵循 ManagementAPIsService.ListModels gRPC API。它會傳回 ModelServer 中模型的狀態。

GET /models

limit - (選用) 要傳回的最大項目數。它會以查詢參數傳遞。預設值為 100。
next_page_token - (選用) 查詢下一頁。它會以查詢參數傳遞。此值由先前的 API 呼叫傳回。

使用 Models API 來查詢目前已註冊模型的預設版本

curl "https://127.0.0.1:8081/models"

此 API 支援分頁

curl "https://127.0.0.1:8081/models?limit=2&next_page_token=2"

{
  "nextPageToken": "4",
  "models": [
    {
      "modelName": "noop",
      "modelUrl": "noop-v1.0"
    },
    {
      "modelName": "noop_v0.1",
      "modelUrl": "noop-v0.1"
    }
  ]
}

API 說明¶

OPTIONS /

若要檢視完整的推論和管理 API 清單，您可以使用以下命令

# To view all inference APIs:
curl -X OPTIONS https://127.0.0.1:8080

# To view all management APIs:
curl -X OPTIONS https://127.0.0.1:8081

輸出為 OpenAPI 3.0.1 JSON 格式。您可以使用它來產生客戶端程式碼，詳情請參閱 swagger codegen。

推論和管理 API 的範例輸出

設定預設版本¶

此 API 遵循 ManagementAPIsService.SetDefault gRPC API。它會傳回 ModelServer 中模型的狀態。

PUT /models/{model_name}/{version}/set-default

若要將模型的任何已註冊版本設定為預設版本，請使用

curl -v -X PUT https://127.0.0.1:8081/models/noop/2.0/set-default

輸出為 OpenAPI 3.0.1 JSON 格式。您可以使用它來產生客戶端程式碼，詳情請參閱 swagger codegen。

Token 授權 API¶

TorchServe 現在預設強制執行 Token 授權。有關更多資訊，請查看以下文件： Token Authorization。

此 API 用於產生一個新的金鑰，以替換管理或推論金鑰。

管理範例

curl localhost:8081/token?type=management -H "Authorization: Bearer {API Token}"

將使用一個新的金鑰替換 key_file 中的目前管理金鑰，並且會更新到期時間。

推論範例

curl localhost:8081/token?type=inference -H "Authorization: Bearer {API Token}"

將使用一個新的金鑰替換 key_file 中的目前推論金鑰，並且會更新到期時間。

管理 API¶