רענון נתונים מובנים ולא מובנים

בדף הזה מוסבר איך לרענן נתונים מובְנים ולא מובְנים.

רענון הנתונים המובְנים

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

אפשר לרענן נתונים מובְנים במסוף Google Cloud או באמצעות ה-API.

המסוף

כדי לרענן נתונים מובְנים מענף של מאגר נתונים באמצעות מסוף Google Cloud :

1. נכנסים לדף Gemini Enterprise במסוף Google Cloud .

   Gemini Enterprise

2. בתפריט הניווט, לוחצים על מאגרי נתונים.

3. בעמודה Name, לוחצים על מאגר הנתונים שרוצים לערוך.

4. בכרטיסייה מסמכים, לוחצים על ייבוא נתונים.

5. כדי לרענן מ-Cloud Storage:

   1. בחלונית Select a data source, בוחרים באפשרות Cloud Storage.
   2. בחלונית Import data from Cloud Storage, לוחצים על Browse, בוחרים את הקטגוריה שמכילה את הנתונים המעודכנים ולוחצים על Select. לחלופין, אפשר להזין את מיקום הקטגוריה ישירות בשדה //:gs.
   3. בקטע אפשרויות ייבוא נתונים, בוחרים אפשרות ייבוא.
   4. לוחצים על Import.

6. כדי לרענן מ-BigQuery:

   1. בחלונית בחירת מקור נתונים, בוחרים באפשרות BigQuery.
   2. בחלונית Import data from BigQuery, לוחצים על Browse, בוחרים טבלה שמכילה את הנתונים שרועננו ולוחצים על Select. לחלופין, אפשר להזין את מיקום הטבלה ישירות בשדה BigQuery path.
   3. בקטע אפשרויות ייבוא נתונים, בוחרים אפשרות ייבוא.
   4. לוחצים על Import.

REST

משתמשים ב-method‏ documents.import כדי לרענן את הנתונים, ומציינים את הערך המתאים של reconciliationMode.

כדי לרענן נתונים מובְנים מ-BigQuery או מ-Cloud Storage באמצעות שורת הפקודה:

1. מאתרים את מזהה מאגר הנתונים. אם כבר יש לכם את מזהה מאגר הנתונים, דלגו לשלב הבא.

   1. במסוף Google Cloud , נכנסים לדף Gemini Enterprise ובתפריט הניווט לוחצים על מאגרי נתונים.

      נכנסים לדף Data Stores.

   2. לוחצים על השם של מאגר הנתונים.

   3. בדף Data של מאגר הנתונים, מאתרים את המזהה של מאגר הנתונים.

2. כדי לייבא את הנתונים המובְנים מ-BigQuery, צריך להפעיל את השיטה הבאה. אפשר לייבא מ-BigQuery או מ-Cloud Storage. כדי לייבא מ-Cloud Storage, דלגו לשלב הבא.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents:import" \
   -d '{
     "bigquerySource": {
       "projectId": "PROJECT_ID",
       "datasetId":"DATASET_ID",
       "tableId": "TABLE_ID",
       "dataSchema": "DATA_SCHEMA_BQ",
     },
     "reconciliationMode": "RECONCILIATION_MODE",
     "autoGenerateIds": AUTO_GENERATE_IDS,
     "idField": "ID_FIELD",
     "errorConfig": {
       "gcsPrefix": "ERROR_DIRECTORY"
     }
   }'
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫DATA_STORE_ID: המזהה של מאגר הנתונים.
   • ‫DATASET_ID: השם של מערך הנתונים ב-BigQuery.
   • ‫TABLE_ID: השם של הטבלה ב-BigQuery.
   • ‫DATA_SCHEMA_BQ: שדה אופציונלי שבו מציינים את הסכימה שבה משתמשים כשמנתחים נתונים מהמקור ב-BigQuery. יכול לקבל את הערכים הבאים:
     • ‫document: ערך ברירת המחדל. הטבלה ב-BigQuery שבה אתם משתמשים צריכה להתאים לסכימת ברירת המחדל הבאה של BigQuery. אתם יכולים להגדיר את המזהה של כל מסמך בעצמכם, ולעטוף את כל הנתונים במחרוזת json_data.
     • ‫custom: אפשר להשתמש בכל סכימה של טבלה ב-BigQuery, ו-Gemini Enterprise יוצר באופן אוטומטי את המזהים לכל מסמך שיובא.
   • ‫ERROR_DIRECTORY: שדה אופציונלי שבו מציינים ספריית Cloud Storage למידע על שגיאות בייבוא, לדוגמה gs://<your-gcs-bucket>/directory/import_errors. ‫Google ממליצה להשאיר את השדה הזה ריק כדי לאפשר ל-Gemini Enterprise ליצור ספרייה זמנית באופן אוטומטי.
   • ‫RECONCILIATION_MODE: שדה אופציונלי שבו מציינים איך המסמכים המיובאים יותאמו למסמכים הקיימים במאגר הנתונים של היעד. יכול לכלול את הערכים הבאים:
     • ‫INCREMENTAL: ערך ברירת המחדל. גורם לרענון מצטבר של הנתונים מ-BigQuery למאגר הנתונים. הפעולה הזו מבצעת עדכון או הוספה (upsert), שמוסיפה מסמכים חדשים ומחליפה מסמכים קיימים במסמכים מעודכנים עם אותו מזהה.
     • ‫FULL: גורם לשינוי בסיס מלא של המסמכים במאגר הנתונים. לכן, מסמכים חדשים ומעודכנים מתווספים למאגר הנתונים, ומסמכים שלא נמצאים ב-BigQuery מוסרים ממאגר הנתונים. מצב FULL שימושי אם רוצים למחוק באופן אוטומטי מסמכים שכבר לא צריך.

   • ‫AUTO_GENERATE_IDS: שדה אופציונלי שבו מציינים אם ליצור מזהי מסמכים באופן אוטומטי. אם הערך הוא true, מזהי המסמכים נוצרים על סמך גיבוב (hash) של המטען הייעודי (payload). חשוב לזכור שמזהי המסמכים שנוצרו לא בהכרח יישארו עקביים בכמה ייבואים. אם אתם יוצרים מזהים באופן אוטומטי בכמה פעולות ייבוא, Google ממליצה מאוד להגדיר את reconciliationMode ל-FULL כדי לשמור על מזהי מסמכים עקביים.

     מציינים את autoGenerateIds רק כש-bigquerySource.dataSchema מוגדר ל-custom. אחרת, תוחזר השגיאה INVALID_ARGUMENT. אם לא מציינים את autoGenerateIds או מגדירים אותו כ-false, צריך לציין את idField. אחרת, ייבוא המסמכים ייכשל.

   • ‫ID_FIELD: שדה אופציונלי שבו מציינים אילו שדות הם מזהי המסמכים. בקובצי מקור של BigQuery, הערך idField מציין את שם העמודה בטבלה ב-BigQuery שמכילה את מזהי המסמכים.

     צריך לציין את idField רק כששני התנאים הבאים מתקיימים, אחרת תוחזר השגיאה INVALID_ARGUMENT:

     • הערך של bigquerySource.dataSchema הוא custom
     • הערך של auto_generate_ids הוא false או לא צוין.

     בנוסף, הערך של שם העמודה ב-BigQuery חייב להיות מסוג מחרוזת, באורך של 1 עד 63 תווים, ובהתאם ל-RFC-1034. אחרת, ייבוא המסמכים ייכשל.

   זו הסכימה שמוגדרת כברירת מחדל ב-BigQuery. הטבלה ב-BigQuery צריכה להתאים לסכימה הזו כשמגדירים את dataSchema לערך document.

   [
    {
      "name": "id",
      "mode": "REQUIRED",
      "type": "STRING",
      "fields": []
    },
    {
      "name": "jsonData",
      "mode": "NULLABLE",
      "type": "STRING",
      "fields": []
    }
   ]
   

3. כדי לייבא את הנתונים המובְנים מ-Cloud Storage, צריך להפעיל את השיטה הבאה. אפשר לייבא מ-BigQuery או מ-Cloud Storage. כדי לייבא מ-BigQuery, צריך לחזור לשלב הקודם.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents:import" \
   -d '{
     "gcsSource": {
       "inputUris": ["GCS_PATHS"],
       "dataSchema": "DATA_SCHEMA_GCS",
     },
     "reconciliationMode": "RECONCILIATION_MODE",
     "idField": "ID_FIELD",
     "errorConfig": {
       "gcsPrefix": "ERROR_DIRECTORY"
     }
   }'
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫DATA_STORE_ID: המזהה של מאגר הנתונים.
   • ‫GCS_PATHS: רשימה מופרדת בפסיקים של מזהי URI למיקומים ב-Cloud Storage שמהם רוצים לייבא. כל URI יכול להיות באורך של 2,000 תווים. מזהי ה-URI יכולים להתאים לנתיב המלא של אובייקט אחסון, או לתבנית של אובייקט אחד או יותר. לדוגמה, gs://bucket/directory/*.json הוא נתיב תקין.
   • ‫DATA_SCHEMA_GCS: שדה אופציונלי שבו מציינים את הסכימה שבה משתמשים כשמנתחים נתונים מהמקור ב-BigQuery. יכול לקבל את הערכים הבאים:
     • ‫document: ערך ברירת המחדל. הטבלה ב-BigQuery שבה אתם משתמשים צריכה להתאים לסכימת ברירת המחדל הבאה של BigQuery. אתם יכולים להגדיר את המזהה של כל מסמך בעצמכם, ולעטוף את כל הנתונים במחרוזת json_data.
     • ‫custom: אפשר להשתמש בכל סכימה של טבלה ב-BigQuery, ו-Gemini Enterprise יוצר באופן אוטומטי את המזהים לכל מסמך שיובא.
   • ‫ERROR_DIRECTORY: שדה אופציונלי שבו מציינים ספריית Cloud Storage למידע על שגיאות בייבוא, לדוגמה gs://<your-gcs-bucket>/directory/import_errors. ‫Google ממליצה להשאיר את השדה הזה ריק כדי לאפשר ל-Gemini Enterprise ליצור ספרייה זמנית באופן אוטומטי.
   • ‫RECONCILIATION_MODE: שדה אופציונלי שבו מציינים איך המסמכים המיובאים יותאמו למסמכים הקיימים במאגר הנתונים של היעד. יכול לכלול את הערכים הבאים:
     • ‫INCREMENTAL: ערך ברירת המחדל. גורם לרענון מצטבר של הנתונים מ-BigQuery למאגר הנתונים. הפעולה הזו מבצעת עדכון או הוספה (upsert), שמוסיפה מסמכים חדשים ומחליפה מסמכים קיימים במסמכים מעודכנים עם אותו מזהה.
     • ‫FULL: גורם לשינוי בסיס מלא של המסמכים במאגר הנתונים. לכן, מסמכים חדשים ומעודכנים נוספים למאגר הנתונים, ומסמכים שלא נמצאים ב-BigQuery מוסרים ממאגר הנתונים. מצב FULL שימושי אם רוצים למחוק באופן אוטומטי מסמכים שכבר לא צריך.

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במדריך למתחילים של Gemini Enterprise באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Gemini Enterprise Python API.

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

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION" # Values: "global"
# data_store_id = "YOUR_DATA_STORE_ID"
# bigquery_dataset = "YOUR_BIGQUERY_DATASET"
# bigquery_table = "YOUR_BIGQUERY_TABLE"

#  For more information, refer to:
# https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)

# Create a client
client = discoveryengine.DocumentServiceClient(client_options=client_options)

# The full resource name of the search engine branch.
# e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
parent = client.branch_path(
    project=project_id,
    location=location,
    data_store=data_store_id,
    branch="default_branch",
)

request = discoveryengine.ImportDocumentsRequest(
    parent=parent,
    bigquery_source=discoveryengine.BigQuerySource(
        project_id=project_id,
        dataset_id=bigquery_dataset,
        table_id=bigquery_table,
        data_schema="custom",
    ),
    # Options: `FULL`, `INCREMENTAL`
    reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
)

# Make the request
operation = client.import_documents(request=request)

print(f"Waiting for operation to complete: {operation.operation.name}")
response = operation.result()

# After the operation is complete,
# get information from operation metadata
metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

# Handle the response
print(response)
print(metadata)

רענון נתונים לא מובנים

אפשר לרענן נתונים לא מובְנים במסוף Google Cloud או באמצעות ה-API.

המסוף

כדי לרענן נתונים לא מובְנים מענף של מאגר נתונים באמצעות מסוף Google Cloud :

1. נכנסים לדף Gemini Enterprise במסוף Google Cloud .

   Gemini Enterprise

2. בתפריט הניווט, לוחצים על מאגרי נתונים.

3. בעמודה Name, לוחצים על מאגר הנתונים שרוצים לערוך.

4. בכרטיסייה מסמכים, לוחצים על ייבוא נתונים.

5. כדי להטמיע מקטגוריה של Cloud Storage (עם או בלי מטא-נתונים):

   1. בחלונית Select a data source, בוחרים באפשרות Cloud Storage.
   2. בחלונית Import data from Cloud Storage, לוחצים על Browse, בוחרים את הקטגוריה שמכילה את הנתונים המעודכנים ולוחצים על Select. לחלופין, אפשר להזין את מיקום הקטגוריה ישירות בשדה gs://.
   3. בקטע אפשרויות ייבוא נתונים, בוחרים אפשרות ייבוא.
   4. לוחצים על Import.

6. כדי להטמיע נתונים מ-BigQuery:

   1. בחלונית בחירת מקור נתונים, בוחרים באפשרות BigQuery.
   2. בחלונית Import data from BigQuery, לוחצים על Browse, בוחרים טבלה שמכילה את הנתונים שרועננו ולוחצים על Select. לחלופין, אפשר להזין את מיקום הטבלה ישירות בשדה BigQuery path.
   3. בקטע אפשרויות ייבוא נתונים, בוחרים אפשרות ייבוא.
   4. לוחצים על Import.

REST

כדי לרענן נתונים לא מובְנים באמצעות ה-API, מייבאים אותם מחדש באמצעות ה-method‏ documents.import ומציינים את הערך המתאים של reconciliationMode. מידע נוסף על ייבוא נתונים לא מובְנים זמין במאמר נתונים לא מובְנים.

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במדריך למתחילים של Gemini Enterprise באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Gemini Enterprise Python API.

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

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION" # Values: "global"
# data_store_id = "YOUR_DATA_STORE_ID"

# Examples:
# - Unstructured documents
#   - `gs://bucket/directory/file.pdf`
#   - `gs://bucket/directory/*.pdf`
# - Unstructured documents with JSONL Metadata
#   - `gs://bucket/directory/file.json`
# - Unstructured documents with CSV Metadata
#   - `gs://bucket/directory/file.csv`
# gcs_uri = "YOUR_GCS_PATH"

#  For more information, refer to:
# https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)

# Create a client
client = discoveryengine.DocumentServiceClient(client_options=client_options)

# The full resource name of the search engine branch.
# e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
parent = client.branch_path(
    project=project_id,
    location=location,
    data_store=data_store_id,
    branch="default_branch",
)

request = discoveryengine.ImportDocumentsRequest(
    parent=parent,
    gcs_source=discoveryengine.GcsSource(
        # Multiple URIs are supported
        input_uris=[gcs_uri],
        # Options:
        # - `content` - Unstructured documents (PDF, HTML, DOC, TXT, PPTX)
        # - `custom` - Unstructured documents with custom JSONL metadata
        # - `document` - Structured documents in the discoveryengine.Document format.
        # - `csv` - Unstructured documents with CSV metadata
        data_schema="content",
    ),
    # Options: `FULL`, `INCREMENTAL`
    reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
)

# Make the request
operation = client.import_documents(request=request)

print(f"Waiting for operation to complete: {operation.operation.name}")
response = operation.result()

# After the operation is complete,
# get information from operation metadata
metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

# Handle the response
print(response)
print(metadata)