apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-07-09 21:32:10 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
trustgraph/docs/tech-specs/universal-decoder.he.md
Jenkins, Kenneth Alexander 1f1aaa24ae
second round of translation fixes 
Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>
2026-04-06 14:50:34 -04:00

14 KiB
Raw Blame History

מפענח מסמכים אוניברסלי

כותרת

מפענח מסמכים אוניברסלי המופעל על ידי unstructured — קבלת פורמטים נפוצים של מסמכים באמצעות שירות יחיד, עם תיעוד מלא של מקור הנתונים ושילוב עם ספריית ניהול מסמכים, תוך רישום מיקומי המקור כמטא-דאטה של גרף ידע למעקב מקצה לקצה.

בעיה

ל-TrustGraph כיום יש מפענח ספציפי ל-PDF. תמיכה בפורמטים נוספים (DOCX, XLSX, HTML, Markdown, טקסט רגיל, PPTX וכו') דורשת או כתיבת מפענח חדש לכל פורמט או אימוץ ספריית חילוץ אוניברסלית. לכל פורמט יש מבנה שונה — חלקם מבוססי דפים, חלקם לא — ושרשרת התיעוד חייבת לתעד היכן בכל המסמך המקורי הגיע כל חלק של הטקסט שחולץ.

גישה

ספרייה: unstructured

יש להשתמש ב-unstructured.partition.auto.partition() שמזהה באופן אוטומטי את הפורמט מסוג MIME או סיומת הקובץ ומחלצת אלמנטים מובנים (כותרת, טקסט, טבלה, פריט רשימה וכו'). כל אלמנט מכיל מטא-דאטה, כולל:

  • page_number (לפורמטים מבוססי דפים כמו PDF, PPTX)
  • element_id (ייחודי לכל אלמנט)
  • coordinates (מלבן תחום עבור PDF)
  • text (תוכן הטקסט שחולץ)
  • category (סוג אלמנט: כותרת, טקסט, טבלה וכו')

סוגי אלמנטים

unstructured מחלץ אלמנטים מסוגים שונים ממסמכים. לכל אלמנט יש קטגוריה ומטא-דאטה נלווים:

אלמנטים טקסטואליים:

  • Title — כותרות סעיפים
  • NarrativeText — פסקאות גוף
  • ListItem — פריטי רשימה/רשימות ממוספרות
  • Header, Footer — כותרות/כותרות שוליים של עמודים
  • FigureCaption — כיתובים עבור תמונות/גרפיקה
  • Formula — ביטויים מתמטיים
  • Address, EmailAddress — פרטי התקשרות
  • CodeSnippet — בלוקי קוד (מ-Markdown)

טבלאות:

  • Table — נתונים טבלאיים מובנים. unstructured מספק גם element.text (טקסט רגיל) וגם element.metadata.text_as_html (תגית HTML מלאה של <table> עם שורות, עמודות וכותרות). עבור פורמטים עם מבנה טבלה מוגדר (DOCX, XLSX, HTML), החילוץ אמין מאוד. עבור PDF, זיהוי טבלאות תלוי באסטרטגיית hi_res עם ניתוח פריסה.

תמונות:

  • Image — תמונות מוטמעות שזוהו באמצעות ניתוח פריסה (דורש אסטרטגיית hi_res). עם extract_image_block_to_payload=True, מחזיר את נתוני התמונה כ-base64 ב-element.metadata.image_base64. טקסט OCR מהתמונה זמין ב-element.text.

טיפול בטבלאות

טבלאות הן פלט ברמה ראשונה. כאשר המפענח נתקל באלמנט Table, הוא שומר על מבנה ה-HTML במקום לפשט לטקסט רגיל. זה נותן למחלץ ה-LLM במעלה הזרם קלט טוב יותר לשליפה של ידע מובנה מנתונים טבלאיים.

הטקסט של העמוד/הסעיף מורכב באופן הבא:

  • אלמנטים טקסטואליים: טקסט רגיל, המחוברים עם שורות חדשות.
  • אלמנטים של טבלאות: תגית טבלה HTML מ-text_as_html, עטופה בתגית <table> כך שה-LLM יכול להבחין בין טבלאות לבין טקסט רגיל.

לדוגמה, עמוד עם כותרת, פסקה וטבלה מייצר:

סקירה פיננסית

ההכנסות גדלו ב-15% שנה אחר שנה, הודות לאימוץ ארגוני.

<table>
<tr><th>רבעון</th><th>הכנסות</th><th>צמיחה</th></tr>
<tr<td>רבעון 1</td><td>$12 מיליון</td><td>12%</td></tr>
<tr<td>רבעון 2</td><td>$14 מיליון</td><td>17%</td></tr>
</table>

זה שומר על מבנה הטבלה במהלך חלוקה לחלקים ולתוך צינור החילוץ, שבו ה-LLM יכול לחלץ קשרים ישירות מתאים מובנים ולא לנחש על התאמת עמודות מרווח לבן.

טיפול בתמונות

תמונות מחולצות ומאוחסנות בספריית הניהול כמסמכים משניים עם document_type="image" ו-ID urn:image:{uuid}. הם מקבלים משולשים של תיעוד מסוג tg:Image, המקושרים לעמוד/סעיף האב שלהם באמצעות prov:wasDerivedFrom. מטא-דאטה של תמונה (קואורדינטות, מימדים, element_id) נרשמים בתיעוד.

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

  1. אין עדיין צינור לעיבוד תמונות (שילוב מודל ראייה הוא עבודה עתידית)
  2. העברת נתוני תמונה ב-base64 או פיסות OCR לצינור חילוץ הטקסט תיצור משולשים של גרף ידע "זבל".

תמונות גם אינן נכללות בטקסט העמוד המורכב — כל אלמנטי Image מושמטים בשקט כאשר מחברים טקסט של אלמנטים עבור עמוד/סעיף. שרשרת התיעוד רושמת שתמונות קיימות ואיפה שהן הופיעו במסמך, כך שניתן יהיה לשלוף אותן על ידי צינור עיבוד תמונות עתידי מבלי לטעון מחדש את המסמך.

עבודה עתידית

  • הכוונת ישויות tg:Image למודל ראייה לתיאור, פרשנות דיאגרמות או חילוץ נתוני תרשימים.
  • אחסון תיאורי תמונה כמסמכים טקסטואליים שמוזנים לצינור החלוקה/חילוץ הסטנדרטי.
  • קישור ידע שנחצה חזרה לתמונות מקור באמצעות תיעוד.

אסטרטגיות סעיפים

לפורמטים מבוססי דפים (PDF, PPTX, XLSX), אלמנטים תמיד מקובצים לפי עמוד/שקופית/גיליון תחילה. עבור פורמטים שאינם מבוססי דפים (DOCX, HTML, Markdown וכו'), למפענח יש אסטרטגיה לחלוקת המסמך לסעיפים. זה מוגדר בזמן ריצה באמצעות --section-strategy.

כל אסטרטגיה היא פונקציית קיבוץ על רשימת האלמנטים של unstructured. הפלט הוא רשימת קבוצות אלמנטים; שאר הצינור (הרכבת טקסט, אחסון בספריית הניהול, תיעוד, פליטת TextDocument) זהים ללא קשר לאסטרטגיה.

whole-document (ברירת מחדל)

פליטת כל המסמך כסעיף יחיד. תן למחלק במעלה הזרם לטפל בכל החלוקה.

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

heading

פיצול בכותרות (Title). כל סעיף הוא כותרת וכל התוכן עד לכותרת ברמה שווה או גבוהה יותר. כותרות מקוננות יוצרות סעיפים מקוננים.

  • מייצר יחידות מגובשות מבחינה נושאית.
  • עובד היטב עבור מסמכים מובנים (דוחות, מדריכים, מפרטים).
  • נותן למחלץ ה-LLM הקשר של כותרת יחד עם התוכן.
  • חוזר ל-whole-document אם לא נמצאות כותרות.

element-type

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

  • שומר על טבלאות כסעיפים עצמאיים.
  • טוב למסמכים עם תוכן מעורב (דוחות עם טבלאות נתונים).
  • לטבלאות יש תשומת לב חילוץ ייעודית.

count

קיבוץ מספר קבוע של אלמנטים לכל סעיף. ניתן להגדרה באמצעות --section-element-count (ברירת מחדל: 20).

  • פשוט וצפוי.
  • לא מכבד את מבנה המסמך.
  • שימושי כברירת מחדל או לניסויים.

size

צבירת אלמנטים עד שמגיעים לגבול תווים, ואז התחלת סעיף חדש. מכבד את גבולות האלמנטים — לעולם לא מפצל באמצע אלמנט. ניתן להגדרה באמצעות --section-max-size (ברירת מחדל: 4000 תווים).

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

אינטראקציה עם פורמטים מבוססי דפים

עבור פורמטים מבוססי דפים, הקיבוץ לפי עמוד תמיד מקבל עדיפות. אסטרטגיות סעיפים יכולות באופן אופציונלי להחיל בתוך עמוד אם הוא גדול מאוד (לדוגמה, עמוד PDF עם טבלה עצומה), דבר ששולט על ידי --section-within-pages (ברירת מחדל: false). כאשר זה כוזב, כל עמוד תמיד סעיף אחד ללא קשר לגודל.

זיהוי פורמט

למפענח יש צורך לדעת את סוג MIME של המסמך כדי להעביר ל-partition() של unstructured. שתי אפשרויות:

  • נתיב ספריית הניהול (document_id מוגדר): אחסון מטא-דאטה של מסמך מהספרייה תחילה — זה נותן לנו את kind (סוג MIME) שנרשם בזמן ההעלאה. ואז אחסון תוכן מסמך. שתי קריאות לספריית הניהול, אך אחזור המטא-דאטה קל משקל.
  • נתיב מקומי (תאימות לאחור, data מוגדר): אין מטא-דאטה זמין על ההודעה. השתמש ב-python-magic כדי לזהות את הפורמט מתוך בתים של תוכן כגיבוי.

אין צורך בשינויים בסכימת Document — ספריית הניהול כבר מאחסנת את סוג ה-MIME.

ארכיטקטורה

שירות universal-decoder יחיד שמבצע את הפעולות הבאות:

  1. מקבל הודעת Document (מקומית או באמצעות הפניה לספריית הניהול).
  2. אם נתיב ספריית הניהול: אחסון מטא-דאטה של מסמך (קבלת סוג MIME), ואז אחסון תוכן. אם נתיב מקומי: זיהוי פורמט מתוך בתים של תוכן.
  3. קריאה ל-partition() כדי לחלץ אלמנטים.
  4. קיבוץ אלמנטים: לפי עמוד עבור פורמטים מבוססי דפים, לפי אסטרטגיית סעיף מוגדרת עבור פורמטים שאינם מבוססי דפים.
  5. עבור כל עמוד/סעיף:
    • יצירת ID urn:page:{uuid} או urn:section:{uuid}.
    • הרכבת טקסט עמוד: טקסט רגיל, טבלאות כ-HTML, תמונות מושמטות.
    • חישוב ההיסט מוחלט של כל אלמנט בתוך טקסט העמוד.
    • שמירה בספריית הניהול כתיעוד משני.
    • יצירת משולשים של תיעוד עם מטא-דאטה מיקומי.
    • שליחת TextDocument במעלה הזרם לחלוקה.
  6. עבור כל אלמנט תמונה:
    • יצירת ID urn:image:{uuid}.
    • שמירת נתוני תמונה בספריית הניהול כתיעוד משני.
    • יצירת משולשים של תיעוד (מאוחסנים בלבד, אינם נשלחים במעלה הזרם).

טיפול בפורמטים

פורמט סוג MIME מבוסס עמוד הערות
PDF application/pdf כן קיבוץ לפי עמוד
DOCX application/vnd.openxmlformats... לא משתמש באסטרטגיית סעיף
PPTX application/vnd.openxmlformats... כן קיבוץ לפי שקופית
XLSX/XLS application/vnd.openxmlformats... כן קיבוץ לפי גיליון
HTML text/html לא משתמש באסטרטגיית סעיף
Markdown text/markdown לא משתמש באסטרטגיית סעיף
רגיל text/plain לא משתמש באסטרטגיית סעיף
CSV text/csv לא משתמש באסטרטגיית סעיף
RST text/x-rst לא משתמש באסטרטגיית סעיף
RTF application/rtf לא משתמש באסטרטגיית סעיף
ODT application/vnd.oasis... לא משתמש באסטרטגיית סעיף
TSV text/tab-separated-values לא משתמש באסטרטגיית סעיף

מטא-דאטה של תיעוד

כל ישות עמוד/סעיף רושמת מטא-דאטה מיקומי כמשולשים של תיעוד בגרף GRAPH_SOURCE, ומאפשרת מעקב מלא מהמשולשים של גרף ידע חזרה למיקומי המסמך המקוריים.

שדות קיימים (כבר ב-derived_entity_triples)

  • page_number — מספר עמוד/גיליון/שקופית (מוגדר מ-1, רק עבור פורמטים מבוססי עמודים)
  • char_offset — היסט מוחלט של תווים של עמוד/סעיף זה בתוך הטקסט המלא של המסמך.
  • char_length — אורך התווים של הטקסט של עמוד/סעיף זה.

שדות חדשים (הרחבת derived_entity_triples)

  • mime_type — פורמט מסמך מקורי (לדוגמה, application/pdf)
  • element_types — רשימה מופרדת בפסיקים של קטגוריות unstructured של אלמנטים (לדוגמה, title, paragraph, table).
  • provenance — מידע על מקור הנתונים.