mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
281
docs/tech-specs/structured-diag-service.ru.md
Normal file
281
docs/tech-specs/structured-diag-service.ru.md
Normal file
|
|
@ -0,0 +1,281 @@
|
|||
---
|
||||
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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue