mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
8954fa3ad7
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.
281 lines
12 KiB
Markdown
281 lines
12 KiB
Markdown
---
|
|
layout: default
|
|
title: "Especificação Técnica do Serviço de Diagnóstico de Dados Estruturados"
|
|
parent: "Portuguese (Beta)"
|
|
---
|
|
|
|
# Especificação Técnica do Serviço de Diagnóstico de Dados Estruturados
|
|
|
|
> **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.
|
|
|
|
## Visão Geral
|
|
|
|
Esta especificação descreve um novo serviço invocável para diagnosticar e analisar dados estruturados dentro do TrustGraph. O serviço extrai a funcionalidade da ferramenta de linha de comando existente `tg-load-structured-data` e a expõe como um serviço de solicitação/resposta, permitindo o acesso programático às capacidades de detecção de tipo de dados e geração de descritores.
|
|
|
|
O serviço suporta três operações principais:
|
|
|
|
1. **Detecção de Tipo de Dados**: Analisa uma amostra de dados para determinar seu formato (CSV, JSON ou XML)
|
|
2. **Geração de Descritor**: Gera um descritor de dados estruturados do TrustGraph para uma determinada amostra de dados e tipo
|
|
3. **Diagnóstico Combinado**: Realiza a detecção de tipo e a geração de descritor em sequência
|
|
|
|
## Objetivos
|
|
|
|
**Modularização da Análise de Dados**: Extrai a lógica de diagnóstico de dados da CLI para componentes de serviço reutilizáveis
|
|
**Habilitar Acesso Programático**: Fornecer acesso baseado em API às capacidades de análise de dados
|
|
**Suportar Múltiplos Formatos de Dados**: Lidar com formatos de dados CSV, JSON e XML de forma consistente
|
|
**Gerar Descritores Precisos**: Produzir descritores de dados estruturados que mapeiem com precisão os dados de origem para os esquemas do TrustGraph
|
|
**Manter a Compatibilidade com Versões Anteriores**: Garantir que a funcionalidade existente da CLI continue a funcionar
|
|
**Habilitar a Composição de Serviços**: Permitir que outros serviços aproveitem as capacidades de diagnóstico de dados
|
|
**Melhorar a Testabilidade**: Separar a lógica de negócios da interface da CLI para melhor teste
|
|
**Suportar a Análise em Streaming**: Permitir a análise de amostras de dados sem carregar arquivos inteiros
|
|
|
|
## Contexto
|
|
|
|
Atualmente, o comando `tg-load-structured-data` fornece funcionalidade abrangente para analisar dados estruturados e gerar descritores. No entanto, essa funcionalidade está fortemente acoplada à interface da CLI, limitando sua reutilização.
|
|
|
|
As limitações atuais incluem:
|
|
Lógica de diagnóstico de dados incorporada no código da CLI
|
|
Sem acesso programático à detecção de tipo e à geração de descritores
|
|
Difícil integrar as capacidades de diagnóstico em outros serviços
|
|
Capacidade limitada de compor fluxos de trabalho de análise de dados
|
|
|
|
Esta especificação aborda essas lacunas, criando um serviço dedicado para o diagnóstico de dados estruturados. Ao expor essas capacidades como um serviço, o TrustGraph pode:
|
|
Permitir que outros serviços analisem dados programaticamente
|
|
Suportar pipelines de processamento de dados mais complexos
|
|
Facilitar a integração com sistemas externos
|
|
Melhorar a manutenção por meio da separação de responsabilidades
|
|
|
|
## Design Técnico
|
|
|
|
### Arquitetura
|
|
|
|
O serviço de diagnóstico de dados estruturados requer os seguintes componentes técnicos:
|
|
|
|
1. **Processador do Serviço de Diagnóstico**
|
|
Lida com solicitações de diagnóstico recebidas
|
|
Orquestra a detecção de tipo e a geração de descritores
|
|
Retorna respostas estruturadas com os resultados do diagnóstico
|
|
|
|
Módulo: `trustgraph-flow/trustgraph/diagnosis/structured_data/service.py`
|
|
|
|
2. **Detector de Tipo de Dados**
|
|
Usa a detecção algorítmica para identificar o formato de dados (CSV, JSON, XML)
|
|
Analisa a estrutura de dados, delimitadores e padrões de sintaxe
|
|
Retorna o formato detectado e as pontuações de confiança
|
|
|
|
Módulo: `trustgraph-flow/trustgraph/diagnosis/structured_data/type_detector.py`
|
|
|
|
3. **Gerador de Descritores**
|
|
Usa o serviço de prompt para gerar descritores
|
|
Invoca prompts específicos do formato (diagnosticar-csv, diagnosticar-json, diagnosticar-xml)
|
|
Mapeia campos de dados para campos de esquema do TrustGraph por meio de respostas de prompt
|
|
|
|
Módulo: `trustgraph-flow/trustgraph/diagnosis/structured_data/descriptor_generator.py`
|
|
|
|
### Modelos de Dados
|
|
|
|
#### StructuredDataDiagnosisRequest
|
|
|
|
Mensagem de solicitação para operações de diagnóstico de dados estruturados:
|
|
|
|
```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
|
|
|
|
Mensagem de resposta contendo os resultados do diagnóstico:
|
|
|
|
```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)
|
|
```
|
|
|
|
#### Estrutura do Descritor
|
|
|
|
O descritor gerado segue o formato existente de descritor de dados estruturados:
|
|
|
|
```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
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Interface de Serviço
|
|
|
|
O serviço exporá as seguintes operações através do padrão de solicitação/resposta:
|
|
|
|
1. **Operação de Detecção de Tipo**
|
|
Entrada: Amostra de dados
|
|
Processamento: Analisar a estrutura de dados usando detecção algorítmica
|
|
Saída: Tipo detectado com pontuação de confiança
|
|
|
|
2. **Operação de Geração de Descritor**
|
|
Entrada: Amostra de dados, tipo, nome do esquema de destino
|
|
Processamento:
|
|
Chamar o serviço de prompt com o ID de prompt específico do formato (diagnosticar-csv, diagnosticar-json ou diagnosticar-xml)
|
|
Passar a amostra de dados e os esquemas disponíveis para o prompt
|
|
Receber o descritor gerado da resposta do prompt
|
|
Saída: Descritor de dados estruturados
|
|
|
|
3. **Operação de Diagnóstico Combinado**
|
|
Entrada: Amostra de dados, nome de esquema opcional
|
|
Processamento:
|
|
Usar a detecção algorítmica para identificar o formato primeiro
|
|
Selecionar o prompt específico do formato apropriado com base no tipo detectado
|
|
Chamar o serviço de prompt para gerar o descritor
|
|
Saída: Tanto o tipo detectado quanto o descritor
|
|
|
|
### Detalhes da Implementação
|
|
|
|
O serviço seguirá as convenções do serviço TrustGraph:
|
|
|
|
1. **Registro de Serviço**
|
|
Registrar como tipo de serviço `structured-diag`
|
|
Usar tópicos padrão de solicitação/resposta
|
|
Implementar a classe base FlowProcessor
|
|
Registrar PromptClientSpec para a interação com o serviço de prompt
|
|
|
|
2. **Gerenciamento de Configuração**
|
|
Acessar as configurações do esquema através do serviço de configuração
|
|
Armazenar em cache os esquemas para desempenho
|
|
Lidar com atualizações de configuração dinamicamente
|
|
|
|
3. **Integração de Prompt**
|
|
Usar a infraestrutura existente do serviço de prompt
|
|
Chamar o serviço de prompt com IDs de prompt específicos do formato:
|
|
`diagnose-csv`: Para análise de dados CSV
|
|
`diagnose-json`: Para análise de dados JSON
|
|
`diagnose-xml`: Para análise de dados XML
|
|
Os prompts são configurados na configuração do prompt, e não codificados no serviço
|
|
Passar esquemas e amostras de dados como variáveis de prompt
|
|
Analisar as respostas do prompt para extrair os descritores
|
|
|
|
4. **Tratamento de Erros**
|
|
Validar as amostras de dados de entrada
|
|
Fornecer mensagens de erro descritivas
|
|
Lidar com dados malformados de forma elegante
|
|
Lidar com falhas no serviço de prompt
|
|
|
|
5. **Amostragem de Dados**
|
|
Processar tamanhos de amostra configuráveis
|
|
Lidar com registros incompletos de forma apropriada
|
|
Manter a consistência da amostragem
|
|
|
|
### Integração de API
|
|
|
|
O serviço será integrado com as APIs TrustGraph existentes:
|
|
|
|
Componentes Modificados:
|
|
`tg-load-structured-data` CLI - Refatorado para usar o novo serviço para operações de diagnóstico
|
|
Flow API - Estendido para suportar solicitações de diagnóstico de dados estruturados
|
|
|
|
Novos Pontos de Extremidade do Serviço:
|
|
`/api/v1/flow/{flow}/diagnose/structured-data` - Endpoint WebSocket para solicitações de diagnóstico
|
|
`/api/v1/diagnose/structured-data` - Endpoint REST para diagnóstico síncrono
|
|
|
|
### Fluxo de Mensagens
|
|
|
|
```
|
|
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)
|
|
```
|
|
|
|
## Considerações de Segurança
|
|
|
|
Validação de entrada para prevenir ataques de injeção
|
|
Limites de tamanho em amostras de dados para prevenir ataques de negação de serviço (DoS)
|
|
Sanitização de descritores gerados
|
|
Controle de acesso através da autenticação TrustGraph existente
|
|
|
|
## Considerações de Desempenho
|
|
|
|
Cache de definições de esquema para reduzir o número de chamadas ao serviço de configuração
|
|
Limitar o tamanho das amostras para manter um desempenho responsivo
|
|
Usar processamento em fluxo para grandes amostras de dados
|
|
Implementar mecanismos de timeout para análises de longa duração
|
|
|
|
## Estratégia de Testes
|
|
|
|
1. **Testes Unitários**
|
|
Detecção de tipo para vários formatos de dados
|
|
Precisão da geração de descritores
|
|
Cenários de tratamento de erros
|
|
|
|
2. **Testes de Integração**
|
|
Fluxo de solicitação/resposta do serviço
|
|
Recuperação e cache de esquema
|
|
Integração com a interface de linha de comando (CLI)
|
|
|
|
3. **Testes de Desempenho**
|
|
Processamento de grandes amostras
|
|
Tratamento de solicitações concorrentes
|
|
Uso de memória sob carga
|
|
|
|
## Plano de Migração
|
|
|
|
1. **Fase 1**: Implementar o serviço com a funcionalidade principal
|
|
2. **Fase 2**: Refatorar a CLI para usar o serviço (manter a compatibilidade com versões anteriores)
|
|
3. **Fase 3**: Adicionar endpoints de API REST
|
|
4. **Fase 4**: Descontinuar a lógica da CLI incorporada (com aviso prévio)
|
|
|
|
## Cronograma
|
|
|
|
Semana 1-2: Implementar o serviço principal e a detecção de tipo
|
|
Semana 3-4: Adicionar geração de descritores e integração
|
|
Semana 5: Testes e documentação
|
|
Semana 6: Refatoração da CLI e migração
|
|
|
|
## Perguntas Abertas
|
|
|
|
O serviço deve suportar formatos de dados adicionais (por exemplo, Parquet, Avro)?
|
|
Qual deve ser o tamanho máximo da amostra para análise?
|
|
Os resultados do diagnóstico devem ser armazenados em cache para solicitações repetidas?
|
|
Como o serviço deve lidar com cenários de vários esquemas?
|
|
Os IDs de prompt devem ser parâmetros configuráveis para o serviço?
|
|
|
|
## Referências
|
|
|
|
[Especificação do Descritor de Dados Estruturados](structured-data-descriptor.md)
|
|
[Documentação de Carregamento de Dados Estruturados](structured-data.md)
|
|
`tg-load-structured-data` implementação: `trustgraph-cli/trustgraph/cli/load_structured_data.py`
|