trustgraph/docs/tech-specs/structured-diag-service.zh-cn.md

---
layout: default
title: "结构化数据诊断服务技术规范"
parent: "Chinese (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. **综合诊断**: 依次执行数据类型检测和描述符生成

## 目标

**模块化数据分析**: 将数据诊断逻辑从 CLI 提取到可重用的服务组件中
**启用编程访问**: 提供基于 API 的访问数据分析能力
**支持多种数据格式**: 始终如一地处理 CSV、JSON 和 XML 数据格式
**生成准确的描述符**: 生成准确映射源数据到 TrustGraph 模式的结构化数据描述符
**保持向后兼容性**: 确保现有的 CLI 功能继续正常工作
**启用服务组合**: 允许其他服务利用数据诊断能力
**提高可测试性**: 将业务逻辑与 CLI 接口分离，以获得更好的测试效果
**支持流式分析**: 允许分析数据样本，而无需加载整个文件

## 背景

目前，`tg-load-structured-data` 命令提供了用于分析结构化数据和生成描述符的全面功能。但是，此功能与 CLI 接口紧密耦合，限制了其可重用性。

当前的限制包括：
数据诊断逻辑嵌入在 CLI 代码中
没有对数据类型检测和描述符生成的编程访问
难以将诊断能力集成到其他服务中
难以组合数据分析工作流程

本规范通过创建一个专用的结构化数据诊断服务来解决这些差距。通过将这些功能暴露为服务，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)
```

#### 结构化数据诊断响应

包含诊断结果的响应消息：

```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. **描述符生成操作**
   输入：数据样本、类型、目标模式名称
   处理：
     使用特定格式的提示 ID（diagnose-csv、diagnose-json 或 diagnose-xml）调用提示服务
     将数据样本和可用模式传递给提示
     从提示响应接收生成的描述符
   输出：结构化数据描述符

3. **综合诊断操作**
   输入：数据样本、可选模式名称
   处理：
     首先使用算法检测识别格式
     根据检测到的类型选择适当的特定格式的提示
     调用提示服务以生成描述符
   输出：检测到的类型和描述符

### 实现细节

该服务将遵循 TrustGraph 服务约定：

1. **服务注册**
   注册为 `structured-diag` 服务类型
   使用标准的请求/响应主题
   实现 FlowProcessor 基础类
   注册 PromptClientSpec 以进行提示服务交互

2. **配置管理**
   通过配置服务访问模式配置
   缓存模式以提高性能
   动态处理配置更新

3. **提示集成**
   使用现有的提示服务基础设施
   使用特定格式的提示 ID调用提示服务：
     `diagnose-csv`：用于 CSV 数据分析
     `diagnose-json`：用于 JSON 数据分析
     `diagnose-xml`：用于 XML 数据分析
   提示配置在提示配置中，而不是硬编码在服务中
   将模式和数据样本作为提示变量传递
   解析提示响应以提取描述符

4. **错误处理**
   验证输入数据样本
   提供描述性的错误消息
   优雅地处理格式错误的数据
   处理提示服务故障

5. **数据采样**
   处理可配置的样本大小
   适当处理不完整的记录
   保持采样的一致性

### API 集成

该服务将与现有的 TrustGraph API 集成：

修改的组件：
`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. **第一阶段**: 实施具有核心功能的服务
2. **第二阶段**: 重构 CLI 以使用服务（保持向后兼容性）
3. **第三阶段**: 添加 REST API 端点
4. **第四阶段**: 弃用嵌入式 CLI 逻辑（提前通知）

## 时间表

第 1-2 周：实施核心服务和类型检测
第 3-4 周：添加描述符生成和集成
第 5 周：测试和文档
第 6 周：CLI 重构和迁移

## 开放问题

该服务是否应支持其他数据格式（例如，Parquet、Avro）？
分析的最大样本大小应为多少？
诊断结果是否应针对重复请求进行缓存？
该服务应如何处理多模式场景？
提示 ID 是否应为服务的可配置参数？

## 参考文献

[结构化数据描述符规范](structured-data-descriptor.md)
[结构化数据加载文档](structured-data.md)
`tg-load-structured-data` 实现：`trustgraph-cli/trustgraph/cli/load_structured_data.py`