Unstructured: разбор Python-библиотеки для PDF, OCR и подготовки данных к RAG

Unstructured — open-source Python-библиотека для превращения PDF и других документов в структурированные элементы перед поиском, аналитикой, ETL и RAG. Здесь рассматривается именно пакет unstructured из PyPI под Apache License 2.0. Коммерческие Pipelines/API, unstructured-client и Transform MCP — отдельные продукты, их возможности и тарифы к локальной библиотеке не относятся.

Скачать Unstructured

Безопасный путь получения библиотеки — официальный пакет unstructured в PyPI либо исходный код из репозитория Unstructured-IO/unstructured на GitHub. Для обычной установки разработчик рекомендует менеджер Python-пакетов и изолированное виртуальное окружение. Базовый пакет можно поставить командой pip install unstructured или через uv. Поддержка всех документных типов подключается дополнительным набором зависимостей unstructured[all-docs], а отдельные форматы можно добавлять выборочно, например unstructured[pdf,docx].

На дату обзора последняя публикация в PyPI — 0.27.5. Пакет распространяется как исходный архив и универсальный wheel для Python 3; PyPI заявляет диапазон Python от 3.11 включительно до 3.14 не включительно. Поскольку это библиотека, отдельного установщика EXE, DMG или AppImage у рассматриваемого продукта нет. Официальный репозиторий также публикует контейнерный образ и указывает поддержку образов для x86_64 и Apple silicon, но контейнер — способ запуска той же библиотеки, а не отдельная настольная редакция.

Не следует загружать случайные «сборки Unstructured» с каталогов программ. У проекта много одноимённых сущностей: unstructured — локальная open-source библиотека; unstructured-client — Python SDK для коммерческого Unstructured API; Unstructured Pipelines — размещаемая платформа с графическим конструктором. Их установка, требования, лицензирование и обработка данных различаются.

Что такое Unstructured

Библиотека Unstructured предназначена для превращения файлов разных типов в единое представление, удобное для программной обработки. Вместо выдачи одной длинной строки она пытается сохранить семантические части документа: заголовки, связный текст, элементы списка, таблицы, подписи, номера страниц, колонтитулы и другие категории. Каждый найденный фрагмент оформляется как объект Element с текстом, типом, уникальным идентификатором и набором метаданных.

Разработчик позиционирует open-source пакет как инструмент для прототипирования ingestion и preprocessing, прежде всего вокруг LLM, RAG, подготовки обучающих данных и традиционного ETL. В официальной документации прямо указано, что core open-source библиотека не рассчитана на production-сценарии в той же степени, что коммерческие Pipelines/API. Это важное ограничение: локальный пакет остаётся полезным и функциональным, но в нём нет фирменного VLM-маршрутинга, production-оркестрации, мониторинга задач, встроенной генерации embeddings в core, облачных enrichments и ряда корпоративных функций.

Unstructured не редактирует PDF визуально и не заменяет просмотрщик. Его задача начинается там, где нужно извлечь содержимое и структуру для кода. Если цель — просто открыть документ, быстро перейти по страницам или читать электронную книгу, архитектурно ближе лёгкий просмотрщик. Если требуется вручную править страницы и аннотации, нужен PDF-редактор: например, на сайте есть отдельные обзоры PDF-XChange Editor и Adobe Acrobat Pro.

Основные функции Unstructured

Partition: разбиение документа на элементы

Центральная операция — partition. Универсальная функция partition() определяет тип файла и направляет его в специализированный обработчик вроде partition_pdf, partition_docx, partition_html или partition_image. Для смешанных наборов это даёт единый контракт; для точной настройки лучше вызывать форматную функцию, где доступны параметры OCR, стратегии PDF, таблиц и разрывов страниц.

Результат — последовательность элементов. Документированы Title, NarrativeText, ListItem, Table, Header, Footer, Image, FigureCaption, PageNumber, PageBreak, Address, EmailAddress, CodeSnippet и UncategorizedText. Каждый элемент может содержать текст, идентификатор и метаданные. Downstream-код поэтому способен, например, исключать колонтитулы, индексировать NarrativeText вместе с Title, а таблицы обрабатывать отдельно независимо от исходного DOCX или PDF.

Метаданные и иерархия

Когда источник и выбранная стратегия позволяют, metadata содержит имя и тип файла, номер страницы, координаты, языки, parent_id и другие поля. parent_id помогает восстановить вложенность элементов, а координаты — связать найденный блок с областью страницы. Наличие конкретного поля не гарантируется для всех форматов и режимов.

Стратегии PDF и изображений

Для PDF доступны auto, fast, hi_res и ocr_only. Fast извлекает существующий текстовый слой и оптимален для обычных цифровых PDF. OCR Only использует OCR и затем разбирает распознанный текст. Hi Res анализирует макет и нужен, в частности, для более структурной обработки таблиц. Auto выбирает путь по характеристикам документа и аргументам.

Стратегии имеют разные ограничения. Официальная документация предупреждает о проблемах hi_res с порядком элементов в некоторых многоколоночных документах без извлекаемого текста; там может быть лучше ocr_only. Защищённый от копирования PDF не обрабатывается fast напрямую и требует fallback к hi_res. Извлечение изображений как отдельных блоков из PDF также привязано к hi_res и соответствующим параметрам.

OCR

Локальный OCR зависит от внешних компонентов. Для PDF и изображений установка указывает Tesseract; дополнительные языки требуют языковых данных. В open-source библиотеке документированы OCR-агенты Tesseract, Paddle OCR и Google Cloud Vision при наличии их зависимостей. Поэтому точность и приватность определяются не только Unstructured, но и выбранным движком.

Chunking для RAG

После partition элементы можно объединять в chunks. В core open-source документированы стратегии basic и by_title. Basic наполняет chunk целыми последовательными элементами до заданных границ и режет текст только при превышении лимита одним элементом. By Title дополнительно сохраняет границы разделов и при настройке может учитывать страницы.

max_characters задаёт жёсткий предел, new_after_n_chars — мягкую границу, overlap — перекрытие при вынужденном делении. Таблица не смешивается с обычным текстом и при необходимости превращается в TableChunk. Это полезнее простой нарезки строки, когда структура документа распознана корректно.

Очистка и staging

Core включает cleaning-функции и вспомогательные операции извлечения. Staging переводит Elements в словари, JSON, CSV или pandas DataFrame и содержит адаптеры к отдельным downstream-инструментам. При этом официальная документация помечает staging как постепенно вытесняемый destination connectors из Unstructured Ingest, поэтому для нового проекта статус конкретного адаптера стоит проверять до закрепления архитектуры.

Интерфейс и удобство использования

У рассматриваемой open-source библиотеки нет собственного графического окна, панели инструментов, миниатюр страниц или визуального редактора. Рабочая среда — Python-проект, ноутбук, скрипт или CLI вокруг библиотеки. Для разработчика это логично: вход задаётся путём к файлу, URL или потоком, параметры передаются аргументами функции, результат возвращается как Python-объекты. Для пользователя, ожидающего «открыть PDF и нажать OCR», порог входа существенно выше.

Самый простой маршрут короткий: импортировать partition, передать filename и получить список элементов. Сложность появляется на реальных документах. Нужно понимать, когда ставить extras, зачем системе Poppler и Tesseract, чем отличается текстовый PDF от скана, почему hi_res тянет модельные зависимости и какую схему chunking выбрать. Ошибки чаще связаны не с «непонятной кнопкой», а с окружением Python, внешними бинарными зависимостями, моделями и характеристиками документа.

Плюс программного интерфейса — воспроизводимость. Настройки можно хранить в коде и зависимостях проекта, прогонять одинаковый pipeline на тысячах файлов, автоматически проверять число элементов и нужные поля. Минус — диагностика требует навыков Python. Встроенного визуального сравнения оригинала и результата у core-пакета нет; для контроля структуры приходится печатать элементы, сохранять JSON, смотреть координаты или строить собственный просмотрщик.

Поддерживаемые форматы и совместимость

Официальная таблица open-source версии перечисляет PDF, DOC/DOCX, PPT/PPTX, XLS/XLSX, CSV, TSV, EML, MSG, P7S, EPUB, HTML, Markdown, ODT, Org Mode, RST, RTF, XML, TXT и изображения BMP, HEIC, JPEG, PNG, TIF/TIFF. Фактическая готовность зависит от extras и системных программ. Минимальная установка сознательно поддерживает более узкий набор; для PDF, Office, изображений и других типов добавляются форматные зависимости.

Основной «экспорт» core-библиотеки — не новый PDF или DOCX, а набор Element. Его можно превратить в список словарей и JSON, сохранить как JSON-файл, конвертировать в CSV или pandas DataFrame. Это формат передачи данных, а не визуальная конвертация документа с гарантией исходной вёрстки. Если нужен редактируемый офисный документ или PDF, который визуально повторяет оригинал, Unstructured не является подходящим конвертером.

Совместимость с внешними системами строится на Python и стандартных структурах данных. Есть отдельный Unstructured Ingest с source/destination connectors, но это соседний компонент, а не свойство минимального core-пакета. В старых примерах встречаются staging-интеграции с системами разметки и DataFrame; их статус нужно проверять перед внедрением, поскольку staging официально объявлен направлением, которое уступает место destination connectors.

Производительность и стабильность

У Unstructured нет одной скорости обработки: она зависит от формата, числа страниц, текстового слоя, OCR, таблиц и стратегии. Fast обычно легче model-based hi_res и OCR Only; документация рекомендует его для PDF с извлекаемым текстом. Модельные режимы закономерно потребляют больше времени и памяти.

Core open-source не поддерживает GPU как штатную возможность и официально позиционируется как средство прототипирования, а не production-платформа. Разработчик отдельно указывает более низкую производительность document/table extraction относительно коммерческого API. Для серьёзного конвейера поэтому важны pinning версий, контрольный корпус и измерения на собственных файлах вместо переносимых «средних» цифр.

К известным ограничениям относятся порядок чтения некоторых многоколоночных сканов в hi_res, зависимость защищённых PDF от hi_res и внешние компоненты для OCR. Fallback между стратегиями удобен, но может менять качество без явной ошибки. Контроль должен проверять типы элементов, порядок, таблицы и ключевые строки, а не только успешное завершение функции.

Лицензирование и версии

Пакет unstructured распространяется по Apache License 2.0. Плата за локальное использование самой библиотеки не взимается, подписки и пробного периода у неё нет. Разрешения и обязанности определяются текстом Apache-2.0, поэтому для корпоративного распространения нужно соблюдать требования лицензии и уведомлений, а не искать «ключ активации».

Версию библиотеки следует отличать от версий облачных сервисов. На 11 сентября 2026 года PyPI показывает 0.27.5 как последнюю публикацию. Отдельный пакет unstructured-client имеет собственную нумерацию и предназначен для вызова Unstructured API; номер клиента не является номером core-библиотеки. Аналогично тарифы Unstructured Pipelines не превращают локальный пакет в freemium-приложение.

С практической точки зрения «редакций» у core нет: разница задаётся установленными extras и внешними зависимостями. Можно держать минимальную установку только для простых текстовых типов, добавить PDF и DOCX или поставить all-docs. Такой модульный подход уменьшает лишние зависимости, но требует документировать окружение, иначе два компьютера с одинаковым Python-кодом могут фактически поддерживать разный набор форматов.

Системные требования

Python и операционная система

Для версии 0.27.5 PyPI требует Python не ниже 3.11 и ниже 3.14. Пакет классифицирован как OS Independent и выпускается универсальным wheel, но это относится к Python-пакету. Полный функционал зависит от нативных программ, а их установка различается в Windows, macOS и Linux. Поэтому утверждение «работает везде одинаково» некорректно: базовый Python-слой переносим, а PDF/OCR/Office-пути требуют проверки окружения.

Системные зависимости

Для максимальной совместимости официальная установка перечисляет libmagic-dev для определения типов, Poppler и Tesseract для изображений и PDF, языковые пакеты Tesseract для дополнительных языков и LibreOffice для Microsoft Office. Pandoc применяется для ряда документных форматов; актуальная документация полного инсталлятора отдельно связывает его с EPUB, ODT и RTF и указывает минимальную версию для RTF. Ставить все компоненты необязательно, если проект работает только с ограниченным набором файлов.

Аппаратные требования

Разработчик не публикует для core-библиотеки универсальный минимум RAM, CPU или дискового пространства. Это ожидаемо: минимальный текстовый parser и hi_res с модельными зависимостями имеют принципиально разные профили. Поэтому безопасный критерий — считать ресурсы на собственном корпусе и не переносить требования коммерческой платформы на локальный пакет. Встроенной поддержки GPU у open-source core документация не заявляет.

Карта критических зависимостей

Для воспроизводимости lock-файла мало: он не всегда фиксирует системные бинарники и OCR-модели. В технической документации стоит записывать версии Poppler, Tesseract, языковых данных и модельных компонентов, а обновление проверять на контрольных документах.

Паспорт обратимости операций

Partition и chunking создают производное представление. Обычный вызов читает исходный файл и возвращает новые объекты, поэтому оригинал остаётся источником истины, а Elements или chunks можно удалить и построить заново с другой стратегией.

Практичная схема хранения — оригинальный документ, полный результат partition в JSON и отдельно производные chunks/embeddings. Тогда изменение chunking или embedding не требует повторять OCR, а обновление parser можно сравнить с предыдущим результатом.

Преимущества и недостатки Unstructured

Плюсы и минусы

• Единая модель элементов для разных файлов. Код после partition меньше зависит от того, пришёл PDF, DOCX или HTML.

• Несколько стратегий для PDF. Можно разделять дешёвое извлечение текстового слоя, OCR и layout-aware обработку.

• Структурные метаданные. Типы элементов, parent_id, номер страницы и координаты дают больше контекста, чем голая строка текста.

• Chunking учитывает элементы документа. Basic и by_title могут сохранять смысловые границы лучше механической нарезки текста.

• Локальный open-source режим. Для core-функций не нужен аккаунт Unstructured, а исходный код доступен по Apache-2.0.

• Модульная установка. Можно не тянуть all-docs, если проект обрабатывает только несколько типов.

Минусы

• Не готовый пользовательский PDF-инструмент. Нет GUI для чтения, аннотаций, визуального редактирования и ручной проверки страниц.

• Сложные зависимости. Для полного PDF/OCR/Office-стека нужны внешние программы и модели, а не только pip.

• Core официально ориентирован на прототипирование. Production-оркестрация, мониторинг и часть современных AI-функций вынесены в коммерческую платформу/API.

• Нет штатного GPU-ускорения core. Модельные режимы на больших пакетах требуют особенно осторожной оценки ресурсов.

• Hi res имеет известные ограничения по порядку чтения. Многоколоночные сканы могут потребовать ocr_only или дополнительной проверки.

• Быстро меняющийся стек. Beta-классификатор и активные релизы делают pinning и regression-тесты практически обязательными для стабильного pipeline.

Сравнение с аналогами

Unstructured корректнее сравнивать с библиотеками извлечения и нормализации, а не с PDF-ридерами. Критерии ниже одинаковы: фокус, локальность, PDF/OCR и тип результата.

Docling подходит, когда особенно важен локальный экспорт в Markdown, JSON, HTML или text и единая модель документа. Apache Tika сильнее там, где главным критерием является широта типов файлов: проект заявляет извлечение из более тысячи форматов. Unstructured специализируется на семантических Elements и chunking под RAG.

PyMuPDF логичнее для PDF-центричных задач — страниц, координат, рендеринга, поиска и прямого доступа к объектам PDF. Для OCR с ручной визуальной проверкой может быть удобнее специализированная программа, например ABBYY FineReader.

Sumatra PDF не конкурент Unstructured: первый нужен человеку для чтения, второй — коду для подготовки данных. Для ручного редактирования ближе PDFelement. В одном процессе Sumatra может использоваться для визуального контроля исходника, а Unstructured — для автоматического извлечения.

Инструкция по установке

Базовая установка в изолированное окружение

1. Установите Python 3.11, 3.12 или 3.13 и создайте отдельный проект.

2. Создайте venv через стандартные средства Python или uv и активируйте его.

3. Для базовых типов установите unstructured; для PDF — extra pdf, для нескольких форматов перечислите extras, для полного набора используйте all-docs.

4. Добавьте необходимые системные программы: для PDF/OCR — Poppler и Tesseract, для дополнительных языков — Tesseract language data, для части Office — LibreOffice.

5. Запустите partition на небольшом контрольном файле и проверьте типы первых Elements и несколько строк текста.

6. Зафиксируйте Python-зависимости lock-файлом, а версии системных бинарников — в документации проекта.

Docker

Официальный репозиторий публикует контейнерный образ и указывает multi-platform сборки для x86_64 и Apple silicon. Контейнер удобен для повторяемого окружения, но для стабильного проекта лучше закреплять конкретный тег или digest, а не latest.

Первый запуск и удаление

Начните с текстового PDF или EML без OCR, затем переходите к скану и hi_res: так проще локализовать missing dependency. Отдельной фирменной процедуры удаления нет. В venv безопаснее сохранить JSON/lock-файл и удалить окружение целиком. Системные Poppler, Tesseract или LibreOffice удаляйте отдельно только если они не нужны другим приложениям.

Практические кейсы

Текстовый PDF: структура без OCR

Цель: получить JSON из PDF с текстовым слоем. Подготовка: PDF extra и документ с известными заголовками и контрольной фразой.

1. Вызовите partition_pdf с strategy=»fast».

2. Убедитесь, что среди Elements есть ожидаемые Title/NarrativeText и ключевая строка.

3. Сохраните результат через elements_to_json.

4. Сверьте порядок первых смысловых блоков с оригиналом.

Ограничение: fast не предназначен для скана без текстового слоя и не даёт преимущества hi_res при layout-sensitive таблицах.

Сканированный PDF: OCR

Цель: извлечь текст из скана. Подготовка: Poppler, Tesseract и языковые данные; небольшой документ с проверяемыми именами и числами.

1. Запустите partition_pdf с strategy=»ocr_only» и корректным languages.

2. Сохраните Elements до cleaning, чтобы не смешивать ошибки OCR и нормализации.

3. Сверьте имена, числа и порядок абзацев на нескольких страницах.

4. Для многоколоночного скана отдельно проверьте порядок чтения.

Ограничение: OCR создаёт распознанные данные, а не исправленную визуальную копию PDF.

Таблицы и layout через hi_res

Цель: получить таблицу как отдельный элемент. Подготовка: компоненты hi_res и PDF с известными заголовками столбцов.

1. Обработайте документ стратегией hi_res с нужными параметрами table inference.

2. Отфильтруйте Table и проверьте text и доступные table metadata.

3. Сверьте заголовки и несколько крайних/сложных ячеек.

4. Если нарушен порядок соседнего текста, сравните другой режим на той же странице.

Ограничение: структурированная таблица не гарантирует пиксельного воспроизведения исходной вёрстки.

Chunking по заголовкам

Цель: получить RAG-chunks без смешивания разделов. Подготовка: проверенные Elements, где реальные заголовки распознаны как Title.

1. Сохраните исходные Elements.

2. Примените chunk_by_title с явными max_characters и new_after_n_chars.

3. Проверьте границы разделов и поведение слишком длинных элементов.

4. Подбирайте размер по embedding-модели и retrieval-проверке, а не по универсальной цифре.

Ограничение: ошибочный Title способен создать слишком маленькие chunks; тогда требуется корректировка partition или параметров объединения.

Навигатор по сбоям

Контроль перед сохранением и передачей

• Оригинал хранится отдельно от производного JSON.

• Проверены element_id, type, text и необходимые metadata.

• Сверены несколько фраз, чисел и имён на разных страницах.

• Для таблиц проверены заголовки и критические ячейки.

• Зафиксированы strategy, OCR-язык и версии окружения.

• Chunking выполняется после проверки partition.

• JSON читается независимым parser; CSV применяется только если допустима потеря вложенности.

• Перед внешней передачей проверена допустимость отправки конфиденциальных данных.

Часто задаваемые вопросы

Unstructured — это программа для открытия PDF?

Нет. Это Python-библиотека, которая извлекает и структурирует содержимое для кода. Для чтения нужен ридер, для визуального редактирования — PDF-редактор.

Нужен ли аккаунт для локальной работы?

Нет. Аккаунт и API-ключ нужны только тогда, когда выбран коммерческий Unstructured API или соседний инструмент, который направляет обработку в него.

Отправляются ли PDF в облако автоматически?

Локальный partition не требует SaaS. В Unstructured Ingest параметр partition_by_api по умолчанию выключен. Но внешний OCR-провайдер или явный API-вызов меняет модель приватности, поэтому проверять нужно фактическую конфигурацию.

Можно ли использовать библиотеку коммерчески?

Core распространяется по Apache License 2.0. Коммерческое использование допускается при соблюдении условий лицензии; тарифы Pipelines не являются лицензией на локальный пакет.

Почему после pip install unstructured не работает PDF?

Минимальная установка не включает полный документный стек. Для PDF нужен соответствующий extra, а для PDF/OCR — системные зависимости вроде Poppler и Tesseract.

Что выбрать: fast, hi_res или ocr_only?

Fast — для PDF с извлекаемым текстом; hi_res — для layout-sensitive задач и таблиц; ocr_only — для сканов, особенно когда нужно отдельно контролировать порядок чтения. Auto подходит как старт, но production-подобный pipeline лучше проверять на своём корпусе.

Есть ли русский интерфейс?

У core-библиотеки нет GUI, поэтому локализация интерфейса неприменима. Язык OCR определяется движком и установленными языковыми данными; их наличие не гарантирует одинаковой точности на всех сканах.

JSON полностью эквивалентен исходному PDF?

Нет. Он хранит распознанный текст, типы и доступные metadata, но не является визуально идентичной копией и может потерять детали макета или содержать OCR-ошибки.

Стоит ли брать core для production?

Разработчик называет open-source библиотеку стартовой точкой для прототипирования. Production-использование возможно как собственное инженерное решение, но оркестрацию, масштабирование, мониторинг, безопасность и regression-тесты придётся обеспечивать самостоятельно.

Вывод

Unstructured 0.27.5 подходит разработчикам, которым нужно превратить PDF, Office-документы, HTML, почту и изображения в единые семантические Elements и подготовить их к ETL, поиску или RAG. Сильные стороны — несколько стратегий PDF, OCR-путь, metadata и chunking поверх структуры документа.

Он не подходит как обычный PDF-ридер, визуальный OCR или редактор: GUI у core нет, а полный стек требует Python, Poppler, Tesseract и других зависимостей. Для чтения Sumatra PDF решает другую задачу; для ручной правки или визуального контроля OCR разумнее специализированное приложение.

Для прототипирования локального document preprocessing выбор оправдан, если команда готова фиксировать окружение и проверять результаты на своём корпусе. Для широкого формата извлечения стоит сравнить Apache Tika, для локальной конвертации в Markdown и единый document model — Docling, для PDF-центричного низкоуровневого контроля — PyMuPDF.