Memproses dokumen dengan fungsi ML.PROCESS_DOCUMENT

Dokumen ini menjelaskan cara menggunakan fungsi ML.PROCESS_DOCUMENT dengan model jarak jauh untuk mengekstrak insight yang berguna dari dokumen dalam tabel objek.

Lokasi yang didukung

Anda harus membuat model jarak jauh yang digunakan dalam prosedur ini di multi-region US atau EU. Anda harus menjalankan fungsi ML.PROCESS_DOCUMENT di region yang sama dengan model jarak jauh.

Peran yang diperlukan

Untuk membuat model jarak jauh dan memproses dokumen, Anda memerlukan peran Identity and Access Management (IAM) berikut di tingkat project:

• Membuat pemroses dokumen: Editor Document AI (roles/documentai.editor)
• Membuat dan menggunakan set data, tabel, dan model BigQuery: BigQuery Data Editor (roles/bigquery.dataEditor)

• Membuat, mendelegasikan, dan menggunakan koneksi BigQuery: BigQuery Connections Admin (roles/bigquery.connectionsAdmin)

  Jika Anda belum mengonfigurasi koneksi default, Anda dapat membuat dan menyetelnya sebagai bagian dari menjalankan pernyataan CREATE MODEL. Untuk melakukannya, Anda harus memiliki peran Admin BigQuery (roles/bigquery.admin) di project Anda. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi koneksi default.

• Memberikan izin ke akun layanan koneksi: Project IAM Admin (roles/resourcemanager.projectIamAdmin)

• Membuat tugas BigQuery: BigQuery Job User (roles/bigquery.jobUser)

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk melakukan tugas dalam dokumen ini. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Sebelum memulai

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

Enable the APIs

Membuat pemroses

Buat pemroses di Document AI untuk memproses dokumen. Prosesor harus berupa jenis yang didukung.

Membuat set data

Anda harus membuat set data, koneksi, dan pemroses dokumen di region yang sama.

Buat set data BigQuery untuk memuat resource Anda:

Konsol

1. Di Google Cloud konsol, buka halaman BigQuery.

   Buka halaman BigQuery

2. Di panel Explorer, klik nama project Anda.

3. Klik more_vert View actions > Create dataset.

4. Di halaman Create dataset, lakukan hal berikut:

   • Untuk ID Set Data, ketik nama untuk set data.

   • Untuk Location type, pilih lokasi untuk set data.

   • Klik Create dataset.

bq

1. Untuk membuat set data baru, gunakan perintah bq mk dengan flag --location:

   bq --location=LOCATION mk -d DATASET_ID

   Ganti kode berikut:

   • LOCATION: lokasi set data.
   • DATASET_ID: ID set data yang Anda buat.

2. Pastikan set data telah dibuat:

   bq ls

Membuat koneksi

Anda dapat melewati langkah ini jika telah mengonfigurasi koneksi default, atau memiliki peran Admin BigQuery.

Buat koneksi resource Cloud untuk digunakan model jarak jauh, lalu dapatkan akun layanan koneksi. Buat koneksi di lokasi yang sama dengan set data yang Anda buat di langkah sebelumnya.

Pilih salah satu opsi berikut:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Di panel Penjelajah, klik add Tambahkan data:

   

   Dialog Tambahkan data akan terbuka.

3. Di panel Filter Menurut, di bagian Jenis Sumber Data, pilih Aplikasi Bisnis.

   Atau, di kolom Telusuri sumber data, Anda dapat memasukkan Vertex AI.

4. Di bagian Sumber data unggulan, klik Vertex AI.

5. Klik kartu solusi Vertex AI Models: BigQuery Federation.

6. Dalam daftar Connection type, pilih Vertex AI remote models, remote functions and BigLake (Cloud Resource).

7. Di kolom Connection ID, masukkan nama untuk koneksi Anda.

8. Klik Create connection.

9. Klik Go to connection.

10. Di panel Connection info, salin ID akun layanan untuk digunakan di langkah berikutnya.

bq

1. Di lingkungan command line, buat koneksi:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   Parameter --project_id akan mengganti project default.

   Ganti kode berikut:

   • REGION: region koneksi Anda
   • PROJECT_ID: Google Cloud project ID Anda
   • CONNECTION_ID: ID untuk koneksi Anda

   Saat Anda membuat resource koneksi, BigQuery akan membuat akun layanan sistem unik dan mengaitkannya dengan koneksi.

   Pemecahan masalah: Jika Anda mendapatkan error koneksi berikut, update Google Cloud SDK:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Ambil dan salin ID akun layanan untuk digunakan pada langkah berikutnya:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   Outputnya mirip dengan hal berikut ini:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
   

Terraform

Gunakan resource google_bigquery_connection.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut membuat koneksi resource Cloud bernama my_cloud_resource_connection di region US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud , selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

1. Luncurkan Cloud Shell.

2. Tetapkan project default Google Cloud tempat Anda ingin menerapkan konfigurasi Terraform.

   Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

   Salin kode contoh ke dalam main.tf yang baru dibuat.

   Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
4. Simpan perubahan Anda.
5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.

   terraform init

   Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:

   terraform init -upgrade

Menerapkan perubahan

1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:

   terraform plan

   Koreksi konfigurasi jika diperlukan.

2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

   terraform apply

   Tunggu hingga Terraform menampilkan pesan "Apply complete!".

3. Buka Google Cloud project Anda untuk melihat hasilnya. Di konsol Google Cloud , buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Memberikan akses ke akun layanan

Pilih salah satu opsi berikut:

Konsol

1. Buka halaman IAM & Admin.

   Buka IAM & Admin

2. Klik person_add Berikan Akses.

   Dialog Add principals akan terbuka.

3. Di kolom New principals, masukkan ID akun layanan yang Anda salin sebelumnya.

4. Di kolom Select a role, pilih Document AI, lalu pilih Document AI Viewer.

5. Klik Add another role.

6. Di kolom Select a role, pilih Cloud Storage, lalu pilih Storage Object Viewer.

7. Klik Simpan.

gcloud

Gunakan perintah gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/documentai.viewer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

Ganti kode berikut:

• PROJECT_NUMBER: nomor project Anda.
• MEMBER: ID akun layanan yang Anda salin sebelumnya.

Kegagalan memberikan izin akan menyebabkan error Permission denied.

Membuat model

Buat model jarak jauh dengan REMOTE_SERVICE_TYPE dari CLOUD_AI_DOCUMENT_V1:

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  REMOTE_SERVICE_TYPE = 'CLOUD_AI_DOCUMENT_V1',
  DOCUMENT_PROCESSOR = 'PROCESSOR_ID'
);

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET_ID: ID set data yang akan berisi model.
• MODEL_NAME: nama model.
• REGION: region yang digunakan oleh koneksi.
• CONNECTION_ID: ID koneksi—misalnya, myconnection.

  Saat Anda melihat detail koneksi di konsol Google Cloud , ID koneksi adalah nilai di bagian terakhir dari ID koneksi yang sepenuhnya memenuhi syarat yang ditampilkan di Connection ID—misalnya projects/myproject/locations/connection_location/connections/myconnection.

• PROCESSOR_ID: ID pemroses dokumen. Untuk menemukan nilai ini, lihat detail prosesor, lalu lihat baris ID di bagian Informasi Dasar.

Untuk melihat kolom output model, klik Buka model di hasil kueri setelah model dibuat. Kolom output ditampilkan di bagian Label pada tab Skema.

Membuat tabel objek

Buat tabel objek di atas sekumpulan dokumen di Cloud Storage. Dokumen dalam tabel objek harus berupa jenis yang didukung.

Memproses dokumen

Proses semua dokumen dengan ML.PROCESS_DOCUMENT:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
  [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')]
);

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET_ID: ID set data yang berisi model.
• MODEL_NAME: nama model.
• OBJECT_TABLE_NAME: nama tabel objek yang berisi URI dokumen yang akan diproses.
• PROCESS_OPTIONS: konfigurasi json yang menentukan cara memproses dokumen. Misalnya, Anda menggunakan ini untuk menentukan chunking dokumen untuk parser tata letak

Atau, proses beberapa dokumen dengan ML.PROCESS_DOCUMENT:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (SELECT *
  FROM `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
  WHERE FILTERS
  LIMIT NUM_DOCUMENTS
  )
  [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')]
);

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET_ID: ID set data yang berisi model.
• MODEL_NAME: nama model.
• OBJECT_TABLE_NAME: nama tabel objek yang berisi URI dokumen yang akan diproses.
• FILTERS: kondisi untuk memfilter dokumen yang ingin Anda proses di kolom tabel objek.
• NUM_DOCUMENTS: jumlah maksimum dokumen yang ingin Anda proses.
• PROCESS_OPTIONS: konfigurasi json yang menentukan konfigurasi, seperti konfigurasi chunking untuk parser tata letak

Contoh

Contoh 1

Contoh berikut menggunakan pengurai biaya untuk memproses dokumen yang diwakili oleh tabel documents:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `myproject.mydataset.expense_parser`,
  TABLE `myproject.mydataset.documents`
);

Kueri ini menampilkan laporan pengeluaran yang diuraikan, termasuk mata uang, jumlah total, tanggal tanda terima, dan item baris pada laporan pengeluaran. Kolom ml_process_document_result berisi output mentah parser biaya, dan kolom ml_process_document_status berisi error yang ditampilkan oleh pemrosesan dokumen.

Contoh 2

Contoh berikut menunjukkan cara memfilter tabel objek untuk memilih dokumen yang akan diproses, lalu menulis hasilnya ke tabel baru:

CREATE TABLE `myproject.mydataset.expense_details`
AS
SELECT uri, content_type, receipt_date, purchase_time, total_amount, currency
FROM
  ML.PROCESS_DOCUMENT(
    MODEL `myproject.mydataset.expense_parser`,
    (SELECT * FROM `myproject.mydataset.expense_reports`
    WHERE uri LIKE '%restaurant%'));

Langkah berikutnya

• Untuk mengetahui informasi tentang inferensi model di BigQuery ML, baca Ringkasan inferensi model.
• Untuk mengetahui informasi tentang pernyataan dan fungsi SQL yang didukung pada setiap jenis model, lihat Perjalanan pengguna menyeluruh untuk setiap model.