Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

데이터 객체 검색

Search API의 목적은 지정된 쿼리와 유사한 데이터 객체를 찾고 순위가 지정된 결과 목록 (유사성별 순위)을 반환하는 것입니다. Search API는 필터링도 지원합니다.

Search API는 데이터 객체를 검색하는 다양한 방법(벡터 검색, 전체 텍스트 검색, 시맨틱 검색)을 제공합니다. 또한 모든 유형의 검색을 여러 개 결합하여 하이브리드 검색을 구현할 수 있습니다.

벡터 검색

벡터 검색을 사용하면 자체 쿼리 벡터를 제공할 수 있습니다. embedding-config가 없는 임베딩 필드를 검색하는 데 필요한 메서드입니다. 여러 vector_search 필드가 제공되면 동일한 가중치를 사용하여 결과가 결합됩니다.

다음 예시에서는 ID가 COLLECTION_ID인 컬렉션에서 벡터 검색을 실행하는 방법을 보여줍니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

COLLECTION_ID: 컬렉션의 ID입니다.
LOCATION: Agent Platform을 사용하는 리전입니다.
PROJECT_ID: Google Cloud 프로젝트 ID

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)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. 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)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. 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: 컬렉션의 ID입니다.
LOCATION: Agent Platform을 사용하는 리전입니다.
PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

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)

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)

참고: 이 명령어가 따옴표로 묶인 콘텐츠에 '를 사용하는 경우 작은따옴표를 큰따옴표로 바꿉니다. 따옴표가 중첩된 경우 \"를 사용하여 안에 있는 따옴표를 이스케이프합니다.

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를 사용하여 여러 검색(벡터 검색, 텍스트 검색, 시맨틱 검색)을 동시에 실행합니다. 결과는 상호 순위 융합 (RFF) 알고리즘을 사용하여 결과 집합을 병합하는 ReciprocalRankFusion 순위 지정 도구를 사용하여 선택적으로 결합하고 순위를 지정할 수 있습니다.

데이터 객체 검색 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

벡터 검색

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

Python

텍스트 검색

시맨틱 검색

하이브리드 검색을 사용하여 검색

데이터 객체 검색