trustgraph/docs/tech-specs/flow-class-definition.he.md

layout	title	parent
default	הגדרת מפרט תוכנית זרימה	Hebrew (Beta)

<<<<<<< HEAD

הגדרת מפרט תוכנית זרימה

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. =======

מפרט הגדרת תוכנית זרימה

82edf2d (New md files from RunPod)

סקירה כללית

תוכנית זרימה מגדירה תבנית מלאה של דפוסי זרימת נתונים במערכת TrustGraph. כאשר היא מופעלת, היא יוצרת רשת מקושרת של מעבדים המטפלים בקליטת נתונים, עיבוד, אחסון ושליפה כחלק ממערכת מאוחדת.

מבנה

הגדרת תוכנית זרימה מורכבת מחמש קטעים עיקריים:

1. קטע מחלקה

<<<<<<< HEAD מגדיר מעבדי שירות משותפים המופעלים פעם אחת לכל תוכנית זרימה. מעבדים אלה מטפלים בבקשות מכל מופעי הזרימה של מחלקה זו.

מגדיר מעבדים משותפים המופעלים פעם אחת לכל תוכנית זרימה. מעבדים אלה מטפלים בבקשות מכל מופעי הזרימה של מחלקה זו.

82edf2d (New md files from RunPod)

"class": {
  "service-name:{class}": {
    "request": "queue-pattern:{class}",
    "response": "queue-pattern:{class}",
    "settings": {
      "setting-name": "fixed-value",
      "parameterized-setting": "{parameter-name}"
    }
  }
}

מאפיינים: משותפים לכל מופעי זרימה מאותו סוג. בדרך כלל שירותים יקרים או חסרי מצב (מודלים של שפה גדולים, מודלים להטמעה). השתמשו במשתנה תבנית {class} עבור שמות תורים. הגדרות יכולות להיות ערכים קבועים או פרמטריות באמצעות תחביר {parameter-name}. דוגמאות: embeddings:{class}, text-completion:{class}, graph-rag:{class}

2. סעיף זרימה

<<<<<<< HEAD מגדיר מעבדים ספציפיים לזרימה, אשר מופעלים עבור כל מופע זרימה בודד. לכל זרימה יש סט נפרד משלה של מעבדים אלה.

מגדיר מעבדים ספציפיים לזרימה אשר מופעלים עבור כל מופע זרימה בודד. לכל זרימה יש סט נפרד משלה של מעבדים אלה.

82edf2d (New md files from RunPod)

"flow": {
  "processor-name:{id}": {
    "input": "queue-pattern:{id}",
    "output": "queue-pattern:{id}",
    "settings": {
      "setting-name": "fixed-value",
      "parameterized-setting": "{parameter-name}"
    }
  }
}

מאפיינים: מופע ייחודי לכל זרימה טיפול בנתונים ובמצב ספציפיים לזרימה שימוש במשתנה תבנית {id} עבור שמות תורים הגדרות יכולות להיות ערכים קבועים או פרמטריות באמצעות תחביר {parameter-name} דוגמאות: chunker:{id}, pdf-decoder:{id}, kg-extract-relationships:{id}

3. סעיף ממשקים

מגדיר את נקודות הכניסה ואת חוזי האינטראקציה עבור הזרימה. אלה מהווים את ממשק ה-API עבור מערכות חיצוניות ותקשורת בין רכיבים פנימיים.

ממשקים יכולים לקבל שתי צורות:

<<<<<<< HEAD תבנית "שלח ושכח" (תור יחיד):

תבנית "שלח והשכח" (תור יחיד):

82edf2d (New md files from RunPod)

"interfaces": {
  "document-load": "persistent://tg/flow/document-load:{id}",
  "triples-store": "persistent://tg/flow/triples-store:{id}"
}

תבנית בקשה/תגובה (אובייקט עם שדות בקשה/תגובה):

"interfaces": {
  "embeddings": {
    "request": "non-persistent://tg/request/embeddings:{class}",
    "response": "non-persistent://tg/response/embeddings:{class}"
  }
}

סוגי ממשקים: <<<<<<< HEAD נקודות כניסה: נקודות שבהן מערכות חיצוניות מזריקות נתונים (document-load, agent) ממשקי שירות: תבניות בקשה/תגובה עבור שירותים (embeddings, text-completion) ממשקי נתונים: נקודות חיבור לזרימת נתונים מסוג "שלח וסגור" (triples-store, entity-contexts-load)

נקודות כניסה: נקודות בהן מערכות חיצוניות מזריקות נתונים (document-load, agent) ממשקי שירות: תבניות בקשה/תגובה עבור שירותים (embeddings, text-completion) ממשקי נתונים: נקודות חיבור לזרימת נתונים מסוג "שלח ושים" (triples-store, entity-contexts-load)

82edf2d (New md files from RunPod)

4. סעיף פרמטרים

ממפה שמות פרמטרים ספציפיים לזרימה להגדרות פרמטרים המאוחסנות באופן מרכזי:

"parameters": {
  "model": "llm-model",
  "temp": "temperature",
  "chunk": "chunk-size"
}

מאפיינים: המפתחות הם שמות הפרמטרים המשמשים בהגדרות המעבד (לדוגמה, {model}) הערכים מפנים להגדרות הפרמטרים המאוחסנות ב-schema/config מאפשר שימוש חוזר בהגדרות פרמטרים נפוצות בין זרימות מפחית כפילויות של סכימות פרמטרים

5. מטא-נתונים

מידע נוסף על תוכנית הזרימה:

"description": "Human-readable description",
"tags": ["capability-1", "capability-2"]

משתנים בתבנית

משתנים של המערכת

{id}

מוחלף במזהה הייחודי של מופע ה-flow יוצר משאבים מבודדים עבור כל flow דוגמה: flow-123, customer-A-flow

{class}

מוחלף בשם התבנית של ה-flow יוצר משאבים משותפים בין flows של אותה תבנית דוגמה: standard-rag, enterprise-rag

משתנים של פרמטרים

{parameter-name}

פרמטרים מותאמים אישית המוגדרים בזמן הפעלת ה-flow שמות הפרמטרים תואמים למפתחות במקטע parameters של ה-flow משמש בהגדרות של מעבדים כדי להתאים אישית את ההתנהגות דוגמאות: {model}, {temp}, {chunk} מוחלף בערכים המסופקים בעת הפעלת ה-flow <<<<<<< HEAD מאומתים מול הגדרות פרמטרים המאוחסנות באופן מרכזי

מאומתים מול הגדרות פרמטרים המאוחסנות במרכז

82edf2d (New md files from RunPod)

הגדרות מעבד

הגדרות מספקות ערכי תצורה למעבדים בזמן יצירתם. ניתן להגדיר אותן כ:

הגדרות קבועות

ערכים ישירים שאינם משתנים:

"settings": {
  "model": "gemma3:12b",
  "temperature": 0.7,
  "max_retries": 3
}

הגדרות מותאמות אישית

ערכים המשתמשים בפרמטרים המסופקים בעת הפעלת ה-flow:

"settings": {
  "model": "{model}",
  "temperature": "{temp}",
  "endpoint": "https://{region}.api.example.com"
}

שמות הפרמטרים בהגדרות תואמים למפתחות במקטע parameters של ה-flow.

דוגמאות להגדרות

מעבד LLM עם פרמטרים:

// In parameters section:
"parameters": {
  "model": "llm-model",
  "temp": "temperature",
  "tokens": "max-tokens",
  "key": "openai-api-key"
}

// In processor definition:
"text-completion:{class}": {
  "request": "non-persistent://tg/request/text-completion:{class}",
  "response": "non-persistent://tg/response/text-completion:{class}",
  "settings": {
    "model": "{model}",
    "temperature": "{temp}",
    "max_tokens": "{tokens}",
    "api_key": "{key}"
  }
}

חלוקה למקטעים עם הגדרות קבועות וניתנות לשינוי:

// In parameters section:
"parameters": {
  "chunk": "chunk-size"
}

// In processor definition:
"chunker:{id}": {
  "input": "persistent://tg/flow/chunk:{id}",
  "output": "persistent://tg/flow/chunk-load:{id}",
  "settings": {
    "chunk_size": "{chunk}",
    "chunk_overlap": 100,
    "encoding": "utf-8"
  }
}

תבניות תורים (פולסר)

תבניות זרימה משתמשות ב-Apache Pulsar עבור העברת הודעות. שמות התורים עוקבים אחר הפורמט של פולסר:

<persistence>://<tenant>/<namespace>/<topic>

רכיבים:

persistence: persistent או non-persistent (מצב אחסון של Pulsar) tenant: tg עבור הגדרות תבניות זרימה המסופקות על ידי TrustGraph namespace: מציין את דפוס העברת ההודעות flow: שירותים מסוג "שלח וגע" (fire-and-forget) <<<<<<< HEAD request: החלק של הבקשה בשירותי בקשה/תגובה (request/response) response: החלק של התגובה בשירותי בקשה/תגובה (request/response)

request: החלק של הבקשה בשירותי "בקשה/תגובה" (request/response) response: החלק של התגובה בשירותי "בקשה/תגובה" (request/response)

82edf2d (New md files from RunPod) topic: שם התור/נושא הספציפי עם משתני תבנית

תורים קבועים (Persistent Queues)

דפוס: persistent://tg/flow/<topic>:{id} משמש עבור שירותים מסוג "שלח וגע" וזרימת נתונים עמידה <<<<<<< HEAD הנתונים נשמרים באחסון של Pulsar בין הפעלות מחדש

הנתונים נשמרים באחסון של Pulsar גם לאחר אתחולים מחדש

82edf2d (New md files from RunPod) דוגמה: persistent://tg/flow/chunk-load:{id}

תורים לא קבועים (Non-Persistent Queues)

דפוס: non-persistent://tg/request/<topic>:{class} או non-persistent://tg/response/<topic>:{class} <<<<<<< HEAD משמש עבור דפוסי העברת הודעות מסוג בקשה/תגובה

משמש עבור דפוסי העברת הודעות מסוג "בקשה/תגובה"

82edf2d (New md files from RunPod) זמני, אינו נשמר בדיסק על ידי Pulsar השהיה נמוכה יותר, מתאים לתקשורת בסגנון RPC דוגמה: non-persistent://tg/request/embeddings:{class}

ארכיטקטורת זרימת נתונים

תבנית זרימת הנתונים יוצרת זרימה מאוחדת שבה:

1. צינור עיבוד מסמכים: זרימה מאיסוף דרך טרנספורמציה לאחסון
2. שירותי שאילתות: מעבדים משולבים השואלים את אותם מאגרי נתונים ושירותים
3. שירותים משותפים: מעבדים מרכזיים שכל הזרימות יכולות להשתמש בהם
4. כותבי אחסון: שומרים נתונים מעובדים לאחסונים המתאימים

כל המעבדים (גם {id} וגם {class}) עובדים יחד כגרף זרימת נתונים מגובש, ולא כמערכות נפרדות.

דוגמה להפעלה של זרימה

בהינתן: מזהה מופע של זרימה: customer-A-flow תבנית זרימה: standard-rag מיפוי פרמטרים של זרימה: "model": "llm-model" "temp": "temperature" "chunk": "chunk-size" פרמטרים שסופקו על ידי המשתמש: model: gpt-4 temp: 0.5 chunk: 512

הרחבות תבניות: persistent://tg/flow/chunk-load:{id} → persistent://tg/flow/chunk-load:customer-A-flow non-persistent://tg/request/embeddings:{class} → non-persistent://tg/request/embeddings:standard-rag "model": "{model}" → "model": "gpt-4" "temperature": "{temp}" → "temperature": "0.5" "chunk_size": "{chunk}" → "chunk_size": "512"

זה יוצר: <<<<<<< HEAD צינור עיבוד מסמכים נפרד עבור customer-A-flow

צינור עיבוד מסמכים מבודד עבור customer-A-flow

82edf2d (New md files from RunPod) שירות הטמעה משותף עבור כל זרימות standard-rag זרימת נתונים שלמה מאיסוף מסמכים דרך שאילתות מעבדים מוגדרים עם ערכי הפרמטרים שסופקו

יתרונות

1. יעילות משאבים: שירותים יקרים משותפים בין זרימות
2. בידוד זרימות: לכל זרימה יש את צינור עיבוד הנתונים שלה
3. מדרגיות: ניתן להפעיל מספר זרימות מאותה תבנית
4. מודולריות: הפרדה ברורה בין רכיבים משותפים ורכיבים ספציפיים לזרימה
5. ארכיטקטורה מאוחדת: שאילתות ועיבוד הם חלק מאותה זרימת נתונים