mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
281 lines
18 KiB
Markdown
281 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`
|