צינור עיבוד הנתונים המנוהל מייבא מסמכים ממאגרי נתונים אל Agent Retrieval, אל אובייקטים של נתונים ואל אוספים שאפשר לחפש באמצעות שאילתות טקסט, ומטפל באופן אוטומטי בניתוח, בפילוח, בהטמעה ובאינדקס.
פורמטים נתמכים של מסמכים
בטבלה הבאה מפורטים פורמטי קובץ המסמכים וסיומות הקבצים שנתמכים.
| סוג המסמך | סיומת הקובץ |
|---|---|
.pdf |
|
| טקסט פשוט | .txt |
| Microsoft Word | .docx |
| Microsoft Excel | .xlsx |
| Microsoft Excel עם פקודות מאקרו | .xlsm (המערכת מתעלמת מסקריפטים ומפקודות מאקרו) |
| Microsoft PowerPoint | .pptx |
דרישות מוקדמות
לפני שמתחילים, צריך:
פרויקט Google Cloud . במאמר הגדרה של פרויקט וסביבת פיתוח מוסבר איך יוצרים פרויקט ב- Google Cloud .
ההרשאה
roles/vectorsearch.serviceAgentשניתנה לסוכן השירותservice-PROJECT_NUMBER@gcp-sa-vectorsearch.iam.gserviceaccount.comבפרויקט של הקטגוריה.
דוגמאות
הדוגמאות בדף הזה מבוססות על קובצי הדוגמה הבאים.
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. הכנת הקבצים
יוצרים קטגוריה ומוסיפים את הקבצים שרוצים לחפש. לא צריך ליצור מניפסט.
הטמעה מנוהלת של מסמכים:
מדלג על מסמכים שגדולים מ-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"
}
הוספת מטא-נתונים לקבצים
אתם יכולים להגדיר מאפייני מטא-נתונים לקבצים שאתם רוצים לייבא באמצעות הטמעה מנוהלת. אפשר לאחזר את המאפיינים האלה מאובייקטי הנתונים התואמים שנוצרו על ידי צינור עיבוד הנתונים, והם שימושיים לסינון של תוצאות החיפוש.
כדי להגדיר מטא-נתונים:
יוצרים קובץ JSONL. הסיומת צריכה להיות
jsonאוjsonl.מוסיפים אובייקט 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. אלה סוגי הנתונים שנתמכים:
stringnumberintegerboolean-
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_namedescriptionlabels-
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 של הקלט יכולות להיות:
- מזהה 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)