trustgraph/docs/tech-specs/structured-diag-service.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. Сервис извлекает функциональность из существующего инструмента командной строки `tg-load-structured-data` и предоставляет ее в виде сервиса запросов/ответов, обеспечивая программный доступ к возможностям определения типа данных и генерации описаний.

Сервис поддерживает три основные операции:

1. **Определение типа данных**: Анализ образца данных для определения его формата (CSV, JSON или XML).
2. **Генерация описания**: Генерация структурированного описания данных TrustGraph для заданного образца данных и типа.
3. **Комплексная диагностика**: Выполнение как определения типа данных, так и генерации описания последовательно.

## Цели

**Модулизация анализа данных**: Извлечение логики диагностики данных из интерфейса командной строки в многократно используемые компоненты сервиса.
**Обеспечение программного доступа**: Предоставление API для доступа к возможностям анализа данных.
**Поддержка нескольких форматов данных**: Обработка форматов данных CSV, JSON и XML согласованным образом.
**Генерация точных описаний**: Создание структурированных описаний данных, которые точно сопоставляют исходные данные со схемами TrustGraph.
**Сохранение обратной совместимости**: Обеспечение продолжения работы существующей функциональности интерфейса командной строки.
**Обеспечение возможности объединения сервисов**: Предоставление другим сервисам возможности использования возможностей диагностики данных.
**Улучшение тестируемости**: Разделение бизнес-логики от интерфейса командной строки для улучшения тестирования.
**Поддержка потоковой обработки**: Обеспечение возможности анализа образцов данных без загрузки целых файлов.

## Обзор

В настоящее время команда `tg-load-structured-data` предоставляет комплексную функциональность для анализа структурированных данных и генерации описаний. Однако эта функциональность тесно связана с интерфейсом командной строки, что ограничивает ее повторное использование.

Существующие ограничения включают:
Логика диагностики данных, встроенная в код интерфейса командной строки.
Отсутствие программного доступа к определению типа данных и генерации описаний.
Сложность интеграции возможностей диагностики в другие сервисы.
Ограниченная возможность создания рабочих процессов анализа данных.

Эта спецификация решает эти проблемы, создавая специальный сервис для диагностики структурированных данных. Предоставляя эти возможности в виде сервиса, TrustGraph может:
Обеспечить возможность другим сервисам программного анализа данных.
Поддерживать более сложные конвейеры обработки данных.
Облегчить интеграцию с внешними системами.
Улучшить поддерживаемость за счет разделения ответственности.

## Технический дизайн

### Архитектура

Сервису диагностики структурированных данных требуются следующие технические компоненты:

1. **Процессор сервиса диагностики**
   Обрабатывает входящие запросы на диагностику.
   Координирует определение типа данных и генерацию описаний.
   Возвращает структурированные ответы с результатами диагностики.

   Модуль: `trustgraph-flow/trustgraph/diagnosis/structured_data/service.py`

2. **Детектор типа данных**
   Использует алгоритмическое определение для идентификации формата данных (CSV, JSON, XML).
   Анализирует структуру данных, разделители и шаблоны синтаксиса.
   Возвращает определенный формат и коэффициенты достоверности.

   Модуль: `trustgraph-flow/trustgraph/diagnosis/structured_data/type_detector.py`

3. **Генератор описаний**
   Использует сервис запросов для генерации описаний.
   Вызывает специфичные для формата запросы (diagnose-csv, diagnose-json, diagnose-xml).
   Отображает поля данных на поля схемы TrustGraph с помощью ответов запросов.

   Модуль: `trustgraph-flow/trustgraph/diagnosis/structured_data/descriptor_generator.py`

### Модели данных

#### StructuredDataDiagnosisRequest

Сообщение запроса для операций диагностики структурированных данных:

```python
class StructuredDataDiagnosisRequest:
    operation: str  # "detect-type", "generate-descriptor", or "diagnose"
    sample: str     # Data sample to analyze (text content)
    type: Optional[str]  # Data type (csv, json, xml) - required for generate-descriptor
    schema_name: Optional[str]  # Target schema name for descriptor generation
    options: Dict[str, Any]  # Additional options (e.g., delimiter for CSV)
```

#### StructuredDataDiagnosisResponse

Сообщение ответа, содержащее результаты диагностики:

```python
class StructuredDataDiagnosisResponse:
    operation: str  # The operation that was performed
    detected_type: Optional[str]  # Detected data type (for detect-type/diagnose)
    confidence: Optional[float]  # Confidence score for type detection
    descriptor: Optional[Dict]  # Generated descriptor (for generate-descriptor/diagnose)
    error: Optional[str]  # Error message if operation failed
    metadata: Dict[str, Any]  # Additional metadata (e.g., field count, sample records)
```

#### Структура дескриптора

Сгенерированный дескриптор соответствует существующему формату структурированного дескриптора данных:

```json
{
  "format": {
    "type": "csv",
    "encoding": "utf-8",
    "options": {
      "delimiter": ",",
      "has_header": true
    }
  },
  "mappings": [
    {
      "source_field": "customer_id",
      "target_field": "id",
      "transforms": [
        {"type": "trim"}
      ]
    }
  ],
  "output": {
    "schema_name": "customer",
    "options": {
      "batch_size": 1000,
      "confidence": 0.9
    }
  }
}
```

### Интерфейс сервиса

Сервис будет предоставлять следующие операции с использованием шаблона запрос/ответ:

1. **Операция определения типа**
   Входные данные: Образец данных
   Обработка: Анализ структуры данных с использованием алгоритмического определения
   Выходные данные: Определенный тип с уровнем достоверности

2. **Операция генерации дескриптора**
   Входные данные: Образец данных, тип, имя целевой схемы
   Обработка:
     Вызов сервиса запросов с идентификатором запроса, специфичным для формата (diagnose-csv, diagnose-json или diagnose-xml)
     Передача образца данных и доступных схем в запрос
     Получение сгенерированного дескриптора из ответа запроса
   Выходные данные: Структурированный дескриптор данных

3. **Комплексная операция диагностики**
   Входные данные: Образец данных, необязательное имя схемы
   Обработка:
     Использование алгоритмического определения для определения формата
     Выбор соответствующего запроса, специфичного для формата, на основе определенного типа
     Вызов сервиса запросов для генерации дескриптора
   Выходные данные: Определенный тип и дескриптор

### Детали реализации

Сервис будет соответствовать соглашениям сервиса TrustGraph:

1. **Регистрация сервиса**
   Регистрация как сервис типа `structured-diag`
   Использование стандартных тем запросов/ответов
   Реализация базового класса FlowProcessor
   Регистрация PromptClientSpec для взаимодействия с сервисом запросов

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

3. **Интеграция с сервисом запросов**
   Использование существующей инфраструктуры сервиса запросов
   Вызов сервиса запросов с идентификаторами запросов, специфичными для формата:
     `diagnose-csv`: Для анализа данных CSV
     `diagnose-json`: Для анализа данных JSON
     `diagnose-xml`: Для анализа данных XML
   Запросы настроены в конфигурации запросов, а не жестко закодированы в сервисе
   Передача схем и образцов данных в качестве переменных запроса
   Разбор ответов запросов для извлечения дескрипторов

4. **Обработка ошибок**
   Проверка входных образцов данных
   Предоставление описательных сообщений об ошибках
   Обработка некорректных данных
   Обработка сбоев сервиса запросов

5. **Выборка данных**
   Обработка настраиваемых размеров выборки
   Правильная обработка неполных записей
   Поддержание согласованности выборки

### Интеграция с API

Сервис будет интегрирован с существующими API TrustGraph:

Измененные компоненты:
`tg-load-structured-data` CLI - Переработан для использования нового сервиса для операций диагностики
Flow API - Расширен для поддержки запросов структурированной диагностики

Новые конечные точки сервиса:
`/api/v1/flow/{flow}/diagnose/structured-data` - WebSocket конечная точка для запросов диагностики
`/api/v1/diagnose/structured-data` - REST конечная точка для синхронной диагностики

### Поток сообщений

```
Client → Gateway → Structured Diag Service → Config Service (for schemas)
                                           ↓
                                    Type Detector (algorithmic)
                                           ↓
                                    Prompt Service (diagnose-csv/json/xml)
                                           ↓
                                 Descriptor Generator (parses prompt response)
                                           ↓
Client ← Gateway ← Structured Diag Service (response)
```

## Соображения безопасности

Проверка входных данных для предотвращения атак внедрения
Ограничения на размер образцов данных для предотвращения DoS-атак
Очистка сгенерированных описаний
Контроль доступа через существующую аутентификацию TrustGraph

## Соображения производительности

Кэширование определений схемы для уменьшения количества обращений к сервису конфигурации
Ограничение размеров образцов для поддержания отзывчивой производительности
Использование потоковой обработки для больших образцов данных
Реализация механизмов тайм-аута для длительных анализов

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

1. **Модульные тесты**
   Обнаружение типа для различных форматов данных
   Точность генерации описаний
   Сценарии обработки ошибок

2. **Интеграционные тесты**
   Поток запросов/ответов сервиса
   Получение и кэширование схемы
   Интеграция с CLI

3. **Тесты производительности**
   Обработка больших образцов
   Обработка одновременных запросов
   Использование памяти при высокой нагрузке

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

1. **Этап 1**: Реализация сервиса с основной функциональностью
2. **Этап 2**: Рефакторинг CLI для использования сервиса (с сохранением обратной совместимости)
3. **Этап 3**: Добавление REST API
4. **Этап 4**: Отказ от встроенной логики CLI (с предварительным уведомлением)

## График

Неделя 1-2: Реализация основного сервиса и обнаружения типа
Неделя 3-4: Добавление генерации описаний и интеграции
Неделя 5: Тестирование и документация
Неделя 6: Рефакторинг CLI и миграция

## Открытые вопросы

Должен ли сервис поддерживать дополнительные форматы данных (например, Parquet, Avro)?
Каков должен быть максимальный размер образца для анализа?
Следует ли кэшировать результаты диагностики для повторяющихся запросов?
Как сервис должен обрабатывать сценарии с несколькими схемами?
Должны ли идентификаторы запросов быть настраиваемыми параметрами для сервиса?

## Ссылки

[Спецификация структурированного описания данных](structured-data-descriptor.md)
[Документация по загрузке структурированных данных](structured-data.md)
`tg-load-structured-data` реализация: `trustgraph-cli/trustgraph/cli/load_structured_data.py`