trustgraph/docs/tech-specs/structured-diag-service.he.md

---
layout: default
title: "מפרט טכני לשירות אבחון נתונים מובנים"
parent: "Hebrew (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. **יצירת תיאור**: יצירת תיאור נתונים מובנים עבור דוגמת נתונים מסוימת וסוג
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)
```

#### תגובת אבחון נתונים מובנים

הודעת תגובה המכילה תוצאות אבחון:

```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

השירות ישולב עם ממשקי 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**: הוספת נקודות קצה של ממשק API REST
4. **שלב 4**: הפסקת השימוש בלוגיקה מוטמעת של שורת הפקודה (עם תקופת התראה)

## ציר זמן

שבוע 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`