Pustaka klien Azure Form Recognizer untuk Python - versi 3.0.0

  • Artikel

Azure Cognitive Services Form Recognizer adalah layanan cloud yang menggunakan pembelajaran mesin untuk mengenali data teks dan tabel dari dokumen formulir. Ini termasuk fungsi utama berikut:

  • Model kustom - Mengenali nilai bidang dan data tabel dari formulir. Model-model ini dilatih dengan data Anda sendiri, sehingga disesuaikan dengan formulir Anda.
  • CONTENT API - Mengenali struktur teks dan tabel, bersama dengan koordinat kotak pembatasnya, dari dokumen. Sesuai dengan API Tata Letak layanan REST.
  • Model tanda terima bawaan - Mengenali data dari tanda terima penjualan AS menggunakan model bawaan.

Kode sumber | Paket (PyPI) | Dokumentasi| referensi API Dokumentasi | produk Sampel

Memulai

Prasyarat

Instal paketnya

Instal pustaka klien Azure Form Recognizer untuk Python - versi 3.0.0 dengan pip:

pip install azure-ai-formrecognizer

Catatan: Versi pustaka klien ini mendukung versi v2.0 dari layanan Form Recognizer

Membuat sumber daya Form Recognizer

Form Recognizer mendukung akses multi-layanan dan layanan tunggal. Buat sumber daya Cognitive Services jika Anda berencana untuk mengakses beberapa layanan kognitif di bawah satu titik akhir/kunci. Hanya untuk akses Form Recognizer, buat sumber daya Form Recognizer.

Anda dapat membuat sumber daya menggunakan

Opsi 1:Portal Microsoft Azure

Opsi 2:Azure CLI. Di bawah ini adalah contoh bagaimana Anda dapat membuat sumber daya Form Recognizer menggunakan CLI:

# Create a new resource group to hold the form recognizer resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create form recognizer
az cognitiveservices account create \
    --name form-recognizer-resource \
    --resource-group my-resource-group \
    --kind FormRecognizer \
    --sku F0 \
    --location westus2 \
    --yes

Mengautentikasi klien

Untuk berinteraksi dengan layanan Form Recognizer, Anda harus membuat instans klien. Titik akhir dan kredensial diperlukan untuk membuat instans objek klien.

Mencari titik akhir

Anda dapat menemukan titik akhir untuk sumber daya Form Recognizer Anda menggunakan Portal Microsoft Azure atau Azure CLI:

# Get the endpoint for the form recognizer resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

Mendapatkan kunci API

Kunci API dapat ditemukan di Portal Microsoft Azure atau dengan menjalankan perintah Azure CLI berikut:

az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"

Membuat klien dengan AzureKeyCredential

Untuk menggunakan kunci API sebagai credential parameter, teruskan kunci sebagai string ke dalam instans AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")
form_recognizer_client = FormRecognizerClient(endpoint, credential)

Membuat klien dengan kredensial Azure Active Directory

AzureKeyCredential autentikasi digunakan dalam contoh dalam panduan memulai ini, tetapi Anda juga dapat mengautentikasi dengan Azure Active Directory menggunakan pustaka azure-identity . Perhatikan bahwa titik akhir regional tidak mendukung autentikasi AAD. Buat nama subdomain kustom untuk sumber daya Anda untuk menggunakan jenis autentikasi ini.

Untuk menggunakan jenis DefaultAzureCredential yang ditunjukkan di bawah ini, atau jenis kredensial lain yang disediakan dengan Azure SDK, harap instal azure-identity paket:

pip install azure-identity

Anda juga perlu mendaftarkan aplikasi AAD baru dan memberikan akses ke Form Recognizer dengan menetapkan peran ke "Cognitive Services User" perwakilan layanan Anda.

Setelah selesai, atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET.

from azure.identity import DefaultAzureCredential
from azure.ai.formrecognizer import FormRecognizerClient
credential = DefaultAzureCredential()

form_recognizer_client = FormRecognizerClient(
    endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",
    credential=credential
)

Konsep utama

FormRecognizerClient

FormRecognizerClient menyediakan operasi untuk:

  • Mengenali bidang formulir dan konten menggunakan model kustom yang dilatih untuk mengenali formulir kustom Anda. Nilai ini ditampilkan dalam kumpulan objek RecognizedForm.
  • Mengenali bidang umum dari tanda terima AS, menggunakan model tanda terima yang telah dilatih sebelumnya. Bidang dan metadata ini dikembalikan dalam kumpulan RecognizedForm objek.
  • Mengenali konten formulir, termasuk tabel, garis, dan kata, tanpa perlu melatih model. Konten formulir dikembalikan dalam kumpulan objek FormPage.

Cuplikan kode sampel disediakan untuk mengilustrasikan menggunakan FormRecognizerClient di sini.

FormTrainingClient

FormTrainingClient menyediakan operasi untuk:

  • Melatih model kustom tanpa label untuk mengenali semua bidang dan nilai yang ditemukan dalam formulir kustom Anda. CustomFormModel dikembalikan yang menunjukkan jenis formulir yang akan dikenali model, dan bidang yang akan diekstrak untuk setiap jenis formulir. Lihat dokumentasi layanan untuk penjelasan yang lebih rinci.
  • Melatih model kustom dengan label untuk mengenali bidang dan nilai tertentu yang Anda tentukan dengan memberi label formulir kustom Anda. CustomFormModel ditampilkan yang menunjukkan bidang yang akan diekstrak model, serta perkiraan akurasi untuk setiap bidang. Lihat dokumentasi layanan untuk penjelasan yang lebih rinci.
  • Mengelola model yang dibuat di akun Anda.
  • Menyalin model kustom dari satu sumber daya Azure Form Recognizer ke sumber daya lainnya.

Harap dicatat bahwa model juga dapat dilatih menggunakan antarmuka pengguna grafis seperti alat pelabelan Form Recognizer.

Cuplikan kode sampel disediakan untuk mengilustrasikan menggunakan FormTrainingClient di sini.

Operasi Long-Running

Operasi jangka panjang adalah operasi yang terdiri dari permintaan awal yang dikirim ke layanan untuk memulai operasi, diikuti dengan polling layanan pada interval untuk menentukan apakah operasi telah selesai atau gagal, dan jika telah berhasil, untuk mendapatkan hasilnya.

Metode yang melatih model, mengenali nilai dari formulir, atau menyalin model dimodelkan sebagai operasi yang berjalan lama. Klien mengekspos begin_<method-name> metode yang mengembalikan LROPoller atau AsyncLROPoller. Penelepon harus menunggu operasi selesai dengan memanggil result() objek poller yang dikembalikan dari begin_<method-name> metode . Cuplikan kode sampel disediakan untuk mengilustrasikan menggunakan Contoh operasi yang berjalan lama di bawah ini.

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Form Recognizer yang paling umum, termasuk:

Mengenali Formulir Menggunakan Model Kustom

Mengenali pasangan nama/nilai dan data tabel dari formulir. Model-model ini dilatih dengan data Anda sendiri, sehingga disesuaikan dengan formulir Anda. Untuk hasil terbaik, Anda hanya boleh mengenali formulir dengan jenis formulir yang sama dengan model kustom yang dilatih.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)
model_id = "<your custom model id>"

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_custom_forms(model_id=model_id, form=form)
result = poller.result()

for recognized_form in result:
    print("Form type: {}".format(recognized_form.form_type))
    for name, field in recognized_form.fields.items():
        print("Field '{}' has label '{}' with value '{}' and a confidence score of {}".format(
            name,
            field.label_data.text if field.label_data else name,
            field.value,
            field.confidence
        ))

Atau, URL formulir juga dapat digunakan untuk mengenali formulir kustom menggunakan begin_recognize_custom_forms_from_url metode . Metode _from_url ada untuk semua metode pengenalan.

form_url = "<url_of_the_form>"
poller = form_recognizer_client.begin_recognize_custom_forms_from_url(model_id=model_id, form_url=form_url)
result = poller.result()

Mengenali Konten

Kenali struktur teks dan tabel, bersama dengan koordinat kotak pembatasnya, dari dokumen.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_content(form)
page = poller.result()

table = page[0].tables[0] # page 1, table 1
print("Table found on page {}:".format(table.page_number))
for cell in table.cells:
    print("Cell text: {}".format(cell.text))
    print("Location: {}".format(cell.bounding_box))
    print("Confidence score: {}\n".format(cell.confidence))

Mengenali Tanda Terima

Mengenali data dari tanda terima penjualan AS menggunakan model bawaan. Bidang tanda terima yang dikenali oleh layanan dapat ditemukan di sini.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your receipt>", "rb") as fd:
    receipt = fd.read()

poller = form_recognizer_client.begin_recognize_receipts(receipt)
result = poller.result()

for receipt in result:
    for name, field in receipt.fields.items():
        if name == "Items":
            print("Receipt Items:")
            for idx, items in enumerate(field.value):
                print("...Item #{}".format(idx+1))
                for item_name, item in items.value.items():
                    print("......{}: {} has confidence {}".format(item_name, item.value, item.confidence))
        else:
            print("{}: {} has confidence {}".format(name, field.value, field.confidence))

Latih model

Latih model kustom pada jenis formulir Anda sendiri. Model yang dihasilkan dapat digunakan untuk mengenali nilai dari jenis formulir yang dilatihnya. Berikan URL SAS kontainer ke kontainer Azure Storage Blob tempat Anda menyimpan dokumen pelatihan. Jika file pelatihan berada dalam subfolder dalam kontainer, gunakan argumen kata kunci awalan untuk menentukan di bawah folder mana yang akan dilatih.

Detail selengkapnya tentang menyiapkan kontainer dan struktur file yang diperlukan dapat ditemukan dalam dokumentasi layanan.

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

container_sas_url = "<container-sas-url>"  # training documents uploaded to blob storage
poller = form_training_client.begin_training(
    container_sas_url, use_training_labels=False
)
model = poller.result()

# Custom model information
print("Model ID: {}".format(model.model_id))
print("Status: {}".format(model.status))
print("Training started on: {}".format(model.training_started_on))
print("Training completed on: {}".format(model.training_completed_on))

print("\nRecognized fields:")
for submodel in model.submodels:
    print(
        "The submodel with form type '{}' has recognized the following fields: {}".format(
            submodel.form_type,
            ", ".join(
                [
                    field.label if field.label else name
                    for name, field in submodel.fields.items()
                ]
            ),
        )
    )

# Training result information
for doc in model.training_documents:
    print("Document name: {}".format(doc.name))
    print("Document status: {}".format(doc.status))
    print("Document page count: {}".format(doc.page_count))
    print("Document errors: {}".format(doc.errors))

Mengelola Model Anda

Kelola model kustom yang dilampirkan ke akun Anda.

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import ResourceNotFoundError

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

account_properties = form_training_client.get_account_properties()
print("Our account has {} custom models, and we can have at most {} custom models".format(
    account_properties.custom_model_count, account_properties.custom_model_limit
))

# Here we get a paged list of all of our custom models
custom_models = form_training_client.list_custom_models()
print("We have models with the following ids: {}".format(
    ", ".join([m.model_id for m in custom_models])
))

# Replace with the custom model ID from the "Train a model" sample
model_id = "<model_id from the Train a Model sample>"

custom_model = form_training_client.get_custom_model(model_id=model_id)
print("Model ID: {}".format(custom_model.model_id))
print("Status: {}".format(custom_model.status))
print("Training started on: {}".format(custom_model.training_started_on))
print("Training completed on: {}".format(custom_model.training_completed_on))

# Finally, we will delete this model by ID
form_training_client.delete_model(model_id=custom_model.model_id)

try:
    form_training_client.get_custom_model(model_id=custom_model.model_id)
except ResourceNotFoundError:
    print("Successfully deleted model with id {}".format(custom_model.model_id))

Pemecahan Masalah

Umum

Form Recognizer pustaka klien akan memunculkan pengecualian yang ditentukan di Azure Core.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG mendetail, termasuk isi permintaan/respons dan header yang tidak diedit, dapat diaktifkan pada klien dengan argumen kata kunci logging_enable:

import sys
import logging
from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

# This client will log detailed information about its HTTP sessions, at DEBUG level
form_recognizer_client = FormRecognizerClient(endpoint, credential, logging_enable=True)

Demikian pula, logging_enable dapat mengaktifkan pengelogan terperinci untuk satu operasi, bahkan ketika tidak diaktifkan untuk klien:

poller = form_recognizer_client.begin_recognize_receipts(receipt, logging_enable=True)

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Langkah berikutnya

Bagian berikut menyediakan beberapa cuplikan kode yang mengilustrasikan pola umum yang digunakan dalam Form Recognizer Python API.

Lebih banyak kode sampel

Sampel kode ini menunjukkan operasi skenario umum dengan pustaka klien Azure Form Recognizer.

API asinkron

Pustaka ini juga menyertakan API asinkron lengkap yang didukung pada Python 3.5+. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Klien asinkron ditemukan di azure.ai.formrecognizer.aio bawah namespace.

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang Form Recognizer Azure Cognitive Services, lihat dokumentasi Form Recognizer tentang docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.