mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
260 lines
22 KiB
Markdown
260 lines
22 KiB
Markdown
---
|
||
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, чтобы
|
||
запросы не замедлялись.
|
||
|
||
## Стратегия тестирования
|
||
|
||
Используйте существующую стратегию тестирования, будут созданы модульные,
|
||
контрактные и интеграционные тесты.
|
||
|
||
## План миграции
|
||
|
||
Отсутствует.
|
||
|
||
## Сроки
|
||
|
||
Не указаны.
|
||
|
||
## Открытые вопросы
|
||
|
||
Можно ли сделать так, чтобы это работало с другими типами хранилищ? Мы стремимся
|
||
использовать интерфейсы, которые делают модули, работающие с одним хранилищем,
|
||
применимыми к другим хранилищам.
|
||
|
||
## Ссылки
|