הערכת הביצועים

‫Document AI יוצר מדדי הערכה, כמו דיוק וזיכרון, כדי לעזור לכם לקבוע את ביצועי החיזוי של המעבדים.

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

הרצת הערכה

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

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

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

ממשק משתמש באינטרנט

1. נכנסים לדף Processors במסוף Google Cloud ובוחרים את המעבד.

   כניסה לדף Processors

2. בכרטיסייה Evaluate & Test (הערכה ובדיקה), בוחרים את הגרסה של המעבד שרוצים להעריך ולוחצים על Run new evaluation (הפעלת הערכה חדשה).

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

Python

למידע נוסף, קראו את מאמרי העזרה של Document AI Python API.

כדי לבצע אימות ב-Document AI, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID'
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'
# gcs_input_uri = # Format: gs://bucket/directory/


def evaluate_processor_version_sample(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version_id: str,
    gcs_input_uri: str,
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    evaluation_documents = documentai.BatchDocumentsInputConfig(
        gcs_prefix=documentai.GcsPrefix(gcs_uri_prefix=gcs_input_uri)
    )

    # NOTE: Alternatively, specify a list of GCS Documents
    #
    # gcs_input_uri = "gs://bucket/directory/file.pdf"
    # input_mime_type = "application/pdf"
    #
    # gcs_document = documentai.GcsDocument(
    #     gcs_uri=gcs_input_uri, mime_type=input_mime_type
    # )
    # gcs_documents = [gcs_document]
    # evaluation_documents = documentai.BatchDocumentsInputConfig(
    #     gcs_documents=documentai.GcsDocuments(documents=gcs_documents)
    # )
    #

    request = documentai.EvaluateProcessorVersionRequest(
        processor_version=name,
        evaluation_documents=evaluation_documents,
    )

    # Make EvaluateProcessorVersion request
    # Continually polls the operation until it is complete.
    # This could take some time for larger files
    operation = client.evaluate_processor_version(request=request)
    # Print operation details
    # Format: projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID
    print(f"Waiting for operation {operation.operation.name} to complete...")
    # Wait for operation to complete
    response = documentai.EvaluateProcessorVersionResponse(operation.result())

    # After the operation is complete,
    # Print evaluation ID from operation response
    print(f"Evaluation Complete: {response.evaluation}")

קבלת תוצאות של הערכה

ממשק משתמש באינטרנט

1. נכנסים לדף Processors במסוף Google Cloud ובוחרים את המעבד.

   כניסה לדף Processors

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

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

Python

למידע נוסף, קראו את מאמרי העזרה של Document AI Python API.

כדי לבצע אימות ב-Document AI, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'
# evaluation_id = 'YOUR_EVALUATION_ID'


def get_evaluation_sample(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version_id: str,
    evaluation_id: str,
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the evaluation
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    evaluation_name = client.evaluation_path(
        project_id, location, processor_id, processor_version_id, evaluation_id
    )
    # Make GetEvaluation request
    evaluation = client.get_evaluation(name=evaluation_name)

    create_time = evaluation.create_time
    document_counters = evaluation.document_counters

    # Print the Evaluation Information
    # Refer to https://cloud.google.com/document-ai/docs/reference/rest/v1beta3/projects.locations.processors.processorVersions.evaluations
    # for more information on the available evaluation data
    print(f"Create Time: {create_time}")
    print(f"Input Documents: {document_counters.input_documents_count}")
    print(f"\tInvalid Documents: {document_counters.invalid_documents_count}")
    print(f"\tFailed Documents: {document_counters.failed_documents_count}")
    print(f"\tEvaluated Documents: {document_counters.evaluated_documents_count}")

הצגת רשימה של כל ההערכות של גרסת מעבד

Python

למידע נוסף, קראו את מאמרי העזרה של Document AI Python API.

כדי לבצע אימות ב-Document AI, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def list_evaluations_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    parent = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    evaluations = client.list_evaluations(parent=parent)

    # Print the Evaluation Information
    # Refer to https://cloud.google.com/document-ai/docs/reference/rest/v1beta3/projects.locations.processors.processorVersions.evaluations
    # for more information on the available evaluation data
    print(f"Evaluations for Processor Version {parent}")

    for evaluation in evaluations:
        print(f"Name: {evaluation.name}")
        print(f"\tCreate Time: {evaluation.create_time}\n")

מדדי הערכה לכל התוויות

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

• דיוק: שיעור החיזויים שתואמים להערות בקבוצת נתונים לבדיקה. מוגדר כ-True Positives / (True Positives + False Positives)

• Recall: the proportion of annotations in the test set that are correctly predicted. מוגדר כ-True Positives / (True Positives + False Negatives)

• ציון F1: הממוצע ההרמוני של הדיוק וההחזרה, שמשלב בין הדיוק וההחזרה למדד יחיד, ונותן משקל שווה לשניהם. מוגדר כ-2 * (Precision * Recall) / (Precision + Recall)

הערה: אין ב-Document AI מדד לדיוק. מדד הדיוק, שמוגדר לעיתים קרובות כשיעור המקרים שחזויים בצורה נכונה, פחות משמעותי כי 1) לא כל התוויות מופיעות בקבוצת נתונים לבדיקה (לדוגמה, שדות אופציונליים) ו-2) יכולים להיות כמה ערכים לתווית אחת (לדוגמה, פריטים בחשבונית). לעומת זאת, אפשר לראות ב-F1 מדד ששווה בערך לדיוק, אבל הוא מתאים יותר לתרחישים האלה.

מדדי הערכה של תוויות ספציפיות

• חיוביים אמיתיים: הישויות החזויות שתואמות להערה במסמך הבדיקה. מידע נוסף זמין במאמר בנושא התנהגות ההתאמה.

• חיוביים כוזבים: ישויות שחזיתם שלא תואמות לאף הערה במסמך הבדיקה.

• שלילי כוזב: ההערות במסמך הבדיקה שלא תואמות לאף אחת מהישויות שחזיתם.

  • False Negatives (Below Threshold): the annotations in the test document that would have matched a predicted entity, but the predicted entity's confidence value is below the specified confidence threshold.

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

טיפ: אם איכות החילוץ של checkbox לא מספיק גבוהה, כדאי להריץ את המסמכים דרך כלי הניתוח של טפסים. הכלי Form Parser מחלץ מידע שיכול לשפר את האיכות של חילוץ תיבות הסימון. לדוגמה, הכלי Form Parser יכול לצייר באופן אוטומטי תיבות תוחמות סביב תיבות סימון, בעוד שתיבות תוחמות שמציירים באופן ידני עשויות להיות פחות עקביות. כדי לעשות את זה, מעבדים את המסמכים באמצעות הכלי Form Parser ואז מייבאים את המסמכים המעובדים ומבצעים שוב את ההערות.

סף ביטחון

לוגיקת ההערכה מתעלמת מכל החיזויים עם רמת סמך מתחת לסף המהימנות שצוין, גם אם החיזוי נכון. ‫Document AI מספק רשימה של False Negatives (Below Threshold), שהן ההערות שהיו מתאימות אם סף הסמך היה מוגדר נמוך יותר.

‫Document AI מחשב באופן אוטומטי את הסף האופטימלי שממקסם את ציון F1, וכברירת מחדל, מגדיר את סף הוודאות לערך האופטימלי הזה.

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

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

• דיוק גבוה יותר, כי יש סיכוי גבוה יותר שהתחזיות יהיו נכונות.
• שיעור היזכרות נמוך יותר, כי יש פחות תחזיות.

ישויות טבלאיות

המדדים של תווית אב לא מחושבים על ידי ממוצע ישיר של מדדי הצאצא, אלא על ידי החלת סף מהימנות האב על כל תוויות הצאצא שלו וצבירת התוצאות.

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

התנהגות ההתאמה

ישות חזויה תואמת להערה אם:

• סוג הישות החזוי (entity.type) תואם לשם התווית של ההערה
• הערך של הישות החזויה (entity.mention_text או entity.normalized_value.text) תואם לערך הטקסט של ההערה, בכפוף להתאמה משוערת אם היא מופעלת.

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

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

תוויות עם מופע יחיד לעומת תוויות עם מופעים מרובים

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

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

התאמה חלקית

המתג התאמה משוערת מאפשר להחמיר או להקל על חלק מכללי ההתאמה כדי להקטין או להגדיל את מספר ההתאמות.

לדוגמה, בלי התאמה משוערת, המחרוזת ABC לא תואמת למחרוזת abc בגלל השימוש באותיות רישיות. אבל עם התאמה חלקית, הם מתאימים.

כשמפעילים התאמה משוערת, אלה השינויים בכללים:

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

• הסרת סימני פיסוק בתחילת הטקסט או בסופו: מסירה את התווים הבאים של סימני פיסוק בתחילת הטקסט או בסופו !,.:;-"?|.

• התאמה לא תלוית אותיות רישיות: ממירה את כל התווים לאותיות קטנות.

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

הערה: אי אפשר להשתמש בהתאמה משוערת לערכים מספריים. לדוגמה, 1 ו-1.00 לא תואמים, גם אם מופעלת התאמה משוערת.

ישויות טבלאיות

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

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

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

ייצוא מדדי הערכה

1. נכנסים לדף Processors במסוף Google Cloud ובוחרים את המעבד.

   כניסה לדף Processors

2. בכרטיסייה הערכה ובדיקה, לוחצים על הורדת מדדים כדי להוריד את מדדי ההערכה כקובץ JSON.

הערה: המדדים שמיוצאים מבוססים על הערך של פס ההזזה סף מהימנות בזמן הייצוא.

לוח הבקרה למעקב

לוח הבקרה של המעקב במסוף Google Cloud מאפשר ליצור בקלות תצוגות חזותיות של מעקב אחרי מדדים ומשאבים שונים שנעשה בהם שימוש במעבדי Document AI.

רשימת המדדים והשדות שלהם: מספר הדפים שעברו עיבוד בהצלחה והמספר הכולל של המסמכים שנשלחו לעיבוד. לשני המדדים האלה יש את השדות הבאים: location,‏ processor type,‏ processor_id,‏ processor_version_id,‏ status ו-processing_type.

המדדים זמן אחזור של סנכרון, זמן אחזור של עיבוד ברצף לכל מסמך ומספר פעולות עיבוד ברצף כוללים את השדות הבאים: location,‏ processor_type,‏ processor_id,‏ processor_version_id ו-status.

יצירת תצוגת מעקב

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

1. במסוף Google Cloud , בקטע Document AI, עוברים לדף Processors.

   כניסה לדף Processors

2. אופציונלי: אם רוצים לעקוב אחרי מעבד ספציפי, בוחרים אותו מהרשימה.

3. בחלונית הניווט, בוחרים באפשרות Monitoring monitoring.

4. מגדירים את טווח הזמן.

5. מסמנים את תיבות הסימון של התוויות שנבחרו למדד ולמשאב ולוחצים על אישור.

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

6. אופציונלי: אפשר לראות אפשרויות נוספות לכל תרשים באמצעות האפשרות תפריט .