최적화된 온라인 서빙을 위해 만든 온라인 스토어 인스턴스의 경우 벡터 유사성 검색을 수행하여 의미상으로 유사하거나 관련있는 항목 목록(근사 최근접 이웃이라고도 함)을 검색할 수 있습니다. 엔티티 ID 또는 임베딩을 기반으로 검색할 수 있습니다.
온라인 스토어 인스턴스에 구성된 엔드포인트 유형에 따라 다음 중 하나를 수행할 수 있습니다.
공개 엔드포인트를 사용하여 최근접 이웃 일치 검색: 온라인 스토어가 공개 엔드포인트에서 최적화된 온라인 서빙을 위해 구성된 경우에만 이 옵션을 선택합니다.
Private Service Connect 엔드포인트를 사용하여 최근접 이웃 일치 검색: 온라인 스토어가 Private Service Connect를 통해 전용 서빙 엔드포인트에서 최적화된 온라인 서빙을 위해 구성된 경우에만 이 옵션을 선택합니다.
시작하기 전에
근사 최근접 이웃을 검색하려면 먼저 다음을 수행해야 합니다.
embedding
열을 포함하여 임베딩을 지원하도록 BigQuery 데이터 소스를 설정합니다. 선택적으로 필터링 및 크라우딩 열을 포함합니다. 자세한 내용은 데이터 소스 준비 가이드라인을 참조하세요.BigQuery 데이터 소스를 직접 연결하여 임베딩을 지원하는 특성 뷰를 만듭니다. 특성 뷰를 만드는 동안
embedding
열을 지정합니다. 임베딩을 지원하는 특성 뷰를 만드는 방법은 특성 뷰의 벡터 검색 구성을 참조하세요.Private Service Connect 엔드포인트를 사용하여 최근접 이웃 일치를 검색하려면 Python SDK를 설치하거나 최신 버전으로 업그레이드하세요. 다음 명령어를 실행합니다.
pip3 install --upgrade --quiet google-cloud-aiplatform
아직 Vertex AI에 인증하지 않았다면 다음 안내에 따라 인증하세요.
Select the tab for how you plan to use the samples on this page:
Python
로컬 개발 환경에서 이 페이지의 Python 샘플을 사용하려면 gcloud CLI를 설치하고 초기화한 후 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정합니다.
Google Cloud CLI를 설치합니다.
외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
자세한 내용은 다음을 참조하세요: Set up authentication for a local development environment.
REST
로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.
Google Cloud CLI를 설치합니다.
외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
자세한 내용은 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
다음 명령어를 실행합니다.
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
다음 명령어를 실행합니다.
$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 } ] } }
Private Service Connect 엔드포인트를 사용하여 최근접 이웃 일치 검색
Private Service Connect 엔드포인트에서 최적화된 온라인 서빙을 사용하여 특성 값을 서빙하도록 온라인 스토어 인스턴스를 구성한 경우 다음을 수행하여 근사 최근접 이웃 일치를 검색해야 합니다.
온라인 스토어의 서비스 연결 문자열 검색
Private Service Connect 엔드포인트로 최적화된 온라인 서빙을 위한 온라인 스토어 인스턴스를 만들면 Vertex AI Feature Store에서 서비스 연결 문자열을 생성합니다. 온라인 스토어 세부정보에서 서비스 연결 문자열을 검색하고 이 문자열을 사용하여 Private Service Connect 엔드포인트를 설정할 수 있습니다.
다음 샘플을 사용하여 온라인 스토어 인스턴스의 세부정보를 검색합니다.
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
다음 명령어를 실행합니다.
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
다음 명령어를 실행합니다.
$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": { "privateServiceConnectConfig": { "enablePrivateServiceConnect": "true", "projectAllowlist": [ "PROJECT_NAME" ] }, serviceAttachment: "SERVICE_ATTACHMENT_STRING" }, "optimized": {} }
다음 단계에서 특성 값을 가져오려면 응답의 SERVICE_ATTACHMENT_STRING이 필요합니다.
Private Service Connect의 엔드포인트 추가
최적화된 온라인 서빙을 위한 Private Service Connect 엔드포인트를 네트워크 구성에 추가하려면 다음 단계를 수행합니다.
Google Cloud 콘솔에서 온라인 스토어 인스턴스가 포함된 프로젝트를 선택합니다.
SERVICE_ATTACHMENT_STRING을 대상 서비스로 지정하여 Private Service Connect의 엔드포인트를 만듭니다.
엔드포인트를 만들면 Private Service Connect 페이지의 연결된 엔드포인트 탭에 표시됩니다. 엔드포인트의 IP 주소가 IP 주소 열에 표시됩니다.
다음 단계에서 gRPC를 통해 온라인 서비스 인스턴스의 엔드포인트를 Private Service Connect 엔드포인트에 연결하려면 이 IP 주소를 사용해야 합니다.
gRPC를 통해 Private Service Connect 엔드포인트에 연결
다음 코드 샘플을 사용하여 gRPC를 통해 온라인 스토어용으로 생성된 Private Service Connect 엔드포인트에 연결합니다.
Python
from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient from google.cloud.aiplatform_v1.services.feature_online_store_service.transports.grpc import FeatureOnlineStoreServiceGrpcTransport import grpc data_client = FeatureOnlineStoreServiceClient( transport = FeatureOnlineStoreServiceGrpcTransport( # Add the IP address of the Endpoint you just created. channel = grpc.insecure_channel("ENDPOINT_IP:10002") ) )
다음을 바꿉니다.
- ENDPOINT_IP: Private Service Connect 페이지의 IP 주소 열에 있는 엔드포인트의 IP 주소입니다.
Private Service Connect 엔드포인트를 사용하여 근사 최근접 이웃 검색
gRPC를 통해 Private Service Connect 엔드포인트에 연결한 후 임베딩 또는 항목의 근사 최근접 이웃을 검색할 수 있습니다.
임베딩의 근사 최근접 이웃 검색
다음 샘플을 사용하여 비공개 엔드포인트를 사용하는 동안 임베딩을 지정하여 의미상 연관된 항목을 검색합니다.
Python
data_client.search_nearest_entities( request=feature_online_store_service_pb2.SearchNearestEntitiesRequest( feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME", query=feature_online_store_service_pb2.NearestNeighborQuery( embedding = "EMBEDDING", neighbor_count = NEIGHBOR_COUNT, ), return_full_entity=RETURN_FULL_ENTITY ))
다음을 바꿉니다.
LOCATION_ID: 온라인 저장소가 있는 리전입니다(예:
us-central1
).PROJECT_ID: 프로젝트 ID입니다.
FEATUREONLINESTORE_NAME: 특성 뷰가 포함된 온라인 스토어의 이름입니다.
FEATUREVIEW_NAME: 근사 최근접 이웃 일치를 검색하려는 특성 뷰의 이름입니다.
EMBEDDING: 근사 최근접 이웃 일치를 검색하려는 임베딩입니다. 임베딩은
double
값의 배열로 표시됩니다.FORMAT: (선택사항) 특성 값을 가져오려는 형식입니다. 지원되는 형식에는 JSON 키-값 쌍 및 proto
Struct
형식이 포함됩니다. protoStruct
형식은 바이트 특성 값 유형을 지원하지 않습니다. 바이트 형식의 특성 값을 가져오려면 JSON을 응답 형식으로 사용하세요.RETURN_FULL_ENTITY: 선택사항: 응답에 항목의 특성을 포함하거나 제외할지 여부를 지정합니다. 응답에 항목과 함께 특성을 포함하려면
true
를 입력합니다. 기본값은false
입니다.NEIGHBOR_COUNT: 검색하려는 근사 최근접 이웃 수입니다.
항목의 근사 최근접 이웃 검색
비공개 엔드포인트를 사용하는 동안 엔티티 ID를 지정하여 의미상 연관된 항목을 검색하려면 다음 샘플을 사용하세요.
Python
data_client.search_nearest_entities( request=feature_online_store_service_pb2.SearchNearestEntitiesRequest( feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME", query=feature_online_store_service_pb2.NearestNeighborQuery( entity_id = "ENTITY_ID", neighbor_count = NEIGHBOR_COUNT, ), return_full_entity=RETURN_FULL_ENTITY )) ```
다음을 바꿉니다.
LOCATION_ID: 온라인 저장소가 있는 리전입니다(예:
us-central1
).PROJECT_ID: 프로젝트 ID입니다.
FEATUREONLINESTORE_NAME: 특성 뷰가 포함된 온라인 스토어의 이름입니다.
FEATUREVIEW_NAME: 근사 최근접 이웃 일치를 검색하려는 특성 뷰의 이름입니다.
ENTITY_ID: 근사 최근접 이웃 일치를 검색하려는 항목의 엔티티 ID입니다.
FORMAT: (선택사항) 특성 값을 가져오려는 형식입니다. 지원되는 형식에는 JSON 키-값 쌍 및 proto
Struct
형식이 포함됩니다. protoStruct
형식은 바이트 특성 값 유형을 지원하지 않습니다. 바이트 형식의 특성 값을 가져오려면 JSON을 응답 형식으로 사용하세요.RETURN_FULL_ENTITY: 선택사항: 응답에 항목의 특성을 포함하거나 제외할지 여부를 지정합니다. 응답에 항목과 함께 특성을 포함하려면
true
를 입력합니다. 기본값은false
입니다.NEIGHBOR_COUNT: 검색하려는 근사 최근접 이웃 수입니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-10-19(UTC)
- LOCATION_ID: 온라인 저장소가 있는 리전입니다(예: