系統結構定義

每個中繼資料資源都會與特定 MetadataSchema 建立關聯。為簡化中繼資料資源建立程序，Vertex 機器學習中繼資料會發布預先定義的類型 (稱為系統結構定義)，用於常見的機器學習概念。系統結構定義位於 system 命名空間下。您可以在 Vertex 機器學習中繼資料 API 中，以 MetadataSchema 資源的形式存取系統結構定義。結構定義一律會加上版本。系統結構定義的格式是 OpenAPI 3.0 規格的子集。

如何使用系統結構定義

Vertex AI 會使用系統結構定義建立中繼資料資源，追蹤您的機器學習工作流程。然後，您可以使用 schema_title 欄位，在後續的中繼資料查詢中篩選及分組資源。如要進一步瞭解如何使用篩選函式，請參閱分析 Vertex 機器學習中繼資料。

您也可以透過 Vertex 機器學習中繼資料 API 使用系統結構定義，直接建立中繼資料資源。您可以根據結構定義標題和結構定義版本，判斷是否為系統結構定義。系統結構定義中的欄位一律視為選填。您不限於系統結構定義的預先定義欄位，也可以將任意中繼資料記錄至任何中繼資料資源。如要進一步瞭解如何使用系統結構定義建立中繼資料資源，請參閱「追蹤 Vertex 機器學習中繼資料」。

列出結構定義

如要查看所有現有已註冊結構定義的清單，請使用下列指令。

REST

使用任何要求資料之前，請先替換以下項目：

  • LOCATION_ID：您的區域。
  • PROJECT_ID：您的專案 ID。

HTTP 方法和網址：

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/metadataSchemas?pageSize=100&filter=schema_title=%22system*%22+OR+schema_title=%22google*%22

如要傳送要求，請展開以下其中一個選項：

您應該會收到如下的 JSON 回應：

{
  "metadataSchemas": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/metadataSchemas/system-resolver-execution-v0-0-1",
      "schemaVersion": "0.0.1",
      "schema": "title: system.ResolverExecution\ntype: object\n",
      "schemaType": "EXECUTION_TYPE",
      "createTime": "2022-07-27T17:41:35.634Z"
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID//metadataStores/default/metadataSchemas/system-html-v0-0-1",
      "schemaVersion": "0.0.1",
      "schema": "title: system.HTML\ntype: object\n",
      "schemaType": "ARTIFACT_TYPE",
      "createTime": "2022-07-27T17:41:35.602Z"
    }
}

嚴格比對結構定義

Vertex 機器學習中繼資料支援兩個標記，可供結構定義作者強制執行嚴格的結構定義比對。

additionalProperties

additionalProperties 值可以是 true 或 false。與 JSON 結構定義一致，additionalProperties 預設為 true。這個標記是在架構的頂層設定。如果設為 false，則不允許任何選用屬性。舉例來說，在下方結構定義中，根據這個結構定義，只有 payload_format 和 container_format 欄位會納入中繼資料。

title: system.Dataset
version: 0.0.1
type: object
additionalProperties: false
properties:
  container_format:
    type: string
  payload_format:
    type: string

上述結構定義接受下列中繼資料：

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}
fields {
  key: 'payload_format'
  value: { string_value: 'CSV' }
}

但系統會拒絕下列中繼資料：

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}
fields {
  key: 'payload_format'
  value: { string_value: 'CSV' }
}
fields {
  key: 'optional_field'
  value: { string_value: 'optional_value' }
}

required

required 關鍵字會採用零或多個字串的陣列。與 JSON 結構定義一致，由屬性關鍵字定義的屬性並非必要。您可以使用 required 關鍵字提供必要屬性清單。舉例來說，下列結構定義一律需要 container_format。也適用於巢狀屬性。舉例來說，下列項目會讓 container_format 成為必要項目。

title: system.Dataset
version: 0.0.1
type: object
required: ['container_format']
properties:
  container_format:
    type: string
  payload_format:
    type: string

上述結構定義接受下列中繼資料：

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}

但系統會拒絕下列中繼資料：

fields {
  key: 'payload_format'
  value: { string_value: 'CSV' }
}

結構定義支援巢狀屬性，其中屬性具有物件類型的欄位。在巢狀結構架構中，巢狀結構屬性節點可以有 required 關鍵字。例如：

title: system.Dataset
version: 0.0.1
type: object
properties:
  container_format:
    type: string
  payload:
    type: string
  nested_property:
    type: object
    required: ['property_1']
    properties:
      property_1:
        type: integer
      property_2:
        type: integer

由於 nested_property 欄位本身並非必要，因此上述結構定義接受下列中繼資料。

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}

下列中繼資料也有效。

fields {
  key: 'nested_property'
  value: {
    struct_value {
      fields {
        key: 'property_1'
        value: { number_value: 1 }
      }
      fields {
        key: 'property_2'
        value: { number_value: 1 }
      }
    }
  }
}

但系統會拒絕下列中繼資料：

fields {
  key: 'nested_property'
  value: {
    struct_value {
      fields {
        key: 'property_2'
        value: { number_value: 1 }
      }
    }
  }
}

系統結構定義範例

以下範例是常見的系統結構定義，可立即使用。

構件

system.Artifact 是通用結構定義，可保存任何構件的中繼資料。這個結構定義未定義任何特定欄位。

title: system.Artifact
version: 0.0.1
type: object

資料集

system.Dataset 代表機器學習工作流程步驟耗用或產生的資料容器。資料集可以指向檔案位置或查詢，例如 BigQuery URI。

title: system.Dataset
version: 0.0.1
type: object
properties:
  container_format:
    type: string
    description: "Format of the container. Examples include 'TFRecord', 'Text', or 'Parquet'."
  payload_format:
    type: string
   description: "Format of the payload. For example, 'proto:TFExample', 'CSV', or 'JSON'."

型號

system.Model 代表訓練好的模型。模型 URI 可以指向檔案位置 (PPP、Cloud Storage bucket、本機磁碟機)，也可以指向 API 資源，例如 Vertex AI API 中的模型資源。

title: system.Model
version: 0.0.1
type: object
properties:
  framework:
    type: string
    description: "The framework type. For example: 'TensorFlow' or 'Scikit-Learn'."
  framework_version:
    type: string
    description: "The framework version. For example: '1.15' or '2.1'."
  payload_format:
    type: string
    description: "The format of the Model payload, for example: 'SavedModel' or 'TFLite'."

指標

system.Metrics 代表機器學習工作流程期間產生的評估指標。指標取決於應用程式和用途，可以是簡單的純量指標 (例如準確度)，也可以是儲存在系統其他位置的複雜指標。

title: system.Metrics
version: 0.0.1
type: object
properties:
  type:
  accuracy:
    type: number
    description: "Optional summary metric describing accuracy of a model."
  precision:
    type: number
    description: "Optional summary metric describing precision of a model."
  recall:
    type: number
    description: "Optional summary metric describing the recall of a model."
  f1score:
    type: number
    description: "Optional summary metric describing the f1-score of a model."
  mean_absolute_error:
    type: number
    description: "Optional summary metric describing the mean absolute error of a model."
  mean_squared_error:
    type: number
    description: "Optional summary metric describing the mean-squared error of a model."

後續步驟