Azure AI Content Understanding SDK pour Python

Service IA multimodal qui extrait le contenu sémantique de fichiers de documents, vidéos, audio et images pour la RAG et les workflows automatisés.

Installation

pip install azure-ai-contentunderstanding

Variables d'environnement

CONTENTUNDERSTANDING_ENDPOINT=https://<resource>.cognitiveservices.azure.com/  # Requis pour toutes les méthodes d'authentification
AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Authentification

import os
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential

endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
# Dev local : DefaultAzureCredential. Production : définir AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utiliser une credential spécifique directement en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
client = ContentUnderstandingClient(endpoint=endpoint, credential=credential)

Flux de travail principal

Les opérations Content Understanding sont des opérations longues et asynchrones :

1. Commencer l'analyse — Démarrer l'opération d'analyse avec begin_analyze() (retourne un poller)
2. Interroger les résultats — Interroger jusqu'à la fin de l'analyse (le SDK gère cela avec .result())
3. Traiter les résultats — Extraire les résultats structurés de AnalyzeResult.contents

Analyseurs prédéfinis

Analyser un document

import os
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.ai.contentunderstanding.models import AnalyzeInput
from azure.identity import DefaultAzureCredential

endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
client = ContentUnderstandingClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Analyser document depuis une URL
poller = client.begin_analyze(
    analyzer_id="prebuilt-documentSearch",
    inputs=[AnalyzeInput(url="https://example.com/document.pdf")]
)

result = poller.result()

# Accéder au contenu markdown (contents est une liste)
content = result.contents[0]
print(content.markdown)

Accéder aux détails du contenu du document

from azure.ai.contentunderstanding.models import MediaContentKind, DocumentContent

content = result.contents[0]
if content.kind == MediaContentKind.DOCUMENT:
    document_content: DocumentContent = content  # type: ignore
    print(document_content.start_page_number)

Analyser une image

from azure.ai.contentunderstanding.models import AnalyzeInput

poller = client.begin_analyze(
    analyzer_id="prebuilt-imageSearch",
    inputs=[AnalyzeInput(url="https://example.com/image.jpg")]
)
result = poller.result()
content = result.contents[0]
print(content.markdown)

Analyser une vidéo

from azure.ai.contentunderstanding.models import AnalyzeInput

poller = client.begin_analyze(
    analyzer_id="prebuilt-videoSearch",
    inputs=[AnalyzeInput(url="https://example.com/video.mp4")]
)

result = poller.result()

# Accéder au contenu vidéo (AudioVisualContent)
content = result.contents[0]

# Obtenir les phrases de la transcription avec les timages
for phrase in content.transcript_phrases:
    print(f"[{phrase.start_time} - {phrase.end_time}]: {phrase.text}")

# Obtenir les images clés (pour la vidéo)
for frame in content.key_frames:
    print(f"Frame at {frame.time}: {frame.description}")

Analyser l'audio

from azure.ai.contentunderstanding.models import AnalyzeInput

poller = client.begin_analyze(
    analyzer_id="prebuilt-audioSearch",
    inputs=[AnalyzeInput(url="https://example.com/audio.mp3")]
)

result = poller.result()

# Accéder à la transcription audio
content = result.contents[0]
for phrase in content.transcript_phrases:
    print(f"[{phrase.start_time}] {phrase.text}")

Analyseurs personnalisés

Créer des analyseurs personnalisés avec des schémas de champs pour l'extraction spécialisée :

# Créer un analyseur personnalisé
analyzer = client.create_analyzer(
    analyzer_id="my-invoice-analyzer",
    analyzer={
        "description": "Custom invoice analyzer",
        "base_analyzer_id": "prebuilt-documentSearch",
        "field_schema": {
            "fields": {
                "vendor_name": {"type": "string"},
                "invoice_total": {"type": "number"},
                "line_items": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "description": {"type": "string"},
                            "amount": {"type": "number"}
                        }
                    }
                }
            }
        }
    }
)

# Utiliser l'analyseur personnalisé
from azure.ai.contentunderstanding.models import AnalyzeInput

poller = client.begin_analyze(
    analyzer_id="my-invoice-analyzer",
    inputs=[AnalyzeInput(url="https://example.com/invoice.pdf")]
)

result = poller.result()

# Accéder aux champs extraits
print(result.fields["vendor_name"])
print(result.fields["invoice_total"])

Gestion des analyseurs

# Lister tous les analyseurs
analyzers = client.list_analyzers()
for analyzer in analyzers:
    print(f"{analyzer.analyzer_id}: {analyzer.description}")

# Obtenir un analyseur spécifique
analyzer = client.get_analyzer("prebuilt-documentSearch")

# Supprimer un analyseur personnalisé
client.delete_analyzer("my-custom-analyzer")

Client asynchrone

import asyncio
import os
from azure.ai.contentunderstanding.aio import ContentUnderstandingClient
from azure.ai.contentunderstanding.models import AnalyzeInput
from azure.identity.aio import DefaultAzureCredential

async def analyze_document():
    endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
    credential = DefaultAzureCredential()

    async with ContentUnderstandingClient(
        endpoint=endpoint,
        credential=credential
    ) as client:
        poller = await client.begin_analyze(
            analyzer_id="prebuilt-documentSearch",
            inputs=[AnalyzeInput(url="https://example.com/doc.pdf")]
        )
        result = await poller.result()
        content = result.contents[0]
        return content.markdown

asyncio.run(analyze_document())

Types de contenu

Les deux dérivent de MediaContent qui fournit les informations de base et la représentation markdown.

Imports de modèles

from azure.ai.contentunderstanding.models import (
    AnalyzeInput,
    AnalyzeResult,
    MediaContentKind,
    DocumentContent,
    AudioVisualContent,
)

Types de clients

Bonnes pratiques

1. Utiliser begin_analyze avec AnalyzeInput — c'est la signature de méthode correcte
2. Accéder aux résultats via result.contents[0] — les résultats sont retournés sous forme de liste
3. Utiliser les analyseurs prédéfinis pour les scénarios courants (recherche de document/image/audio/vidéo)
4. Créer des analyseurs personnalisés uniquement pour l'extraction de champs spécifiques au domaine
5. Utiliser le client asynchrone pour les scénarios à haut débit avec les credentials azure.identity.aio
6. Gérer les opérations longues — l'analyse vidéo/audio peut prendre plusieurs minutes
7. Utiliser les sources URL quand c'est possible pour éviter les frais généraux de téléchargement