trustgraph/docs/tech-specs/extraction-flows.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.

Этот документ описывает, как данные передаются через конвейер извлечения данных TrustGraph, начиная с отправки документов и заканчивая хранением в хранилищах знаний.

## Обзор

```
┌──────────┐     ┌─────────────┐     ┌─────────┐     ┌────────────────────┐
│ Librarian│────▶│ PDF Decoder │────▶│ Chunker │────▶│ Knowledge          │
│          │     │ (PDF only)  │     │         │     │ Extraction         │
│          │────────────────────────▶│         │     │                    │
└──────────┘     └─────────────┘     └─────────┘     └────────────────────┘
                                          │                    │
                                          │                    ├──▶ Triples
                                          │                    ├──▶ Entity Contexts
                                          │                    └──▶ Rows
                                          │
                                          └──▶ Document Embeddings
```

## Хранение контента

### Blob-хранилище (S3/Minio)

Содержимое документов хранится в блочном хранилище, совместимом с S3:
Формат пути: `doc/{object_id}`, где object_id - это UUID
Все типы документов хранятся здесь: исходные документы, страницы, фрагменты

### Хранилище метаданных (Cassandra)

Метаданные документов, хранящиеся в Cassandra, включают:
Идентификатор документа, заголовок, тип (MIME-тип)
Ссылку `object_id` на блочное хранилище
Ссылку `parent_id` для дочерних документов (страниц, фрагментов)
Тип `document_type`: "source", "page", "chunk", "answer"

### Порог для встроенных данных и потоковой передачи

Передача контента использует стратегию, основанную на размере:
**< 2 МБ**: Контент включается непосредственно в сообщение (в кодировке base64)
**≥ 2 МБ**: Отправляется только `document_id`; процессор извлекает данные через API librarian

## Этап 1: Отправка документа (Librarian)

### Точка входа

Документы поступают в систему через операцию `add-document` librarian:
1. Контент загружается в блочное хранилище
2. Создается запись метаданных в Cassandra
3. Возвращается идентификатор документа

### Запуск извлечения

Операция `add-processing` запускает извлечение:
Указывает `document_id`, `flow` (идентификатор конвейера), `collection` (целевое хранилище)
Операция `load_document()` librarian извлекает контент и публикует его в очередь ввода конвейера

### Схема: Document

```
Document
├── metadata: Metadata
│   ├── id: str              # Document identifier
│   ├── user: str            # Tenant/user ID
│   ├── collection: str      # Target collection
│   └── metadata: list[Triple]  # (largely unused, historical)
├── data: bytes              # PDF content (base64, if inline)
└── document_id: str         # Librarian reference (if streaming)
```

**Маршрутизация**: Основана на поле `kind`:
`application/pdf` → очередь `document-load` → Декодер PDF
`text/plain` → очередь `text-load` → Разделитель (Chunker)

## Этап 2: Декодер PDF

Преобразует документы PDF в текстовые страницы.

### Процесс

1. Получение содержимого (встроенное `data` или через `document_id` от библиотекаря)
2. Извлечение страниц с использованием PyPDF
3. Для каждой страницы:
   Сохранение как дочерний документ в библиотеке (`{doc_id}/p{page_num}`)
   Отправка информации о происхождении (страница получена из документа)
   Передача разделителю (chunker)

### Схема: TextDocument

```
TextDocument
├── metadata: Metadata
│   ├── id: str              # Page URI (e.g., https://trustgraph.ai/doc/xxx/p1)
│   ├── user: str
│   ├── collection: str
│   └── metadata: list[Triple]
├── text: bytes              # Page text content (if inline)
└── document_id: str         # Librarian reference (e.g., "doc123/p1")
```

## Этап 3: Разделение на фрагменты

Разделяет текст на фрагменты заданного размера.

### Параметры (настраиваются в процессе выполнения)

`chunk_size`: Целевой размер фрагмента в символах (по умолчанию: 2000)
`chunk_overlap`: Перекрытие между фрагментами (по умолчанию: 100)

### Процесс

1. Получение содержимого текста (встроенного или через библиотеку)
2. Разделение с использованием рекурсивного разделителя символов
3. Для каждого фрагмента:
   Сохранение как дочерний документ в библиотеке (`{parent_id}/c{index}`)
   Вывод информации о происхождении (фрагмент получен из страницы/документа)
   Передача на этапы обработки извлечения

### Схема: Фрагмент

```
Chunk
├── metadata: Metadata
│   ├── id: str              # Chunk URI
│   ├── user: str
│   ├── collection: str
│   └── metadata: list[Triple]
├── chunk: bytes             # Chunk text content
└── document_id: str         # Librarian chunk ID (e.g., "doc123/p1/c3")
```

### Иерархия идентификаторов документов

Дочерние документы кодируют свою родословную в идентификаторе:
Источник: `doc123`
Страница: `doc123/p5`
Часть страницы: `doc123/p5/c2`
Часть текста: `doc123/c2`

## Этап 4: Извлечение знаний

Доступно несколько шаблонов извлечения, выбираемых конфигурацией потока.

### Шаблон A: Базовый GraphRAG

Два параллельных процессора:

**kg-extract-definitions**
Вход: Часть текста
Выход: Тройки (определения сущностей), Контексты сущностей
Извлекает: метки сущностей, определения

**kg-extract-relationships**
Вход: Часть текста
Выход: Тройки (отношения), Контексты сущностей
Извлекает: отношения субъект-предикат-объект

### Шаблон B: Основанный на онтологии (kg-extract-ontology)

Вход: Часть текста
Выход: Тройки, Контексты сущностей
Использует настроенную онтологию для управления извлечением

### Шаблон C: Основанный на агентах (kg-extract-agent)

Вход: Часть текста
Выход: Тройки, Контексты сущностей
Использует агентную платформу для извлечения

### Шаблон D: Извлечение строк (kg-extract-rows)

Вход: Часть текста
Выход: Строки (структурированные данные, а не тройки)
Использует определение схемы для извлечения структурированных записей

### Схема: Тройки

```
Triples
├── metadata: Metadata
│   ├── id: str
│   ├── user: str
│   ├── collection: str
│   └── metadata: list[Triple]  # (set to [] by extractors)
└── triples: list[Triple]
    └── Triple
        ├── s: Term              # Subject
        ├── p: Term              # Predicate
        ├── o: Term              # Object
        └── g: str | None        # Named graph
```

### Схема: EntityContexts

```
EntityContexts
├── metadata: Metadata
└── entities: list[EntityContext]
    └── EntityContext
        ├── entity: Term         # Entity identifier (IRI)
        ├── context: str         # Textual description for embedding
        └── chunk_id: str        # Source chunk ID (provenance)
```

### Схема: Строки

```
Rows
├── metadata: Metadata
├── row_schema: RowSchema
│   ├── name: str
│   ├── description: str
│   └── fields: list[Field]
└── rows: list[dict[str, str]]   # Extracted records
```

## Этап 5: Генерация векторных представлений (эмбеддингов)

### Векторные представления графа

Преобразует контексты сущностей в векторные представления.

**Процесс:**
1. Получение контекстов сущностей (EntityContexts)
2. Вызов сервиса генерации векторных представлений с текстом контекста
3. Вывод векторных представлений графа (отображение сущности во вектор)

**Схема: Векторные представления графа (GraphEmbeddings)**

```
GraphEmbeddings
├── metadata: Metadata
└── entities: list[EntityEmbeddings]
    └── EntityEmbeddings
        ├── entity: Term         # Entity identifier
        ├── vector: list[float]  # Embedding vector
        └── chunk_id: str        # Source chunk (provenance)
```

### Векторные представления документов

Преобразует текстовые фрагменты непосредственно в векторные представления.

**Процесс:**
1. Получение фрагмента текста
2. Вызов сервиса векторизации с текстом фрагмента
3. Вывод векторного представления документа

**Схема: Векторное представление документа**

```
DocumentEmbeddings
├── metadata: Metadata
└── chunks: list[ChunkEmbeddings]
    └── ChunkEmbeddings
        ├── chunk_id: str        # Chunk identifier
        └── vector: list[float]  # Embedding vector
```

### Встраивания строк

Преобразует поля индекса строк в векторные представления.

**Процесс:**
1. Получение строк
2. Встраивание настроенных полей индекса
3. Вывод в хранилище векторов строк

## Этап 6: Хранение

### Тройной магазин

Получает: Тройки
Хранение: Cassandra (таблицы, ориентированные на сущности)
Именованные графы разделяют основные знания от информации об источнике:
  `""` (по умолчанию): Факты основных знаний
  `urn:graph:source`: Информация об источнике извлечения
  `urn:graph:retrieval`: Объяснимость во время запроса

### Хранилище векторов (Встраивания графов)

Получает: Встраивания графов
Хранение: Qdrant, Milvus или Pinecone
Индексируется по: IRI сущности
Метаданные: chunk_id для информации об источнике

### Хранилище векторов (Встраивания документов)

Получает: Встраивания документов
Хранение: Qdrant, Milvus или Pinecone
Индексируется по: chunk_id

### Хранилище строк

Получает: Строки
Хранение: Cassandra
Структура таблицы, определяемая схемой

### Хранилище векторов строк

Получает: Встраивания строк
Хранение: Векторная база данных
Индексируется по: полям индекса строк

## Анализ полей метаданных

### Активно используемые поля

| Поле | Использование |
|-------|-------|
| `metadata.id` | Идентификатор документа/фрагмента, ведение журнала, информация об источнике |
| `metadata.user` | Многопользовательский режим, маршрутизация хранения |
| `metadata.collection` | Выбор целевой коллекции |
| `document_id` | Ссылка на библиотекаря, связывание с информацией об источнике |
| `chunk_id` | Отслеживание информации об источнике через конвейер |

<<<<<<< HEAD
### Потенциально избыточные поля

| Поле | Статус |
|-------|--------|
| `metadata.metadata` | Устанавливается в `[]` всеми извлекателями; метаданные на уровне документа теперь обрабатываются библиотекарем при отправке |
=======
### Удаленные поля

| Поле | Статус |
|-------|--------|
| `metadata.metadata` | Удалено из класса `Metadata`. Тройки метаданных на уровне документа теперь напрямую выдаются библиотекарем в тройной магазин при отправке, а не передаются через конвейер извлечения. |
>>>>>>> e3bcbf73 (The metadata field (list of triples) in the pipeline Metadata class)

### Шаблон полей байтов

Все поля содержимого (`data`, `text`, `chunk`) являются `bytes`, но немедленно декодируются в строки UTF-8 всеми процессорами. Ни один процессор не использует необработанные байты.

## Конфигурация потока

Потоки определяются внешне и предоставляются библиотекарию через сервис конфигурации. Каждый поток определяет:

Входные очереди (`text-load`, `document-load`)
Цепочка процессоров
Параметры (размер фрагмента, метод извлечения и т. д.)

Пример шаблонов потоков:
`pdf-graphrag`: PDF → Decoder → Chunker → Definitions + Relationships → Embeddings
`text-graphrag`: Text → Chunker → Definitions + Relationships → Embeddings
`pdf-ontology`: PDF → Decoder → Chunker → Ontology Extraction → Embeddings
`text-rows`: Text → Chunker → Row Extraction → Row Store