חיפוש מסמכים במאגר נתונים

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

פורמטים נתמכים של מסמכים

בטבלה הבאה מפורטים פורמטי קובץ המסמכים וסיומות הקבצים שנתמכים.

סוג המסמך סיומת הקובץ
PDF .pdf
טקסט פשוט .txt
Microsoft Word .docx
Microsoft Excel .xlsx
‫Microsoft Excel עם פקודות מאקרו .xlsm (המערכת מתעלמת מסקריפטים ומפקודות מאקרו)
Microsoft PowerPoint .pptx

דרישות מוקדמות

לפני שמתחילים, צריך:

דוגמאות

הדוגמאות בדף הזה מבוססות על קובצי הדוגמה הבאים.

curl

PROJECT=acme-prod
LOCATION=us-east4
BASE=https://vectorsearch.googleapis.com/v1alpha
INGEST=${BASE}/projects/${PROJECT}/locations/${LOCATION}
AUTH="Authorization: Bearer $(gcloud auth print-access-token)"

Python

import time
import google.auth
from google.auth.transport.requests import AuthorizedSession

PROJECT = "acme-prod"          # Replace with your project ID
LOCATION = "us-east4"          # Replace with your region

credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
session = AuthorizedSession(credentials)

BASE = "https://vectorsearch.googleapis.com/v1alpha"
INGEST = BASE + "/projects/" + PROJECT + "/locations/" + LOCATION

def wait(operation, poll_seconds=10):
    """Poll a long-running operation until it finishes, then return it."""
    name = operation["name"]
    while True:
        op = session.get(BASE + "/" + name).json()
        if op.get("done"):
            if "error" in op:
                raise RuntimeError(op["error"])
            return op
        meta = op.get("metadata", {})
        print("in progress:", meta)
        time.sleep(poll_seconds)

צינור עיבוד הנתונים המנוהל להטמעת נתונים

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

כל מה שצריך לעשות הוא:

  1. העבירו את הקבצים ל-staging.

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

  3. מייבאים את הקבצים.

  4. לחפש קבצים באמצעות שאילתות טקסט.

1. הכנת הקבצים

יוצרים קטגוריה ומוסיפים את הקבצים שרוצים לחפש. לא צריך ליצור מניפסט.

הטמעה מנוהלת של מסמכים:

  • מדלג על מסמכים שגדולים מ-200MB.

  • המערכת מתעלמת מפקודות מאקרו וסקריפטים במסמכי Microsoft Excel עם פקודות מאקרו (.xlsm).

  • אפשר לייבא רק 100,000 מסמכים בכל פעם.

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

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

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

הטמעה מנוהלת זמינה רק למאגרי נתונים שנמצאים באזור us-east4 או europe-west4.

כדי ליצור מאגר נתונים, שולחים בקשת POST ל-API של dataStores ומציינים את הפרמטר הבא:

  • ‫data_store_id: המזהה של מאגר הנתונים שנוצר. השם צריך להתחיל באות קטנה, להסתיים באות קטנה או בספרה, להכיל רק אותיות קטנות, ספרות ומקפים, ולהיות באורך של 1 עד 63 תווים.

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

המטען הייעודי (payload) של ה-JSON חייב לכלול את המאפיין document_type ברמה העליונה. כאן מציינים את סוגי הקבצים שרוצים לייבא ממאגר הנתונים. הערכים החוקיים הם:

  • ‫UNSTRUCTURED: מאגר הנתונים מכיל מסמכים. רשימה של הפורמטים הנתמכים מופיעה בקטע פורמטים נתמכים של מסמכים.

  • ‫VIDEO: מאגר הנתונים מכיל סרטונים.

המאפיינים הבאים הם אופציונליים:

  • ‫display_name: (STRING) השם המוצג של מאגר הנתונים. הגודל המקסימלי הוא 1,024 בייטים. ברירת המחדל היא מחרוזת ריקה.

  • ‫description: (STRING) תיאור מאגר הנתונים. הגודל המקסימלי הוא 1,024 בייטים. ברירת המחדל היא מחרוזת ריקה.

  • ‫labels: (מערך STRING) מערך של צמדי מפתח/ערך. מידע נוסף זמין במאמר ארגון משאבים באמצעות תוויות. ברירת המחדל היא מערך ריק.

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

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

הגדרות אופציונליות לקובצי מסמכים

אפשר להגדיר את ההגדרות האופציונליות הבאות במאגרי נתונים של מסמכים:

  • ‫processing_config.unstructured_processing_config.segmentation_config: (OBJECT) הגדרת הטמעת הנתונים שקובעת איך לפלח את המסמך (החיפושים הם לפי פלח, לא לפי מסמך). מידע נוסף זמין במאמר בנושא חלוקת מסמכים למקטעים. אובייקט ריק גורם לדחיית הבקשה עם הסטטוס INVALID_ARGUMENT. אם מציינים את המאפיין הזה, הוא צריך לכלול אחד מהערכים הבאים:
    • ‫page_segmentation_config: (OBJECT) לאובייקט הזה אין מאפיינים.
    • ‫chunk_segmentation_config: (OBJECT) כולל את המאפיינים הבאים:
    • ‫chunk_size: (INTEGER) המספר המקסימלי של אסימונים בקטע. הערך המינימלי הוא 300 והערך המקסימלי הוא 500. ערך ברירת המחדל הוא 500.
    • ‫include_ancestor_headings: (BOOL) מוסיף שרשרת של כותרות קטעים לכל קטע טקסט כדי לספק הקשר. ערך ברירת המחדל הוא false.
  • ‫processing_config.unstructured_processing_config.parsing_config: (OBJECT) הגדרת ההטמעה של אופן ניתוח המסמך. מידע נוסף זמין במאמר ניתוח מסמכים. אובייקט ריק גורם לדחיית הבקשה עם הסטטוס INVALID_ARGUMENT. אם מציינים את המאפיין הזה, הוא צריך לכלול אחד מהערכים הבאים:
    • layout_parsing_config: (OBJECT) המערכת תשתמש בניתוח פריסה. לאובייקט הזה אין מאפיינים.
    • digital_parsing_config: (OBJECT) המערכת תשתמש בניתוח דיגיטלי. לאובייקט הזה אין מאפיינים.
  • processing_config.unstructured_processing_config.embedding_config.mode: (STRING) מצב ההטמעה שבו משתמשים. יכול להיות:

    • ‫TEXT: רק הטקסט שחולץ מוטמע. המערכת מתעלמת מתמונות. ערך ברירת המחדל הוא TEXT.

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

דוגמאות

בדוגמאות הבאות מוסבר איך ליצור מאגר נתונים של מסמכים.

curl

  curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores?data_store_id=acme-financials" \
  -d '{
    "display_name": "Acme financial reports",
    "document_type": "UNSTRUCTURED",
    "processing_config": {
      "unstructured_processing_config": {
        "segmentation_config": {
          "chunk_segmentation_config": {
            "chunk_size": 300,
            "include_ancestor_headings": true
          }
        },
        "parsing_config": {
          "layout_parsing_config": {}
        }
      }
    }
  }'

Python

  op = session.post(
    INGEST + "/dataStores",
    params={"data_store_id": "acme-financials"},
    json={
        "display_name": "Acme financial reports",
        "document_type": "UNSTRUCTURED",
        "processing_config": {
            "unstructured_processing_config": {
                "segmentation_config": {
                    "chunk_segmentation_config": {
                        "chunk_size": 300,
                        "include_ancestor_headings": True,
                    }
                },
                "parsing_config": {"layout_parsing_config": {}},
            }
        },
    },
).json()

wait(op)

תגובה לדוגמה

  "name": "projects/acme-prod/locations/us-east4/dataStores/acme-financials",
  "documentType": "UNSTRUCTURED",
  "state": "ACTIVE",
  "collectionName": "projects/acme-prod/locations/us-east4/collections/google-acme-financials"
}

הוספת מטא-נתונים לקבצים

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

כדי להגדיר מטא-נתונים:

  1. יוצרים קובץ JSONL. הסיומת צריכה להיות json או jsonl.

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

    • ‫name: שם הקובץ במאגר הנתונים. החלק האחרון של השם משמש כמזהה של אובייקט הנתונים שנוצר בשביל הקובץ.

    • ‫content.gcsUri: ה-URI של המסמך ב-Cloud Storage.

    • ‫metadata.value: המטא-נתונים של המסמך. מאפייני המטא-נתונים מוגדרים בסכימה שאתם מציינים כשאתם יוצרים את מאגר הנתונים. מידע נוסף זמין במאמר הוספת סכימת מטא-נתונים.

בדוגמה הבאה מוצג קובץ JSONL של מטא-נתונים עם מאפייני המטא-נתונים category,‏ year,‏ tags ו-issuer.

{"name":"projects/acme-prod/locations/us-east4/dataStores/acme-financials/documents/q3-earnings","content":{"gcsUri":"gs://acme-docs/reports/2025-q3-earnings.pdf"},"metadata":{"value":{"category":"earnings","year":2025,"tags":["revenue"],"issuer":{"country":"US"}}}}
{"name":"projects/acme-prod/locations/us-east4/dataStores/acme-financials/documents/covenants","content":{"gcsUri":"gs://acme-docs/reports/covenant-summary.docx"},"metadata":{"value":{"category":"covenant","year":2024,"tags":["credit","debt"]}}}

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

קובצי ה-JSONL שיצרתם ישמשו ככתובות URI של קלט כשתייבאו את הקבצים.

הוספת סכימת מטא-נתונים

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

מאפייני המטא-נתונים חייבים להתאים לסכימה שאתם מספקים כשאתם יוצרים את מאגר הנתונים. הסכימה דומה מאוד לטיוטה 7 של סכימת JSON. אלה סוגי הנתונים שנתמכים:

  • string
  • number
  • integer
  • boolean
  • ‫object (כולל נכסים)
  • array

שמות של נכסים יכולים לכלול רק אותיות, ספרות, קווים תחתונים (_) ומקפים (-), והם לא יכולים להתחיל ב-google (בכל אות רישית או קטנה). הקידומת שמורה לשדות שהשירות כותב.

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

בדוגמה הבאה מוגדרת סכימת מטא-נתונים עם מאפייני המטא-נתונים category,‏ year,‏ tags ו-issuer.

"document_metadata_schema": {
  "schema": {
    "type": "object",
    "properties": {
      "category": {"type": "string"},
      "year":     {"type": "integer"},
      "tags":     {"type": "array", "items": {"type": "string"}},
      "issuer":   {"type": "object", "properties": {"country": {"type": "string"}}}
    }
  }
}

עדכון של הגדרת עיבוד

אחרי שיוצרים את מאגר הנתונים, אפשר לעדכן את הגדרות העיבוד (processing_config) באמצעות בקשת PATCH.

אפשר לעדכן את המאפיינים הבאים:

  • display_name
  • description
  • labels
  • ‫document_metadata_schema (אפשר להוסיף רק נכסים נוספים)

המאפיינים שמתעדכנים צריכים להיכלל בפרמטר השאילתה update_mask.

בדוגמאות הבאות מוסבר איך לעדכן את המאפיינים display_name ו-document_metadata_schema של הגדרת עיבוד.

curl

curl -X PATCH -H "${AUTH}" -H "Content-Type: application/json" \
"${INGEST}/dataStores/acme-financials?update_mask=display_name,document_metadata_schema" \
-d '{"display_name": "Acme reports",
"document_metadata_schema": {"schema": {"type": "object", "properties": {
"category": {"type": "string"}, "year": {"type": "integer"},
"region": {"type": "string"}}}}}'

חלוקת מסמכים למקטעים

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

  • פילוח דפים (processing_config.segmentation_config.page_segmentation_config): ההטמעה המנוהלת מנסה לפלח מסמכים לפי דף.

  • פילוח לפי מקטעים (processing_config.segmentation_config.chunk_segmentation_config): ההטמעה המנוהלת מפצלת את המסמכים למקטעים נפרדים.

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

חלוקת הדף למקטעים

כשמציינים חלוקה לדפים (processing_config.segmentation_config.page_segmentation_config), צינור עיבוד הנתונים המנוהל מחלק את המסמכים לפי דף או טווח דפים. אם המסמך לא מכיל מידע על דפים, כמו קובץ טקסט, הוא מחולק לדפים בגודל של עד 2.5MB.

חלוקת הדף למקטעים מותאמת לאחזור מסמכים, כמו אפליקציות שמחזירות קובצי PDF או מסמכי Word עם כל תוצאת חיפוש. מידע נוסף מופיע במאמר חלוקת מסמכים לחלקים בשביל RAG.

חלוקה למקטעים

כשמציינים פילוח לחלקים (processing_config.segmentation_config.chunk_segmentation_config), צינור עיבוד הנתונים המנוהל להטמעת נתונים מקבל הוראה לפלח מסמכים לחלקים של עד processing_config.segmentation_config.chunk_segmentation_config.chunk_size אסימונים. כברירת מחדל, גודל המקטע הוא 500 טוקנים (גודל המקטע המקסימלי). גודל החלק המינימלי הוא 300.

חתיכות גדולות:

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

קטעים קצרים:

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

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

מזהי URI של קלט

המאפיין gcs_source.input_uris ב-JSON הוא מערך מחרוזות שמציין את הקלט לבקשת הטמעה מנוהלת, כמו הקבצים שצריך לייבא ממאגר הנתונים או מה שצריך למחוק מ-Agent Retrieval.

אם לא מציינים את gcs_source.source_format או מגדירים אותו כ-SOURCE_FORMAT_UNSPECIFIED (ברירת המחדל), כתובות ה-URI של הקלט יכולות להיות:

אם הערך של gcs_source.source_format מוגדר כ-SOURCE_FORMAT_DOCUMENT_JSON, מזהי ה-URI של הקלט מוגדרים בפורמט JSONL. פרטים נוספים זמינים במאמר הוספת מטא-נתונים למסמכים.

תווים כלליים לחיפוש

דוגמת קוד התאמות
gs://acme/files/hello_world.xyz הקובץ שצוין.
gs://acme/files/* כל קובץ שתואם ל-document_type שצוין ישירות ב-gs://acme/files/.
gs://acme/files/*.xyz כל קובץ עם הסיומת .xyz.

תווים כלליים לחיפוש הם לא רקורסיביים. לדוגמה, אם מציינים את gs://acme/files/*, קבצים ב-gs://acme/files/2025/ לא ייובאו. התו הכללי לחיפוש ** מפורש כמו *. כדי לעקוף את הבעיה, אפשר לשטח את ההיררכיה או להעביר תבנית אחת לכל רמה.

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

3. ייבוא הקבצים

השלב הבא בתהליך הוא להפעיל את importDocuments עם מזהי ה-URI של הקבצים במאגר הנתונים שרוצים להטמיע.

בדוגמאות הבאות מוסבר איך לייבא מסמכים.

curl

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores/acme-financials:importDocuments" \
  -d '{
    "gcs_source": {
      "input_uris": ["gs://acme-docs/reports/*"]
    },
    "import_output_config": {
      "error_gcs_prefix": "gs://acme-docs/import-errors/"
    }
  }'

Python

op = session.post(
    INGEST + "/dataStores/acme-financials:importDocuments",
    json={
        "gcs_source": {"input_uris": ["gs://acme-docs/reports/*"]},
        "import_output_config": {
            "error_gcs_prefix": "gs://acme-docs/import-errors/"
        },
    },
).json()

result = wait(op)
print(result["metadata"]["successCount"], "imported")
# failureCount is not set on import metadata; check error files instead.

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

בדוגמאות הבאות מוסבר איך לייבא את קובצי ה-JSONL של המטא-נתונים.

curl

gcloud storage cp docs.jsonl gs://acme-docs/manifests/docs.jsonl
curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores/acme-financials:importDocuments" \
  -d '{
    "gcs_source": {
      "input_uris": ["gs://acme-docs/manifests/docs.jsonl"],
      "source_format": "SOURCE_FORMAT_DOCUMENT_JSON"
    },
    "import_output_config": {
      "error_gcs_prefix": "gs://acme-docs/import-errors-json/"
    }
  }'

Python

op = session.post(
    INGEST + "/dataStores/acme-financials:importDocuments",
    json={
        "gcs_source": {
            "input_uris": ["gs://acme-docs/manifests/docs.jsonl"],
            "source_format": "SOURCE_FORMAT_DOCUMENT_JSON",
        },
        "import_output_config": {
            "error_gcs_prefix": "gs://acme-docs/import-errors-json/"
        },
    },
).json()

result = wait(op)

ההטמעה המנוהלת של האוסף יוצרת

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

במאמר חיפוש במסמכים מוסבר איך לשלוח שאילתות לאוסף.

בדוגמה הבאה אפשר לראות איך מקבלים את שם האוסף ממאגר הנתונים.

curl

curl -H "${AUTH}" "${INGEST}/dataStores/acme-financials"

Python

data_store = session.get(INGEST + "/dataStores/acme-financials").json()
collection_name = data_store["collectionName"]
print(collection_name)

מעקב אחרי התקדמות הייבוא

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

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

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

curl

curl -H "${AUTH}" "${BASE}/{OPERATION_NAME}"

Python

# To check once, without blocking, using the op returned by the import call:
status = session.get(BASE + "/" + op["name"]).json()
print(status.get("done"), status.get("metadata", {}))

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

curl

curl -H "${AUTH}" "${INGEST}/dataStores/acme-financials/documents"

Python

docs = session.get(INGEST + "/dataStores/acme-financials/documents").json()
print(len(docs.get("documents", [])))

הפעלה מחדש של פעולת ייבוא

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

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

דוגמאות

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

curl

COLLECTION=projects/${PROJECT}/locations/${LOCATION}/collections/google-acme-financials

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "https://vectorsearch.googleapis.com/v1/${COLLECTION}/dataObjects:search" \
  -d '{
    "semantic_search": {
      "search_text": "what is the total revenue?",
      "search_field": "multimodal_embedding",
      "task_type": "RETRIEVAL_QUERY",
      "top_k": 10,
      "output_fields": {
        "data_fields": ["google_document_id", "google_customer_uri", "google_unstructured_details.content_snippet"]
      }
    }
  }'

Python

from google.cloud import vectorsearch_v1

# Create the client
search_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request argument(s)
semantic_search = vectorsearch_v1.SemanticSearch(
    search_text="what is the total revenue?",
    search_field="multimodal_embedding",
    task_type=vectorsearch_v1.EmbeddingTaskType.RETRIEVAL_QUERY,
    top_k=10,
    output_fields=vectorsearch_v1.OutputFields(
        data_fields=["google_document_id", "google_customer_uri", "google_unstructured_details.content_snippet"],
    ),
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    semantic_search=semantic_search,
)

# Make the request
response = search_client.search_data_objects(request=request)

# Handle the response
for hit in response.results:
    data = dict(hit.data_object.data)
    print(hit.distance, data["google_customer_uri"][0])
    print(data["google_unstructured_details"]["content_snippet"][:200])

תוצאות חיפוש

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

מאפיין (property) סוג תיאור
google_document_id מחרוזת המסמך שממנו הגיע הקטע.
google_customer_uri מחרוזת ה-URI המקורי של gs:// לציטוט.
google_modality מחרוזת ‫UNSTRUCTURED או VIDEO.
google_unstructured_details.content_snippet מחרוזת הטקסט של הקטע.
google_unstructured_details.start_page / end_page מספר שלם טווח הדפים של החלק. מאוכלס רק בפילוח דפים, שדורש ניתוח דיגיטלי. ריק בפילוח קטעים.
google_video_details.start_offset_nanos / end_offset_nanos מספר שלם משך הזמן של קטע וידאו.
multimodal_embedding וקטור, צפוף, 768 מימדים הטמעת החלק מ-gemini-embedding-2.
metadata אובייקט מועתק מהמסמך לכל אחד מהקטעים שלו, ללא קידומת ומקונן כפי שהוצהר (כמו category או issuer.country).

המאפיינים start_page,‏ end_page,‏ start_offset_nanos ו-end_offset_nanos תמיד מוחזרים, בלי קשר לסוג המסמך שצוין.

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

המאפיינים ב-metadata תואמים לסכימת ה-JSON שסופקה במהלך הייבוא.

מחיקת קבצים

כדי למחוק קובץ ממאגר נתונים, מעלים קובץ טקסט אחד או יותר ל-Cloud Storage, כשכל שורה מכילה את המזהה של הקובץ שרוצים למחוק. מעבירים את מזהי ה-URI של קובצי הטקסט אל purgeDocuments.

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

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

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

בדוגמאות הבאות מוסבר איך למחוק קבצים.

curl

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
"${INGEST}/dataStores/acme:purgeDocuments" \
-d '{
  "gcs_source": {
    "input_uris": ["gs://acme/purge/purge-ids.txt"]
  },
  "purge_output_config": {
    "error_gcs_prefix": "gs://acme/purge-force-errors/"
  },
  "force": true
}'

Python

op = session.post(
  INGEST + "/dataStores/acme:purgeDocuments",
  json={
      "gcs_source": {
            "input_uris": ["gs://acme/purge/purge-ids.txt"],
        },
        "purge_output_config": {
            "error_gcs_prefix": "gs://acme/purge-force-errors/",
        },
        "force": True,
    },
).json()

result = wait(op)

מחיקת מאגר נתונים

שולחים בקשת DELETE עם ה-URI של מאגר הנתונים כדי למחוק את מאגר הנתונים. אם הערך של force מוגדר כ-true ומאגר הנתונים עדיין מכיל קבצים, הבקשה תיכשל עם הסטטוס FAILED_PRECONDITION וההודעה DataStore deletion is not allowed because it still contains documents. Set force=true to delete the DataStore and all its Documents..

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

בזמן שבקשת המחיקה פועלת, בקשת get מחזירה את הסטטוס DELETING, ואחרי שהיא מסתיימת היא מחזירה את השגיאה 404.

בדוגמה הבאה מוסבר איך למחוק מאגר נתונים.

curl

curl -X DELETE -H "${AUTH}" \
  "${INGEST}/dataStores/acme-financials?force=true&backing_collection_deleted=true"

Python

op = session.delete(
  INGEST + "/dataStores/acme-financials",
  params={"force": "true", "backing_collection_deleted": "true"},
).json()

result = wait(op)