trustgraph/docs/tech-specs/universal-decoder.he.md

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

## כותרת

מפענח מסמכים אוניברסלי המופעל על ידי `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, זיהוי טבלאות תלוי ב
  ⟦CODE_0⟧. For PDFs, table detection depends on ⟦CODE_0⟧.
  האסטרטגיה של `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 יכול להבחין בין טבלאות לבין טקסט

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

```
Financial Overview

Revenue grew 15% year-over-year driven by enterprise adoption.

<table>
<tr><th>Quarter</th><th>Revenue</th><th>Growth</th></tr>
<tr><td>Q1</td><td>$12M</td><td>12%</td></tr>
<tr><td>Q2</td><td>$14M</td><td>17%</td></tr>
</table>
```

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

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

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

**חשוב מאוד: תמונות אינן משודרות כפלט של מסמך טקסט (TextDocument).** הן
נשמרות בלבד - אינן נשלחות כלפי מטה ליחידת החלוקה (chunker) או לכל
תהליך עיבוד טקסט. זה נעשה בכוונה:

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

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

#### עבודה עתידית

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

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

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

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

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

להוציא את כל המסמך כקטע יחיד. לאפשר ליחידת החלוקה
(chunker) לטפל בכל החלוקה.

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

#### `heading`

לחלק בנקודות כותרת (`Title`). כל קטע הוא כותרת וכל
התוכן עד הכותרת הבאה באותו רמה או ברמה גבוהה יותר.
כותרות מקוננות יוצרות קטעים מקוננים.

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

#### `element-type`

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

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

#### `count`

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

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

#### `size`

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

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

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

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

### זיהוי פורמט

ה-דקודר צריך לדעת את סוג ה-mime של המסמך כדי להעביר ל-
`unstructured`'s `partition()`. שני מסלולים:

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

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


### ארכיטקטורה

שירות `universal-decoder` יחיד שמבצע:

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

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

| פורמט   | סוג MIME                          | מבוסס דפים | הערות                          |
|----------|------------------------------------|------------|--------------------------------|
| PDF      | application/pdf                    | כן        | קיבוץ לפי דף              |
| DOCX     | application/vnd.openxmlformats...  | לא         | משתמש באסטרטגיית סעיפים          |
| PPTX     | application/vnd.openxmlformats...  | כן        | קיבוץ לפי שקופית             |
| XLSX/XLS | application/vnd.openxmlformats...  | כן        | קיבוץ לפי גיליון             |
| HTML     | text/html                          | לא         | משתמש באסטרטגיית סעיפים          |
| Markdown | text/markdown                      | לא         | משתמש באסטרטגיית סעיפים          |
| Plain    | 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`
  שנמצאו בדף/סעיף זה (לדוגמה, "כותרת,טקסט נרטיבי,טבלה")
`table_count` — מספר הטבלאות בדף/סעיף זה
`image_count` — מספר התמונות בדף/סעיף זה

אלה דורשים טווח שמות של טריגרים חדשים:

```
TG_SECTION_TYPE  = "https://trustgraph.ai/ns/Section"
TG_IMAGE_TYPE    = "https://trustgraph.ai/ns/Image"
TG_ELEMENT_TYPES = "https://trustgraph.ai/ns/elementTypes"
TG_TABLE_COUNT   = "https://trustgraph.ai/ns/tableCount"
TG_IMAGE_COUNT   = "https://trustgraph.ai/ns/imageCount"
```

סכימת URN לתמונות: `urn:image:{uuid}`

(`TG_MIME_TYPE` כבר קיים.)

#### סוג ישות חדש

עבור פורמטים שאינם דפי אינטרנט (DOCX, HTML, Markdown, וכו') שבהם
ה-דקודר משדר את כל המסמך כיחידה אחת ולא מחלק אותו לדפים,
הישות מקבלת סוג חדש:

```
TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
```

זה מבחין בין חלקים לדפים בעת שאילתת מקור:

| ישות | סוג | מתי משמש |
|----------|-----------------------------|----------------------------------------|
| מסמך | `tg:Document` | קובץ שהועלה במקור |
| דף | `tg:Page` | פורמטים מבוססי דפים (PDF, PPTX, XLSX) |
| חלק | `tg:Section` | פורמטים שאינם מבוססי דפים (DOCX, HTML, MD, וכו') |
| תמונה | `tg:Image` | תמונות מוטמעות (מאוחסנות, לא מעובדות) |
| מקטע | `tg:Chunk` | פלט של מפריד מקטעים |
| תת-גרף | `tg:Subgraph` | פלט של חילוץ גרף ידע |

הסוג נקבע על ידי ה-decoder בהתאם לשאלה האם הוא מקבץ לפי עמוד
או פולט חלק שלם מהמסמך. `derived_entity_triples` מקבל
פרמטר בוליאני אופציונלי `section` — כאשר הוא מוגדר כ-true, היישות היא
הוקלד כ-`tg:Section` במקום `tg:Page`.

#### שרשרת מקור מלאה

```
KG triple
  → subgraph (extraction provenance)
    → chunk (char_offset, char_length within page)
      → page/section (page_number, char_offset, char_length within doc, mime_type, element_types)
        → document (original file in librarian)
```

כל קישור הוא קבוצה של שלשות בגרף המכונה `GRAPH_SOURCE`.

### תצורת שירות

ארגומנטים של שורת הפקודה:

```
--strategy              Partitioning strategy: auto, hi_res, fast (default: auto)
--languages             Comma-separated OCR language codes (default: eng)
--section-strategy      Section grouping: whole-document, heading, element-type,
                        count, size (default: whole-document)
--section-element-count Elements per section for 'count' strategy (default: 20)
--section-max-size      Max chars per section for 'size' strategy (default: 4000)
--section-within-pages  Apply section strategy within pages too (default: false)
```

בנוסף ל-`FlowProcessor` הסטנדרטי ולטיעוני תור המאפשרים גישה לספרייה.

### אינטגרציה של זרימת העבודה

ה-דקודר האוניברסלי תופס את אותו מיקום בזרימת העיבוד
כמו ה-דקודר של PDF הנוכחי:

```
Document → [universal-decoder] → TextDocument → [chunker] → Chunk → ...
```

זה רושם:
`input` צרכן (סכימת מסמכים)
`output` מפיק (סכימת TextDocument)
`triples` מפיק (סכימת Triples)
בקשה/תגובה של ספרן (לשליפה ואחסון של מסמכים משניים)

### פריסה

קונטיינר חדש: `trustgraph-flow-universal-decoder`
תלות: `unstructured[all-docs]` (כולל PDF, DOCX, PPTX, וכו')
ניתן להפעיל לצד או להחליף את מפענח ה-PDF הקיים, בהתאם
  לתצורת זרימת העבודה
מפענח ה-PDF הקיים נשאר זמין עבור סביבות שבהן
  התלויות של `unstructured` כבדות מדי

### מה משתנה

| רכיב | שינוי |
|------------------------------|-------------------------------------------------|
| `provenance/namespaces.py`   | הוספת `TG_SECTION_TYPE`, `TG_IMAGE_TYPE`, `TG_ELEMENT_TYPES`, `TG_TABLE_COUNT`, `TG_IMAGE_COUNT` |
| `provenance/triples.py`      | הוספת ארגומנטים `mime_type`, `element_types`, `table_count`, `image_count` (kwargs) |
| `provenance/__init__.py`     | ייצוא קבועים חדשים |
| חדש: `decoding/universal/`   | מודול שירות פענוח חדש |
| `setup.cfg` / `pyproject`    | הוספת תלות `unstructured[all-docs]` |
| Docker                       | תמונת קונטיינר חדשה |
| הגדרות זרימה | חיבור universal-decoder כקלט מסמך |

### מה שלא משתנה

Chunker (מקבל TextDocument, פועל כרגיל)
מודולים לחילוץ מידע (מקבלים Chunk, ללא שינוי)
Librarian (מאחסן מסמכים משניים, ללא שינוי)
Schema (Document, TextDocument, Chunk ללא שינוי)
מקור מידע בזמן שאילתה (ללא שינוי)

## סיכונים

ל-`unstructured[all-docs]` יש תלות רבה (poppler, tesseract,
  libreoffice עבור פורמטים מסוימים). תמונת המכולה תהיה גדולה יותר.
  פתרון אפשרי: להציע גרסה של `[light]` ללא תלות ב-OCR/office.
פורמטים מסוימים עשויים לייצר חילוץ טקסט באיכות ירודה (קבצי PDF מסרוקים ללא
  OCR, פריסות מורכבות של קבצי XLSX). אמצעי מניעה: פרמטר הניתן להגדרה `strategy`.
  ומפענח ה-OCR של Mistral הקיים זמין
  עבור OCR באיכות גבוהה של קבצי PDF.
עדכוני גרסה של `unstructured` עשויים לשנות מטא-נתונים של אלמנטים.
  אמצעי מניעה: קביעת גרסה, בדיקת איכות החילוץ עבור כל פורמט.