הערה: חבילת המסמכים הזו מיועדת למהדורות Standard,‏ Plus,‏ תשלום לפי שימוש ו-Frontline של Gemini Enterprise. לעיון במסמכי התיעוד של מהדורת Business, אפשר להיכנס אל מרכז העזרה של Gemini Enterprise – מהדורת Business.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

יצירת מחבר בהתאמה אישית

בדף הזה מוסבר איך ליצור מחבר בהתאמה אישית.

לפני שמתחילים

לפני שמתחילים, חשוב לוודא שהתנאים הבאים מתקיימים:

איך בודקים אם החיוב מופעל בפרויקט Google Cloud
מתקינים ומפעילים את ה-CLI של gcloud. מוודאים שהיא מאומתת בפרויקט.
מתקינים את ספריות Python הנדרשות:
```
pip install google-cloud-discoveryengine requests
```
מקבלים גישה של אדמין ב-Discovery Engine לפרויקט ב- Google Cloud .
מקבלים פרטי גישה למקור הנתונים של הצד השלישי (כמו מפתחות API או אימות מסד נתונים).
יוצרים תוכנית ברורה למיפוי הנתונים. ההגדרה הזו צריכה לכלול את השדות שצריך להוסיף לאינדקס ואת האופן שבו בקרת הגישה מיוצגת, כולל זהויות של צד שלישי.

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

יצירת מחבר בסיסי

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

אחזור נתונים

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

Python

    from typing import List
    import requests

    def fetch_posts(base_url: str, per_page: int = 15) -> List[dict]:
        #Fetch all posts from the given site.#
        url = base_url.rstrip("/") + "/wp-json/wp/v2/posts"
        posts: List[dict] = []
        page = 1
        while True:
            resp = requests.get(
                url,
                params={"page": page, "per_page": per_page},
                # headers={"Authorization": "Bearer YOUR_API_KEY"}, # Add auth if needed
            )
            resp.raise_for_status()
            batch = resp.json()
            posts.extend(batch)
            if len(batch) < per_page:
                break
            page += 1
        return posts

שינוי נתונים

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

Python

    from typing import List
    import json
    from google.cloud import discoveryengine_v1 as discoveryengine

    def convert_posts_to_documents(posts: List[dict]) -> List[discoveryengine.Document]:
        # Convert WP posts into Discovery Engine Document messages.
        docs: List[discoveryengine.Document] = []
        for post in posts:
            payload = {
                "title": post.get("title", {}).get("rendered"),
                "body": post.get("content", {}).get("rendered"),
                "url": post.get("link"),
                "author": post.get("author"),
                "categories": post.get("categories"),
                "tags": post.get("tags"),
                "date": post.get("date"),
            }
            doc = discoveryengine.Document(
                id=str(post["id"]),
                json_data=json.dumps(payload),
            )
            docs.append(doc)
        return docs

אחזור או יצירה של מאגר זהויות

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

Python

    from google.cloud import discoveryengine_v1 as discoveryengine

    def get_or_create_ims_data_store(
        project_id: str,
        location: str,
        identity_mapping_store_id: str,
    ) -> discoveryengine.DataStore:
      """Get or create a DataStore."""
      # Initialize the client
      client_ims = discoveryengine.IdentityMappingStoreServiceClient()
      # Construct the parent resource name
      parent_ims = client_ims.location_path(project=project_id, location=location)

      try:
        # Create the request object
        name = f"projects/{project_id}/locations/{location}/identityMappingStores/{identity_mapping_store_id}"
        request = discoveryengine.GetIdentityMappingStoreRequest(
            name=name,
        )
        return client_ims.get_identity_mapping_store(request=request)
      except:
        # Create the IdentityMappingStore object (it can be empty for basic creation)
        identity_mapping_store = discoveryengine.IdentityMappingStore()
        # Create the request object
        request = discoveryengine.CreateIdentityMappingStoreRequest(
            parent=parent_ims,
            identity_mapping_store=identity_mapping_store,
            identity_mapping_store_id=identity_mapping_store_id,
        )
        return client_ims.create_identity_mapping_store(request=request)

הפונקציה get_or_create_ims_data_store משתמשת במשתני המפתח הבאים:

‫project_id: מזהה הפרויקט ב- Google Cloud .
‫location: Google Cloud המיקום של מאגר מיפוי הזהויות.
‫identity_mapping_store_id: מזהה ייחודי של מאגר הזהויות.
‫client_ims: מופע של discoveryengine.IdentityMappingStoreServiceClient שמשמש לאינטראקציה עם ה-API של מאגר הזהויות.
‫parent_ims: שם המשאב של מיקום האב, שנוצר באמצעות client_ims.location_path.
‫name: שם המשאב המלא של מאגר מיפוי הזהויות, שמשמש ל-GetIdentityMappingStoreRequest.

הטמעת מיפוי זהויות במאגר הזהויות

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

Python

from google.cloud import discoveryengine_v1 as discoveryengine

def load_ims_data(
    ims_store: discoveryengine.DataStore,
    id_mapping_data: list[discoveryengine.IdentityMappingEntry],
) -> discoveryengine.DataStore:
  """Get the IMS data store."""
  # Initialize the client
  client_ims = discoveryengine.IdentityMappingStoreServiceClient()

  #  Create the InlineSource object
  inline_source = discoveryengine.ImportIdentityMappingsRequest.InlineSource(
      identity_mapping_entries=id_mapping_data
  )

  # Create the main request object
  request_ims = discoveryengine.ImportIdentityMappingsRequest(
      identity_mapping_store=ims_store.name,
      inline_source=inline_source,
  )

  try:
    # Create the InlineSource object, which holds your list of entries
    operation = client_ims.import_identity_mappings(
        request=request_ims,
    )
    result = operation.result()
    return result

  except Exception as e:
    print(f"IMS Load Error: {e}")
    return None

הפונקציה load_ims_data משתמשת במשתני המפתח הבאים:

‫ims_store: האובייקט discoveryengine.DataStore שמייצג את מאגר מיפוי הזהויות שאליו ייטענו הנתונים.
‫id_mapping_data: רשימה של אובייקטים מסוג discoveryengine.IdentityMappingEntry, שכל אחד מהם מכיל זהות חיצונית ואת מזהה המשתמש או הקבוצה התואם.
‫result: ערך ההחזרה מסוג discoveryengine.DataStore.

יצירת מאגר נתונים

כדי להשתמש במחבר בהתאמה אישית, צריך להפעיל מאגר נתונים לתוכן. משתמשים ב-default_collection עבור מחברים בהתאמה אישית. הפרמטר IndustryVertical מתאים אישית את ההתנהגות של מאגר הנתונים לתרחישים ספציפיים לדוגמה. ההגדרה GENERIC מתאימה לרוב התרחישים. עם זאת, אתם יכולים לבחור ערך אחר לתחום מסוים, כמו MEDIA או HEALTHCARE_FHIR. מגדירים את השם המוצג ומאפיינים אחרים בהתאם לדרישות ולמוסכמות מתן השמות של הפרויקט.

Python

from google.cloud import discoveryengine_v1 as discoveryengine

def get_or_create_data_store(
    project_id: str,
    location: str,
    display_name: str,
    data_store_id: str,
    identity_mapping_store: str,
) -> discoveryengine.DataStore:
  """Get or create a DataStore."""
  client = discoveryengine.DataStoreServiceClient()
  ds_name = client.data_store_path(project_id, location, data_store_id)
  try:
    result = client.get_data_store(request={"name": ds_name})
    return result
  except:
    parent = client.collection_path(project_id, location, "default_collection")
    operation = client.create_data_store(
        request={
            "parent": parent,
            "data_store": discoveryengine.DataStore(
                display_name=display_name,
                acl_enabled=True,
                industry_vertical=discoveryengine.IndustryVertical.GENERIC,
                identity_mapping_store=identity_mapping_store,
            ),
            "data_store_id": data_store_id,
        }
    )
    result = operation.result()
    return result

הפונקציה get_or_create_data_store משתמשת במשתני המפתח הבאים:

‫project_id: מזהה הפרויקט ב- Google Cloud .
location: המיקום של Google Cloud מאגר הנתונים.
‫display_name: השם המוצג של מאגר הנתונים, שקריא לאנשים.
‫data_store_id: מזהה ייחודי של מאגר הנתונים.
‫identity_mapping_store: שם המשאב של מאגר מיפוי הזהויות לקשירה.
‫result: ערך החזרה מסוג discoveryengine.DataStore.

העלאת מסמכים בתוך הטקסט

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

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

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

Python

    from typing import List
    from google.cloud import discoveryengine_v1 as discoveryengine

    def upload_documents_inline(
        project_id: str,
        location: str,
        data_store_id: str,
        branch_id: str,
        documents: List[discoveryengine.Document],
    ) -> discoveryengine.ImportDocumentsMetadata:
        """Inline import of Document messages."""
        client = discoveryengine.DocumentServiceClient()
        parent = client.branch_path(
            project=project_id,
            location=location,
            data_store=data_store_id,
            branch=branch_id,
        )
        request = discoveryengine.ImportDocumentsRequest(
            parent=parent,
            inline_source=discoveryengine.ImportDocumentsRequest.InlineSource(
                documents=documents,
            ),
        )
        operation = client.import_documents(request=request)
        operation.result()
        result = operation.metadata
        return result

הפונקציה upload_documents_inline משתמשת במשתני המפתח הבאים:

‫project_id: מזהה הפרויקט ב- Google Cloud .
location: המיקום של Google Cloud מאגר הנתונים.
‫data_store_id: המזהה של מאגר הנתונים.
‫branch_id: המזהה של הענף במאגר הנתונים (בדרך כלל '0').
‫documents: רשימה של אובייקטים מסוג discoveryengine.Document להעלאה.
‫result: ערך החזרה מסוג discoveryengine.ImportDocumentsMetadata.

השדה uri באובייקט discoveryengine.Document משמש כדי להצביע על מקור התוכן שהוטמע, כבייטים גולמיים או כ-URI ב- Google Cloud Storage. ה-URI הזה שונה מה-URI של תוכן המקור של הצד השלישי. צריך להגדיר את ה-URI של תוכן המקור של הצד השלישי כשדה בתוך המטען הייעודי (payload) של json_data במסמך. לדוגמה, בפונקציה convert_posts_to_documents, השדה url ב-payload משמש למטרה הזו.

אימות המחבר

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

Python

    from google.cloud import discoveryengine_v1 as discoveryengine
    from google.api_core import exceptions as gcp_exceptions

    SITE = "https://altostrat.com"
    PROJECT_ID = "ucs-3p-connectors-testing"
    LOCATION = "global"
    IDENTITY_MAPPING_STORE_ID = "your-unique-ims-id17" # A unique ID for your new store
    DATA_STORE_ID = "my-acl-ds-id1"
    BRANCH_ID = "0"

    posts = fetch_posts(SITE)
    docs = convert_posts_to_documents(posts)
    print(f"Fetched {len(posts)} posts and converted to {len(docs)} documents.")

    try:
      # Step #1: Retrieve an existing identity mapping store or create a new identity mapping store
      ims_store = get_or_create_ims_data_store(PROJECT_ID, LOCATION, IDENTITY_MAPPING_STORE_ID)
      print(f"STEP #1: IMS Store Retrieval/Creation: {ims_store}")

      RAW_IDENTITY_MAPPING_DATA = [
          discoveryengine.IdentityMappingEntry(
              external_identity="external_id_1",
              user_id="testuser1@example.com",
          ),
          discoveryengine.IdentityMappingEntry(
              external_identity="external_id_2",
              user_id="testuser2@example.com",
          ),
          discoveryengine.IdentityMappingEntry(
              external_identity="external_id_2",
              group_id="testgroup1@example.com",
          )
      ]

      # Step #2: Load IMS Data
      response = load_ims_data(ims_store, RAW_IDENTITY_MAPPING_DATA)
      print(
          "\nStep #2: Load Data in IMS Store successful.", response
      )

      # Step #3: Create Entity Data Store & Bind IMS Data Store
      data_store =  get_or_create_data_store(PROJECT_ID, LOCATION, "my-acl-datastore", DATA_STORE_ID, ims_store.name)
      print("\nStep #3: Entity Data Store Create Result: ", data_store)

      metadata = upload_documents_inline(
          PROJECT_ID, LOCATION, DATA_STORE_ID, BRANCH_ID, docs
      )
      print(f"Uploaded {metadata.success_count} documents inline.")

    except gcp_exceptions.GoogleAPICallError as e:
      print(f"\n--- API Call Failed ---")
      print(f"Server Error Message: {e.message}")
      print(f"Status Code: {e.code}")

    except Exception as e:
      print(f"An error occurred: {e}")

מוודאים שקוד המחבר משתמש במשתני המפתח הבאים:

‫SITE: כתובת ה-URL הבסיסית של מקור הנתונים של הצד השלישי.
‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
‫LOCATION: Google Cloud המיקום של המשאבים.
‫IDENTITY_MAPPING_STORE_ID: מזהה ייחודי של מאגר מיפוי הזהויות.
‫DATA_STORE_ID: מזהה ייחודי של מאגר הנתונים.
‫BRANCH_ID: המזהה של הענף במאגר הנתונים.
‫posts: מאחסן את הפוסטים שנמשכו ממקור צד שלישי.
‫docs: מאחסן את המסמכים שהומרו בפורמט discoveryengine.Document.
‫ims_store: אובייקט discoveryengine.DataStore שאוחזר או נוצר למיפוי זהויות.
‫RAW_IDENTITY_MAPPING_DATA: רשימה של אובייקטים מסוג discoveryengine.IdentityMappingEntry.

הפלט אמור להיראות כך:

מעטפת

  Fetched 20 posts and converted to 20 documents.
  STEP #1: IMS Store Retrieval/Creation: "projects/ <Project Number>/locations/global/identityMappingStores/your-unique-ims-id17"
  Step #2: Load Data in IMS Store successful.
  Step #3: Entity Data Store Create Result: "projects/ <Project Number>/locations/global/collections/default_collection/dataStores/my-acl-ds-id1"
  display_name: "my-acl-datastore"
  industry_vertical: GENERIC
  create_time {
    seconds: 1760906997
    nanos: 192641000
  }
  default_schema_id: "default_schema"
  acl_enabled: true
  identity_mapping_store: "projects/ <Project Number>/locations/global/identityMappingStores/your-unique-ims-id17".
  Uploaded 20 documents inline.

בשלב הזה, אתם יכולים לראות את מאגר הנתונים גם במסוף Google Google Cloud :

כשמבצעים חיפוש, המערכת משתמשת בשדות מהמטען הייעודי (payload) לצורך החיפוש, ובשדה ה-URI של המטען הייעודי לצורך ציטוטים. שלושת שדות המאפיינים העיקריים ש-Gemini Enterprise מזהה הם title,‏ description ו-uri. לשדות המסמך המתאימים יכולים להיות שמות שונים, ואפשר למפות אותם באמצעות האפשרות Schema (סכימה) -> Edit (עריכה) במסוף Google Cloud .

יצירת מחבר באמצעות Google Cloud העלאה לאחסון

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

המרת מסמכים ל-JSONL

כדי להכין מסמכים לייבוא בכמות גדולה ל-Discovery Engine, צריך להמיר אותם לפורמט JSON Lines.

Python

    from typing import List
    from google.cloud import discoveryengine_v1 as discoveryengine

    def convert_documents_to_jsonl(
        documents: List[discoveryengine.Document],
    ) -> str:
        """Serialize Document messages to JSONL."""
        return "\n".join(
            discoveryengine.Document.to_json(doc, indent=None)
            for doc in documents
        ) + "\n"

הפונקציה convert_documents_to_jsonl משתמשת במשתנה הבא:

‫documents: רשימה של אובייקטים מסוג discoveryengine.Document להמרה.

העלאה ל Google Cloud Storage

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

Python

    from google.cloud import storage

    def upload_jsonl_to_gcs(jsonl: str, bucket_name: str, blob_name: str) -> str:
        """Upload JSONL content to Google Cloud Storage."""
        client = storage.Client()
        bucket = client.bucket(bucket_name)
        blob = bucket.blob(blob_name)
        blob.upload_from_string(jsonl, content_type="application/json")
        return f"gs://{bucket_name}/{blob_name}"

הפונקציה upload_jsonl_to_gcs משתמשת במשתני המפתח הבאים:

‫jsonl: התוכן של המחרוזת בפורמט JSONL שרוצים להעלות.
‫bucket_name: השם של קטגוריית האחסון ב- Google Cloud .
‫blob_name: השם של ה-blob (האובייקט) בקטגוריה שצוינה.

ייבוא מ- Google Cloud Storage עם התאמה מלאה

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

כשמייבאים מ- Google Cloud Storage, חשוב לשים לב למגבלות הבאות:

בקשת ייבוא אחת יכולה להכיל עד 100 קבצים, או 100,000 קבצים אם הפרמטר dataSchema מוגדר לערך content.
כל קובץ יכול להיות בגודל של עד 2GB, או 100MB אם הפרמטר dataSchema מוגדר ל-content.

Python

    from google.cloud import discoveryengine_v1 as discoveryengine

    def import_documents_from_gcs(
        project_id: str,
        location: str,
        data_store_id: str,
        branch_id: str,
        gcs_uri: str,
    ) -> discoveryengine.ImportDocumentsMetadata:
        """Bulk-import documents from Google Cloud Storage with FULL reconciliation mode."""
        client = discoveryengine.DocumentServiceClient()
        parent = client.branch_path(
            project=project_id,
            location=location,
            data_store=data_store_id,
            branch=branch_id,
        )
        gcs_source = discoveryengine.GcsSource(input_uris=[gcs_uri])
        request = discoveryengine.ImportDocumentsRequest(
            parent=parent,
            gcs_source=gcs_source,
            reconciliation_mode=
                discoveryengine.ImportDocumentsRequest
                .ReconciliationMode.FULL,
        )
        operation = client.import_documents(request=request)
        operation.result()
        return operation.metadata

הפונקציה import_documents_from_gcs משתמשת במשתני המפתח הבאים:

‫project_id: מזהה הפרויקט ב- Google Cloud .
location: המיקום של Google Cloud מאגר הנתונים.
‫data_store_id: המזהה של מאגר הנתונים.
‫branch_id: המזהה של הענף במאגר הנתונים (בדרך כלל '0').
‫gcs_uri: ה-URI של Google Cloud Storage שמצביע על קובץ ה-JSONL.

העלאה לאחסון של Test Google Cloud

כדי לאמת את Google Cloud תהליך העבודה של ייבוא מבוסס-אחסון, מריצים את הפקודה הבאה:

Python

  BUCKET = "your-existing-bucket"
  BLOB = "path-to-any-blob/wp/posts.jsonl"
  SITE = "https://altostrat.com"
  PROJECT_ID = "ucs-3p-connectors-testing"
  LOCATION = "global"
  IDENTITY_MAPPING_STORE_ID = "your-unique-ims-id17" # A unique ID for your new store
  DATA_STORE_ID = "your-data-store-id"
  BRANCH_ID = "0"
  posts = fetch_posts(SITE)
  docs = convert_posts_to_documents(posts)
  print(f"Fetched {len(posts)} posts and converted to {len(docs)} documents.")
  jsonl_payload = convert_documents_to_jsonl(docs)
  gcs_uri = upload_jsonl_to_gcs(jsonl_payload, BUCKET, BLOB)
  print("Uploaded to:", gcs_uri)

  metadata = import_documents_from_gcs(
      PROJECT_ID, LOCATION, DATA_STORE_ID, BRANCH_ID, gcs_uri
  )
  print(f"Imported: {metadata.success_count} documents")

המשתנים העיקריים הבאים משמשים לבדיקת ההעלאה ל- Google Cloud Storage:

‫BUCKET: השם של קטגוריית האחסון ב- Google Cloud .
‫BLOB: הנתיב ל-blob בתוך הקטגוריה.
‫SITE: כתובת ה-URL הבסיסית של מקור הנתונים של הצד השלישי.
‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
‫LOCATION: המיקום של המשאבים (לדוגמה, global). Google Cloud
‫IDENTITY_MAPPING_STORE_ID: מזהה ייחודי של מאגר מיפוי הזהויות.
‫DATA_STORE_ID: מזהה ייחודי של מאגר הנתונים.
‫BRANCH_ID: המזהה של הענף במאגר הנתונים (בדרך כלל '0').
‫jsonl_payload: המסמכים שהומרו לפורמט JSONL.
‫gcs_uri: ה-URI של Google Cloud האחסון של קובץ ה-JSONL שהועלה.

הפלט אמור להיראות כך:

מעטפת

    Fetched 20 posts and converted to 20 documents.
    Uploaded to: gs://alex-de-bucket/wp/posts.jsonl
    Imported: 20 documents

ניהול הרשאות

כדי לנהל גישה ברמת המסמך בסביבות ארגוניות, Gemini Enterprise תומך ברשימות של בקרת גישה (ACL) ובמיפוי זהויות, שעוזרים להגביל את התוכן שהמשתמשים יכולים לראות.

הפעלת רשימות ACL במאגר הנתונים

כדי להפעיל רשימות ACL כשיוצרים את מאגר הנתונים, מריצים את הפקודה הבאה:

Python

  # get_or_create_data_store()
  "data_store": discoveryengine.DataStore(
      display_name=data_store_id,
      industry_vertical=discoveryengine.IndustryVertical.GENERIC,
      acl_enabled=True, # ADDED
  )

הוספת רשימות ACL למסמכים

כדי לחשב את AclInfo ולכלול אותו כשממירים את המסמכים, מריצים את הפקודה הבאה:

Python

  # convert_posts_to_documents()
  doc = discoveryengine.Document(
      id=str(post["id"]),
      json_data=json.dumps(payload),
      acl_info=discoveryengine.Document.AclInfo(
          readers=[{
              "principals": [
                  {"user_id": "baklavainthebalkans@gmail.com"},
                  {"user_id": "cloudysanfrancisco@gmail.com"}
              ]
          }]
      ),
  )

הגדרת התוכן כגלוי לכולם

כדי להפוך מסמך לנגיש לכולם, מגדירים את השדה readers באופן הבא:

Python

  readers=[{"idp_wide": True}]

אימות רשימות ACL

כדי לוודא שהגדרות ה-ACL פועלות כמצופה, כדאי לשקול את הדברים הבאים:

חיפוש בתור משתמש שאין לו גישה למסמך.
בודקים את מבנה המסמך שהועלה ב-Cloud Storage ומשווים אותו למבנה של מסמך לדוגמה.

JSON

  {
    "id": "108",
    "jsonData": "{...}",
    "aclInfo": {
      "readers": [
        {
          "principals": [
            { "userId": "baklavainthebalkans@gmail.com" },
            { "userId": "cloudysanfrancisco@gmail.com" }
          ],
          "idpWide": false
        }
      ]
    }
  }

שימוש במיפוי זהויות

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

מקור הנתונים של הצד השלישי משתמש ב-Google Identity
אתם רוצים להפנות לקבוצות בהתאמה אישית (למשל, wp-admins) במקום למשתמשים ספציפיים
ה-API מחזיר רק שמות של קבוצות
צריך לקבץ משתמשים באופן ידני כדי להשיג קנה מידה או עקביות
המערכת של הצד השלישי מטמיעה רשימות ACL באמצעות קבוצות שלא מבוססות על ספק זהויות, ואתם רוצים לכבד את רשימות ה-ACL האלה באמצעות מאגר הנתונים בהתאמה אישית ב-Gemini Enterprise.

כדי למפות זהויות, פועלים לפי השלבים הבאים:

יוצרים ומקשרים את מאגר נתוני הזהויות.
מייבאים זהויות חיצוניות (לדוגמה, external_group:wp-admins). לא כוללים את external_group: prefix כשמייבאים, לדוגמה:
JSON
{ "externalIdentity": "wp-admins", "userId": "user@example.com" }
בפרטי ה-ACL של המסמך, מגדירים את מזהה הישות החיצונית ב-principal identifier. כשמפנים לקבוצות בהתאמה אישית, משתמשים בקידומת external_group: בשדה groupId.

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

JSON

  {
    "id": "108",
    "aclInfo": {
      "readers": [
        {
          "principals": [
            {
              "userId": "cloudysanfrancisco@gmail.com"
            },
            {
              "groupId": "external_group:wp-admins"
            }
          ]
        }
      ]
    },
    "structData": {
      "id": 108,
      "date": "2025-04-24T18:16:04",
      ...
    }
  }

המאמרים הבאים

כדי לספק ממשק משתמש לשליחת שאילתות לגבי הנתונים, יוצרים אפליקציה ב-Gemini Enterprise ומקשרים אותה למאגר הנתונים הקיים של המחבר בהתאמה אישית.

ספריות לקוח של Gemini Enterprise

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

לפני שמתחילים

יצירת מחבר בסיסי

אחזור נתונים

Python

שינוי נתונים

Python

אחזור או יצירה של מאגר זהויות

Python

הטמעת מיפוי זהויות במאגר הזהויות

Python

Python

יצירת מאגר נתונים

Python

העלאת מסמכים בתוך הטקסט

Python

אימות המחבר

Python

מעטפת

יצירת מחבר באמצעות Google Cloud העלאה לאחסון

המרת מסמכים ל-JSONL

Python

העלאה ל Google Cloud Storage

Python

ייבוא מ- Google Cloud Storage עם התאמה מלאה

Python

העלאה לאחסון של Test Google Cloud

Python

מעטפת

ניהול הרשאות

הפעלת רשימות ACL במאגר הנתונים

Python

הוספת רשימות ACL למסמכים

Python

הגדרת התוכן כגלוי לכולם

Python

אימות רשימות ACL

JSON

שימוש במיפוי זהויות

JSON

JSON

המאמרים הבאים

יצירת מחבר בהתאמה אישית