update more languages

Signed-off-by: Alex Jenkins <kjenkins60@gatech.edu>
This commit is contained in:
Alex Jenkins 2026-04-11 01:08:44 +00:00
parent 835acaa70e
commit 16c2f12a54
249 changed files with 117186 additions and 186 deletions

View file

@ -5,15 +5,24 @@
מפרט זה מתאר את יישום פורמט הפלט JSONL (JSON Lines)
עבור תשובות לשאילתות ב-TrustGraph. JSONL מאפשר חילוץ עמיד לקיטוע
של נתונים מובנים מתשובות של מודלי שפה גדולים (LLM), תוך התמודדות עם בעיות
<<<<<<< HEAD
קריטיות שבהן פלט מערך JSON נפגע כאשר תשובות ה-LLM מגיעות למגבלות
של מספר הטוקנים.
=======
קריטיות שבהן מערכי JSON יוצאים מכלל שימוש כאשר תשובות ה-LLM מגיעות
למגבלות מספר הטוקנים.
>>>>>>> 82edf2d (New md files from RunPod)
יישום זה תומך בתרחישי שימוש הבאים:
1. **חילוץ עמיד לקיטוע**: חילוץ תוצאות חלקיות ותקינות גם כאשר
פלט ה-LLM מקוטע באמצע התגובה.
2. **חילוץ בקנה מידה גדול**: טיפול בחילוץ של פריטים רבים מבלי
<<<<<<< HEAD
להסתכן בכשל מוחלט עקב מגבלות טוקנים.
=======
להסתכן בכשל מוחלט עקב מגבלות מספר הטוקנים.
>>>>>>> 82edf2d (New md files from RunPod)
3. **חילוץ מסוגים מעורבים**: תמיכה בחילוץ של סוגי ישויות מרובים
(הגדרות, קשרים, ישויות, תכונות) בשאילתה אחת.
4. **פלט תואם לסטרימינג**: אפשור עיבוד עתידי של תוצאות החילוץ
@ -35,10 +44,17 @@
### ארכיטקטורה נוכחית
<<<<<<< HEAD
שירות השאילתות תומך בשני סוגי תגובה:
1. `response-type: "text"` - תגובה טקסטואלית גולמית המוחזרת כפי שהיא.
2. `response-type: "json"` - JSON המנותח מהתגובה, ומאומת כנגד
=======
שירות השאילתות תומך בשני סוגי תגובות:
1. `response-type: "text"` - תגובה טקסטואלית גולמית המוחזרת כפי שהיא.
2. `response-type: "json"` - JSON המנותח מהתגובה, ומאומת מול
>>>>>>> 82edf2d (New md files from RunPod)
`schema` אופציונלי.
יישום נוכחי ב-`trustgraph-flow/trustgraph/template/prompt_manager.py`:
@ -56,7 +72,11 @@ class Prompt:
כאשר הנחיות החילוץ מבקשות פלט כמערכים מסוג JSON (`[{...}, {...}, ...]`):
<<<<<<< HEAD
**שחיתות עקב קיטום**: אם מודל השפה (LLM) מגיע למגבלת מספר הטוקנים במהלך יצירת המערך,
=======
**שחיתות עקב קיטוע:** אם מודל השפה (LLM) מגיע למגבלת מספר הטוקנים במהלך יצירת המערך,
>>>>>>> 82edf2d (New md files from RunPod)
התגובה כולה הופכת ל-JSON לא חוקי ואי אפשר לנתח אותה.
**ניתוח "הכל או כלום":** יש לקבל את הפלט השלם לפני הניתוח.
**אין תוצאות חלקיות:** תגובה מקוטעת מניבה אפס נתונים שניתן להשתמש בהם.
@ -74,7 +94,11 @@ class Prompt:
#### שינויי תצורה
<<<<<<< HEAD
**ערך חדש עבור סוג התגובה:**
=======
**ערך סוג תגובה חדש:**
>>>>>>> 82edf2d (New md files from RunPod)
```
"response-type": "jsonl"
@ -118,7 +142,11 @@ class Prompt:
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}
```
<<<<<<< HEAD
**ניגוד לפורמט מערך JSON הקודם:**
=======
**השוואה לפורמט מערך JSON הקודם:**
>>>>>>> 82edf2d (New md files from RunPod)
```json
[
{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"},
@ -130,10 +158,17 @@ class Prompt:
אם מודל השפה הגדול (LLM) מקצר אחרי השורה 2, פורמט מערך ה-JSON ייתן JSON לא תקין,
בעוד ש-JSONL ייתן שני אובייקטים תקינים.
<<<<<<< HEAD
#### חילוץ של טיפוסים מעורבים (איחודים מובחנים)
עבור הנחיות המפיקות מספר סוגים של אובייקטים (לדוגמה, גם הגדרות וגם
קשרים, או ישויות, קשרים ומאפיינים), השתמש בשדה `"type"`
=======
#### חילוץ מסוגים מעורבים (איחודים מובחנים)
עבור הנחיות המפיקות סוגים מרובים של אובייקטים (לדוגמה, גם הגדרות וגם
קשרים, או ישויות, קשרים ומאפיינים), השתמשו בשדה `"type"`
>>>>>>> 82edf2d (New md files from RunPod)
כמבחין:
**פורמט פלט של ההנחיה:**
@ -245,7 +280,11 @@ def parse_jsonl(self, text):
#### שינויים ב-PromptManager.invoke
<<<<<<< HEAD
הרחב את השיטה invoke כדי לטפל בסוג התגובה החדש:
=======
הרחב את המיפעל invoke כדי לטפל בסוג התגובה החדש:
>>>>>>> 82edf2d (New md files from RunPod)
```python
async def invoke(self, id, input, llm):
@ -321,7 +360,11 @@ async def invoke(self, id, input, llm):
#### נקודת מבט של הלקוח
ניתוח JSONL שקוף למשתמשי ה-API של שירות ההנחיות. הניתוח מתבצע
<<<<<<< HEAD
בצד השרת בשירות ההנחיות, והתגובה מוחזרת באמצעות השדה הסטנדרטי
=======
בצד השרת בשירות ההנחיות, והתגובה מוחזרת דרך השדה הסטנדרטי
>>>>>>> 82edf2d (New md files from RunPod)
`PromptResponse.object` כמערך JSON מוסרי.
כאשר לקוחות קוראים לשירות ההנחיות (דרך `PromptClient.prompt()` או דומה):
@ -330,10 +373,17 @@ async def invoke(self, id, input, llm):
**`response-type: "jsonl"`** → הלקוח מקבל `list` בפייתון
מנקודת מבטו של הלקוח, שתי השיטות מחזירות מבני נתונים זהים. ההבדל
<<<<<<< HEAD
הוא אך ורק באופן שבו פלט ה-LLM מנותח בצד השרת:
פורמט מערך JSON: קריאה אחת ל-`json.loads()`; נכשל לחלוטין אם הוא חתוך
פורמט JSONL: ניתוח שורה אחר שורה; מייצר תוצאות חלקיות אם הוא חתוך
=======
הוא אך ורק באופן שבו הפלט של מודל השפה הגדול (LLM) מנותח בצד השרת:
פורמט מערך JSON: קריאה אחת ל-`json.loads()`; נכשל לחלוטין אם הוא חתוך.
פורמט JSONL: ניתוח שורה אחר שורה; מייצר תוצאות חלקיות אם הוא חתוך.
>>>>>>> 82edf2d (New md files from RunPod)
המשמעות היא שקוד לקוח קיים שמצפה לרשימה מהנחיות חילוץ
אינו דורש שינויים בעת העברת הנחיות מפורמט JSON לפורמט JSONL.
@ -346,10 +396,17 @@ async def invoke(self, id, input, llm):
#### טיפול בשגיאות
<<<<<<< HEAD
תוצאות ריקות: מחזיר רשימה ריקה `[]` עם רישום אזהרה
כשל חלקי בניתוח: מחזיר רשימה של אובייקטים שנותחו בהצלחה עם
רישומי אזהרה עבור כשלים
כשל מוחלט בניתוח: מחזיר רשימה ריקה `[]` עם רישומי אזהרה
=======
תוצאות ריקות: מחזיר רשימה ריקה `[]` עם רישום אזהרה.
כשל חלקי בניתוח: מחזיר רשימה של אובייקטים שנותחו בהצלחה עם
רישומי אזהרה עבור כשלים.
כשל מוחלט בניתוח: מחזיר רשימה ריקה `[]` עם רישומי אזהרה.
>>>>>>> 82edf2d (New md files from RunPod)
זה שונה מ-`response-type: "json"` שמגביר `RuntimeError`
בעת כשל בניתוח. ההתנהגות הסלחנית עבור JSONL היא מכוונת כדי לספק
@ -382,19 +439,34 @@ async def invoke(self, id, input, llm):
## שיקולי אבטחה
<<<<<<< HEAD
**בדיקת תקינות קלט**: ניתוח JSON משתמש ב-`json.loads()` הסטנדרטי, שהוא בטוח
מפני התקפות הזרקה.
**בדיקת תאימות סכימה**: משתמש ב-`jsonschema.validate()` לאכיפת סכימה.
**ללא משטח תקיפה חדש**: ניתוח JSONL בטוח יותר מניתוח מערך JSON
=======
**בדיקת קלט**: ניתוח JSON משתמש ב-`json.loads()` הסטנדרטי, שהוא בטוח
מפני התקפות הזרקה.
**בדיקת סכימה**: משתמש ב-`jsonschema.validate()` לאכיפת סכימה.
**ללא נקודות תורפה חדשות**: ניתוח JSONL בטוח יותר מניתוח מערך JSON
>>>>>>> 82edf2d (New md files from RunPod)
בשל עיבוד שורה אחר שורה.
## שיקולי ביצועים
<<<<<<< HEAD
**זיכרון**: ניתוח שורה אחר שורה משתמש בפחות זיכרון שיא בהשוואה לטעינת מערכי JSON שלמים.
**השהיה**: ביצועי הניתוח דומים לניתוח מערך JSON.
**בדיקת תאימות**: בדיקת תאימות סכימה מתבצעת עבור כל אובייקט, מה שמוסיף תקורה אך
מאפשר תוצאות חלקיות במקרה של כשל בבדיקת התאימות.
=======
**זיכרון**: ניתוח שורה אחר שורה משתמש בפחות זיכרון שיא בהשוואה לטעינת
מערכי JSON שלמים.
**השהיה**: ביצועי הניתוח דומים לניתוח מערך JSON.
**בדיקה**: בדיקת סכימה מתבצעת עבור כל אובייקט, מה שמוסיף תקורה אך
מאפשר תוצאות חלקיות במקרה של כשל בבדיקה.
>>>>>>> 82edf2d (New md files from RunPod)
## אסטרטגיית בדיקות
@ -405,7 +477,11 @@ async def invoke(self, id, input, llm):
ניתוח JSONL עם גדרות קוד Markdown.
ניתוח JSONL עם שורה אחרונה חתוכה.
ניתוח JSONL עם שורות JSON לא תקינות המפוזרות.
<<<<<<< HEAD
בדיקת תאימות סכימה עם איחודים מובחנים של `oneOf`.
=======
בדיקת סכימה עם איחודים מובחנים של `oneOf`.
>>>>>>> 82edf2d (New md files from RunPod)
תאימות לאחור: הנחיות `"text"` ו-`"json"` קיימות אינן משתנות.
### בדיקות אינטגרציה
@ -418,7 +494,11 @@ async def invoke(self, id, input, llm):
### בדיקות איכות חילוץ
השוואת תוצאות חילוץ: פורמט JSONL לעומת מערך JSON.
<<<<<<< HEAD
בדיקת עמידות בפני קיטוע: JSONL מניב תוצאות חלקיות כאשר JSON נכשל.
=======
בדיקת עמידות בפני קיטוע: פורמט JSONL מספק תוצאות חלקיות כאשר פורמט JSON נכשל.
>>>>>>> 82edf2d (New md files from RunPod)
## תוכנית מעבר
@ -439,8 +519,13 @@ async def invoke(self, id, input, llm):
### שלב 3: עדכונים במערכות משימתיות
<<<<<<< HEAD
1. עדכון כל קוד המשתמש בתוצאות החילוץ כדי לטפל בסוג החזרה של רשימה.
2. עדכון קוד המקטלג חילוצים מסוגים מעורבים לפי שדה `type`.
=======
1. עדכון כל קוד הצורך בתוצאות החילוץ כדי לטפל בסוג החזרה של רשימה.
2. עדכון קוד שמקטלג חילוצים מסוגים מעורבים לפי שדה `type`.
>>>>>>> 82edf2d (New md files from RunPod)
3. עדכון בדיקות המאמתות את פורמט הפלט של החילוץ.
## שאלות פתוחות