Nilai fitur impor batch

Untuk mempelajari lebih lanjut, jalankan notebook Jupyter "Contoh alur kerja Feature Store dengan data sampel" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di notebook Vertex AI Workbench yang dikelola pengguna | Lihat di GitHub

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 jenis entity. Perhatikan bahwa Anda hanya dapat memiliki satu tugas impor batch yang berjalan per jenis entity untuk menghindari konflik.

Dalam permintaan impor batch, tentukan lokasi data sumber dan cara pemetaannya 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.

• Untuk informasi tentang persyaratan data sumber, lihat Persyaratan data sumber.
• Untuk mengetahui informasi tentang durasi Vertex AI Feature Store (Lama) menyimpan data Anda di toko offline, lihat Vertex AI Feature Store (Lama) di Kuota dan batas.
• Untuk mengetahui informasi tentang stempel waktu nilai fitur terlama yang dapat Anda impor, lihat Vertex AI Feature Store (Lama) di Kuota dan batas.
• Anda tidak dapat mengimpor nilai fitur yang stempel waktunya menunjukkan tanggal atau waktu mendatang.

Performa tugas impor

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 (tidak ada node penyaluran online), tugas impor hanya akan 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 bahwa setiap modifikasi data sumber selesai 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 dalam file CSV input penyaluran untuk mewakili nilai NaN. Selama penyaluran online dan penyaluran batch, Vertex AI Feature Store (Lama) menampilkan NaN untuk nilai NaN.

Catatan: NaN dianggap sebagai data yang valid hanya jika itu untuk jenis data Double. Untuk semua jenis data lainnya, NaN dianggap sebagai nilai fitur yang tidak valid. Dalam skenario seperti ini, Vertex AI Feature Store (Lama) akan membatalkan validasi dan mengabaikan seluruh baris.

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:
   • Cloud Storage CSV file: 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.
   • BigQuery table: 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 Continue.
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 bagi fitur yang sudah 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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login , atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI . Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login . Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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,
    )

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();

Melihat tugas impor

Gunakan Konsol Google Cloud untuk melihat tugas impor batch di project Google Cloud.

Catatan: Untuk featurestore yang dibuat selama Pratinjau, Konsol Google Cloud mencantumkan tugas impor batch dan penyaluran batch. Featurestore yang dibuat pada atau setelah Ketersediaan Umum (5 Oktober 2021) hanya menampilkan tugas impor batch. Jika Anda melihat kedua jenis tugas dan hanya ingin melihat tugas impor batch, Anda harus create dan menggunakan featurestore baru.

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 View ingestion jobs 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 penyaluran batch dan online, tunggu hingga tugas impor selesai sebelum membuat permintaan penyaluran apa pun.

Mengisi ulang data historis

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

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

Langkah berikutnya

• Pelajari cara menayangkan fitur melalui penyaluran online atau penyaluran batch.
• Pelajari cara memantau nilai fitur yang diimpor dari waktu ke waktu.
• Lihat kuota tugas batch serentak Vertex AI Feature Store (Lama).
• Memecahkan masalah umum Vertex AI Feature Store (Lama).