Modell verwalten

Der Edge Manager-Agent kann mehrere Modelle gleichzeitig laden und Inferences mit geladene Modellen auf Edge-Geräten erstellen. Die Anzahl der Modelle, die der Agent laden kann, richtet sich nach dem auf dem Gerät verfügbaren Speicher. Der Agent validiert die Modellsignatur und lädt alle Artefakte in den Speicher, die durch den Edge-Paketerstellungsauftrag erzeugt wurden. Für diesen Schritt müssen alle in den obigen Schritten beschriebenen erforderlichen Zertifikate zusammen mit der übrigen Binärinstallation installiert werden. Wenn die Signatur des Modells nicht geprüft werden kann, schlägt das Laden des Modells mit dem entsprechenden Rückgabecode und der entsprechenden Begründung fehl.

SageMaker Der Edge Manager-Agent stellt eine Liste von Model Management-APIs bereit, die APIs für die Steuerungsebene und die Datenebene auf Edge-Geräten implementieren. Wir empfehlen, zusammen mit dieser Dokumentation auch die Beispiel-Client-Implementierung durchzugehen, die die kanonische Verwendung der unten beschriebenen APIs zeigt.

Die proto Datei steht als Teil der Release-Artefakte (im Release-Tarball) zur Verfügung. In diesem Dokument wird die Verwendung der in dieser proto Datei aufgeführten APIs aufgeführt und beschrieben.

Anmerkung

In der Windows-Version gibt es eine one-to-one Zuordnung für diese APIs, und ein Beispielcode für eine in C# implementierte Anwendung wird mit den Release-Artefakten für Windows gemeinsam genutzt. Die folgenden Anweisungen beziehen sich auf die Ausführung des Agenten als eigenständigen Prozess und gelten für die Release-Artefakte für Linux.

Extrahieren Sie das Archiv je nach Ihrem Ihres Betriebssystem. Wobei VERSION in drei Komponenten aufgeteilt ist: <MAJOR_VERSION>.<YYYY-MM-DD>-<SHA-7>. Informationen dazu, wie Sie die Release-Version (<MAJOR_VERSION>), den Zeitstempel des Release-Artefakts (<YYYY-MM-DD>) und die Commit-ID (SHA-7) des Repositorys erhalten können, finden Sie unter Installation des Edge Manager-Agenten

Linux

Das ZIP-Archiv kann mit dem folgenden Befehl extrahiert werden:

tar -xvzf <VERSION>.tgz

Windows

Das Zip-Archiv kann mit Hilfe der Benutzeroberfläche oder mit dem folgenden Befehl extrahiert werden:

unzip <VERSION>.tgz

Die Hierarchie der Release-Artefakte (nach Extrahieren des tar/zip Archivs) ist weiter unten dargestellt. Die proto Agentendatei steht unter api/ zur Verfügung.

0.20201205.7ee4b0b
├── bin
│         ├── sagemaker_edge_agent_binary
│         └── sagemaker_edge_agent_client_example
└── docs
├── api
│         └── agent.proto
├── attributions
│         ├── agent.txt
│         └── core.txt
└── examples
└── ipc_example
├── CMakeLists.txt
├── sagemaker_edge_client.cc
├── sagemaker_edge_client_example.cc
├── sagemaker_edge_client.hh
├── sagemaker_edge.proto
├── README.md
├── shm.cc
├── shm.hh
└── street_small.bmp

Modell laden

Der Edge Manager-Agent unterstützt das Laden mehrerer Modelle. Diese API validiert die Modellsignatur und lädt alle durch den EdgePackagingJob-Vorgang erzeugten Artefakte in den Speicher. Für diesen Schritt müssen alle erforderlichen Zertifikate zusammen mit der restlichen Binärinstallation des Agenten installiert werden. Wenn die Signatur des Modells nicht geprüft werden kann, schlägt dieser Schritt fehl und es werden entsprechende Rückgabecodes und Fehlermeldungen im Protokoll angezeigt.

// perform load for a model
// Note:
// 1. currently only local filesystem paths are supported for loading models.
// 2. multiple models can be loaded at the same time, as limited by available device memory
// 3. users are required to unload any loaded model to load another model.
// Status Codes:
// 1. OK - load is successful
// 2. UNKNOWN - unknown error has occurred
// 3. INTERNAL - an internal error has occurred
// 4. NOT_FOUND - model doesn't exist at the url
// 5. ALREADY_EXISTS - model with the same name is already loaded
// 6. RESOURCE_EXHAUSTED - memory is not available to load the model
// 7. FAILED_PRECONDITION - model is not compiled for the machine.
//
rpc LoadModel(LoadModelRequest) returns (LoadModelResponse);

Input

//
// request for LoadModel rpc call
//
message LoadModelRequest {
  string url = 1;
  string name = 2;  // Model name needs to match regex "^[a-zA-Z0-9](-*[a-zA-Z0-9])*$"
}

Output

//
//
// response for LoadModel rpc call
//
message LoadModelResponse {
  Model model = 1;
}

//
// Model represents the metadata of a model
//  url - url representing the path of the model
//  name - name of model
//  input_tensor_metadatas - TensorMetadata array for the input tensors
//  output_tensor_metadatas - TensorMetadata array for the output tensors
//
// Note:
//  1. input and output tensor metadata could empty for dynamic models.
//
message Model {
  string url = 1;
  string name = 2;
  repeated TensorMetadata input_tensor_metadatas = 3;
  repeated TensorMetadata output_tensor_metadatas = 4;
}

Modell entladen

Entlädt ein zuvor geladenes Modell. Dieses wird über das Modell-Alias identifiziert, der während loadModel angegeben wurde. Wenn das Alias nicht gefunden wird oder das Modell nicht geladen ist, wird ein Fehler zurückgegeben.

//
// perform unload for a model
// Status Codes:
// 1. OK - unload is successful
// 2. UNKNOWN - unknown error has occurred
// 3. INTERNAL - an internal error has occurred
// 4. NOT_FOUND - model doesn't exist
//
rpc UnLoadModel(UnLoadModelRequest) returns (UnLoadModelResponse);

Input

//
// request for UnLoadModel rpc call
//
message UnLoadModelRequest {
 string name = 1; // Model name needs to match regex "^[a-zA-Z0-9](-*[a-zA-Z0-9])*$"
}

Output

//
// response for UnLoadModel rpc call
//
message UnLoadModelResponse {}

Modelle auflisten

Listet alle geladenen Modelle mit ihren Aliasen auf.

//
// lists the loaded models
// Status Codes:
// 1. OK - unload is successful
// 2. UNKNOWN - unknown error has occurred
// 3. INTERNAL - an internal error has occurred
//
rpc ListModels(ListModelsRequest) returns (ListModelsResponse);

Input

//
// request for ListModels rpc call
//
message ListModelsRequest {}

Output

//
// response for ListModels rpc call
//
message ListModelsResponse {
 repeated Model models = 1;
}

Modell beschreiben

Beschreibt ein Modell, das auf den Agenten geladen wird.

//
// Status Codes:
// 1. OK - load is successful
// 2. UNKNOWN - unknown error has occurred
// 3. INTERNAL - an internal error has occurred
// 4. NOT_FOUND - model doesn't exist at the url
//
rpc DescribeModel(DescribeModelRequest) returns (DescribeModelResponse);

Input

//
// request for DescribeModel rpc call
//
message DescribeModelRequest {
  string name = 1;
}

Output

//
// response for DescribeModel rpc call
//
message DescribeModelResponse {
  Model model = 1;
}

Erfassen von Daten

Hiermit kann die Client-Anwendung Eingabe- und Ausgabetensoren im Amazon-S3-Bucket und optional den Hilfstensor erfassen. Es wird erwartet, dass die Client-Anwendung bei jedem Aufruf dieser API eine eindeutige Erfassungs-ID übergibt. Hiermit kann später der Status der erfassten Daten abgefragt werden.

//
// allows users to capture input and output tensors along with auxiliary data.
// Status Codes:
// 1. OK - data capture successfully initiated
// 2. UNKNOWN - unknown error has occurred
// 3. INTERNAL - an internal error has occurred
// 5. ALREADY_EXISTS - capture initiated for the given capture_id
// 6. RESOURCE_EXHAUSTED - buffer is full cannot accept any more requests.
// 7. OUT_OF_RANGE - timestamp is in the future.
// 8. INVALID_ARGUMENT - capture_id is not of expected format.
//
rpc CaptureData(CaptureDataRequest) returns (CaptureDataResponse);

Input

enum Encoding {
 CSV = 0;
 JSON = 1;
 NONE = 2;
 BASE64 = 3;
}

//
// AuxilaryData represents a payload of extra data to be capture along with inputs and outputs of inference
// encoding - supports the encoding of the data
// data - represents the data of shared memory, this could be passed in two ways:
// a. send across the raw bytes of the multi-dimensional tensor array
// b. send a SharedMemoryHandle which contains the posix shared memory segment id and
// offset in bytes to location of multi-dimensional tensor array.
//
message AuxilaryData {
 string name = 1;
 Encoding encoding = 2;
 oneof data {
 bytes byte_data = 3;
 SharedMemoryHandle shared_memory_handle = 4;
 }
}

//
// Tensor represents a tensor, encoded as contiguous multi-dimensional array.
// tensor_metadata - represents metadata of the shared memory segment
// data_or_handle - represents the data of shared memory, this could be passed in two ways:
// a. send across the raw bytes of the multi-dimensional tensor array
// b. send a SharedMemoryHandle which contains the posix shared memory segment
// id and offset in bytes to location of multi-dimensional tensor array.
//
message Tensor {
 TensorMetadata tensor_metadata = 1; //optional in the predict request
 oneof data {
 bytes byte_data = 4;
 // will only be used for input tensors
 SharedMemoryHandle shared_memory_handle = 5;
 }
}

//
// request for CaptureData rpc call
//
message CaptureDataRequest {
 string model_name = 1;
 string capture_id = 2; //uuid string
 Timestamp inference_timestamp = 3;
 repeated Tensor input_tensors = 4;
 repeated Tensor output_tensors = 5;
 repeated AuxilaryData inputs = 6;
 repeated AuxilaryData outputs = 7;
}

Output

//
// response for CaptureData rpc call
//
message CaptureDataResponse {}

Erfassungsstatus abrufen

Je nach den geladenen Modellen können die Eingangs- und Ausgangstensoren groß sein (für viele Edge-Geräte). Die Erfassung in der Cloud kann zeitaufwändig sein. Daher wird die CaptureData() als asynchrone Operation implementiert. Eine Erfassungs-ID ist eine eindeutige Kennung, die der Client beim Aufrufen der erfassten Daten bereitstellt. Anhand dieser ID kann der Status des asynchronen Aufrufs abgefragt werden.

//
// allows users to query status of capture data operation
// Status Codes:
// 1. OK - data capture successfully initiated
// 2. UNKNOWN - unknown error has occurred
// 3. INTERNAL - an internal error has occurred
// 4. NOT_FOUND - given capture id doesn't exist.
//
rpc GetCaptureDataStatus(GetCaptureDataStatusRequest) returns (GetCaptureDataStatusResponse);

Input

//
// request for GetCaptureDataStatus rpc call
//
message GetCaptureDataStatusRequest {
  string capture_id = 1;
}

Output

enum CaptureDataStatus {
  FAILURE = 0;
  SUCCESS = 1;
  IN_PROGRESS = 2;
  NOT_FOUND = 3;
}

//
// response for GetCaptureDataStatus rpc call
//
message GetCaptureDataStatusResponse {
  CaptureDataStatus status = 1;
}

Voraussagen

Die predict API nimmt Inferences auf einem zuvor geladenen Modell vor. Sie akzeptiert eine Anfrage in Form eines Tensors, der direkt in das neuronale Netzwerk eingespeist wird. Die Ausgabe ist der Ausgabetensor (oder Skalar) aus dem Modell. Das ist ein blockierender Aufruf.

//
// perform inference on a model.
//
// Note:
// 1. users can chose to send the tensor data in the protobuf message or
// through a shared memory segment on a per tensor basis, the Predict
// method with handle the decode transparently.
// 2. serializing large tensors into the protobuf message can be quite expensive,
// based on our measurements it is recommended to use shared memory of
// tenors larger than 256KB.
// 3. SMEdge IPC server will not use shared memory for returning output tensors,
// i.e., the output tensor data will always send in byte form encoded
// in the tensors of PredictResponse.
// 4. currently SMEdge IPC server cannot handle concurrent predict calls, all
// these call will be serialized under the hood. this shall be addressed
// in a later release.
// Status Codes:
// 1. OK - prediction is successful
// 2. UNKNOWN - unknown error has occurred
// 3. INTERNAL - an internal error has occurred
// 4. NOT_FOUND - when model not found
// 5. INVALID_ARGUMENT - when tenors types mismatch
//
rpc Predict(PredictRequest) returns (PredictResponse);

Input

// request for Predict rpc call
//
message PredictRequest {
string name = 1;
repeated Tensor tensors = 2;
}

//
// Tensor represents a tensor, encoded as contiguous multi-dimensional array.
//    tensor_metadata - represents metadata of the shared memory segment
//    data_or_handle - represents the data of shared memory, this could be passed in two ways:
//                        a. send across the raw bytes of the multi-dimensional tensor array
//                        b. send a SharedMemoryHandle which contains the posix shared memory segment
//                            id and offset in bytes to location of multi-dimensional tensor array.
//
message Tensor {
  TensorMetadata tensor_metadata = 1; //optional in the predict request
  oneof data {
    bytes byte_data = 4;
    // will only be used for input tensors
    SharedMemoryHandle shared_memory_handle = 5;
  }
}

//
// Tensor represents a tensor, encoded as contiguous multi-dimensional array.
//    tensor_metadata - represents metadata of the shared memory segment
//    data_or_handle - represents the data of shared memory, this could be passed in two ways:
//                        a. send across the raw bytes of the multi-dimensional tensor array
//                        b. send a SharedMemoryHandle which contains the posix shared memory segment
//                            id and offset in bytes to location of multi-dimensional tensor array.
//
message Tensor {
  TensorMetadata tensor_metadata = 1; //optional in the predict request
  oneof data {
    bytes byte_data = 4;
    // will only be used for input tensors
    SharedMemoryHandle shared_memory_handle = 5;
  }
}

//
// TensorMetadata represents the metadata for a tensor
//    name - name of the tensor
//    data_type  - data type of the tensor
//    shape - array of dimensions of the tensor
//
message TensorMetadata {
  string name = 1;
  DataType data_type = 2;
  repeated int32 shape = 3;
}

//
// SharedMemoryHandle represents a posix shared memory segment
//    offset - offset in bytes from the start of the shared memory segment.
//    segment_id - shared memory segment id corresponding to the posix shared memory segment.
//    size - size in bytes of shared memory segment to use from the offset position.
//
message SharedMemoryHandle {
  uint64 size = 1;
  uint64 offset = 2;
  uint64 segment_id = 3;
}

Output

Anmerkung

Der PredictResponse gibt lediglich Tensors zurück, und nicht SharedMemoryHandle.

// response for Predict rpc call
//
message PredictResponse {
   repeated Tensor tensors = 1;
}