RAG와 함께 벡터 검색 2.0 사용

이 페이지에서는 Gemini Enterprise Agent Platform의 RAG Engine이 Gemini Enterprise Agent Platform 벡터 검색 2.0을 사용하는 방법을 보여줍니다. 이 제품은 문서의 벡터 표현을 저장하고 관리하는 포괄적인 스토리지 및 검색 시스템 역할을 하는 Cloud de Confiance by S3NS 제품입니다. 그런 다음 Gemini Enterprise Agent Platform 벡터 검색 2.0을 사용하여 주어진 쿼리와 의미적으로 유사한 문서를 기반으로 관련 문서를 검색합니다.

RAG는 벡터 검색 2.0 컬렉션을 관리하며, 프로젝트의 벡터 검색 2.0 컬렉션에 대한 전체 액세스 권한을 갖게 됩니다.

RAG 백엔드 선택

Gemini Enterprise Agent Platform에서 RAG Engine을 사용할 때는 RAG 코퍼스에 대해 다양한 백엔드 스토리지 옵션 중에서 선택할 수 있습니다. 다음 표에는 주요 차이점이 요약되어 있습니다.

Vector Search 2.0 데이터에 대한 최신 기능, 자동화된 관리, 투명성을 위해 RagManagedVertexVectorSearch를 선택하세요. CMEK 지원이 엄격한 요구사항인 경우 백엔드 데이터베이스에 대한 직접적인 가시성이 부족하다는 점을 염두에 두고 RagManagedDb를 고려하세요.

Vector Search API 사용 설정

RAG 관리형 Gemini Enterprise Agent Platform 벡터 검색을 사용하려면 먼저 Vector Search API를 사용 설정해야 합니다.

RagManagedVertexVectorSearch로 RAG 코퍼스 만들기

이 코드 샘플은 RagManagedVertexVectorSearch를 사용하여 RAG 코퍼스를 만드는 방법을 보여줍니다.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

vector_db = rag.RagManagedVertexVectorSearch()
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "rag_managed_vertex_vector_search": {}
      }
    }'

RagManagedVertexVectorSearch로 데이터 가져오기

ImportRagFiles API 또는 UploadRagFile API를 사용하여 데이터를 RagManagedVertexVectorSearch로 가져올 수 있습니다.

로컬 파일을 RAG 코퍼스에 업로드하려면 RAG 파일 업로드를 참조하세요. RAG 코퍼스로 데이터를 가져오려면 Cloud Storage에서 가져오는 방법을 보여주는 다음 코드 샘플을 참조하세요. 지원되는 데이터 소스에 대해 알아보려면 RAG에 지원되는 데이터 소스를 참조하세요.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
)

# Wait for the import to complete.
await response.result()

GCS_URI=GCS_URI

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
  }
}'

코퍼스의 색인 만들기

RAG Engine은 각 코퍼스에 대해 벡터 검색 2.0 컬렉션을 만들지만 해당 컬렉션에 색인을 만들지는 않습니다. 색인을 만들기 전까지는 모든 검색이 무차별 대입 KNN 스캔입니다.

무작위 스캔은 색인 생성 검색보다 느리며 KNN은 최대 100,000개의 데이터 객체 컬렉션에서만 실행됩니다. RAG Engine은 데이터 객체당 하나의 청크를 저장하므로 코퍼스가 이 한도를 초과하면 색인이 존재할 때까지 검색이 실패합니다.

모든 코퍼스를 색인 생성하지 마세요. 색인은 자체 서빙 인프라에서 실행되며 쿼리 여부와 관계없이 존재하는 동안 요금이 청구됩니다. 어떤 corpora에 필요한지 결정하려면 색인을 생성할 corpora 결정을 참조하세요.

색인이 있으면 검색에서 자동으로 사용합니다. 코퍼스는 변경되지 않으며 데이터를 다시 가져올 필요가 없습니다.

여러 코퍼스의 색인을 생성하는 경우 루프를 스크립트로 작성합니다. 일괄 생성 경로는 없습니다. 동시 색인 작업은 할당량이 제한되므로 색인을 순차적으로 또는 소규모 배치로 만듭니다. 자세한 내용은 할당량을 참조하세요.

시작하기 전에

색인을 만들려면 컬렉션에 대한 vectorsearch.indexes.create 권한이 필요하고 데이터 객체를 계산하려면 vectorsearch.dataObjects.query이 필요합니다. 두 권한 모두 벡터 검색 관리자(roles/vectorsearch.admin) 역할에 포함되어 있습니다. 벡터 검색 색인 작성자(roles/vectorsearch.indexWriter)는 첫 번째 권한을 부여합니다. 프로젝트에서 벡터 검색 API도 사용 설정해야 합니다.

코퍼스 ID 찾기

프로젝트에서 각 코퍼스에는 vertex-rag-RAG_CORPUS_ID라는 컬렉션이 정확히 하나 있습니다. 코퍼스를 나열하여 ID를 가져옵니다.

PROJECT_ID를 프로젝트 ID로 바꿉니다.

PROJECT_ID=PROJECT_ID
LOCATION=us-central1

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora?pageSize=100"

각 코퍼스 name 끝에 있는 숫자 부분은 RAG_CORPUS_ID입니다. 각 코퍼스는 vectorDbConfig.ragManagedVertexVectorSearch.collectionName에서 전체 컬렉션 리소스 이름도 보고합니다.

응답에는 최대 100개의 코퍼스가 나열되며, pageSize를 생략하면 최대 25개가 나열됩니다. 응답에 nextPageToken가 포함된 경우 해당 값을 pageToken로 전달하여 다음 페이지를 가져옵니다.

색인을 생성하려는 RAG_CORPUS_ID를 이미 알고 있는 경우 해당 코퍼스를 가져옵니다. 응답에는 동일한 collectionName가 포함됩니다.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/RAG_CORPUS_ID"

색인을 생성할 코퍼스 결정

각 코퍼스에 대해 컬렉션의 데이터 객체를 계산합니다. 전체 컬렉션을 계산하려면 빈 filter를 전달합니다.

COLLECTION_ID=vertex-rag-RAG_CORPUS_ID

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/dataObjects:aggregate" \
-d '{"aggregate": "COUNT", "filter": {}}'

개수는 aggregateResults로 반환됩니다.

{
  "aggregateResults": [
    {
      "count": 95217
    }
  ]
}

다음 중 하나에 해당하는 경우 해당 코퍼스의 색인을 만듭니다.

• 개수가 100,000개에 근접하거나 초과합니다. 이 한도는 파일이 아닌 데이터 객체를 계산하므로 큰 파일이 적은 코퍼스는 여전히 한도를 초과할 수 있습니다.
• 쿼리 속도에 비해 검색 속도가 너무 느립니다. 색인 생성 검색은 전체 데이터를 직접 스캔하는 것보다 빠르며 컬렉션이 커질수록 그 차이가 벌어집니다.

그렇지 않으면 색인을 생성하지 않은 상태로 두고 게재 비용을 피합니다. 나중에 커지면 색인을 추가할 수 있습니다.

컬렉션 스키마 검토

RAG Engine은 다음 스키마를 사용하여 각 컬렉션을 만듭니다. 색인 필드와 필터 필드를 지정할 때 이 이름을 사용합니다.

색인 설정 선택

UpdateIndex는 표시 이름, 설명, 라벨, 복제본 수만 변경하므로 이 섹션의 설정을 변경하려면 색인을 삭제하고 새 색인을 만들어야 합니다.

색인 필드: 컬렉션 스키마의 유일한 벡터 필드인 text_embedding로 설정합니다.

거리 측정항목: 코사인으로 설정합니다. RAG Engine은 항상 검색 요청에 COSINE_DISTANCE를 전송하며, 벡터 검색 2.0은 측정항목이 색인과 일치하지 않는 검색 요청을 거부합니다. 측정항목을 생략하면 기본적으로 DOT_PRODUCT로 설정되므로 측정항목 없이 생성된 색인은 해당 코퍼스의 검색을 중단합니다. RAG Engine은 실패를 FAILED_PRECONDITION로 보고하고 Failed to process Rag Managed Vertex Vector Search response. 메시지를 표시하지만 측정항목을 원인으로 식별하지 않습니다. 표기법은 표시 경로에 따라 다릅니다. REST 본문은 COSINE_DISTANCE를 사용하고 gcloud CLI 플래그는 cosine-distance를 사용합니다.

인프라: 스토리지 최적화 인프라에서는 코사인 거리가 지원되지 않으므로 색인을 기본 성능 최적화 인프라에 그대로 둡니다. 색인은 전용 서빙 인프라에서 실행되며 존재하는 동안 요금이 청구됩니다. v1에서 min_replica_count 및 max_replica_count는 모두 기본적으로 2로 설정되므로 기본적으로 색인은 두 개의 복제본으로 제공되며 자동 확장되지 않습니다. 자세한 내용은 컬렉션 색인을 참조하세요.

필터 필드: filter_fields를 file_id로만 설정합니다. 이는 검색 시 RAG Engine이 필터링하는 유일한 필드이며, 검색 요청이 검색을 특정 파일로 제한하는 경우에만 필터링합니다. 특히 corpus_id는 지정된 컬렉션의 모든 데이터 객체에 동일한 값을 보유하므로 필터링해도 이점이 없습니다.

메타데이터 필터링에는 추가 필터 필드가 필요하지 않습니다. 검색 요청이 ragRetrievalConfig.filter.metadataFilter를 설정하면 RAG Engine은 먼저 파일 메타데이터에 대해 필터를 확인하고 결과를 일치하는 RAG 파일 ID 집합으로 변환한 후 해당 집합을 동일한 file_id 필터로 벡터 검색에 전송합니다. rag_metadata를 filter_fields에 추가하면 검색을 변경하지 않고 색인 크기가 증가합니다.

스토어 필드: store_fields를 설정하지 않은 상태로 둡니다. RAG Engine은 검색할 때마다 모든 데이터 필드를 요청하므로 인라인 서빙에 적합하지 않으며, 따라서 청크 데이터는 백업 데이터베이스에서 읽습니다. store_fields에 나열된 필드는 색인으로 푸시되고 크기에 반영되므로 이를 설정하면 검색을 변경하지 않고도 비용이 추가됩니다.

색인 만들기

from google.cloud import vectorsearch_v1

client = vectorsearch_v1.VectorSearchServiceClient()

index = vectorsearch_v1.Index(
    index_field="text_embedding",
    distance_metric=vectorsearch_v1.DistanceMetric.COSINE_DISTANCE,
    filter_fields=["file_id"],
)
request = vectorsearch_v1.CreateIndexRequest(
    parent="projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID",
    index_id="vertex-rag-RAG_CORPUS_ID-index",
    index=index,
)

operation = client.create_index(request=request)

# Wait for the result (note this may take up to several minutes).
operation.result()

PROJECT_ID=PROJECT_ID
RAG_CORPUS_ID=RAG_CORPUS_ID
LOCATION=us-central1
COLLECTION_ID=vertex-rag-${RAG_CORPUS_ID}
INDEX_ID=${COLLECTION_ID}-index

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/indexes?indexId=${INDEX_ID}" \
-d '{
      "index_field": "text_embedding",
      "distance_metric": "COSINE_DISTANCE",
      "filter_fields": ["file_id"]
    }'

gcloud vector-search collections indexes create vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --index-field=text_embedding \
  --distance-metric=cosine-distance \
  --filter-fields=file_id \
  --location=us-central1 \
  --project=PROJECT_ID

완료 폴링

색인을 만들면 장기 실행 작업이 반환됩니다.

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/operation-1770302393524-64a14a54fa197-0dea326c-5a90efda",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.OperationMetadata",
    "createTime": "2026-02-05T14:39:53.558308609Z",
    "target": "projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID/indexes/vertex-rag-RAG_CORPUS_ID-index",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

해당 응답의 이름을 사용하여 작업을 폴링합니다.

OPERATION_NAME=OPERATION_NAME

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/${OPERATION_NAME}"

done가 true이면 response 필드는 색인이 성공적으로 빌드되었음을 의미하고 error 필드는 실패한 이유를 나타냅니다. 색인을 빌드하는 데는 몇 분 정도 걸리며 대규모 코퍼스의 경우 더 오래 걸립니다.

프로젝트 및 위치의 작업을 나열하려면 다음을 실행합니다.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/operations"

기존 색인을 검사하려면 다음을 실행합니다.

gcloud vector-search collections indexes describe vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

색인을 삭제하려면 다음을 실행합니다. 영구 설정을 변경하려면 색인을 삭제해야 합니다. 대체 색인이 빌드될 때까지 검색은 무차별 대입 KNN 스캔으로 대체되며, 코퍼스가 100,000개 청크를 초과하면 완전히 실패합니다.

gcloud vector-search collections indexes delete vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

다음 단계

• Google Drive 또는 Cloud Storage에서 파일과 폴더를 가져오려면 RAG 파일 가져오기 예시를 참조하세요.

• RAG 파일을 나열하려면 RAG 파일 나열 예시를 참조하세요.

• 검색에 재랭커를 사용하려면 Gemini Enterprise Agent Platform RAG Engine 재랭킹을 참조하세요.

• 색인 인프라, 거리 측정항목, ScaNN 매개변수를 조정하려면 컬렉션 색인을 참조하세요.