Registry / azure / azure-ai-formrecognizer

azure-ai-formrecognizer

JSON →
library3.3.3pypypi✓ verified 23d ago

The Azure AI Form Recognizer client library for Python, now part of Azure AI Document Intelligence, uses machine learning to analyze text and structured data from documents. It provides capabilities for layout extraction, prebuilt models (e.g., receipts, invoices, identity documents), custom model building and analysis, and document classification. This library is actively maintained as part of the broader Azure SDK for Python and typically sees regular updates with new service features and bug fixes.

pip install azure-ai-formrecognizer
INSTALL
IMPORT
SIG · AZURE-AI-FORMRECOG
A
azure-ai-formrecognizer
azurepythonv3.3.3
Install
2.9s avg
Import
911ms
Disk
28MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.958s · 29.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.9s · import 0.864s · 30MB
28MB installed
● package 28MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DocumentAnalysisClient
from azure.ai.formrecognizer import DocumentAnalysisClient
from azure.ai.formrecognizer import FormRecognizerClient
DocumentAnalysisClient is the primary client for API versions 2022-08-31 and higher (default for 3.x+ SDKs). FormRecognizerClient is for older API versions (v2.1 and below).
DocumentModelAdministrationClient
from azure.ai.formrecognizer import DocumentModelAdministrationClient
Used for building, composing, and managing custom document models.
AzureKeyCredential
from azure.core.credentials import AzureKeyCredential
Used for authenticating with an API key.

This quickstart demonstrates how to create a DocumentAnalysisClient, authenticate using an API key, and analyze a document from a URL using the 'prebuilt-document' model to extract general key-value pairs and other structural information. Remember to replace placeholder endpoint and key values with your actual Azure Form Recognizer resource credentials and provide a URL to your document.

import os from azure.ai.formrecognizer import DocumentAnalysisClient from azure.core.credentials import AzureKeyCredential # Set these environment variables for authentication endpoint = os.environ.get('AZURE_FORM_RECOGNIZER_ENDPOINT', 'YOUR_FORM_RECOGNIZER_ENDPOINT') key = os.environ.get('AZURE_FORM_RECOGNIZER_KEY', 'YOUR_FORM_RECOGNIZER_KEY') if endpoint == 'YOUR_FORM_RECOGNIZER_ENDPOINT' or key == 'YOUR_FORM_RECOGNIZER_KEY': print("Please set the AZURE_FORM_RECOGNIZER_ENDPOINT and AZURE_FORM_RECOGNIZER_KEY environment variables.") exit() # Example document URL (replace with your own) document_url = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-quickstart-code/master/python/FormRecognizer/rest/sample_data/Form_1.jpg" def analyze_general_document(): document_analysis_client = DocumentAnalysisClient( endpoint=endpoint, credential=AzureKeyCredential(key) ) print(f"Analyzing document from: {document_url}") # Use the prebuilt-document model for general document analysis poller = document_analysis_client.begin_analyze_document_from_url( "prebuilt-document", document_url ) result = poller.result() if result.documents: for idx, doc in enumerate(result.documents): print(f"----Detected Document #{idx+1}-----") print(f"Document type: {doc.doc_type}") if doc.fields: print("Fields:") for name, field in doc.fields.items(): field_value = field.value if field.value else field.content print(f" {name}: {field_value} (Confidence: {field.confidence:.2f})") else: print("No documents detected.") print("---Analysis complete.---") if __name__ == "__main__": analyze_general_document()
Debug
Known issues
breakingFor API versions 2022-08-31 and later, you must use `DocumentAnalysisClient` and `DocumentModelAdministrationClient`. The older `FormRecognizerClient` is deprecated for these versions and only supports service API versions 2.1 and below.
fix
Migrate client instantiation from `FormRecognizerClient` to `DocumentAnalysisClient` or `DocumentModelAdministrationClient` as per service API version. Refer to migration guides for detailed changes.
affects: >=3.2.0 (SDK) / >=2022-08-31 (Service API)
breakingAs of SDK version 3.3.0 and service API version 2023-07-31 (now default), several properties and models were removed, including `query_fields` keyword argument, `DocumentPage.images`, `DocumentImage` model, `DocumentPage.annotations`, `DocumentAnnotation` model, and `DocumentKeyValuePair.common_name`. Some `AnalysisFeature` enum members were also renamed.
fix
Review the official changelog and migration guide for your specific version. Adapt code to use the new add-on capabilities (e.g., `features` parameter for barcodes, formulas, key-value pairs) instead of removed properties.
affects: >=3.3.0
deprecatedThe service name 'Azure Form Recognizer' was officially renamed to 'Azure AI Document Intelligence' in July 2023. While the Python package `azure-ai-formrecognizer` retains its name, documentation and service terminology refer to 'Document Intelligence'.
fix
Be aware of the name change when consulting documentation or troubleshooting. The underlying functionality remains the same.
affects: All
breakingAs of `azure-ai-formrecognizer` version 3.3.3, Python 3.7 is no longer supported. The minimum required Python version is 3.8.
fix
Upgrade your Python environment to 3.8 or later.
affects: >=3.3.3
gotchaCommon 'Unauthorized' errors (HTTP 401) often indicate an incorrect endpoint, an invalid or expired subscription key, or attempting Azure Active Directory (AAD) authentication on a regional endpoint (AAD requires a custom subdomain).
fix
Verify your `endpoint` and `key` against your Azure resource. Ensure the endpoint format is correct (e.g., `https://<your-resource-name>.cognitiveservices.azure.com/`). For AAD, confirm a custom subdomain is used and service principal has 'Cognitive Services User' role.
affects: All
gotchaErrors like 'InvalidContentSourceFormat', 'InvalidContent', or `DecodeError: JSON is invalid` for specific documents can stem from corrupted files, unsupported file types, incorrect SAS URLs, or issues with blob storage paths (e.g., an extra leading '/' in container paths can create a virtual directory that is not recognized).
fix
Validate document integrity and format. Check SAS token permissions and expiry. Ensure blob storage paths are correct without leading slashes if not intended. For `DecodeError` on long PDFs, try splitting documents or increasing service timeouts if available.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.ai.formrecognizer'
The 'azure-ai-formrecognizer' package is not installed in the Python environment.
fix
Install the package using 'pip install azure-ai-formrecognizer'.
ImportError: cannot import name 'DocumentAnalysisClient' from 'azure.ai.formrecognizer'
The 'DocumentAnalysisClient' class is not available in the installed version of the 'azure-ai-formrecognizer' package.
fix
Ensure you have the latest version by running 'pip install --upgrade azure-ai-formrecognizer'.
azure.core.exceptions.HttpResponseError: (1001) Specified model not found or not ready, Model Id: mymodel
The specified model ID does not exist or is not ready for use.
fix
Verify the model ID is correct and that the model is trained and ready.
ModuleNotFoundError: No module named 'azure'
The 'azure' package is not installed or the Python environment is not set up correctly.
fix
Install the package using 'pip install azure'.
ModuleNotFoundError: No module named 'azure.ai'
The 'azure-ai' package is not installed in the Python environment.
fix
Install the package using 'pip install azure-ai'.
Upgrade
Version history
3.3.3latest on PyPI · released Apr 9, 2024
Audit
Dependencies
pythonrequiredRequires Python 3.8 or later.
aiohttpoptionalRequired for using asynchronous APIs.
Agent activity
46 hits · last 30 days
node
36
OpenAI (training)
1
Resources
azure-ai-formrecognizer — pip install azure-ai-formrecognizer · libregistry