Azure Document Intelligence

Document Intelligence terms — defined before code

The problem it solves

Where Document Intelligence fits in the Microsoft ecosystem

Three types of models — which to choose

Prebuilt Models — ready to use with no training

Custom Models — train on your own documents

Composed Models — one API, many layouts

How to train, test, and deploy a custom model

How analyze_document works — POST then poll

Document Intelligence uses an asynchronous API for all analysis operations. Here is why and how it works:

Analyze a receipt with a prebuilt model, then a custom model

Install: pip install azure-ai-documentintelligence azure-core

import os
from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
from azure.core.credentials import AzureKeyCredential

# ── Connection details ─────────────────────────────────────────────────
# These come from your Document Intelligence resource in Azure portal
# Keys and Endpoint → copy the endpoint URL and one of the two keys
endpoint = os.environ.get("DOCUMENTINTELLIGENCE_ENDPOINT")
key      = os.environ.get("DOCUMENTINTELLIGENCE_KEY")

# Create a credential object — wraps the key in a standard credential type
credential = AzureKeyCredential(key)

# Create the client — this object provides all data extraction methods
# The endpoint format is: https://<your-resource-name>.cognitiveservices.azure.com/
client = DocumentIntelligenceClient(endpoint=endpoint, credential=credential)


# ══════════════════════════════════════════════════════════════════════
# EXAMPLE 1 — Prebuilt Receipt Model
# Use this when you have a standard point-of-sale receipt
# No training needed — Microsoft has pre-trained this model
# ══════════════════════════════════════════════════════════════════════

# URL of the document to analyse (can also use a local file — see Example 2)
receipt_url = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/contoso-receipt.png"

# begin_analyze_document() submits the document for analysis
# "prebuilt-receipt" is the model ID for the prebuilt receipt model
# Other prebuilt model IDs: "prebuilt-invoice", "prebuilt-idDocument", "prebuilt-businessCard"
# "prebuilt-layout" (structure + tables), "prebuilt-read" (text only)
# AnalyzeDocumentRequest wraps the document URL (can also use urlSource= parameter directly)
poller = client.begin_analyze_document(
    "prebuilt-receipt",                       # Which model to use
    AnalyzeDocumentRequest(url_source=receipt_url)  # The document URL to analyse
)

# .result() waits for the async operation to complete and returns the result
# The Python SDK handles the POST → poll → GET loop automatically
# This may take several seconds for large documents
result = poller.result()

# The result contains a list of documents — one per recognised document in the input
# For a single receipt image, there will be one document
for receipt in result.documents:
    # doc_type: which prebuilt sub-type was detected (e.g. "receipt.retailMeal")
    print(f"Document Type: {receipt.doc_type}")
    print(f"Confidence:    {receipt.confidence:.2f}")

    # receipt.fields is a dictionary of field name → AnalyzedDocumentField objects
    # Each field has: .value (the extracted value), .confidence (0.0 to 1.0)
    # .get() returns None if the field wasn't found in this document
    merchant = receipt.fields.get("MerchantName")
    total    = receipt.fields.get("Total")
    date     = receipt.fields.get("TransactionDate")

    # Always check if the field was found before accessing its value
    if merchant:
        # .value gives you the extracted value in a Python-friendly type
        # .confidence tells you how certain the model is (0.0 = uncertain, 1.0 = certain)
        print(f"Merchant: {merchant.value}  (confidence: {merchant.confidence:.2f})")
    if total:
        # For currency fields, .value is a CurrencyValue object with .amount and .currency_symbol
        print(f"Total: {total.value.amount} {total.value.currency_symbol}  (confidence: {total.confidence:.2f})")
    if date:
        # For date fields, .value is a Python datetime.date object
        print(f"Date: {date.value}")

    # Receipts also contain line items — stored as a list in the Items field
    items = receipt.fields.get("Items")
    if items:
        print("\nLine Items:")
        # items.value is a list of ValueArray objects, one per line item
        for item in items.value:
            # Each item is itself a dictionary of fields (Description, Price, Quantity)
            desc  = item.value.get("Description")
            price = item.value.get("Price")
            if desc and price:
                print(f"  {desc.value}: {price.value.amount}")


# ══════════════════════════════════════════════════════════════════════
# EXAMPLE 2 — Analyse a LOCAL FILE using the prebuilt Invoice model
# ══════════════════════════════════════════════════════════════════════

# Open a local PDF file in binary mode ("rb" = read binary)
# Binary mode is needed because we are sending raw bytes, not text
with open("invoice.pdf", "rb") as f:
    # f.read() reads the entire file as a bytes object
    document_bytes = f.read()

# When passing a local file, use bytes_source= instead of url_source=
poller = client.begin_analyze_document(
    "prebuilt-invoice",                              # Model: prebuilt invoice
    AnalyzeDocumentRequest(bytes_source=document_bytes)  # Local file as bytes
)
result = poller.result()

for invoice in result.documents:
    vendor_name    = invoice.fields.get("VendorName")
    invoice_id     = invoice.fields.get("InvoiceId")
    invoice_total  = invoice.fields.get("InvoiceTotal")
    due_date       = invoice.fields.get("DueDate")

    print("\n--- Invoice Extraction ---")
    if vendor_name:   print(f"Vendor:       {vendor_name.value}")
    if invoice_id:    print(f"Invoice ID:   {invoice_id.value}")
    if invoice_total: print(f"Total Amount: {invoice_total.value.amount}")
    if due_date:      print(f"Due:          {due_date.value}")


# ══════════════════════════════════════════════════════════════════════
# EXAMPLE 3 — Custom Model
# Use the same client and same begin_analyze_document() call
# The only difference: pass YOUR model ID instead of a prebuilt model ID
# ══════════════════════════════════════════════════════════════════════

# Your custom model ID — found in Document Intelligence Studio after training
# Format: a GUID like "abc12345-1234-5678-abcd-123456789abc"
my_custom_model_id = "your-custom-model-id-here"

with open("my_custom_form.pdf", "rb") as f:
    document_bytes = f.read()

# Same API call — just replace the model ID with your trained custom model ID
poller = client.begin_analyze_document(
    my_custom_model_id,
    AnalyzeDocumentRequest(bytes_source=document_bytes)
)
result = poller.result()

for doc in result.documents:
    # doc_type: "your-model-id:Type" — the custom model type name you defined
    print(f"Doc type: {doc.doc_type}, Confidence: {doc.confidence:.2f}")
    # doc.fields is a dictionary of the LABEL NAMES you used when labeling in Studio
    for field_name, field_value in doc.fields.items():
        if field_value.value:
            print(f"  {field_name}: {field_value.value} (confidence: {field_value.confidence:.2f})")

Python — Extracting tables and bounding box positions

Documents often contain tables — rows and columns of structured data. Document Intelligence extracts them with full position information.

# Use the Layout model to extract tables from any document
# "prebuilt-layout" extracts text + tables + structure without assuming a document type
with open("contract_with_table.pdf", "rb") as f:
    document_bytes = f.read()

poller = client.begin_analyze_document(
    "prebuilt-layout",
    AnalyzeDocumentRequest(bytes_source=document_bytes)
)
result = poller.result()

# result.tables is a list of all detected tables in the document
for i, table in enumerate(result.tables):
    # row_count, column_count: dimensions of the detected table
    print(f"\nTable {i+1}: {table.row_count} rows × {table.column_count} cols")

    # table.cells is a flat list of all cells in the table
    # Each cell has: row_index, column_index, content, bounding_regions
    for cell in table.cells:
        # row_index and column_index tell you where in the table this cell sits
        # kind: "columnHeader" for header row cells, "content" for data cells
        label = "[HEADER]" if cell.kind == "columnHeader" else ""
        print(f"  Row {cell.row_index}, Col {cell.column_index} {label}: {cell.content}")

# Bounding box — where on the page each piece of content appears
# result.pages contains all the pages with their words and lines
for page in result.pages:
    print(f"\nPage {page.page_number}: {page.width}w × {page.height}h ({page.unit})")
    # page.words is a flat list of every recognised word on the page
    for word in page.words:
        # word.polygon: the [x1,y1, x2,y2, x3,y3, x4,y4] corners of the word's bounding box
        # word.confidence: how confident the OCR was about this word (0.0 to 1.0)
        # word.content: the text of the word
        print(f"  Word: '{word.content}' conf={word.confidence:.2f}")
        # The polygon lets you draw a box around the word on a rendered document image

Document Intelligence — what the exam tests

Test your understanding