trustgraph/docs/tech-specs/universal-decoder.ru.md

---
layout: default
title: "Универсальный Декодер Документов"
parent: "Russian (Beta)"
---

# Универсальный Декодер Документов

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## Заголовок

Универсальный декодер документов, работающий на базе `unstructured` — извлекает любые распространенные форматы документов через единый сервис, обеспечивая полную отслеживаемость и интеграцию с библиотекой, регистрируя позиции источника в качестве метаданных графа знаний для обеспечения полной отслеживаемости.

## Проблема

В настоящее время TrustGraph имеет декодер, специфичный для PDF. Поддержка дополнительных форматов (DOCX, XLSX, PPTX и т.д.) требует значительных изменений.

## Решение

Мы предлагаем универсальный декодер, который будет поддерживать широкий спектр форматов документов. Этот декодер будет использовать библиотеку `unstructured` для извлечения текста и метаданных из документов.

## Архитектура

Универсальный декодер будет состоять из следующих компонентов:

*   **Входной компонент:** Принимает документ в качестве входных данных.
*   **Компонент извлечения:** Использует библиотеку `unstructured` для извлечения текста и метаданных из документа.
*   **Компонент формирования provenance:** Генерирует provenance-данные, которые содержат информацию о том, откуда взялся каждый фрагмент текста.
*   **Компонент выходных данных:** Выдает извлеченные данные и provenance-данные.

## Процесс

1.  Декодер получает документ в качестве входных данных.
2.  Декодер использует библиотеку `unstructured` для извлечения текста и метаданных из документа.
3.  Декодер генерирует provenance-данные, которые содержат информацию о том, откуда взялся каждый фрагмент текста.
4.  Декодер выдает извлеченные данные и provenance-данные.

## Форматы Документов

| Формат | MIME-тип | Поддержка страниц | Примечания |
|---|---|---|---|
| PDF | application/pdf | Да | Группировка по страницам |
| DOCX | application/vnd.openxmlformats... | Нет | Использование стратегии секций |
| PPTX | application/vnd.openxmlformats... | Да | Группировка по слайдам |
| XLSX/XLS | application/vnd.openxmlformats... | Да | Группировка по листам |
| HTML | text/html | Нет | Использование стратегии секций |
| Markdown | text/markdown | Нет | Использование стратегии секций |
| Plain | text/plain | Нет | Использование стратегии секций |
| CSV | text/csv | Нет | Использование стратегии секций |
| RST | text/x-rst | Нет | Использование стратегии секций |
| RTF | application/rtf | Нет | Использование стратегии секций |
| ODT | application/vnd.oasis... | Нет | Использование стратегии секций |
| TSV | text/tab-separated-values | Нет | Использование стратегии секций |

## Метаданные Provenance

Каждая сущность страницы/секции регистрирует метаданные о позиции в виде triple в `GRAPH_SOURCE`, обеспечивая полную отслеживаемость от triple в графе знаний обратно к исходным позициям в документе.

#### Существующие поля (уже в `derived_entity_triples`)

*   `page_number` — номер страницы/листа/слайда (1-indexed, только для страниц)
*   `char_offset` — смещение символов для этой страницы/секции в полном тексте
*   `char_length` — длина текста для этой страницы/секции в документе

#### Новые поля (расширяем `derived_entity_triples`)

*   `mime_type` — исходный формат документа (например, `application/pdf`)
*   `element_types` — список категорий элементов `unstructured`, найденных на этой странице/секции (например, "Title,NarrativeText,Table")
*   `table_count` — количество таблиц на этой странице/секции
*   `image_count` — количество изображений на этой странице/секции

Эти требуют новых префиксов пространства имен TG:

```
TG_SECTION_TYPE  = "https://trustgraph.ai/ns/Section"
TG_IMAGE_TYPE    = "https://trustgraph.ai/ns/Image"
TG_ELEMENT_TYPES = "https://trustgraph.ai/ns/elementTypes"
TG_TABLE_COUNT   = "https://trustgraph.ai/ns/tableCount"
TG_IMAGE_COUNT   = "https://trustgraph.ai/ns/imageCount"
```

Схема URN для изображений: `urn:image:{uuid}`

(`TG_MIME_TYPE` уже существует.)

#### Новый тип сущности

Для не-страничных форматов (DOCX, HTML, Markdown и т.д.), где декодер выдает весь документ в виде одной сущности, тип сущности становится:

```
TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
```

Это отличает секции от страниц при запросе provenance:

| Entity | Type | Когда используется |
|---|---|---|
| Document | `tg:Document` | Оригинальный загруженный файл |
| Page | `tg:Page` | Для page-based форматов (PDF, PPTX, XLSX) |
| Section | `tg:Section` | Для не-page форматов (DOCX, HTML, MD и т.д.) |
| Image | `tg:Image` | Встроенные изображения (сохранены, не обрабатываются) |
| Chunk | `tg:Chunk` | Выход из chunker |
| Subgraph | `tg:Subgraph` | Выход из extraции KG |

Тип устанавливается декодером в зависимости от группировки по страницам или выдачи всей документа в виде одной сущности. `derived_entity_triples` добавляет необязательный параметр `section` — если он установлен, сущность имеет тип `tg:Section` вместо `tg:Page`.

#### Полная цепочка provenance

```
Triple KG
  → subgraph (provenance)
    → chunk (char_offset, char_length within page)
      → page/section (page_number, char_offset, char_length within doc, mime_type, element_types)
        → document (оригинальный файл в librarian)
```

Каждый линк — это набор triple в графе `GRAPH_SOURCE`.

## Конфигурация Сервиса

Аргументы командной строки:

```
--strategy            Стратегия партиционирования: auto, hi_res, fast (по умолчанию: auto)
--languages           Разделенные кодами OCR (по умолчанию: eng)
--section-strategy     Группировка секций: whole-document, heading, element-type,
                        count, size (по умолчанию: whole-document)
--section-element-count Элементы на секцию для 'count' strategy (по умолчанию: 20)
--section-max-size      Макс. символов на секцию для 'size' strategy (по умолчанию: 4000)
--section-within-pages  Применение стратегии секций также для страниц (по умолчанию: false)
```

Кроме стандартных аргументов для `FlowProcessor` и очереди librarian.

## Интеграция с Flow

Универсальный декодер занимает ту же позицию в потоке обработки, что и существующий декодер PDF:

```
Document → [universal-decoder] → TextDocument → [chunker] → Chunk → ...
```

Он регистрирует:
*   Консумент `input` (схема Document)
*   Производитель `output` (схема TextDocument)
*   Производитель `triples` (схема)
*   Запросы/отзывы к librarian (для fetch и хранения child document)

## Развертывание

*   Новый контейнер: `trustgraph-flow-universal-decoder`
*   Зависимость: `unstructured[all-docs]` (включает PDF, DOCX, PPTX и т.д.)
*   Можно запускать параллельно или заменять существующий декодер PDF, в зависимости от конфигурации потока
*   Существующий декодер PDF остается доступным, если зависимости `unstructured` слишком велики

## Изменения

| Компонент | Изменение |
|---|---|
| `provenance/namespaces.py` | Добавить `TG_SECTION_TYPE`, `TG_IMAGE_TYPE`, `TG_ELEMENT_TYPES`, `TG_TABLE_COUNT`, `TG_IMAGE_COUNT` |
| `provenance/triples.py` | Добавить параметры `mime_type`, `element_types`, `table_count`, `image_count` |
| `provenance/__init__.py` | Экспортировать новые константы |
| Новый: `decoding/universal/` | Новый модуль сервиса |
| `setup.cfg` / `pyproject` | Добавить зависимость `unstructured[all-docs]` |
| Docker | Новый образ контейнера |
| Flow definitions |  |

## Что не меняется

*   Chunker (принимает TextDocument, работает как раньше)
*   Downstream extractors (принимают Chunk, без изменений)
*   Librarian (хранит child document, без изменений)
*   Схема (Document, TextDocument, Chunk без изменений)
*   Запрос provenance (без изменений)

## Риски

*   `unstructured[all-docs]` имеет тяжелые зависимости (poppler, tesseract, libreoffice для некоторых форматов)
*   Необходимы значительные изменения.

## Преимущества

*   Поддержка широкого спектра форматов документов
*   Использование библиотеки `unstructured` для извлечения текста и метаданных
*   Генерация provenance-данных
*   Возможность интеграции с существующей системой обработки документов

## Дополнительные Замечания

*   Эта архитектура требует тщательного тестирования и оптимизации.
*   Необходимо учитывать производительность при обработке больших документов.
*   Важно обеспечить совместимость с существующими системами обработки документов.
*   Следует использовать возможности библиотеки `unstructured` для оптимизации извлечения текста.
*   Необходимо провести анализ требований к производительности и выбрать оптимальную конфигурацию.
*   Необходимо обеспечить безопасность при обработке конфиденциальных данных.

## Заключение

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