Mendeteksi teks dalam file

Layanan Pengenalan Karakter Optik (OCR) Vertex AI di Google Distributed Cloud (GDC) dengan air gap mendeteksi dan mengekstrak teks dari file PDF dan TIFF. Anda dapat mengirim file lokal dalam permintaan inline ke metode API BatchAnnotateFiles atau memproses file yang disimpan di bucket secara asinkron dengan metode API AsyncBatchAnnotateFiles. Metode BatchAnnotateFiles API mendukung satu permintaan per panggilan batch.

Sebelum memulai

Untuk mendeteksi teks dalam file, hubungi Admin Project IAM Anda untuk meminta peran AI OCR Developer (ai-ocr-developer) di namespace project Anda.

Untuk mengetahui informasi selengkapnya tentang peran ini, lihat Menyiapkan izin IAM.

Sebelum dapat mulai menggunakan OCR API, Anda harus memiliki project dengan OCR API yang diaktifkan dan memiliki kredensial yang sesuai. Anda juga dapat menginstal library klien untuk membantu melakukan panggilan ke API. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan project pengenalan karakter.

Mendeteksi teks dengan permintaan inline

Metode BatchAnnotateFiles mendeteksi teks dari batch file PDF atau TIFF. Anda mengirim file yang teksnya ingin Anda deteksi secara langsung sebagai konten dalam permintaan API. Sistem akan menampilkan teks yang terdeteksi dalam format JSON di respons API.

Anda harus menentukan nilai untuk kolom dalam isi JSON permintaan API Anda. Tabel berikut berisi deskripsi kolom isi permintaan yang harus Anda berikan saat menggunakan metode BatchAnnotateFiles API untuk permintaan deteksi teks:

Kolom isi permintaan	Deskripsi kolom
content	File dengan teks yang akan dideteksi. Anda memberikan representasi Base64 (string ASCII) dari konten file biner Anda. Catatan: Anda hanya dapat memproses file yang disimpan secara lokal di lingkungan Distributed Cloud.
mime_type	Jenis file sumber. Anda harus menetapkannya ke salah satu nilai berikut: application/pdf untuk file PDF image/tiff untuk file TIFF
type	Jenis deteksi teks yang Anda perlukan dari file. Tentukan salah satu dari dua fitur anotasi: TEXT_DETECTION mendeteksi dan mengekstrak teks dari file apa pun. Respons JSON mencakup string yang diekstrak, setiap kata, dan kotak pembatasnya. DOCUMENT_TEXT_DETECTION juga mengekstrak teks dari file, tetapi layanan ini mengoptimalkan respons untuk teks dan dokumen yang padat. JSON mencakup informasi halaman, blok, paragraf, kata, dan jeda. Untuk mengetahui informasi selengkapnya tentang fitur anotasi ini, lihat Fitur pengenalan karakter optis.
language_hints	Opsional. Daftar bahasa yang akan digunakan untuk deteksi teks. Sistem menafsirkan nilai kosong untuk kolom ini sebagai deteksi bahasa otomatis. Anda tidak perlu menetapkan kolom language_hints untuk bahasa yang didasarkan pada alfabet Latin. Jika Anda mengetahui bahasa teks dalam file, menyetel petunjuk akan meningkatkan hasil. Bagaimana cara kerja petunjuk bahasa? Format language_hints menggunakan panduan pemformatan tag bahasa BCP 47 berikut: language ["-" script] ["-" region] *("-" variant) *("-" extension) ["-" privateuse]. Misalnya, petunjuk bahasa "en-t-i0-handwrit" menentukan bahasa Inggris (en), singleton ekstensi transformasi (t), kode ekstensi transformasi mesin metode input (i0), dan kode transformasi tulisan tangan (handwrit). Hal ini secara garis besar berarti bahasanya adalah "Bahasa Inggris yang ditransformasi dari tulisan tangan". Anda tidak perlu menentukan kode skrip karena bahasa "en" sudah mencakup Latn. Untuk mengetahui daftar bahasa yang didukung, lihat Bahasa yang didukung.
pages	Opsional. Jumlah halaman dari file yang akan diproses untuk deteksi teks. Jumlah maksimum halaman yang dapat Anda tentukan adalah lima. Jika Anda tidak menentukan jumlah halaman, layanan akan memproses lima halaman pertama file.

Untuk mengetahui informasi tentang representasi JSON lengkap, lihat AnnotateFileRequest.

Membuat permintaan API inline

Buat permintaan ke API terlatih OCR menggunakan metode REST API. Atau, berinteraksilah dengan API terlatih OCR dari skrip Python untuk mendeteksi teks dari file PDF atau TIFF.

Catatan: Metode BatchAnnotateFiles API hanya mendukung satu permintaan per panggilan batch.

Contoh berikut menunjukkan cara mendeteksi teks dalam file menggunakan OCR:

REST

Ikuti langkah-langkah berikut untuk mendeteksi teks dalam file menggunakan metode REST API:

1. Simpan file request.json berikut untuk isi permintaan Anda:

   cat <<- EOF > request.json
   {
     "requests": [
       {
         "input_config": {
           "content": BASE64_ENCODED_FILE,
           "mime_type": "application/pdf"
         },
         "features": [
           {
             "type": "FEATURE_TYPE"
           }
         ],
         "image_context": {
           "language_hints": [
             "LANGUAGE_HINT_1",
             "LANGUAGE_HINT_2",
             ...
           ]
         },
         "pages": []
       }
     ]
   }
   EOF
   

   Ganti kode berikut:

   • BASE64_ENCODED_FILE: representasi Base64 (string ASCII) dari konten file biner Anda. String ini diawali dengan karakter yang terlihat mirip dengan /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
   • FEATURE_TYPE: jenis deteksi teks yang Anda perlukan dari file. Nilai yang diizinkan adalah TEXT_DETECTION atau DOCUMENT_TEXT_DETECTION.
   • LANGUAGE_HINT: tag bahasa BCP 47 yang akan digunakan sebagai petunjuk bahasa untuk deteksi teks, seperti en-t-i0-handwrit. Kolom ini bersifat opsional dan sistem akan menafsirkan nilai kosong sebagai deteksi bahasa otomatis.

2. Dapatkan token autentikasi.

3. Buat permintaan:

   curl

   curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "x-goog-user-project: projects/PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     https://ENDPOINT/v1/files:annotate
   

   Ganti kode berikut:

   • TOKEN: token autentikasi yang Anda peroleh.
   • PROJECT_ID: project ID Anda.
   • ENDPOINT: endpoint OCR yang Anda gunakan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat status dan endpoint layanan.

   PowerShell

   $headers = @{
     "Authorization" = "Bearer TOKEN"
     "x-goog-user-project" = "projects/PROJECT_ID"
   }
   
   Invoke-WebRequest
     -Method POST
     -Headers $headers
     -ContentType: "application/json; charset=utf-8"
     -InFile request.json
     -Uri "ENDPOINT/v1/files:annotate" | Select-Object -Expand Content
   

   Ganti kode berikut:

   • TOKEN: token autentikasi yang Anda peroleh.
   • ENDPOINT: endpoint OCR yang Anda gunakan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat status dan endpoint layanan.

Python

Ikuti langkah-langkah berikut untuk menggunakan layanan OCR dari skrip Python guna mendeteksi teks dalam file:

1. Instal library klien OCR versi terbaru.

2. Tetapkan variabel lingkungan yang diperlukan pada skrip Python.

3. Mengautentikasi permintaan API Anda.

4. Tambahkan kode berikut ke skrip Python yang Anda buat:

   from google.cloud import vision
   import google.auth
   from google.auth.transport import requests
   from google.api_core.client_options import ClientOptions
   
   audience = "https://ENDPOINT:443"
   api_endpoint="ENDPOINT:443"
   
   def vision_client(creds):
     opts = ClientOptions(api_endpoint=api_endpoint)
     return vision.ImageAnnotatorClient(credentials=creds, client_options=opts)
   
   def main():
     creds = None
     try:
       creds, project_id = google.auth.default()
       creds = creds.with_gdch_audience(audience)
       req = requests.Request()
       creds.refresh(req)
     except Exception as e:
       print("Caught exception" + str(e))
       raise e
     return creds
   
   def vision_func(creds):
     vc = vision_client(creds)
     input_config = {"content": "BASE64_ENCODED_FILE"}
     features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
     # Each requests element corresponds to a single file. To annotate more
     # files, create a request element for each file and add it to
     # the array of requests
     req = {"input_config": input_config, "features": features}
   
     metadata = [("x-goog-user-project", "projects/PROJECT_ID")]
   
     resp = vc.annotate_file(req,metadata=metadata)
   
     print(resp)
   
   if __name__=="__main__":
     creds = main()
     vision_func(creds)
   

   Ganti kode berikut:

   • ENDPOINT: endpoint OCR yang Anda gunakan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat status dan endpoint layanan.
   • BASE64_ENCODED_FILE: representasi Base64 (string ASCII) dari konten file Anda. String ini diawali dengan karakter yang terlihat mirip dengan /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
   • FEATURE_TYPE: jenis deteksi teks yang Anda perlukan dari file. Nilai yang diizinkan adalah TEXT_DETECTION atau DOCUMENT_TEXT_DETECTION.
   • PROJECT_ID: project ID Anda.

5. Simpan skrip Python.

6. Jalankan skrip Python untuk mendeteksi teks dalam file:

   python SCRIPT_NAME
   

   Ganti SCRIPT_NAME dengan nama yang Anda berikan untuk skrip Python, seperti vision.py.

Mendeteksi teks dengan permintaan offline

Metode AsyncBatchAnnotateFiles mendeteksi teks dari batch file PDF atau TIFF dengan menjalankan permintaan offline (asinkron). File tersebut mungkin berisi beberapa halaman dan beberapa gambar per halaman. File sumber harus berada di bucket penyimpanan project Distributed Cloud Anda. Sistem akan menyimpan teks yang terdeteksi dalam format JSON ke bucket penyimpanan.

Layanan OCR memulai pemrosesan offline dan menampilkan ID proses yang berjalan lama yang melakukan deteksi teks pada file. Anda dapat menggunakan ID yang ditampilkan untuk melacak status pemrosesan offline. Jika ada terlalu banyak operasi yang sedang berlangsung, pemrosesan offline mungkin tidak langsung dimulai.

Anda harus menentukan nilai untuk kolom dalam isi JSON permintaan API Anda. Tabel berikut berisi deskripsi kolom isi permintaan yang harus Anda berikan saat menggunakan metode AsyncBatchAnnotateFiles API untuk permintaan deteksi teks:

Kolom isi permintaan	Deskripsi kolom
gcs_source.uri	Jalur URI ke file sumber yang valid (PDF atau TIFF) di bucket penyimpanan project Distributed Cloud Anda. File ini berisi teks yang ingin Anda deteksi. Pengguna atau akun layanan yang meminta setidaknya harus memiliki hak istimewa baca ke file tersebut.
mime_type	Jenis file sumber. Anda harus menetapkannya ke salah satu nilai berikut: application/pdf untuk file PDF image/tiff untuk file TIFF
type	Jenis deteksi teks yang Anda perlukan dari file. Tentukan salah satu dari dua fitur anotasi: TEXT_DETECTION mendeteksi dan mengekstrak teks dari file apa pun. Respons JSON mencakup string yang diekstrak, setiap kata, dan kotak pembatasnya. DOCUMENT_TEXT_DETECTION juga mengekstrak teks dari file, tetapi layanan ini mengoptimalkan respons untuk teks dan dokumen yang padat. JSON mencakup informasi halaman, blok, paragraf, kata, dan jeda. Untuk mengetahui informasi selengkapnya tentang fitur anotasi ini, lihat Fitur pengenalan karakter optis.
gcs_destination.uri	Jalur URI ke bucket penyimpanan project Distributed Cloud Anda untuk menyimpan file output. Lokasi ini adalah tempat Anda ingin menyimpan hasil deteksi. Pengguna atau akun layanan yang meminta harus memiliki izin tulis ke bucket.

Menyimpan file sumber di bucket penyimpanan

Sebelum mengirim permintaan, Anda harus memastikan akun layanan OCR memiliki izin baca ke bucket input dan izin tulis ke bucket output.

Bucket input dan output dapat berbeda dan berada di namespace project yang berbeda. Sebaiknya gunakan bucket input dan output yang sama untuk mencegah error, seperti menyimpan hasil di bucket yang salah.

Ikuti langkah-langkah berikut untuk menyimpan file yang teksnya ingin Anda deteksi di bucket penyimpanan:

1. Konfigurasikan gdcloud CLI untuk penyimpanan objek.

2. Buat bucket penyimpanan di namespace project Anda.Gunakan kelas penyimpanan Standard.

   Anda dapat membuat bucket penyimpanan dengan men-deploy resource Bucket di namespace project:

   apiVersion: object.gdc.goog/v1
   kind: Bucket
   metadata:
     name: ocr-async-bucket
     namespace: PROJECT_NAMESPACE
   spec:
     description: bucket for async ocr
     storageClass: Standard
     bucketPolicy:
       lockingPolicy:
         defaultObjectRetentionDays: 90
   

3. Berikan izin read dan write pada bucket ke akun layanan (g-vai-ocr-sie-sa) yang digunakan oleh layanan OCR.

   Anda dapat mengikuti langkah-langkah berikut untuk membuat peran dan binding peran menggunakan resource kustom:

   1. Buat peran dengan men-deploy resource Role di namespace project:

        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: ocr-async-reader-writer
          namespace: PROJECT_NAMESPACE
        rules:
          -
            apiGroups:
              - object.gdc.goog
            resources:
              - buckets
            verbs:
              - read-object
              - write-object
      

   2. Buat binding peran dengan men-deploy resource RoleBinding di namespace project:

        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
      
        metadata:
          name: ocr-async-reader-writer-rolebinding
          namespace: PROJECT_NAMESPACE
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: ocr-async-reader-writer
        subjects:
          -
            kind: ServiceAccount
            name: g-vai-ocr-sie-sa
            namespace: g-vai-ocr-sie
      

4. Upload file Anda ke bucket penyimpanan yang Anda buat. Untuk mengetahui informasi selengkapnya, lihat Mengupload dan mendownload objek penyimpanan di project.

Membuat permintaan API offline

Buat permintaan ke API terlatih OCR menggunakan metode REST API. Atau, berinteraksilah dengan API terlatih OCR dari skrip Python untuk mendeteksi teks dari file PDF atau TIFF.

Contoh berikut menunjukkan cara mendeteksi teks dalam file menggunakan OCR:

REST

Ikuti langkah-langkah berikut untuk mendeteksi teks dalam file menggunakan metode REST API:

1. Simpan file request.json berikut untuk isi permintaan Anda:

   cat <<- EOF > request.json
   {
     "parent": PROJECT_ID,
     "requests":[
       {
         "input_config": {
           "gcs_source": {
             "uri": "SOURCE_FILE"
           },
           "mime_type": "application/pdf"
         },
         "features": [
           {
             "type": "FEATURE_TYPE"
           }
         ],
         "output_config": {
           "gcs_destination": {
             "uri": "DESTINATION_BUCKET"
           }
         }
       }
     ]
   }
   EOF
   

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • SOURCE_FILE: jalur URI ke file sumber yang valid (PDF atau TIFF) di bucket penyimpanan project Distributed Cloud Anda.
   • FEATURE_TYPE: jenis deteksi teks yang Anda perlukan dari file. Nilai yang diizinkan adalah TEXT_DETECTION atau DOCUMENT_TEXT_DETECTION.
   • DESTINATION_BUCKET: jalur URI ke bucket penyimpanan project Distributed Cloud Anda untuk menyimpan file output.

2. Dapatkan token autentikasi.

3. Buat permintaan:

   curl

   curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "x-goog-user-project: projects/PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     https://ENDPOINT/v1/files:asyncBatchAnnotate
   

   Ganti kode berikut:

   • TOKEN: token autentikasi yang Anda peroleh.
   • PROJECT_ID: project ID Anda.
   • ENDPOINT: endpoint OCR yang Anda gunakan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat status dan endpoint layanan.

   PowerShell

   $headers = @{
     "Authorization" = "Bearer TOKEN"
     "x-goog-user-project" = "projects/PROJECT_ID"
   }
   
   Invoke-WebRequest
     -Method POST
     -Headers $headers
     -ContentType: "application/json; charset=utf-8"
     -InFile request.json
     -Uri "ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content
   

   Ganti kode berikut:

   • TOKEN: token autentikasi yang Anda peroleh.
   • ENDPOINT: endpoint OCR yang Anda gunakan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat status dan endpoint layanan.

Python

Ikuti langkah-langkah berikut untuk menggunakan layanan OCR dari skrip Python guna mendeteksi teks dalam file:

1. Instal library klien OCR versi terbaru.

2. Tetapkan variabel lingkungan yang diperlukan pada skrip Python.

3. Mengautentikasi permintaan API Anda.

4. Tambahkan kode berikut ke skrip Python yang Anda buat:

   from google.cloud import vision
   import google.auth
   from google.auth.transport import requests
   from google.api_core.client_options import ClientOptions
   
   audience = "https://ENDPOINT:443"
   api_endpoint="ENDPOINT:443"
   
   def vision_client(creds):
     opts = ClientOptions(api_endpoint=api_endpoint)
     return vision.ImageAnnotatorClient(credentials=creds, client_options=opts)
   
   def vision_func_async(creds):
     vc = vision_client(creds)
     features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
     input_config = {"gcs_source":{"uri":"SOURCE_FILE"},"mime_type": "application/pdf"}
     output_config = {"gcs_destination": {"uri": "DESTINATION_BUCKET"}}
     req = {"input_config": input_config, "output_config": output_config, "features":features}
     reqs = {"requests":[req],"parent":"PROJECT_ID"}
   
     metadata = [("x-goog-user-project", "projects/PROJECT_ID")]
   
     operation = vc.async_batch_annotate_files(request=reqs, metadata=metadata)
     lro = operation.operation
     resp = operation.result()
   
   def main():
     creds = None
     try:
       creds, project_id = google.auth.default()
       creds = creds.with_gdch_audience(audience)
       req = requests.Request()
       creds.refresh(req)
     except Exception as e:
       print("Caught exception" + str(e))
       raise e
     return creds
   
   if __name__=="__main__":
     creds = main()
     vision_func_async(creds)
   

   Ganti kode berikut:

   • ENDPOINT: endpoint OCR yang Anda gunakan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat status dan endpoint layanan.
   • FEATURE_TYPE: jenis deteksi teks yang Anda perlukan dari file. Nilai yang diizinkan adalah TEXT_DETECTION atau DOCUMENT_TEXT_DETECTION.
   • SOURCE_FILE: jalur URI ke file sumber yang valid (PDF atau TIFF) di bucket penyimpanan project cloud Distributed Cloud Anda.
   • DESTINATION_BUCKET: jalur URI ke bucket penyimpanan project Distributed Cloud Anda untuk menyimpan file output.
   • PROJECT_ID: project ID Anda.

5. Simpan skrip Python.

6. Jalankan skrip Python untuk mendeteksi teks dalam file:

   python SCRIPT_NAME
   

   Ganti SCRIPT_NAME dengan nama yang Anda berikan untuk skrip Python, seperti vision.py.

Anda dapat menggunakan nama operasi yang ditampilkan oleh metode AsyncBatchAnnotateFiles untuk memeriksa status operasi.

Mendapatkan status operasi

Metode get menampilkan status terbaru dari operasi yang berjalan lama, seperti permintaan offline untuk deteksi teks. Gunakan metode ini untuk memeriksa status operasi seperti dalam contoh berikut:

curl -X GET "http://ENDPOINT/v1/OPERATION_NAME"

Ganti OPERATION_NAME dengan nama operasi yang ditampilkan metode AsyncBatchAnnotateFiles saat Anda membuat permintaan offline.

Mencantumkan operasi

Metode list menampilkan daftar operasi yang cocok dengan filter yang ditentukan dalam permintaan. Metode ini dapat menampilkan operasi dari project tertentu. Untuk memanggil metode list, tentukan project ID dan endpoint OCR seperti dalam contoh berikut:

curl -X GET "http://ENDPOINT/v1/PROJECT_ID?page_size=10"