Gerenciar índices

Um índice do Vision Warehouse (disponível para setores de imagem e vídeo em lote) é um recurso no nível do corpus que é uma representação gerenciada de recursos e anotações analisados. Um índice pode ser visto como um conjunto de dados de vetores de embedding e restrições semânticas que representam o significado do conteúdo de mídia. Os índices podem ser implantados em endpoints de índice para pesquisa.

Quando você cria um índice em um corpus, ele inclui todos os recursos analisados e todas as anotações no corpus. Para recursos ou anotações adicionados depois da criação do índice, é necessário analisar o corpus ou esses recursos novamente e atualizar o índice para incluí-los.

Criar um índice de warehouse

REST

Para criar um recurso de índice, envie uma solicitação POST usando o método projects.locations.corpora.indexes.create.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • REGIONALIZED_ENDPOINT: o endpoint pode incluir um prefixo correspondente ao LOCATION_ID, como europe-west4-. Saiba mais sobre os endpoints regionalizados.
  • PROJECT_NUMBER: o número do projeto do Google Cloud.
  • LOCATION_ID: a região em que você está usando a Vertex AI Vision. Por exemplo: us-central1, europe-west4. Consulte as regiões disponíveis.
  • CORPUS_ID: o ID do corpus de destino.
  • INDEX_ID: (opcional) um valor fornecido pelo usuário para o ID do índice. Nesta solicitação, o valor é adicionado ao URL da solicitação no formato:
    • https://REGIONALIZED_ENDPOINT/v1/[...]/corpora/CORPUS_ID/indexes?index_id=INDEX_ID

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "display_name": "DISPLAY_NAME",
  "description": "INDEX_DESCRIPTION",
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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/indexes"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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/indexes" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.visionai.v1.CreateIndexMetadata"
  }
}

Atualizar um índice de warehouse

A API UpdateIndex permite atualizar os campos de metadados do índice, como display_name e description, bem como o conteúdo do índice subjacente (assets e os annotations deles).

O campo update_mask na solicitação, também conhecido como máscara de campo, é usado para especificar os campos a serem substituídos no recurso de índice pela atualização. Os campos especificados em update_mask são relativos ao recurso, não à solicitação completa. Um campo do recurso será substituído se estiver na máscara. Não é permitido usar uma máscara de campo vazia. Se a máscara for "*", ela vai acionar uma atualização completa do índice e uma reconstrução total dos dados dele.

REST

Para atualizar um recurso de índice, envie uma solicitação PATCH usando o método projects.locations.corpora.indexes.patch.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • REGIONALIZED_ENDPOINT: o endpoint pode incluir um prefixo correspondente ao LOCATION_ID, como europe-west4-. Saiba mais sobre os endpoints regionalizados.
  • PROJECT_NUMBER: o número do projeto do Google Cloud.
  • LOCATION_ID: a região em que você está usando a Vertex AI Vision. Por exemplo: us-central1, europe-west4. Consulte as regiões disponíveis.
  • CORPUS_ID: o ID do corpus de destino.
  • INDEX_ID: o ID do índice de destino.
  • ?update_mask=fieldToUpdate: lista dos campos disponíveis em que você quer aplicar um update_mask. Especifique os valores correspondentes para os novos campos no corpo da solicitação. Esse novo valor substitui o valor do campo atual. É possível especificar vários campos como valores separados por vírgula. Campos disponíveis:
    • Nome de exibição: ?update_mask=display_name
    • Descrição: ?update_mask=description
    • Atualizar dados do índice subjacente: ?update_mask=entire_corpus
    • Atualizar todos os campos: ?update_mask=*

Método HTTP e URL: 

PATCH https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID?update_mask=display_name,entire_corpus

Corpo JSON da solicitação:

{
  "display_name": "DISPLAY_NAME",
  "entire_corpus": true
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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/indexes/INDEX_ID?update_mask=display_name,entire_corpus"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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/indexes/INDEX_ID?update_mask=display_name,entire_corpus" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.visionai.v1.UpdateIndexMetadata"
  }
}

Atualizações de índice de streaming

As APIs IndexAsset e RemoveIndexAsset permitem atualizações de streaming para índices. Essas APIs são compatíveis apenas com o Vision Warehouse para vídeos em lote.

Listar índices em um data warehouse

REST

Para listar os índices em um corpus, envie uma solicitação GET usando o método projects.locations.corpora.indexes.list.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • REGIONALIZED_ENDPOINT: o endpoint pode incluir um prefixo correspondente ao LOCATION_ID, como europe-west4-. Saiba mais sobre os endpoints regionalizados.
  • PROJECT_NUMBER: o número do projeto do Google Cloud.
  • LOCATION_ID: a região em que você está usando a Vertex AI Vision. Por exemplo: us-central1, europe-west4. Consulte as regiões disponíveis.
  • CORPUS_ID: o ID do corpus de destino.

Método HTTP e URL: 

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

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes"

PowerShell

execute o seguinte comando: 

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "indexes": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID_1",
      "display_name": "DISPLAY_NAME_1",
      "description": "DESCRIPTION_1",
      "entireCorpus": true,
      "state": "CREATED"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID_2",
      "display_name": "DISPLAY_NAME_2",
      "description": "DESCRIPTION_2",
      "entireCorpus": true,
      "state": "CREATED"
    }
  ]
}

Receber um índice

REST

Para mais detalhes sobre um índice, envie uma solicitação GET usando o método projects.locations.corpora.indexes.get.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • REGIONALIZED_ENDPOINT: o endpoint pode incluir um prefixo correspondente ao LOCATION_ID, como europe-west4-. Saiba mais sobre os endpoints regionalizados.
  • PROJECT_NUMBER: o número do projeto do Google Cloud.
  • LOCATION_ID: a região em que você está usando a Vertex AI Vision. Por exemplo: us-central1, europe-west4. Consulte as regiões disponíveis.
  • CORPUS_ID: o ID do corpus de destino.
  • INDEX_ID: o ID do índice de destino.

Método HTTP e URL: 

GET https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID"

PowerShell

execute o seguinte comando: 

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID",
  "display_name": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "entireCorpus": true,
  "state": "CREATED"
}

Conferir recursos em um índice

REST

Para conferir detalhes sobre os recursos presentes em um índice, envie uma solicitação GET usando o método projects.locations.corpora.indexes.viewAssets.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • REGIONALIZED_ENDPOINT: o endpoint pode incluir um prefixo correspondente ao LOCATION_ID, como europe-west4-. Saiba mais sobre os endpoints regionalizados.
  • PROJECT_NUMBER: o número do projeto do Google Cloud.
  • LOCATION_ID: a região em que você está usando a Vertex AI Vision. Por exemplo: us-central1, europe-west4. Consulte as regiões disponíveis.
  • CORPUS_ID: o ID do corpus de destino.
  • INDEX_ID: o ID do índice de destino.
  • PAGE_SIZE: (opcional) o número de resultados a serem retornados.
  • PAGE_TOKEN: (opcional) o nextPageToken fornecido pela resposta da chamada anterior. Isso pode ser usado para receber a próxima página de resultados.

Método HTTP e URL: 

GET https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID:viewAssets?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID:viewAssets?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN"

PowerShell

execute o seguinte comando: 

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID:viewAssets?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "indexedAssets": [
    {
      "index": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID",
      "asset": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID_1"
    },
    {
      "index": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID",
      "asset": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID_2"
    }
  ],
  "nextPageToken": "NEXT_PAGE_TOKEN"
}

Ver recursos indexados com um filtro

É possível fornecer uma lista de IDs de recursos separados por vírgulas usando o campo filter no método projects.locations.corpora.indexes.viewAssets para filtrar todos os recursos em um índice e mostrar apenas os recursos fornecidos.

REST

Para listar e filtrar recursos presentes em um índice, envie uma solicitação GET usando o método projects.locations.corpora.indexes.viewAssets.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • REGIONALIZED_ENDPOINT: o endpoint pode incluir um prefixo correspondente ao LOCATION_ID, como europe-west4-. Saiba mais sobre os endpoints regionalizados.
  • PROJECT_NUMBER: o número do projeto do Google Cloud.
  • LOCATION_ID: a região em que você está usando a Vertex AI Vision. Por exemplo: us-central1, europe-west4. Consulte as regiões disponíveis.
  • CORPUS_ID: o ID do corpus de destino.
  • INDEX_ID: o ID do índice de destino.
  • PAGE_SIZE: (opcional) o número de resultados a serem retornados.
  • PAGE_TOKEN: (opcional) o nextPageToken fornecido pela resposta da chamada anterior. Isso pode ser usado para receber a próxima página de resultados.
  • ASSET_ID_FILTER: (opcional) uma lista separada por vírgulas de IDs de recursos que você quer filtrar na lista retornada. Por exemplo:
    • ?filter=ASSET_ID_1"
    • ?filter=ASSET_ID_1,ASSET_ID_2"

Método HTTP e URL: 

GET https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID:viewAssets?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN&filter=ASSET_ID_FILTER

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID:viewAssets?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN&filter=ASSET_ID_FILTER"

PowerShell

execute o seguinte comando: 

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID:viewAssets?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN&filter=ASSET_ID_FILTER" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "indexedAssets": [
    {
      "index": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID",
      "asset": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID_1"
    },
    {
      "index": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID",
      "asset": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID_2"
    }
  ],
  "nextPageToken": "NEXT_PAGE_TOKEN"
}

Excluir um índice

Um índice só pode ser excluído se não estiver implantado em um indexEndpoint. Siga o guia para cancelar a implantação de um índice antes de excluir um índice implantado.

REST

Para excluir um recurso de índice, envie uma solicitação DELETE usando o método projects.locations.corpora.indexes.delete.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • REGIONALIZED_ENDPOINT: o endpoint pode incluir um prefixo correspondente ao LOCATION_ID, como europe-west4-. Saiba mais sobre os endpoints regionalizados.
  • PROJECT_NUMBER: o número do projeto do Google Cloud.
  • LOCATION_ID: a região em que você está usando a Vertex AI Vision. Por exemplo: us-central1, europe-west4. Consulte as regiões disponíveis.
  • CORPUS_ID: o ID do corpus de destino.
  • INDEX_ID: o ID do índice de destino.

Método HTTP e URL: 

DELETE https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID"

PowerShell

execute o seguinte comando: 

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/indexes/INDEX_ID/operations/OPERATION_ID",
}