임베딩을 사용하여 검색

임베딩을 지원하도록 온라인 저장소를 구성한 경우 벡터 유사성 검색을 수행해서 근사 최근접 이웃이라고도 부르는 의미상으로 유사하거나 관련이 있는 엔티티 목록을 검색할 수 있습니다. 엔티티 ID 또는 임베딩을 기반으로 검색할 수 있습니다.

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

  • embedding 열을 포함하여 임베딩을 지원하도록 BigQuery 데이터 소스를 설정합니다. 선택적으로 필터링 및 크라우딩 열을 포함합니다. 자세한 내용은 데이터 소스 준비 가이드라인을 참조하세요.

  • 임베딩 관리를 지원하는 온라인 스토어 인스턴스를 만듭니다. 임베딩 관리를 지원하는 온라인 스토어 인스턴스를 만드는 방법은 온라인 스토어의 임베딩 관리 구성을 참조하세요.

  • 특성 뷰를 만드는 동안 embedding 열을 지정합니다. 임베딩을 지원하는 특성 뷰를 만드는 방법은 특성 뷰의 벡터 검색 구성을 참조하세요.

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

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

임베딩을 관리할 수 있도록 온라인 저장소 인스턴스를 만들고 구성할 때 Vertex AI Feature Store에서 온라인 저장소용 공개 엔드포인트 도메인 이름을 생성합니다. 온라인 저장소의 특성 뷰에서 최근접 이웃 검색하려면 먼저 온라인 저장소 세부정보에서 공개 엔드포인트 도메인 이름을 검색해야 합니다.

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

REST

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

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

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

HTTP 메서드 및 URL: 

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

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

curl

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

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

PowerShell

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "http://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 값의 배열로 표시됩니다.
  • BOOLEAN: 선택사항: 응답에 엔티티의 특성을 포함하거나 제외할지 여부를 지정합니다. 응답에 엔티티와 함께 특성을 포함하려면 true를 입력합니다. 기본값은 false입니다.
  • NEIGHBOR_COUNT: 검색하려는 근사 최근접 이웃 수입니다.

HTTP 메서드 및 URL: 

POST http://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": BOOLEAN
}

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

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 \
     "http://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 "http://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입니다.
  • BOOLEAN: 선택사항: 응답에 엔티티의 특성을 포함하거나 제외할지 여부를 지정합니다. 응답에 엔티티와 함께 특성을 포함하려면 true를 입력합니다. 기본값은 false입니다.
  • NEIGHBOR_COUNT: 검색하려는 근사 최근접 이웃 수입니다.

HTTP 메서드 및 URL: 

POST http://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": BOOLEAN
}

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

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 \
     "http://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 "http://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
    } ]
  }
}