mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
282 lines
18 KiB
Markdown
282 lines
18 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. Сервис извлекает функциональность из существующего инструмента командной строки `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`
|