azure-ai-contentunderstanding-py

Azure AI Content Understanding SDK for Python — это навык Microsoft для мультимодального извлечения содержимого из документов, изображений, аудио и видео. Он ориентирован на Python-приложения, которым нужно получить структурированный результат для RAG и автоматизированных workflow: markdown из документа, транскрипцию аудио, временные фразы видео, ключевые кадры или поля, определённые собственным анализатором. Для установки источник указывает пакет azure-ai-contentunderstanding. Для подключения требуются endpoint ресурса Content Understanding и настроенная аутентификация Azure. Основной сценарий начинается с ContentUnderstandingClient и AnalyzeInput. Операция begin_analyze запускает асинхронную долгую операцию и возвращает poller; после завершения результат читается через poller.result(), а полезное содержимое берётся из result.contents. Для документов в источнике показан prebuilt-documentSearch: он принимает URL входного файла и возвращает markdown, пригодный для последующего поиска или обработки. Для изображений используется prebuilt-imageSearch. Для аудио и видео доступны prebuilt-audioSearch и prebuilt-videoSearch; видео дополнительно даёт фразы транскрипта с временными границами и описания ключевых кадров. В списке предварительно собранных анализаторов также есть prebuilt-invoice для извлечения полей из документов. Когда готового анализатора недостаточно, навык описывает создание custom analyzer с идентификатором, базовым анализатором и field schema. Схема может включать строковые и числовые поля, массивы и вложенные объекты, например имя поставщика, итог счёта и строки invoice. Пользовательский анализатор затем вызывается тем же begin_analyze, а поля доступны через result.fields. Отдельно перечислен жизненный цикл анализаторов: list_analyzers для просмотра, get_analyzer для получения конкретного объекта и delete_analyzer для удаления пользовательского анализатора. Это позволяет отделить обычное извлечение от доменной схемы и не создавать custom analyzer там, где достаточно prebuilt-варианта. Источник поддерживает синхронный и асинхронный клиент. Для sync используется azure.ai.contentunderstanding.ContentUnderstandingClient, для async — вариант из azure.ai.contentunderstanding.aio; модели AnalyzeInput, AnalyzeResult, MediaContentKind, DocumentContent и AudioVisualContent импортируются из azure.ai.contentunderstanding.models. Sync и async режимы нужно выбирать последовательно внутри одного call path. Клиенты следует оборачивать в контекстный менеджер, чтобы HTTP-транспорт, сокеты и кэши токенов освобождались детерминированно; для асинхронного DefaultAzureCredential нужен собственный async context manager. В аутентификации рекомендуется DefaultAzureCredential: локально он может использовать Azure CLI, VS Code или Developer CLI, а в Azure — managed identity или workload identity. Для production источник рекомендует ограничить цепочку через AZURE_TOKEN_CREDENTIALS=prod либо конкретное имя credential и не подменять аудит Entra строками подключения или ключами. Переменная CONTENTUNDERSTANDING_ENDPOINT обязательна для endpoint ресурса. URL-входы предпочтительны, когда они доступны, поскольку уменьшают необходимость предварительной загрузки файлов. Асинхронный клиент указан как вариант для высокопроизводительных сценариев. Практический результат карточки — понятный маршрут от входного URL до poller и result.contents, выбор prebuilt-анализатора для документа, изображения, аудио, видео или invoice, а затем переход к custom field schema только при доменной необходимости. Ограничения также существенны: навык описывает SDK и рекомендуемый lifecycle, но для реального запуска нужны доступный Azure-ресурс, корректный endpoint, credential и права; операции над аудио и видео могут занимать минуты. Нельзя смешивать sync и async клиенты без отдельной архитектурной причины, считать пример готовой конфигурацией любого окружения или утверждать наличие результата до завершения poller. Набор полей custom analyzer, версия пакета и поведение сервиса должны проверяться в документации и ресурсах конкретного проекта.