mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
355
docs/tech-specs/extraction-flows.ru.md
Normal file
355
docs/tech-specs/extraction-flows.ru.md
Normal file
|
|
@ -0,0 +1,355 @@
|
|||
---
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue