trustgraph/docs/tech-specs/structured-data.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 с потоками структурированных данных, что позволяет системе работать с данными, которые могут быть представлены в виде строк в таблицах или объектов в хранилищах объектов. Интеграция поддерживает четыре основных сценария использования:

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, чтобы
запросы не замедлялись.

## Стратегия тестирования

Используйте существующую стратегию тестирования, будут созданы модульные,
контрактные и интеграционные тесты.

## План миграции

Отсутствует.

## Сроки

Не указаны.

## Открытые вопросы
  
  Можно ли сделать так, чтобы это работало с другими типами хранилищ? Мы стремимся
использовать интерфейсы, которые делают модули, работающие с одним хранилищем,
применимыми к другим хранилищам.

## Ссылки