apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-04-26 08:56:21 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Structure the tech specs directory (#836)

Browse source 
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon 2026-04-21 16:06:41 +01:00 • committed by GitHub
parent 48da6c5f8b
commit e7efb673ef
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
423 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

200
docs/tech-specs/ru/universal-decoder.ru.md Normal file
View file

@ -0,0 +1,200 @@
---
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` для оптимизации извлечения текста.
* Необходимо провести анализ требований к производительности и выбрать оптимальную конфигурацию.
* Необходимо обеспечить безопасность при обработке конфиденциальных данных.
## Заключение
Предлагаемая архитектура универсального декодера представляет собой мощное решение для обработки широкого спектра форматов документов. Она обеспечивает гибкость, масштабируемость и возможность интеграции с существующими системами. При правильной реализации и тестировании, эта архитектура позволит эффективно извлекать данные из различных источников и использовать их в аналитических целях.