임베딩을 사용하여 검색

최적화된 온라인 서빙을 위해 만든 온라인 스토어 인스턴스의 경우 벡터 유사성 검색을 수행하여 의미상으로 유사하거나 관련있는 항목 목록(근사 최근접 이웃이라고도 함)을 검색할 수 있습니다. 엔티티 ID 또는 임베딩을 기반으로 검색할 수 있습니다.

근사 최근접 이웃을 검색하려면 먼저 다음을 수행해야 합니다.

embedding 열을 포함하여 임베딩을 지원하도록 BigQuery 데이터 소스를 설정합니다. 선택적으로 필터링 및 크라우딩 열을 포함합니다. 자세한 내용은 데이터 소스 준비 가이드라인을 참조하세요.
최적화된 온라인 서빙을 위한 온라인 스토어 인스턴스 만들기
특성 뷰를 만드는 동안 embedding 열을 지정합니다. 임베딩을 지원하는 특성 뷰를 만드는 방법은 특성 뷰의 벡터 검색 구성을 참조하세요.

이 페이지에서는 다음을 수행하는 방법을 설명합니다.

온라인 스토어의 공개 엔드포인트 도메인 이름 검색
임베딩의 최근접 이웃 일치 검색
항목의 최근접 이웃 일치 검색

시작하기 전에

아직 인증하지 않은 경우 Vertex AI에 인증합니다.

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공하는 사용자 인증 정보를 사용합니다.

Install the Google Cloud CLI, then initialize it by running the following command:

gcloud init

자세한 내용은 Google Cloud 인증 문서의 REST 사용 인증을 참조하세요.

온라인 스토어의 공개 엔드포인트 도메인 이름 검색

최적화된 온라인 서빙을 위한 온라인 스토어 인스턴스를 만들면 Vertex AI Feature Store에서 온라인 스토어의 공개 엔드포인트 도메인 이름을 생성합니다. 온라인 저장소의 특성 뷰에서 최근접 이웃 검색하려면 먼저 온라인 저장소 세부정보에서 공개 엔드포인트 도메인 이름을 검색해야 합니다.

다음 샘플을 사용하여 온라인 스토어 인스턴스의 세부정보를 검색합니다.

REST

프로젝트의 FeatureOnlineStore 리소스 세부정보를 검색하려면 featureOnlineStores.get 메서드를 사용하여 GET 요청을 전송합니다.

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

LOCATION_ID: 온라인 저장소가 있는 리전입니다(예: us-central1).
PROJECT_ID: 프로젝트 ID입니다.
FEATUREONLINESTORE_NAME: 온라인 스토어 인스턴스의 이름입니다.

HTTP 메서드 및 URL:

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "publicEndpointDomainName": "PUBLIC_ENDPOINT_DOMAIN_NAME"
  },
  "optimized": {}
}

다음 단계에서 최근접 이웃을 검색하려면 응답에서 PUBLIC_ENDPOINT_DOMAIN_NAME이 필요합니다.

임베딩의 근사 최근접 이웃 검색

다음 샘플을 통해 임베딩을 사용하고 임베딩을 지정하여 의미상으로 관련된 엔티티 검색을 수행합니다.

REST

임베딩의 최근접 이웃을 검색하려면 featureViews.searchNearestEntities 메서드를 사용해서 POST 요청을 전송합니다.

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

PUBLIC_ENDPOINT_DOMAIN_NAME: featureOnlineStores.get 메서드를 사용하여 검색한 온라인 스토어 인스턴스의 공개 엔드포인트 도메인 이름입니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION_ID: 온라인 저장소 인스턴스가 있는 리전입니다(예: us-central1).
FEATUREONLINESTORE_NAME: 근사 최근접 이웃 일치를 검색하려는 특성 뷰가 포함된 온라인 저장소 인스턴스의 이름입니다.
FEATUREVIEW_NAME: 근사 최근접 이웃 일치를 검색하려는 특성 뷰의 이름입니다.
EMBEDDING: 근사 최근접 이웃 일치를 검색하려는 임베딩입니다. 임베딩은 double 값의 배열로 표시됩니다.
RETURN_FULL_ENTITY: 선택사항: 응답에 엔티티의 특성을 포함하거나 제외할지 여부를 지정합니다. 응답에 엔티티와 함께 특성을 포함하려면 true를 입력합니다. 기본값은 false입니다.
NEIGHBOR_COUNT: 검색하려는 근사 최근접 이웃 수입니다.

HTTP 메서드 및 URL:

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

JSON 요청 본문:

{
  "query": {
    "embedding": {
      "value": EMBEDDING
    },
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

요청 본문을 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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

엔티티의 근사 최근접 이웃 검색

다음 샘플을 통해 임베딩을 사용하고 엔티티 ID를 지정하여 의미상으로 관련된 엔티티 검색을 수행합니다.

REST

엔티티 ID의 최근접 이웃을 검색하려면 featureViews.searchNearestEntities 메서드를 사용해서 POST 요청을 전송합니다.

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

PUBLIC_ENDPOINT_DOMAIN_NAME: featureOnlineStores.get 메서드를 사용하여 검색한 온라인 스토어 인스턴스의 공개 엔드포인트 도메인 이름입니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION_ID: 온라인 저장소 인스턴스가 있는 리전입니다(예: us-central1).
FEATUREONLINESTORE_NAME: 근사 최근접 이웃 일치를 검색하려는 특성 뷰가 포함된 온라인 저장소 인스턴스의 이름입니다.
FEATUREVIEW_NAME: 근사 최근접 이웃 일치를 검색하려는 특성 뷰의 이름입니다.
ENTITY_ID: 근사 최근접 이웃 일치를 검색하려는 엔티티의 엔티티 ID입니다.
RETURN_FULL_ENTITY: 선택사항: 응답에 엔티티의 특성을 포함하거나 제외할지 여부를 지정합니다. 응답에 엔티티와 함께 특성을 포함하려면 true를 입력합니다. 기본값은 false입니다.
NEIGHBOR_COUNT: 검색하려는 근사 최근접 이웃 수입니다.

HTTP 메서드 및 URL:

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

JSON 요청 본문:

{
  "query": {
    "entity_id": ENTITY_ID,
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

요청 본문을 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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}