trustgraph/docs/tech-specs/jsonl-prompt-output.he.md

מפרט טכני של פלט JSONL עבור הנחיות

סקירה כללית

מפרט זה מתאר את יישום פורמט הפלט JSONL (JSON Lines) עבור תגובות הנחיות ב-TrustGraph. JSONL מאפשר חילוץ נתונים מובנים מעמידים בסיכויים גבוהים יותר מתגובות של מודלי שפה גדולים (LLM), ומטפל בבעיות קריטיות שמתרחשות כאשר פלטי JSON מערך פגומים כאשר תגובות LLM מגיעות למגבלות של מספר הטוקנים.

יישום זה תומך בתרחישים הבאים:

1. חילוץ עמיד בפני קיטוע: חילוץ תוצאות חלקיות תקפות גם כאשר פלט LLM מקוטע באמצע התגובה.
2. חילוץ בקנה מידה גדול: טיפול בחילוץ של פריטים רבים מבלי להסתכן בכשל מוחלט עקב מגבלות טוקנים.
3. חילוץ מסוגים מעורבים: תמיכה בחילוץ סוגים מרובים של ישויות (entities) (הגדרות, קשרים, נושאים וכו')
4. שיפור ביצועים: חילוץ יעיל יותר וצריכת זיכרון נמוכה יותר בהשוואה לפורמט JSON מערך.

שינויים ב-API

• לקוח: אין שינויים נדרשים בצד הלקוח. לקוחות ממשיכים לקבל רשימה של אובייקטים (list of objects) כפלט, ללא הבדל אם מדובר בפורמט JSON או JSONL.
• שרת: שינוי בצד השרת לטובת ניתוח (parsing) של קבצי JSONL שורות-אחר-שורות (line-by-line) כדי לאפשר חילוץ חלקי גם במקרה של קיטוע.

תוכנית מעבר

• שלב 1: יישום: יישום פונקציית ניתוח JSONL חדשה בצד השרת.
• שלב 2: מעבר הנחיות: מעבר הדרגתי של הנחיות קיימות לפורמט JSONL.
• שלב 3: עדכונים נלווים: עדכון קוד צד לקוח (אם יש) כדי להתאים לפורמט הפלט החדש.

שיקולי אבטחה

• אימות קלט: ניתוח JSON משתמש בפונקציה json.loads() הסטנדרטית, הבטוחה מפני התקפות הזרקה (injection).
• אימות סכימה: שימוש ב-jsonschema.validate() לאכיפת סכימה.
• ללא משטח תקיפה חדש: ניתוח JSONL בטוח יותר מניתוח JSON מערך עקב עיבוד שורות-אחר-שורות.

שיקולי ביצועים

• זיכרון: ניתוח שורות-אחר-שורות משתמש בפחות זיכרון שיא בהשוואה לטעינת מערכי JSON שלמים.
• השהייה: ביצועי הניתוח דומים לניתוח מערכי JSON.
• אימות: אימות סכימה מתבצע עבור כל אובייקט, מה שמוסיף תקורה, אך מאפשר קבלת תוצאות חלקיות גם במקרה של כשל באימות.

שיקולים נוספים

• אמינות: פלט JSONL מאפשר המשך עיבוד גם במקרה של שגיאות או קיטועים, בעוד שפלט JSON מערך עלול לגרום לכשל מוחלט.
• גמישות: תמיכה בסוגים מעורבים של ישויות (entities) מאפשרת חילוץ נתונים מורכבים יותר.

שאלות פתוחות

אף אחת בשלב זה.

הפניות

• יישום נוכחי: trustgraph-flow/trustgraph/template/prompt_manager.py
• מפרט JSON Lines: https://jsonlines.org/
• סכימת JSON oneOf: https://json-schema.org/understanding-json-schema/reference/combining.html#oneof
• מפרט קשור: Streaming LLM Responses (docs/tech-specs/streaming-llm-responses.md)