צינור להעברת נתונים ב-Cloud Storage

במאמר הזה מוסבר מה עושה צינור ההזנה של Cloud Storage ואיך מפעילים אותו.

מה עושה צינור ההזנה של Cloud Storage?

המשתמשים יכולים להעביר מסמכים מ-Cloud Storage אל Document AI Warehouse. המשתמשים יכולים לבחור אם לעבד את הקבצים למשימות כמו חיפוש, תהליכי עבודה לניהול מסמכים או פשוט לבדוק את הפלט של Document AI.

למה כדאי להשתמש בצינור הזה?

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

תכונות של צינורות עיבוד נתונים

באופן כללי, צינור עיבוד הנתונים להעברה ל-Cloud Storage תומך בפעולות הבאות:

  • הטמעת מסמכים גולמיים ב-Document AI Warehouse.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
  }
}

  • הטמעת מסמכים שעברו עיבוד ב-Document AI ב-Document AI Warehouse.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}

    חובה להשתמש ב-processor_type כדי לציין שקובצי הקלט עברו עיבוד על ידי Document AI. ‫processor_type (OCR_PROCESSOR, INVOICE_PROCESSOR, FORM_PARSER_PROCESSOR) אפשר למצוא בשדה Type in API כאן.

  • הטמעת מסמכים שעברו עיבוד ב-Document AI ומסמכי המקור התואמים באותה בקשה.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}

    המיקום input_path חייב להכיל מסמכים שעברו עיבוד ב-Document AI. הצינור מאתר מסמכים גולמיים תואמים לכל מסמך שעבר עיבוד ב-Doc AI בנתיב ה-URI הזה.

  • הטמעת סוג אחד של מסמך גולמי והפעלת עיבוד באמצעות AI של Document AI בפייפליין.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    extract_processor_infos: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
      schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
    },
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

    השדה extract_processor_infos חייב להכיל רק מעבד חילוץ אחד. כל המסמכים בשדה input_path נחשבים לסוג מסמך אחד ומעובדים על ידי אותו מעבד חילוץ.

  • הטמעה של סוגים שונים של מסמכים גולמיים והפעלת עיבוד באמצעות AI של Document AI בפייפליין.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    split_classify_processor_info: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
    },
    extract_processor_infos: [
      {
        processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
        document_type: "DOCUMENT_TYPE",
        schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
      }
    ],
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

    בשדה split_classify_processor_info המסמכים מסווגים לפי סוג. השדה extract_processor_infos (שמועבר כמערך) צריך להכיל מעבדי חילוץ שונים שמתאימים לכל סוג מסמך מתוצאת הסיווג.

הגדרות הטמעה

צינור ההזנה של Cloud Storage תומך בהתאמות אישיות אופציונליות במהלך ההזנה של מסמכים, כפי שמתואר באפשרויות הבאות:

  • משתמשים בדגל skip_ingested_documents כדי לדלג על מסמכים שהועברו לעיבוד כשהצינור מופעל באותה תיקייה ב-Cloud Storage יותר מפעם אחת. אם מסמכים ב-Cloud Storage מכילים את המטא-נתונים status=ingested, שהם תכונה למעקב אחר סטטוס של צינורות, המסמכים לא ייקלטו מחדש אם הדגל הזה מופעל.

  • אפשר להשתמש בדגל document_acl_policy כדי לספק מדיניות ACL נוספת ברמת המסמך במהלך יצירת המסמכים. הדגל הזה מיועד לפרויקטים שבהם מופעלות רשימות ACL ברמת המסמך ב-Document AI Warehouse.

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

    • RAW_DOCUMENT_FILE_TYPE_TEXT
    • RAW_DOCUMENT_FILE_TYPE_DOCX

  • משתמשים בשדה folder כדי לציין את תיקיית היעד למסמכים שהועלו. כל המסמכים שיועברו יקושרו לתיקיית ההורה שצוינה.

  • אפשר להשתמש בשדה cloud_function כדי להתאים אישית עוד יותר את השדות בקובץ הפרוטו של המסמך לפני שהוא מועבר אל Document AI Warehouse. הערך של cloud_function חייב להיות כתובת URL תקינה שחשבון השירות של Document AI Warehouse יכול לגשת אליה. כל שיחה חייבת להסתיים תוך 5 דקות. הבקשות והתשובות הן בפורמט JSON. יכול להיות שתמצאו את המפתחות האלה במטען הייעודי (payload) של הבקשה:

    • display_name
    • properties
    • plain_text או cloud_ai_document.text
    • reference_id
    • document_schema_name
    • raw_document_path
    • raw_document_file_type

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

    • display_name
    • properties
    • plain_text או cloud_ai_document.text
    • reference_id
    • document_acl_policy
    • folder

  • התאמה אישית של צינור עיבוד נתונים להעברה באמצעות pipeline_config.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    skip_ingested_documents: "true",
    pipeline_config: {
      enable_document_text_extraction: "true"
      folder: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documents/FOLDER_DOCUMENT_ID",
      cloud_function: "https://REGION-PROJECT_ID.cloudfunctions.net/CLOUD_FUNCTION_NAME"
    }
  }
}

מעקב אחר סטטוס

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

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

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

    • מפתח: status; ערך: status=queued או status=processed או status=ingested או status=failed.
    • מקש: error; ערך: the error message.

סוגי המסמכים שאפשר להעלות

סוגי המסמכים הנתמכים בצינור הם אותם סוגים שנתמכים ב-Document AI Warehouse: טקסט, קובצי PDF, תמונות (קובצי PDF סרוקים, קובצי TIFF, קובצי JPEG), קובץ Microsoft Office (DOCX, ‏ PPTX, ‏ XSLX).

מאפייני מסמך ממטא-נתונים של Cloud Storage

אתם יכולים להשתמש במטא-נתונים של Cloud Storage בצינור כדי ליצור מאפיינים בהתאמה אישית ב-Document AI Warehouse. ערך מטא-נתונים של מסמך Cloud Storage יועתק באופן אוטומטי למאפיין המסמך התואם ב-Document AI Warehouse אם המפתח שלו תואם לשם מאפיין בסכימה.

הרצת צינור עיבוד הנתונים

הפרמטרים השונים נדרשים כדי להפעיל פונקציות שונות בצינור ההעברה של Cloud Storage. מידע נוסף זמין במאמר בנושא Method: projects.locations.runPipeline.

בחלק הבא מופיעות שתי דוגמאות להפעלת צינור ההזנה של Cloud Storage.

  • מריצים את צינור ההזנה של Cloud Storage בלי מעבדים של Document AI.

    REST

    curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
"schema_name": "projects/PROJECT_NUMBER/locations/
LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

  • הפעלת צינור להטמעת נתונים ב-Cloud Storage באמצעות מעבדים של Document AI.

    REST

    curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_with_doc_ai_processors_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
            "split_classify_processor_info": {
              "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
            },
            "extract_processor_infos": [
              {
                "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
                "document_type": "DOCUMENT_TYPE",
                "schema_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
              }
            ],
            "processor_results_folder_path": "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME/"
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

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

קבלת תוצאה של פעולה ממושכת

REST

curl --location --request GET 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION' \
--header "Authorization: Bearer ${AUTH_TOKEN}"

השלבים הבאים

כדי לבדוק מסמכים שהועלו, עוברים אל אפליקציית האינטרנט של Document AI Warehouse.