mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
282 lines
13 KiB
Markdown
282 lines
13 KiB
Markdown
|
---
|
|||
|
|
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`
|