חיפוש אובייקטים של נתונים

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

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

חיפוש וקטורי

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

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

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫COLLECTION_ID: המזהה של האוסף.
• ‫LOCATION: האזור שבו משתמשים ב-Agent Platform.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

ה-method של ה-HTTP וכתובת ה-URL:

POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search

תוכן בקשת JSON:

{
  "vector_search": {
    "search_field": "plot_embedding",
    "vector": {
      "values": [
        0.42426406871192845,
        0.565685424949238,
        0.7071067811865475
      ]
    },
    "filter": {
      "genre": {
        "$eq": "Thriller"
      }
    },
    "top_k": 5,
    "output_fields": {
      "data_fields": "*",
      "vector_fields": "*",
      "metadata_fields": "*"
    }
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "results": [
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
        "createTime": "2026-01-31T20:05:06Z",
        "updateTime": "2026-02-02T13:59:24Z",
        "data": {
          "year": 1991,
          "title": "The Silence of the Lambs",
          "director": "Jonathan Demme",
          "genre": "Thriller"
        },
        "vectors": {
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.697
    },
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
        "createTime": "2026-02-04T14:35:29Z",
        "updateTime": "2026-02-04T14:37:29Z",
        "data": {
          "year": 1995,
          "title": "Se7en",
          "director": "David Fincher",
          "genre": "Thriller"
        },
        "vectors": {
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.75
    }
  ]
}

gcloud

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

• ‫SEARCH_VECTOR_FILE: הנתיב המקומי לקובץ JSON שמכיל את הווקטור הדחוס או הדליל לחיפוש.

  דוגמה לתוכן של קובץ וקטור צפוף:

  {
    "dense": {
      "values": [
        0.42426406871192845,
        0.565685424949238,
        0.7071067811865475
      ]
    }
  }

  דוגמה לתוכן של קובץ וקטור דליל:

  {
    "sparse": {
      "indices": [1, 5, 10],
      "values": [0.1, 0.5, 0.21]
    }
  }

• ‫COLLECTION_ID: המזהה של האוסף.
• ‫LOCATION: האזור שבו משתמשים ב-Agent Platform.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט באמצעות אחת מהפקודות הבאות: gcloud init; או gcloud auth login ו- gcloud config set project.

gcloud beta vector-search collections data-objects search \
  --vector-search-field="plot_embedding" \
  --vector-from-file=SEARCH_VECTOR_FILE \
  --json-filter='{"genre": {"$eq": "Thriller"}}' \
  --top-k=5 \
  --output-data-fields='*' \
  --output-vector-fields='*' \
  --output-metadata-fields='*' \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

‏Windows (PowerShell)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט באמצעות אחת מהפקודות הבאות: gcloud init; או gcloud auth login ו- gcloud config set project.

gcloud beta vector-search collections data-objects search `
  --vector-search-field="plot_embedding" `
  --vector-from-file=SEARCH_VECTOR_FILE `
  --json-filter='{"genre": {"$eq": "Thriller"}}' `
  --top-k=5 `
  --output-data-fields='*' `
  --output-vector-fields='*' `
  --output-metadata-fields='*' `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows‏ (cmd.exe)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט באמצעות אחת מהפקודות הבאות: gcloud init; או gcloud auth login ו- gcloud config set project.

הערה: אם משתמשים בפקודה ב-' לציטוט תוכן, צריך להחליף את הגרשיים במירכאות. אם הציטוט הוא חלק מרכיב בתוך רכיב, צריך להשתמש ב-\" כדי לסמן בתו בריחה (escape) את הציטוט הפנימי.

gcloud beta vector-search collections data-objects search ^
  --vector-search-field="plot_embedding" ^
  --vector-from-file=SEARCH_VECTOR_FILE ^
  --json-filter='{"genre": {"$eq": "Thriller"}}' ^
  --top-k=5 ^
  --output-data-fields='*' ^
  --output-vector-fields='*' ^
  --output-metadata-fields='*' ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

אמורים לקבל תגובה שדומה לזו:

---
dataObject:
  createTime: '2026-01-31T20:05:06Z'
  data:
    director: Jonathan Demme
    genre: Thriller
    title: The Silence of the Lambs
    year: 1991
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
  updateTime: '2026-02-02T13:59:24Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.697
---
dataObject:
  createTime: '2026-02-04T14:35:29Z'
  data:
    director: David Fincher
    genre: Thriller
    title: Se7en
    year: 1995
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
  updateTime: '2026-02-04T14:37:29Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.75

Python

from google.cloud import vectorsearch_v1beta

# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()

# Initialize request
vector_search = vectorsearch_v1beta.VectorSearch(
    search_field="plot_embedding",
    vector={"values": [0.1, 0.2, 0.3]},
    filter={"genre": {"$eq": "Thriller"}},
    top_k=5,
)
request = vectorsearch_v1beta.SearchDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    vector_search=vector_search,
)

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

# Handle the response
print(response)

חיפוש טקסט

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

• ‫OR: אופרטור הפרדה תלוי אותיות רישיות שתואם למסמכים שמכילים לפחות אחד מהמונחים שצוינו. ההגדרה הזו רלוונטית רק לשני המונחים הסמוכים.

• ‫": (מירכאות כפולות) לחיפוש של צירוף מילים.

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

חיפוש סמנטי

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

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

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

משתמשים ב-batch_search_data_objects כדי להריץ כמה חיפושים במקביל (חיפוש וקטורי, חיפוש טקסט וחיפוש סמנטי). אפשר לשלב את התוצאות ולדרג אותן באמצעות ReciprocalRankFusion Ranker, שמשלב קבוצות של תוצאות באמצעות האלגוריתם Reciprocal Rank Fusion (RFF).