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

‫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")

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

evaluate-the-performance-of-processors-1

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

  • דיוק: שיעור החיזויים שתואמים להערות בקבוצת נתונים לבדיקה. מוגדר כ-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)

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

evaluate-the-performance-of-processors-2

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

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

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

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

סף ביטחון

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

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

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

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

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

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

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

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

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

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

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

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

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

התאמה חלקית

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

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

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

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

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

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

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

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

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

אחרי שמתבצעת התאמה בין ההורים, מתבצעת התאמה בין הילדים כאילו הם לא היו ישויות טבלאיות. אם לא נמצאה התאמה בין ההורים, 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. אופציונלי: כדי לראות אפשרויות נוספות לכל תרשים, לוחצים על סמל התפריט .

הקודם
אימון מחדש של מעבד שעבר אימון מראש
הבא
קידוד Base64