mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
260
docs/tech-specs/ru/structured-data.ru.md
Normal file
260
docs/tech-specs/ru/structured-data.ru.md
Normal file
|
|
@ -0,0 +1,260 @@
|
|||
---
|
||||
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 с потоками структурированных данных, что позволяет системе работать с данными, которые могут быть представлены в виде строк в таблицах или объектов в хранилищах объектов. Интеграция поддерживает четыре основных сценария использования:
|
||||
|
||||
1. **Извлечение неструктурированных данных в структурированные**: Чтение неструктурированных источников данных, выявление и извлечение объектных структур и хранение их в табличном формате.
|
||||
2. **Импорт структурированных данных**: Загрузка данных, которые уже находятся в структурированных форматах, непосредственно в структурированное хранилище вместе с извлеченными данными.
|
||||
3. **Запросы на естественном языке**: Преобразование вопросов, заданных на естественном языке, в структурированные запросы для извлечения соответствующих данных из хранилища.
|
||||
4. **Прямые структурированные запросы**: Выполнение структурированных запросов непосредственно к хранилищу данных для точного извлечения данных.
|
||||
|
||||
## Цели
|
||||
|
||||
**Унифицированный доступ к данным**: Предоставление единого интерфейса для доступа как к структурированным, так и к неструктурированным данным в TrustGraph.
|
||||
**Бесшовная интеграция**: Обеспечение плавного взаимодействия между графовым представлением знаний TrustGraph и традиционными форматами структурированных данных.
|
||||
**Гибкое извлечение**: Поддержка автоматического извлечения структурированных данных из различных неструктурированных источников (документов, текста и т.д.).
|
||||
**Универсальность запросов**: Предоставление пользователям возможности выполнять запросы к данным как на естественном языке, так и с использованием структурированных языков запросов.
|
||||
**Согласованность данных**: Поддержание целостности и согласованности данных в различных представлениях.
|
||||
**Оптимизация производительности**: Обеспечение эффективного хранения и извлечения структурированных данных в масштабе.
|
||||
**Гибкость схемы**: Поддержка как подходов "схема при записи", так и "схема при чтении" для адаптации к различным источникам данных.
|
||||
**Обратная совместимость**: Сохранение существующей функциональности TrustGraph при добавлении возможностей работы со структурированными данными.
|
||||
|
||||
## Предыстория
|
||||
|
||||
В настоящее время TrustGraph отлично справляется с обработкой неструктурированных данных и построением графов знаний из различных источников. Однако, многие корпоративные сценарии использования включают данные, которые изначально являются структурированными - записи о клиентах, журналы транзакций, базы данных инвентаризации и другие табличные наборы данных. Эти структурированные наборы данных часто необходимо анализировать вместе с неструктурированным контентом для получения всесторонних сведений.
|
||||
|
||||
Текущие ограничения включают:
|
||||
Отсутствие встроенной поддержки импорта данных в предварительно структурированных форматах (CSV, массивы JSON, экспорты баз данных).
|
||||
Невозможность сохранения исходной структуры при извлечении табличных данных из документов.
|
||||
Отсутствие эффективных механизмов запросов для структурированных данных.
|
||||
Отсутствие моста между запросами, похожими на SQL, и графовыми запросами TrustGraph.
|
||||
|
||||
Эта спецификация решает эти проблемы, вводя слой структурированных данных, который дополняет существующие возможности TrustGraph. Поддерживая структурированные данные нативно, TrustGraph может:
|
||||
Служить унифицированной платформой для анализа как структурированных, так и неструктурированных данных.
|
||||
Обеспечивать гибридные запросы, охватывающие как графовые отношения, так и табличные данные.
|
||||
Предоставлять знакомые интерфейсы для пользователей, привыкших работать со структурированными данными.
|
||||
Открывать новые сценарии использования в интеграции данных и бизнес-аналитике.
|
||||
|
||||
## Технический дизайн
|
||||
|
||||
### Архитектура
|
||||
|
||||
Интеграция структурированных данных требует следующих технических компонентов:
|
||||
|
||||
1. **Сервис преобразования естественного языка в структурированные запросы**
|
||||
Преобразует вопросы, заданные на естественном языке, в структурированные запросы.
|
||||
Поддерживает несколько целевых языков запросов (изначально синтаксис, похожий на SQL).
|
||||
Интегрируется с существующими возможностями NLP TrustGraph.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/query/nlp_query/cassandra
|
||||
|
||||
2. **Поддержка схемы конфигурации** ✅ **[ПОЛНО]**
|
||||
Расширенная система конфигурации для хранения схем структурированных данных.
|
||||
Поддержка определения структуры таблиц, типов полей и взаимосвязей.
|
||||
Возможности версионирования и миграции схем.
|
||||
|
||||
3. **Модуль извлечения объектов** ✅ **[ПОЛНО]**
|
||||
Улучшенная интеграция потока извлечения знаний.
|
||||
Определяет и извлекает структурированные объекты из неструктурированных источников.
|
||||
Сохраняет информацию о происхождении и коэффициенты уверенности.
|
||||
Регистрирует обработчик конфигурации (например: trustgraph-flow/trustgraph/prompt/template/service.py) для получения данных конфигурации и декодирования информации о схеме.
|
||||
Получает объекты и декодирует их в объекты ExtractedObject для передачи в очередь Pulsar.
|
||||
ВАЖНО: Существует существующий код по адресу `trustgraph-flow/trustgraph/extract/object/row/`. Это была предыдущая попытка, и его потребуется серьезно переработать, поскольку он не соответствует текущим API. Используйте его, если это полезно, начните с нуля, если нет.
|
||||
Требуется интерфейс командной строки: `kg-extract-objects`
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/extract/kg/objects/
|
||||
|
||||
4. **Модуль записи структурированных данных** ✅ **[ПОЛНО]**
|
||||
Получает объекты в формате ExtractedObject из очередей Pulsar.
|
||||
Первоначальная реализация, ориентированная на Apache Cassandra в качестве хранилища структурированных данных.
|
||||
Обрабатывает динамическое создание таблиц на основе обнаруженных схем.
|
||||
Управляет сопоставлением схем и таблиц Cassandra и преобразованием данных.
|
||||
Предоставляет операции пакетной и потоковой записи для оптимизации производительности.
|
||||
Не имеет выходных данных Pulsar - это терминальный сервис в потоке данных.
|
||||
|
||||
**Обработка схем**:
|
||||
Отслеживает входящие сообщения ExtractedObject на наличие ссылок на схемы.
|
||||
При первом обнаружении новой схемы автоматически создает соответствующую таблицу Cassandra.
|
||||
Поддерживает кэш известных схем, чтобы избежать повторных попыток создания таблиц.
|
||||
Следует рассмотреть, следует ли получать определения схем напрямую или полагаться на имена схем в сообщениях ExtractedObject.
|
||||
|
||||
**Сопоставление таблиц Cassandra**:
|
||||
Имя пространства ключей (keyspace) берется из поля `user` из метаданных объекта ExtractedObject.
|
||||
Имя таблицы берется из поля `schema_name` объекта ExtractedObject.
|
||||
Коллекция из метаданных становится частью ключа секции (partition key) для обеспечения:
|
||||
Естественного распределения данных между узлами Cassandra.
|
||||
Эффективных запросов внутри определенной коллекции.
|
||||
Логической изоляции между различными импортами данных/источниками.
|
||||
Структура первичного ключа: `PRIMARY KEY ((collection, <schema_primary_key_fields>), <clustering_keys>)`.
|
||||
Коллекция всегда является первым компонентом ключа секции.
|
||||
Поля, определенные в схеме, следуют за первичным ключом в виде составного ключа секции.
|
||||
Это требует, чтобы запросы указывали коллекцию, что обеспечивает предсказуемую производительность.
|
||||
Определение полей сопоставляется с столбцами Cassandra с преобразованием типов:
|
||||
`string` → `text`.
|
||||
`integer` → `int` или `bigint` в зависимости от размера.
|
||||
`float` → `float` или `double` в зависимости от требуемой точности.
|
||||
`boolean` → `boolean`.
|
||||
`timestamp` → `timestamp`.
|
||||
`enum` → `text` с проверкой на уровне приложения.
|
||||
Индексированные поля создают вторичные индексы Cassandra (за исключением полей, которые уже находятся в первичном ключе).
|
||||
Обязательные поля проверяются на уровне приложения (Cassandra не поддерживает NOT NULL).
|
||||
|
||||
**Хранилище объектов**:
|
||||
Извлекает значения из карты ExtractedObject.values.
|
||||
Выполняет преобразование типов и проверку перед вставкой.
|
||||
Обрабатывает отсутствующие необязательные поля корректно.
|
||||
Поддерживает метаданные об источнике объекта (исходный документ, показатели достоверности).
|
||||
Поддерживает идемпотентные записи для обработки сценариев повторной отправки сообщений.
|
||||
|
||||
**Примечания к реализации**:
|
||||
Существующий код, расположенный по адресу `trustgraph-flow/trustgraph/storage/objects/cassandra/`, устарел и не соответствует текущим API.
|
||||
Следует использовать `trustgraph-flow/trustgraph/storage/triples/cassandra` в качестве примера работающего процессора хранилища.
|
||||
Необходимо оценить существующий код на предмет наличия компонентов, которые можно повторно использовать, прежде чем принимать решение о рефакторинге или переписывании.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/storage/objects/cassandra
|
||||
|
||||
5. **Сервис структурированных запросов** ✅ **[ЗАВЕРШЕНО]**
|
||||
Принимает структурированные запросы в определенных форматах.
|
||||
Выполняет запросы к структурированному хранилищу.
|
||||
Возвращает объекты, соответствующие критериям запроса.
|
||||
Поддерживает постраничную выдачу и фильтрацию результатов.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/query/objects/cassandra
|
||||
|
||||
6. **Интеграция с инструментами агентов**:
|
||||
Новый класс инструмента для фреймворков агентов.
|
||||
Позволяет агентам выполнять запросы к структурированным хранилищам данных.
|
||||
Предоставляет интерфейсы структурированных запросов и запросов на естественном языке.
|
||||
Интегрируется с существующими процессами принятия решений агентами.
|
||||
|
||||
7. **Сервис приема структурированных данных**:
|
||||
Принимает структурированные данные в нескольких форматах (JSON, CSV, XML).
|
||||
Разбирает и проверяет входящие данные в соответствии с определенными схемами.
|
||||
Преобразует данные в нормализованные потоки объектов.
|
||||
Отправляет объекты в соответствующие очереди сообщений для обработки.
|
||||
Поддерживает массовую загрузку и потоковую передачу данных.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/decoding/structured
|
||||
|
||||
8. **Сервис встраивания объектов**:
|
||||
Генерирует векторные представления для структурированных объектов.
|
||||
Обеспечивает семантический поиск по структурированным данным.
|
||||
Поддерживает гибридный поиск, сочетающий структурированные запросы с семантической схожестью.
|
||||
Интегрируется с существующими векторными хранилищами.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant
|
||||
|
||||
### Модели данных
|
||||
|
||||
#### Механизм хранения схем
|
||||
|
||||
Схемы хранятся в системе конфигурации TrustGraph со следующей структурой:
|
||||
|
||||
**Тип**: `schema` (фиксированное значение для всех схем структурированных данных).
|
||||
**Ключ**: Уникальное имя/идентификатор схемы (например, `customer_records`, `transaction_log`).
|
||||
**Значение**: Определение схемы JSON, содержащее структуру.
|
||||
|
||||
Пример записи конфигурации:
|
||||
```
|
||||
Type: schema
|
||||
Key: customer_records
|
||||
Value: {
|
||||
"name": "customer_records",
|
||||
"description": "Customer information table",
|
||||
"fields": [
|
||||
{
|
||||
"name": "customer_id",
|
||||
"type": "string",
|
||||
"primary_key": true
|
||||
},
|
||||
{
|
||||
"name": "name",
|
||||
"type": "string",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "email",
|
||||
"type": "string",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "registration_date",
|
||||
"type": "timestamp"
|
||||
},
|
||||
{
|
||||
"name": "status",
|
||||
"type": "string",
|
||||
"enum": ["active", "inactive", "suspended"]
|
||||
}
|
||||
],
|
||||
"indexes": ["email", "registration_date"]
|
||||
}
|
||||
```
|
||||
|
||||
Этот подход позволяет:
|
||||
Динамическое определение схемы без внесения изменений в код
|
||||
Простое обновление и версионирование схемы
|
||||
Последовательная интеграция с существующим управлением конфигурацией TrustGraph
|
||||
Поддержка нескольких схем в рамках одного развертывания
|
||||
|
||||
### API
|
||||
|
||||
Новые API:
|
||||
Схемы Pulsar для вышеперечисленных типов
|
||||
Интерфейсы Pulsar в новых потоках
|
||||
Необходим способ указания типов схем в потоках, чтобы потоки знали, какие
|
||||
типы схем загружать
|
||||
API добавлены в шлюз и обратный шлюз
|
||||
|
||||
Измененные API:
|
||||
Конечные точки извлечения знаний - Добавлена опция структурированного объектного вывода
|
||||
Конечные точки агентов - Добавлена поддержка инструментов для структурированных данных
|
||||
|
||||
### Детали реализации
|
||||
|
||||
В соответствии с существующими соглашениями - это просто новые модули обработки.
|
||||
Все находится в пакетах trustgraph-flow, за исключением элементов схемы,
|
||||
находящихся в trustgraph-base.
|
||||
|
||||
Требуется некоторая работа в пользовательском интерфейсе Workbench, чтобы
|
||||
продемонстрировать / протестировать эту
|
||||
возможность.
|
||||
|
||||
## Вопросы безопасности
|
||||
|
||||
Нет дополнительных соображений.
|
||||
|
||||
## Вопросы производительности
|
||||
|
||||
Некоторые вопросы, касающиеся использования запросов и индексов Cassandra, чтобы
|
||||
запросы не замедлялись.
|
||||
|
||||
## Стратегия тестирования
|
||||
|
||||
Используйте существующую стратегию тестирования, будут созданы модульные,
|
||||
контрактные и интеграционные тесты.
|
||||
|
||||
## План миграции
|
||||
|
||||
Отсутствует.
|
||||
|
||||
## Сроки
|
||||
|
||||
Не указаны.
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
Можно ли сделать так, чтобы это работало с другими типами хранилищ? Мы стремимся
|
||||
использовать интерфейсы, которые делают модули, работающие с одним хранилищем,
|
||||
применимыми к другим хранилищам.
|
||||
|
||||
## Ссылки
|
||||
Loading…
Add table
Add a link
Reference in a new issue