Vertex AI RAG Engine에서 Pinecone 사용

이 페이지에서는 RAG 코퍼스를 Pinecone 데이터베이스에 연결하는 방법을 보여줍니다.

이 Pinecone을 사용한 Vertex AI RAG Engine 노트북을 사용하여 따라할 수도 있습니다.

Vertex AI RAG Engine과 함께 Pinecone 데이터베이스 인스턴스를 사용하여 색인을 생성하고 벡터 기반 유사성 검색을 실행할 수 있습니다. 유사성 검색은 찾고 있는 텍스트와 유사한 텍스트를 찾는 방법으로, 임베딩 모델을 사용해야 합니다. 임베딩 모델은 비교되는 각 텍스트에 대한 벡터 데이터를 생성합니다. 유사성 검색은 LLM에서 가장 정확한 콘텐츠를 반환하기 위해 그라운딩의 시맨틱 컨텍스트를 검색하는 데 사용됩니다.

Vertex AI RAG Engine을 사용하면 프로비저닝할 책임이 있는 완전 관리형 벡터 데이터베이스 인스턴스를 계속 사용할 수 있습니다. Vertex AI RAG Engine은 스토리지, 색인 관리, 검색에 벡터 데이터베이스를 사용합니다.

Vertex AI RAG Engine에서 Pinecone을 사용할지 고려

다음을 검토하여 Pinecone 데이터베이스를 사용하는 것이 RAG 애플리케이션에 가장 적합한 선택인지 고려하세요.

Pinecone 데이터베이스 인스턴스의 확장을 만들고 구성하고 관리해야 합니다.
Vertex AI RAG Engine은 색인의 기본 네임스페이스를 사용합니다. 이 네임스페이스는 다른 항목에서 수정할 수 없어야 합니다.
Vertex AI RAG Engine이 Pinecone 데이터베이스와 상호작용할 수 있도록 하는 Pinecone API 키를 제공해야 합니다. Vertex AI RAG Engine은 Pinecone API 키를 저장하고 관리하지 않습니다. 대신 다음을 수행해야 합니다.
- Google Cloud Secret Manager에 키를 저장합니다.
- 보안 비밀에 액세스할 수 있는 권한을 프로젝트의 서비스 계정에 부여합니다.
- Vertex AI RAG Engine에 보안 비밀의 리소스 이름에 대한 액세스 권한을 부여합니다.
- RAG 코퍼스와 상호작용할 때 Vertex AI RAG Engine은 서비스 계정을 사용하여 보안 비밀 리소스에 액세스합니다.
RAG 코퍼스와 Pinecone 색인은 일대일로 매핑됩니다. 이 연결은 CreateRagCorpus API 호출 또는 UpdateRagCorpus API 호출의 일부로 이루어집니다.

Pinecone 색인 만들기

Pinecone 색인을 만들려면 다음 단계를 따르세요.

색인을 RAG 코퍼스와 호환되도록 색인에 지정해야 하는 색인 구성을 확인하려면 Pinecone 빠른 시작 가이드를 참고하세요.
다음과 같은 이유로 Pinecone 색인의 위치가 Vertex AI RAG Engine을 사용하는 위치와 동일하거나 그 근처에 있어야 합니다.
- 지연 시간을 줄이려고 합니다.
- 관련 법규에서 정한 데이터 상주 요구사항을 충족하려고 합니다.
Pinecone 색인을 만드는 동안 Vertex AI RAG Engine과 함께 사용할 임베딩 차원을 지정합니다. 이 표에는 차원 크기 또는 차원 크기의 위치가 나와 있습니다.

모델 차원 크기

퍼스트 파티 Gecko 768

미세 조정된 퍼스트 파티 Gecko 768

E5 OSS 임베딩 모델 사용을 참고하세요.
지원되는 다음 거리 측정항목 중 하나를 선택합니다.
- cosine
- dotproduct
- euclidean
선택사항: 포드 기반 색인을 만들 때는 pod.metadata_config.indexed 필드에 file_id를 지정해야 합니다. 자세한 내용은 선택적 메타데이터 색인 생성을 참고하세요.

모델	차원 크기
퍼스트 파티 Gecko	768
미세 조정된 퍼스트 파티 Gecko	768
E5	OSS 임베딩 모델 사용을 참고하세요.

Pinecone API 키 만들기

Vertex AI RAG Engine은 인증 및 승인에 API 키를 사용하여 Pinecone 색인에만 연결할 수 있습니다. Pinecone 프로젝트에서 API 키 기반 인증을 구성하려면 인증에 관한 Pinecone 공식 가이드를 따라야 합니다.

Secret Manager에 API 키 저장

API 키에는 법적 요건이 적용되는 민감한 개인 식별 정보(SPII)가 포함됩니다. SPII 데이터가 유출되거나 오용되면 개인에게 심각한 위험이나 피해가 발생할 수 있습니다. Vertex AI RAG Engine을 사용하는 동안 개인에 대한 위험을 최소화하려면 API 키를 저장 및 관리하지 마세요. 또한 암호화되지 않은 API 키를 공유하지 마세요.

SPII를 보호하려면 다음 단계를 따르세요.

Secret Manager에 API 키를 저장합니다.
Vertex AI RAG Engine 서비스 계정에 보안 비밀에 대한 권한을 부여하고 보안 비밀 리소스 수준에서 액세스 제어를 관리합니다.
1. 프로젝트 권한으로 이동합니다.
2. Google 제공 역할 부여 포함 옵션을 사용 설정합니다.
3. 다음과 같은 형식의 서비스 계정을 찾습니다.
  
  service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
4. 서비스 계정의 주 구성원을 수정합니다.
5. Secret Manager Secret Accessor 역할을 서비스 계정에 추가합니다.
RAG 코퍼스를 만들거나 업데이트하는 동안 보안 비밀 리소스 이름을 Vertex AI RAG Engine에 전달하고 보안 비밀 리소스 이름을 저장합니다.

Pinecone 색인에 API 요청을 수행하면 Vertex AI RAG Engine은 각 서비스 계정을 사용하여 프로젝트에서 Secret Manager의 보안 비밀 리소스에 해당하는 API 키를 읽습니다.

Vertex AI RAG Engine 서비스 계정 프로비저닝

프로젝트에서 첫 번째 RAG 코퍼스를 만들면 Vertex AI RAG Engine이 전용 서비스 계정을 만듭니다. 프로젝트의 Identity and Access Management 페이지에서 서비스 계정을 찾을 수 있습니다.

서비스 계정은 다음 고정 형식을 따릅니다.

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

예를 들면 다음과 같습니다.

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

RAG 코퍼스 준비

Vertex AI RAG Engine에서 Pinecone 색인을 사용하려면 생성 단계에서 색인을 RAG 코퍼스와 연결해야 합니다. 연결이 이루어지면 이 바인딩은 RAG 코퍼스의 전체 기간 동안 영구적으로 유지됩니다. CreateRagCorpus 또는 UpdateRagCorpus API를 사용하여 연결할 수 있습니다.

연결이 완료된 것으로 간주되려면 RAG 코퍼스에 다음 세 가지 키 필드를 설정해야 합니다.

rag_vector_db_config.pinecone: 이 필드는 RAG 코퍼스와 연결할 벡터 데이터베이스를 선택하는 데 도움이 되며 CreateRagCorpus API 호출 중에 설정해야 합니다. 설정되지 않은 경우 기본 벡터 데이터베이스 선택사항 RagManagedDb가 RAG 코퍼스에 할당됩니다.
rag_vector_db_config.pinecone.index_name: RAG 코퍼스와 함께 사용되는 Pinecone 색인을 만드는 데 사용되는 이름입니다. CreateRagCorpus 호출 중에 이름을 설정하거나 UpdateRagCorpus API를 호출할 때 이름을 지정할 수 있습니다.
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Secret Manager에 저장된 보안 비밀의 전체 리소스 이름으로, Pinecone API 키가 포함되어 있습니다. CreateRagCorpus 호출 중에 이름을 설정하거나 UpdateRagCorpus API를 호출할 때 이름을 지정할 수 있습니다. 이 필드를 지정할 때까지는 데이터를 RAG 코퍼스에 가져올 수 없습니다.
이 필드의 형식은 다음과 같아야 합니다.
projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

RAG 코퍼스 만들기

권한이 설정된 Pinecone 색인 이름과 보안 비밀 리소스 이름에 액세스할 수 있는 경우 RAG 코퍼스를 만들고 Pinecone 색인과 연결할 수 있습니다. 이 샘플 코드에서 이를 보여줍니다.

RAG 코퍼스를 처음 만드는 경우 서비스 계정 정보가 준비되어 있지 않습니다. 그러나 이 필드는 선택사항이며 UpdateRagCorpus API를 사용하여 RAG 코퍼스와 연결할 수 있습니다.

서비스 계정 정보를 제공하지 않고 RAG 코퍼스를 만드는 방법의 예시는 색인 이름 또는 API 키 없이 RAG 코퍼스 만들기를 참고하세요.

Python

이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Vertex AI Python API 참고 문서를 참조하세요.

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# pinecone_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
        publisher_model="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = rag.Pinecone(
    index_name=pinecone_index_name,
    api_key=pinecone_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=embedding_model_config,
        vector_db=vector_db,
    ),
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

색인 이름 또는 API 키 없이 RAG 코퍼스 만들기

첫 번째 RAG 코퍼스이며 서비스 계정 세부정보에 액세스할 수 없거나 Pinecone 색인의 프로비저닝 단계를 완료하지 않은 경우에도 RAG 코퍼스를 만들 수 있습니다. 그런 다음 RAG 코퍼스를 빈 Pinecone 구성과 연결하고 나중에 세부정보를 추가할 수 있습니다.

다음 사항을 고려해야 합니다.

색인 이름과 API 키 보안 비밀 이름을 제공하지 않으면 파일을 RAG 코퍼스에 가져올 수 없습니다.
RAG 코퍼스의 벡터 데이터베이스로 Pinecone을 선택하면 나중에 다른 데이터베이스로 전환할 수 없습니다.

이 코드 예시에서는 Pinecone 색인 이름이나 API 보안 비밀 이름을 제공하지 않고 Pinecone으로 RAG 코퍼스를 만드는 방법을 보여줍니다. UpdateRagCorpus API를 사용하여 나중에 누락된 정보를 지정합니다.

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

RAG 코퍼스 업데이트

UpdateRagCorpus API를 사용하면 벡터 데이터베이스 구성을 업데이트할 수 있습니다. Pinecone 색인 이름과 API 키 보안 비밀 버전이 이전에 설정되지 않은 경우 Pinecone API를 사용하여 필드를 업데이트할 수 있습니다. 선택한 벡터 데이터베이스를 업데이트할 수 없습니다. API 키 보안 비밀을 제공하는 것은 선택사항입니다. 하지만 API 키 보안 비밀을 지정하지 않으면 데이터를 RAG 코퍼스에 가져올 수 있습니다.

필드	변경 가능 여부	필수 또는 선택사항
`rag_vector_db_config.vector_db`	선택한 후에는 변경할 수 없습니다.	필수
`rag_vector_db_config.pinecone.index_name`	RAG 코퍼스에서 필드를 설정하면 변경할 수 없습니다.	필수
`rag_vector_db_config.api_auth.api_key_config.api_key_secret_version`	변경 가능합니다. API 키를 설정한 후에는 키를 삭제할 수 없습니다.	선택사항

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

다음 단계

Vertex AI RAG Engine에서 Vertex AI 벡터 검색 사용

Vertex AI RAG Engine에서 Pinecone 사용 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Vertex AI RAG Engine에서 Pinecone을 사용할지 고려

Pinecone 색인 만들기

Pinecone API 키 만들기

Secret Manager에 API 키 저장

Vertex AI RAG Engine 서비스 계정 프로비저닝

RAG 코퍼스 준비

RAG 코퍼스 만들기

Python

REST

색인 이름 또는 API 키 없이 RAG 코퍼스 만들기

Python

REST

RAG 코퍼스 업데이트

Python

REST

다음 단계

Vertex AI RAG Engine에서 Pinecone 사용