Aracılığıyla paylaş

Python için Azure Form Tanıma istemci kitaplığı - sürüm 3.0.0

  • Makale

Azure Bilişsel Hizmetler Form Tanıma, form belgelerindeki metin ve tablo verilerini tanımak için makine öğrenmesini kullanan bir bulut hizmetidir. Aşağıdaki ana işlevleri içerir:

  • Özel modeller - Formlardan alan değerlerini ve tablo verilerini tanıma. Bu modeller kendi verilerinizle eğitildiğinden formlarınıza göre uyarlanır.
  • İçerik API'si - Belgelerden metin ve tablo yapılarının yanı sıra sınırlayıcı kutu koordinatlarını da tanıyabilirsiniz. REST hizmetinin Düzen API'sine karşılık gelir.
  • Önceden oluşturulmuş makbuz modeli - Önceden oluşturulmuş bir model kullanarak ABD satış makbuzlarından gelen verileri tanıma.

Kaynak kodu | Paket (PyPI) | API başvuru belgeleri| Ürün belgeleri | Örnekleri

Başlarken

Önkoşullar

Paketi yükleme

Python için Azure Form Tanıma istemci kitaplığını yükleyin - pip ile sürüm 3.0.0:

pip install azure-ai-formrecognizer

Not: İstemci kitaplığının bu sürümü Form Tanıma hizmetinin v2.0 sürümünü destekler

Form Tanıma kaynağı oluşturma

Form Tanıma hem çok hizmetli hem de tek hizmetli erişimi destekler. Tek bir uç nokta/anahtar altında birden çok bilişsel hizmete erişmeyi planlıyorsanız Bilişsel Hizmetler kaynağı oluşturun. Yalnızca Form Tanıma erişim için bir Form Tanıma kaynağı oluşturun.

Kaynağı oluşturmak için

Seçenek 1:Azure Portal

Seçenek 2:Azure CLI. Aşağıda CLI kullanarak Form Tanıma kaynağı oluşturma örneği verilmiştir:

# 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

İstemcinin kimliğini doğrulama

Form Tanıma hizmetiyle etkileşim kurmak için bir istemci örneği oluşturmanız gerekir. İstemci nesnesinin örneğini oluşturmak için bir uç nokta ve kimlik bilgisi gereklidir.

Uç noktayı arama

azure portalını veya AzureCLI'yı kullanarak Form Tanıma kaynağınızın uç noktasını bulabilirsiniz:

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

API anahtarını alma

API anahtarı Azure Portal'da veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:

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

AzureKeyCredential ile istemci oluşturma

Parametre olarak credentialbir API anahtarı kullanmak için anahtarı dize olarak AzureKeyCredential örneğine geçirin.

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)

Azure Active Directory kimlik bilgileriyle istemci oluşturma

AzureKeyCredential kimlik doğrulaması bu başlangıç kılavuzundaki örneklerde kullanılır, ancak azure-identity kitaplığını kullanarak Azure Active Directory ile kimlik doğrulaması da yapabilirsiniz. Bölgesel uç noktaların AAD kimlik doğrulamayı desteklemediğini unutmayın. Bu kimlik doğrulama türünü kullanmak için kaynağınız için özel bir alt etki alanı adı oluşturun.

Aşağıda gösterilen DefaultAzureCredential türünü veya Azure SDK ile sağlanan diğer kimlik bilgileri türlerini kullanmak için lütfen paketi yükleyin azure-identity :

pip install azure-identity

Ayrıca yeni bir AAD uygulaması kaydetmeniz ve rolü hizmet sorumlunuza atayarak "Cognitive Services User" Form Tanıma erişimi vermeniz gerekir.

Tamamlandıktan sonra, AAD uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_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
)

Önemli kavramlar

FormRecognizerClient

FormRecognizerClient şu işlemler için işlemler sağlar:

  • Özel formlarınızı tanımak için eğitilmiş özel modelleri kullanarak form alanlarını ve içeriği tanıma. Bu değerler bir nesne koleksiyonunda RecognizedForm döndürülür.
  • Önceden eğitilmiş bir makbuz modeli kullanarak ABD makbuzlarındaki ortak alanları tanıma. Bu alanlar ve meta veriler bir nesne koleksiyonunda RecognizedForm döndürülür.
  • Bir modeli eğitmeye gerek kalmadan tablolar, satırlar ve sözcükler de dahil olmak üzere form içeriğini tanıma. Form içeriği bir nesne koleksiyonunda FormPage döndürülür.

FormRecognizerClient burada göstermek için örnek kod parçacıkları sağlanır.

FormTrainingClient

FormTrainingClient şu işlemler için işlemler sağlar:

  • Özel formlarınızda bulunan tüm alanları ve değerleri tanımak için etiketleri olmayan özel modelleri eğitin. Modelin tanıyacağı form türlerini ve her form türü için ayıklayacak alanları belirten bir CustomFormModel döndürülür. Daha ayrıntılı bir açıklama için hizmet belgelerine bakın.
  • Özel formlarınızı etiketleyerek belirttiğiniz belirli alanları ve değerleri tanımak için etiketlerle özel modelleri eğitin. Modelin ayıkacağı alanları ve her alan için tahmini doğruluğu gösteren bir CustomFormModel döndürülür. Daha ayrıntılı bir açıklama için hizmet belgelerine bakın.
  • Hesabınızda oluşturulan modelleri yönetme.
  • Özel modeli bir Form Tanıma kaynağından diğerine kopyalama.

Modellerin Form Tanıma Etiketleme Aracı gibi bir grafik kullanıcı arabirimi kullanılarak da eğitilebileceğini lütfen unutmayın.

FormTrainingClient kullanılarak göstermek için örnek kod parçacıkları sağlanır.

Long-Running İşlemleri

Uzun süre çalışan işlemler, bir işlemi başlatmak için hizmete gönderilen ilk isteklerden oluşan ve ardından işlemin tamamlanıp tamamlanmadığını ve başarılı olup olmadığını belirlemek için hizmeti aralıklarla yoklayarak sonucu almak için gerçekleştirilen işlemlerdir.

Modelleri eğiten, formlardan değerleri tanıyan veya kopyalayan yöntemler, uzun süre çalışan işlemler olarak modellenir. İstemci, veya AsyncLROPollerdöndüren bir begin_<method-name>LROPoller yöntemi kullanıma sunar. Çağıranların yönteminden döndürülen poller nesnesini çağırarak result() işlemin tamamlanmasını beklemesi begin_<method-name> gerekir. Örnek kod parçacıkları, aşağıda uzun süre çalışan işlemlerin kullanılmasını göstermek için

Örnekler

Aşağıdaki bölümde, en yaygın Form Tanıma görevlerden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

Özel Model Kullanarak Formları Tanıma

Formlardan ad/değer çiftlerini ve tablo verilerini tanıma. Bu modeller kendi verilerinizle eğitildiğinden formlarınıza göre uyarlanır. En iyi sonuçlar için, yalnızca özel modelin eğitildiği form türündeki formları tanımanız gerekir.

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

Alternatif olarak, bir form URL'si yöntemini kullanarak begin_recognize_custom_forms_from_url özel formları tanımak için de kullanılabilir. Tüm _from_url tanıma yöntemleri için yöntemler vardır.

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

İçeriği Tanıma

Belgelerden metin ve tablo yapılarının yanı sıra sınırlayıcı kutu koordinatlarını da tanıyabilirsiniz.

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

Alındı Bilgilerini Tanıma

Önceden oluşturulmuş bir model kullanarak ABD satış makbuzlarından alınan verileri tanıma. Hizmet tarafından tanınan giriş alanları burada bulunabilir.

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

Modeli eğitme

Kendi form türünüzde özel bir model eğitin. Elde edilen model, eğitildiği form türlerindeki değerleri tanımak için kullanılabilir. Eğitim belgelerini depoladığınız Azure Depolama Blobu kapsayıcınıza bir kapsayıcı SAS URL'si sağlayın. Eğitim dosyaları kapsayıcıdaki bir alt klasördeyse, hangi klasörün altında eğitileceğini belirtmek için prefix anahtar sözcüğü bağımsız değişkenini kullanın.

Kapsayıcıyı ve gerekli dosya yapısını ayarlama hakkında daha fazla bilgi hizmet belgelerinde bulunabilir.

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

Modellerinizi Yönetme

Hesabınıza bağlı özel modelleri yönetin.

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

Sorun giderme

Genel

Form Tanıma istemci kitaplığı, Azure Core'da tanımlanan özel durumları tetikler.

Günlüğe Kaydetme

Bu kitaplık, günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumlarıyla ilgili temel bilgiler (URL'ler, üst bilgiler vb.) BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve işlenmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü, anahtar sözcük bağımsız değişkeniyle logging_enable bir istemcide etkinleştirilebilir:

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)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

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

İsteğe Bağlı Yapılandırma

İsteğe bağlı anahtar sözcük bağımsız değişkenleri istemcide ve işlem düzeyinde geçirilebilir. Azure-core başvuru belgelerinde yeniden denemeler, günlüğe kaydetme, aktarım protokolleri ve daha fazlası için kullanılabilir yapılandırmalar açıklanmaktadır.

Sonraki adımlar

Aşağıdaki bölümde, Form Tanıma Python API'sinde kullanılan yaygın desenleri gösteren çeşitli kod parçacıkları verilmiştir.

Daha fazla örnek kod

Bu kod örnekleri, Azure Form Tanıma istemci kitaplığıyla yaygın senaryo işlemlerini gösterir.

Zaman Uyumsuz API'ler

Bu kitaplık ayrıca Python 3.5+ üzerinde desteklenen tam bir zaman uyumsuz API içerir. Bunu kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Zaman uyumsuz istemciler ad alanının azure.ai.formrecognizer.aio altında bulunur.

Diğer belgeler

Azure Bilişsel Hizmetler Form Tanıma hakkında daha kapsamlı belgeler için docs.microsoft.com hakkındaki Form Tanıma belgelerine bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .