创建和更新数据架构

已部署的数据提取应用中关联的 Vision Warehouse (corpus) 具有一个或多个媒体对象 assets。您可以使用 dataSchema 和用户提供的 annotation 资源，详细说明这些媒体对象 assets。

您需要先创建数据架构资源，然后才能创建包含该数据架构键的 annotation 资源。创建数据架构（dataSchema 资源）以告知 Vertex AI Vision API 如何解读媒体注释后，您就可以在仓库中为媒体创建 annotation 资源。

创建数据架构 (API)

REST

在使用任何请求数据之前，请先进行以下替换：

  • REGIONALIZED_ENDPOINT：端点可能包含与 LOCATION_ID 匹配的前缀，例如 europe-west4-。详细了解 区域级端点。
  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • LOCATION_ID：您在其中使用 Vertex AI Vision 的区域。例如：us-central1、europe-west4。请参阅可用区域。
  • CORPUS_ID：目标语料库的 ID。
  • DATASCHEMA_KEY：此键必须与用户指定的注释的键匹配，并且在 corpus 中是唯一的。例如 data-key。
  • ANNOTATION_DATA_TYPE：注释的数据类型。可用的值包括：
    • DATA_TYPE_UNSPECIFIED
    • INTEGER
    • FLOAT
    • STRING
    • DATETIME
    • GEO_COORDINATE
    • PROTO_ANY
    • BOOLEAN

    如需了解详情，请参阅 API 参考文档。

  • ANNOTATION_GRANULARITY：此 dataSchema 下的注释的粒度。可用的值包括：
    • GRANULARITY_UNSPECIFIED - 未指定粒度。
    • GRANULARITY_ASSET_LEVEL - 资产级精细程度（注释不得包含媒体资产的时间分区信息）。
    • GRANULARITY_PARTITION_LEVEL - 分区级精细度（注释必须包含媒体资产的时间分区信息）。
  • SEARCH_STRATEGY：可用的枚举值之一。要应用于注释键的搜索策略类型。可用的值包括：
    • NO_SEARCH
    • EXACT_SEARCH
    • SMART_SEARCH

HTTP 方法和网址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas

请求 JSON 正文： 

{
  "key": "DATASCHEMA_KEY",
  "schema_details": {
    "type": "ANNOTATION_DATA_TYPE",
    "granularity": "ANNOTATION_GRANULARITY",
    "search_strategy": {
      "search_strategy_type": "SEARCH_STRATEGY"
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "data-key",
  "schemaDetails": {
    "type": "BOOLEAN",
    "granularity": "GRANULARITY_ASSET_LEVEL",
    "searchStrategy": {
      "search_strategy_type": "EXACT_SEARCH"
    }
  }
}

更新数据架构 (API)

REST 和命令行

以下代码使用 projects.locations.corpora.dataSchemas.patch 方法更新 dataSchema。

此示例在请求网址中使用 ?updateMask=schemaDetails.type,schemaDetails.granularity，并在请求正文中添加新的 schemaDetails.type 和 schemaDetails.granularity 值以更新数据架构。

在使用任何请求数据之前，请先进行以下替换：

  • REGIONALIZED_ENDPOINT：端点可能包含与 LOCATION_ID 匹配的前缀，例如 europe-west4-。详细了解 区域级端点。
  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • LOCATION_ID：您在其中使用 Vertex AI Vision 的区域。例如：us-central1、europe-west4。请参阅可用区域。
  • CORPUS_ID：目标语料库的 ID。
  • DATASCHEMA_ID：目标数据架构的 ID。
  • ?updateMask=fieldToUpdate：可应用 updateMask 的某个可用字段。在请求正文中指定相应的新字段值。此新值会替换现有字段值。可用字段：
    • 键：?updateMask=key
    • 架构类型：?updateMask=schemaDetails.type
    • 架构粒度：?updateMask=schemaDetails.granularity
    • 架构搜索策略类型：?updateMask=schemaDetails.searchStrategy.searchStrategyType
    • 更新所有字段：?updateMask=*

HTTP 方法和网址：

PATCH https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity

请求 JSON 正文： 

{
  "key": "original-data-key",
  "schemaDetails": {
    "type":"INTEGER",
    "granularity":"GRANULARITY_PARTITION_LEVEL"
    "searchStrategy": {
      "searchStrategyType": "NO_SEARCH"
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "original-data-key",
  "schemaDetails": {
    "type": "INTEGER",
    "granularity": "GRANULARITY_PARTITION_LEVEL",
    "searchStrategy": {
      "searchStrategyType": "NO_SEARCH"
    }
  }
}

添加自定义结构体数据架构

借助自定义结构体，用户可以定义更复杂的容器来存储值并提供搜索功能。如需使用此功能，需要定义数据架构，例如：

REST

在使用任何请求数据之前，请先进行以下替换：

  • REGIONALIZED_ENDPOINT：端点可能包含与 LOCATION_ID 匹配的前缀，例如 europe-west4-。详细了解 区域级端点。
  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • LOCATION_ID：您在其中使用 Vertex AI Vision 的区域。例如：us-central1、europe-west4。请参阅可用区域。
  • CORPUS_ID：目标语料库的 ID。

HTTP 方法和网址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas

请求 JSON 正文： 

{
  "key": "person",
  "schema_details" : {
    "type":"CUSTOMIZED_STRUCT",
    "granularity":"GRANULARITY_ASSET_LEVEL",
    "customized_struct_config": {
      "field_schemas": {
         "name": {
            "type":"STRING",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         },
         "age": {
            "type":"FLOAT",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         }
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "person",
  "schemaDetails" : {
    "type":"CUSTOMIZED_STRUCT",
    "granularity":"GRANULARITY_ASSET_LEVEL",
    "customized_struct_config": {
      "field_schemas": {
         "name": {
            "type":"STRING",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         },
         "age": {
            "type":"FLOAT",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         }
      }
    }
  }
}

然后，我们可以插入注释

在使用任何请求数据之前，请先进行以下替换：

  • REGIONALIZED_ENDPOINT：端点可能包含与 LOCATION_ID 匹配的前缀，例如 europe-west4-。详细了解 区域级端点。
  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • LOCATION_ID：您在其中使用 Vertex AI Vision 的区域。例如：us-central1、europe-west4。请参阅可用区域。
  • CORPUS_ID：目标语料库的 ID。
  • ASSET_ID：目标素材资源的 ID。

HTTP 方法和网址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations

请求 JSON 正文： 

{
  "user_specified_annotation" : {
    "key": "person",
    "value": {
      "customized_struct_value":{
        "elements" : {
          "name": {
            "str_value":"John"
          },
          "age": {
            "float_value":10.5
          }
        }
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID",
  "userSpecifiedAnnotation": {
    "key": "person",
    "value": {
      "customized_struct_value":{
        "elements" : {
          "name": {
            "str_value":"John"
          },
          "age": {
            "float_value":10.5
          }
        }
      }
    }
  }
}

将注释编入索引后，您可以发出搜索请求，如下所示：

在使用任何请求数据之前，请先进行以下替换：

  • REGIONALIZED_ENDPOINT：端点可能包含与 LOCATION_ID 匹配的前缀，例如 europe-west4-。详细了解 区域级端点。
  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • LOCATION_ID：您在其中使用 Vertex AI Vision 的区域。例如：us-central1、europe-west4。请参阅可用区域。
  • CORPUS_ID：目标语料库的 ID。

HTTP 方法和网址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID:searchAssets

请求 JSON 正文： 

{
  "page_size": 10,
  "criteria": {
    "field": "person.name",
    "text_array": {
      "txt_values": "John"
    },
  },
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID:searchAssets"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID:searchAssets" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

修改仓库架构详情（控制台）

架构字段是通过应用从模型生成的。您还可以添加自定义字段。

修改 Facetable 字段后，您可以使用这些字段搜索您的仓库。

控制台

  1. 打开 Vertex AI Vision 信息中心的仓库标签页。

    前往“仓库”标签页

  2. 找到所需的仓库，然后选择其名称。 系统随即会显示仓库详情页面。

  3. 选择要启用搜索功能的字段。

在界面中选择 Facetable 搜索字段