Nilai fitur impor batch

Impor batch memungkinkan Anda mengimpor nilai fitur secara massal dari sumber data yang valid. Dalam permintaan impor batch, Anda dapat mengimpor nilai hingga 100 fitur untuk satu jenis entity. Perhatikan bahwa Anda hanya dapat menjalankan satu tugas impor batch per jenis entity untuk menghindari konflik.

Dalam permintaan impor batch, tentukan lokasi data sumber dan caranya dipetakan ke fitur di featurestore Anda. Karena setiap permintaan impor batch adalah untuk satu jenis entity, data sumber Anda juga harus untuk satu jenis entity.

Setelah impor berhasil diselesaikan, nilai fitur tersedia untuk operasi baca berikutnya.

Impor performa tugas

Vertex AI Feature Store (Lama) menyediakan impor throughput tinggi, tetapi latensi minimumnya dapat memerlukan waktu beberapa menit. Setiap permintaan ke Vertex AI Feature Store (Lama) memulai tugas untuk menyelesaikan pekerjaan. Tugas impor memerlukan waktu beberapa menit untuk diselesaikan meskipun Anda mengimpor satu kumpulan data.

Jika Anda ingin melakukan penyesuaian pada performa suatu tugas, ubah dua variabel berikut:

  • Jumlah node penyaluran online featurestore.
  • Jumlah pekerja yang digunakan untuk tugas impor. Worker memproses dan menulis data ke featurestore.

Jumlah worker yang direkomendasikan adalah satu worker untuk setiap 10 node layanan online di featurestore. Anda dapat naik ke level yang lebih tinggi jika beban penyaluran online rendah. Anda dapat menentukan maksimum 100 worker. Untuk panduan selengkapnya, lihat memantau dan menyesuaikan resource sesuai kebutuhan untuk mengoptimalkan impor batch.

Jika cluster penyaluran online tidak disediakan, tugas impor mungkin akan gagal. Jika terjadi kegagalan, coba lagi permintaan impor saat beban penyaluran online rendah, atau tingkatkan jumlah node featurestore Anda, lalu coba lagi permintaan tersebut.

Jika featurestore tidak memiliki toko online (nol node penayangan online), tugas impor hanya menulis ke toko offline, dan performa tugas hanya bergantung pada jumlah pekerja impor.

Konsistensi data

Inkonsistensi dapat terjadi jika data sumber diubah selama impor. Pastikan setiap modifikasi data sumber diselesaikan sebelum Anda memulai tugas impor. Selain itu, nilai fitur duplikat dapat menghasilkan nilai yang berbeda yang disalurkan antara permintaan online dan batch. Pastikan Anda memiliki satu nilai fitur untuk setiap pasangan ID entity dan stempel waktu.

Jika operasi impor gagal, featurestore mungkin hanya memiliki sebagian data, yang dapat menyebabkan nilai yang tidak konsisten ditampilkan antara permintaan penyaluran batch dan online. Untuk menghindari inkonsistensi ini, coba lagi permintaan impor yang sama dan tunggu hingga permintaan berhasil diselesaikan.

Nilai null dan array kosong

Selama impor, Vertex AI Feature Store (Lama) menganggap nilai skalar null atau array kosong sebagai nilai kosong. Ini mencakup nilai kosong di kolom CSV. Vertex AI Feature Store (Lama) tidak mendukung nilai null non-skalar, seperti nilai null dalam array.

Selama penyaluran online dan penyaluran batch, Vertex AI Feature Store (Lama) menampilkan nilai non-null atau nilai yang tidak kosong terbaru dari fitur tersebut. Jika nilai historis fitur tidak tersedia, Vertex AI Feature Store (Lama) akan menampilkan null.

Nilai NaN

Vertex AI Feature Store (Lama) mendukung nilai NaN (Bukan Angka) di Double dan DoubleArray. Selama impor, Anda dapat memasukkan NaN di file CSV input penayangan untuk mewakili nilai NaN. Selama penyaluran online dan penyaluran batch, Vertex AI Feature Store (Lama) menampilkan NaN untuk nilai NaN.

Impor batch

Impor nilai secara massal ke featurestore untuk satu atau beberapa fitur dari satu jenis entity.

UI Web

  1. Di bagian Vertex AI pada Konsol Google Cloud, buka halaman Features.

    Buka halaman Fitur

  2. Pilih region dari menu drop-down Region.
  3. Dalam tabel fitur, lihat kolom Entity type dan temukan jenis entity yang berisi fitur yang nilainya ingin Anda impor.
  4. Klik nama jenis entity.
  5. Dari panel tindakan, klik Ingest values.
  6. Untuk Data source, pilih salah satu opsi berikut:
    • File CSV Cloud Storage: Pilih opsi ini untuk mengimpor data dari beberapa file CSV dari Cloud Storage. Tentukan jalur dan nama file CSV. Untuk menentukan file tambahan, klik Tambahkan file lain.
    • Cloud Storage AVRO file: Pilih opsi ini untuk mengimpor data dari file AVRO dari Cloud Storage. Tentukan jalur dan nama file AVRO.
    • Tabel BigQuery: Pilih opsi ini untuk mengimpor data dari tabel BigQuery atau tampilan BigQuery. Cari dan pilih tabel atau tampilan yang akan digunakan, yang dalam format berikut: PROJECT_ID.DATASET_ID.TABLE_ID
  7. Klik Lanjutkan.
  8. Untuk Map column to features, tentukan kolom mana dalam data sumber yang dipetakan ke entity dan fitur di featurestore Anda.
    1. Tentukan nama kolom dalam data sumber yang berisi ID entity.
    2. Untuk stempel waktu, tentukan kolom stempel waktu dalam data sumber atau tentukan satu stempel waktu yang terkait dengan semua nilai fitur yang Anda impor.
    3. Pada daftar fitur, masukkan nama kolom data sumber yang memetakan ke setiap fitur. Secara default, Vertex AI Feature Store (Lama) mengasumsikan bahwa nama fitur dan nama kolom cocok.
  9. Klik Ingest.

REST

Untuk mengimpor nilai fitur untuk fitur yang ada, kirim permintaan POST menggunakan metode featurestores.entityTypes.importFeatureValues. Perhatikan bahwa jika nama kolom data sumber dan ID fitur tujuan berbeda, sertakan parameter sourceField.

Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

  • LOCATION_ID: Region tempat featurestore dibuat. Contoh, us-central1.
  • PROJECT_ID: Project ID Anda.
  • FEATURESTORE_ID: ID featurestore.
  • ENTITY_TYPE_ID: ID jenis entity.
  • ENTITY_SOURCE_COLUMN_ID: ID kolom sumber yang berisi ID entity.
  • FEATURE_TIME_ID: ID kolom sumber yang berisi stempel waktu fitur untuk nilai fitur.
  • FEATURE_ID: ID fitur yang ada di featurestore tempat nilai akan diimpor.
  • FEATURE_SOURCE_COLUMN_ID: ID kolom sumber yang berisi nilai fitur untuk entity.
  • SOURCE_DATA_DETAILS: Lokasi data sumber, yang juga menunjukkan format, seperti "bigquerySource": { "inputUri": "bq://test.dataset.sourcetable" } untuk tabel BigQuery atau tampilan BigQuery.
  • WORKER_COUNT: Jumlah worker yang akan digunakan untuk menulis data ke featurestore.

Metode HTTP dan URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues

Isi JSON permintaan: 

{
  "entityIdField": "ENTITY_SOURCE_COLUMN_ID",
  "featureTimeField": "FEATURE_TIME_ID",
  SOURCE_DATA_DETAILS,
  "featureSpecs": [{
    "id": "FEATURE_ID",
    "sourceField": "FEATURE_SOURCE_COLUMN_ID"
  }],
  "workerCount": WORKER_COUNT
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues" | Select-Object -Expand Content

Anda akan melihat output yang mirip dengan berikut ini: Anda dapat menggunakan OPERATION_ID sebagai respons untuk mendapatkan status operasi.

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.ImportFeatureValuesOperationMetadata",
    "genericMetadata": {
      "createTime": "2021-03-02T00:04:13.039166Z",
      "updateTime": "2021-03-02T00:04:13.039166Z"
    }
  }
}

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Python API. 

import datetime
from typing import List, Union

from google.cloud import aiplatform

def import_feature_values_sample(
    project: str,
    location: str,
    entity_type_id: str,
    featurestore_id: str,
    feature_ids: List[str],
    feature_time: Union[str, datetime.datetime],
    gcs_source_uris: Union[str, List[str]],
    gcs_source_type: str,
):

    aiplatform.init(project=project, location=location)

    my_entity_type = aiplatform.featurestore.EntityType(
        entity_type_name=entity_type_id, featurestore_id=featurestore_id
    )

    my_entity_type.ingest_from_gcs(
        feature_ids=feature_ids,
        feature_time=feature_time,
        gcs_source_uris=gcs_source_uris,
        gcs_source_type=gcs_source_type,
    )

Python

Library klien untuk Vertex AI disertakan saat Anda menginstal Vertex AI SDK untuk Python. Guna mempelajari cara menginstal Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Vertex AI SDK untuk Python. 

from google.cloud import aiplatform

def import_feature_values_sample(
    project: str,
    featurestore_id: str,
    entity_type_id: str,
    avro_gcs_uri: str,
    entity_id_field: str,
    feature_time_field: str,
    worker_count: int = 2,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
    timeout: int = 300,
):
    # The AI Platform services require regional API endpoints, which need to be
    # in the same region or multi-region overlap with the Feature Store location.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.FeaturestoreServiceClient(client_options=client_options)
    entity_type = f"projects/{project}/locations/{location}/featurestores/{featurestore_id}/entityTypes/{entity_type_id}"
    avro_source = aiplatform.gapic.AvroSource(
        gcs_source=aiplatform.gapic.GcsSource(uris=[avro_gcs_uri])
    )
    feature_specs = [
        aiplatform.gapic.ImportFeatureValuesRequest.FeatureSpec(id="age"),
        aiplatform.gapic.ImportFeatureValuesRequest.FeatureSpec(id="gender"),
        aiplatform.gapic.ImportFeatureValuesRequest.FeatureSpec(id="liked_genres"),
    ]
    import_feature_values_request = aiplatform.gapic.ImportFeatureValuesRequest(
        entity_type=entity_type,
        avro_source=avro_source,
        feature_specs=feature_specs,
        entity_id_field=entity_id_field,
        feature_time_field=feature_time_field,
        worker_count=worker_count,
    )
    lro_response = client.import_feature_values(request=import_feature_values_request)
    print("Long running operation:", lro_response.operation.name)
    import_feature_values_response = lro_response.result(timeout=timeout)
    print("import_feature_values_response:", import_feature_values_response)

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.AvroSource;
import com.google.cloud.aiplatform.v1.EntityTypeName;
import com.google.cloud.aiplatform.v1.FeaturestoreServiceClient;
import com.google.cloud.aiplatform.v1.FeaturestoreServiceSettings;
import com.google.cloud.aiplatform.v1.GcsSource;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesOperationMetadata;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesRequest;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesRequest.FeatureSpec;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesResponse;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ImportFeatureValuesSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String featurestoreId = "YOUR_FEATURESTORE_ID";
    String entityTypeId = "YOUR_ENTITY_TYPE_ID";
    String entityIdField = "YOUR_ENTITY_FIELD_ID";
    String featureTimeField = "YOUR_FEATURE_TIME_FIELD";
    String gcsSourceUri = "YOUR_GCS_SOURCE_URI";
    int workerCount = 2;
    String location = "us-central1";
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    int timeout = 300;
    importFeatureValuesSample(
        project,
        featurestoreId,
        entityTypeId,
        gcsSourceUri,
        entityIdField,
        featureTimeField,
        workerCount,
        location,
        endpoint,
        timeout);
  }

  static void importFeatureValuesSample(
      String project,
      String featurestoreId,
      String entityTypeId,
      String gcsSourceUri,
      String entityIdField,
      String featureTimeField,
      int workerCount,
      String location,
      String endpoint,
      int timeout)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    FeaturestoreServiceSettings featurestoreServiceSettings =
        FeaturestoreServiceSettings.newBuilder().setEndpoint(endpoint).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (FeaturestoreServiceClient featurestoreServiceClient =
        FeaturestoreServiceClient.create(featurestoreServiceSettings)) {
      List<FeatureSpec> featureSpecs = new ArrayList<>();

      featureSpecs.add(FeatureSpec.newBuilder().setId("title").build());
      featureSpecs.add(FeatureSpec.newBuilder().setId("genres").build());
      featureSpecs.add(FeatureSpec.newBuilder().setId("average_rating").build());
      ImportFeatureValuesRequest importFeatureValuesRequest =
          ImportFeatureValuesRequest.newBuilder()
              .setEntityType(
                  EntityTypeName.of(project, location, featurestoreId, entityTypeId).toString())
              .setEntityIdField(entityIdField)
              .setFeatureTimeField(featureTimeField)
              .addAllFeatureSpecs(featureSpecs)
              .setWorkerCount(workerCount)
              .setAvroSource(
                  AvroSource.newBuilder()
                      .setGcsSource(GcsSource.newBuilder().addUris(gcsSourceUri)))
              .build();
      OperationFuture<ImportFeatureValuesResponse, ImportFeatureValuesOperationMetadata>
          importFeatureValuesFuture =
              featurestoreServiceClient.importFeatureValuesAsync(importFeatureValuesRequest);
      System.out.format(
          "Operation name: %s%n", importFeatureValuesFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      ImportFeatureValuesResponse importFeatureValuesResponse =
          importFeatureValuesFuture.get(timeout, TimeUnit.SECONDS);
      System.out.println("Import Feature Values Response");
      System.out.println(importFeatureValuesResponse);
      featurestoreServiceClient.close();
    }
  }
}

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const project = 'YOUR_PROJECT_ID';
// const featurestoreId = 'YOUR_FEATURESTORE_ID';
// const entityTypeId = 'YOUR_ENTITY_TYPE_ID';
// const avroGcsUri = 'AVRO_FILE_IN_THE_GCS_URI';
// const entityIdField = 'ENTITY_ID_FIELD_IN_AVRO';
// const featureTimeField = 'TIMESTAMP_FIELD_IN_AVRO';
// const workerCount = <NO_OF_WORKERS_FOR_INGESTION_JOB>;
// const location = 'YOUR_PROJECT_LOCATION';
// const apiEndpoint = 'YOUR_API_ENDPOINT';
// const timeout = <TIMEOUT_IN_MILLI_SECONDS>;

// Imports the Google Cloud Featurestore Service Client library
const {FeaturestoreServiceClient} = require('@google-cloud/aiplatform').v1;

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: apiEndpoint,
};

// Instantiates a client
const featurestoreServiceClient = new FeaturestoreServiceClient(
  clientOptions
);

async function importFeatureValues() {
  // Configure the entityType resource
  const entityType = `projects/${project}/locations/${location}/featurestores/${featurestoreId}/entityTypes/${entityTypeId}`;

  const avroSource = {
    gcsSource: {
      uris: [avroGcsUri],
    },
  };

  const featureSpecs = [{id: 'age'}, {id: 'gender'}, {id: 'liked_genres'}];

  const request = {
    entityType: entityType,
    avroSource: avroSource,
    entityIdField: entityIdField,
    featureSpecs: featureSpecs,
    featureTimeField: featureTimeField,
    workerCount: Number(workerCount),
  };

  // Import Feature Values Request
  const [operation] = await featurestoreServiceClient.importFeatureValues(
    request,
    {timeout: Number(timeout)}
  );
  const [response] = await operation.promise();

  console.log('Import feature values response');
  console.log('Raw response:');
  console.log(JSON.stringify(response, null, 2));
}
importFeatureValues();

Lihat tugas impor

Gunakan konsol Google Cloud untuk melihat tugas impor batch dalam project Google Cloud.

UI Web

  1. Di bagian Vertex AI pada Konsol Google Cloud, buka halaman Features.

    Buka halaman Fitur

  2. Pilih region dari menu drop-down Region.
  3. Dari panel tindakan, klik Lihat tugas penyerapan untuk mencantumkan tugas impor untuk semua featurestore.
  4. Klik ID tugas impor untuk melihat detailnya seperti sumber datanya, jumlah entity impor, dan jumlah nilai fitur yang diimpor.

Timpa data yang ada di featurestore

Anda dapat mengimpor ulang nilai untuk menimpa nilai fitur yang sudah ada jika keduanya memiliki stempel waktu yang sama. Anda tidak perlu menghapus nilai fitur yang sudah ada terlebih dahulu. Misalnya, Anda mungkin mengandalkan data sumber dasar yang baru-baru ini diubah. Agar featurestore Anda tetap konsisten dengan data dasar tersebut, impor kembali nilai fitur Anda. Jika stempel waktu tidak cocok, nilai yang diimpor dianggap unik dan nilai lama tetap ada (tidak ditimpa).

Untuk memastikan konsistensi antara permintaan penayangan batch dan online, tunggu hingga tugas impor selesai sebelum membuat permintaan penayangan apa pun.

Mengisi ulang data historis

Jika Anda mengisi ulang data, tempat Anda mengimpor nilai fitur yang lalu, nonaktifkan penayangan online untuk tugas impor Anda. Penyaluran online hanya untuk menayangkan nilai fitur terbaru, yang tidak mencakup pengisian ulang. Menonaktifkan penayangan online berguna karena menghilangkan beban apa pun pada node penyaluran online dan meningkatkan throughput tugas impor, yang dapat mengurangi waktu penyelesaiannya.

Anda dapat menonaktifkan penayangan online untuk tugas impor saat menggunakan API atau library klien. Untuk mengetahui informasi selengkapnya, lihat kolom disableOnlineServing untuk metode importFeatureValue.

Langkah selanjutnya