메타데이터 검색으로 필터링

이 페이지에서는 Gemini Enterprise 에이전트 플랫폼의 RAG Engine에서 스키마 기반 메타데이터 검색 기능을 사용하는 방법을 보여줍니다. 코퍼스의 메타데이터 스키마를 정의하고, 코퍼스 내 파일에 메타데이터를 첨부하고, 이 메타데이터를 사용하여 검색 중에 컨텍스트를 필터링할 수 있습니다.

시작하기 전에

메타데이터 검색을 사용하려면 기존 RAG 코퍼스와 RAG 파일이 있어야 합니다. 코퍼스를 만들고 파일을 업로드하는 방법을 알아보려면 RAG 기술 자료 관리하기를 참고하세요.

코퍼스를 만들거나 파일을 업로드하면 API에서 숫자 RAG_CORPUS_ID 및 RAG_FILE_ID (예: 123456789)를 반환합니다. 메타데이터 리소스를 관리하려면 이러한 ID가 있어야 합니다.

메타데이터 리소스

메타데이터 검색 기능은 다음 리소스 계층 구조를 사용합니다.

  • RagCorpus: RAG 파일과 해당 구성을 포함하는 최상위 리소스입니다.

    • RagDataSchema: RagCorpus의 하위 리소스입니다. 코퍼스 내에서 사용되는 단일 메타데이터 필드의 구조를 정의합니다. 각 스키마는 키 (예: year)와 데이터 유형 (INTEGER, FLOAT, STRING, DATETIME, BOOLEAN 또는 LIST)을 지정합니다. 필터링에 사용할 각 메타데이터 키에 대해 RagDataSchema를 정의해야 합니다.

    • RagFile: 단일 인그레스된 문서를 나타내는 RagCorpus의 하위 리소스입니다.

      • RagMetadata: RagFile의 하위 리소스입니다. 특정 파일 (예: year=2024)에 연결된 단일 키-값 메타데이터 쌍을 나타냅니다. RagMetadata 리소스에 사용된 키는 상위 코퍼스의 RagDataSchema에 정의된 키에 상응해야 합니다. 단일 파일에 여러 RagMetadata 리소스를 연결할 수 있습니다.

메타데이터 스키마 관리

RAG 코퍼스를 만든 후 코퍼스 수준에서 RagDataSchema 리소스를 사용하여 메타데이터 구조를 정의합니다. 정의한 스키마를 보고 삭제할 수도 있습니다.

메타데이터 스키마 정의

스키마를 정의할 때는 키와 데이터 유형을 지정합니다. 키가 될 수 있는 유효한 유형은 다음과 같습니다.

  • INTEGER: 메타데이터 값을 int_value로 전달합니다.
  • FLOAT: 메타데이터 값을 float_value로 전달합니다.
  • STRING: 메타데이터 값을 str_value로 전달합니다.
  • DATETIME: 메타데이터 값이 datetime_value (RFC 3339 형식 문자열, 예: '2024-01-01T00:00:00Z')로 전달됩니다.
  • BOOLEAN: 메타데이터 값을 bool_value로 전달합니다.
  • LIST: 메타데이터 값을 list_value로 전달합니다. 다음 REST 샘플은 코퍼스의 year 및 month 필드를 정의하는 메타데이터 스키마를 일괄적으로 만드는 방법을 보여줍니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
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/${RAG_CORPUS_ID}/ragDataSchemas:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "year",
        "schema_details": {"type": "INTEGER"}
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "month",
        "schema_details": {"type": "STRING"}
      }
    }
  ]
}'

메타데이터 스키마 나열

다음 REST 샘플은 코퍼스에 정의된 메타데이터 스키마를 나열하는 방법을 보여줍니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
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}/ragDataSchemas

메타데이터 스키마 삭제

다음 REST 샘플은 코퍼스에서 메타데이터 스키마를 일괄 삭제하는 방법을 보여줍니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
  • RAG_DATA_SCHEMA_KEY_1: 삭제할 첫 번째 메타데이터 스키마의 키 이름입니다.
  • RAG_DATA_SCHEMA_KEY_2: 삭제할 두 번째 메타데이터 스키마의 키 이름입니다.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_DATA_SCHEMA_KEY_1=RAG_DATA_SCHEMA_KEY_1
RAG_DATA_SCHEMA_KEY_2=RAG_DATA_SCHEMA_KEY_2
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/${RAG_CORPUS_ID}/ragDataSchemas:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_2}"'"
  ]
}'

파일 메타데이터 관리

코퍼스에 파일을 업로드하거나 가져온 후 해당 파일과 연결된 메타데이터를 첨부, 업데이트, 보기, 삭제할 수 있습니다.

파일에 메타데이터 첨부

첨부된 메타데이터는 코퍼스에 정의된 스키마를 준수해야 합니다. 다음 REST 샘플은 파일에 여러 메타데이터 값을 연결하는 방법을 보여줍니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
  • RAG_FILE_ID: RAG 파일의 ID.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
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/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "year", "value": { "int_value": 2024 } }
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "month", "value": { "str_value": "May" } }
      }
    }
  ]
}'

파일의 메타데이터 나열

다음 REST 샘플은 특정 파일에 연결된 메타데이터를 나열하는 방법을 보여줍니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
  • RAG_FILE_ID: RAG 파일의 ID.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
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}/ragFiles/${RAG_FILE_ID}/ragMetadata

메타데이터 업데이트

파일에 연결된 메타데이터 값을 업데이트할 수 있습니다. 다음 REST 샘플은 year 키와 연결된 메타데이터 값을 업데이트하는 방법을 보여줍니다. RAG_METADATA_KEY는 메타데이터를 만들 때 사용한 문자열입니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
  • RAG_FILE_ID: RAG 파일의 ID.
  • RAG_METADATA_KEY: 업데이트할 메타데이터의 키 이름입니다.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY=RAG_METADATA_KEY
curl -X PATCH \
-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/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata/${RAG_METADATA_KEY} \
-d '{
  "user_specified_metadata": { "key": "'"${RAG_METADATA_KEY}"'", "value": { "int_value": 2025 } }
}'

파일에서 메타데이터 삭제

다음 REST 샘플은 파일에서 메타데이터 값을 일괄 삭제하는 방법을 보여줍니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
  • RAG_FILE_ID: RAG 파일의 ID.
  • RAG_METADATA_KEY_1: 삭제할 첫 번째 메타데이터 값의 키 이름입니다.
  • RAG_METADATA_KEY_2: 삭제할 두 번째 메타데이터 값의 키 이름입니다.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY_1=RAG_METADATA_KEY_1
RAG_METADATA_KEY_2=RAG_METADATA_KEY_2
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/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_2}"'"
  ]
}'

메타데이터로 컨텍스트 필터링

결과의 관련성을 높이려면 파일 메타데이터를 사용하여 컨텍스트 검색 중에 검색 공간을 좁히세요. CEL (Common Expression Language)을 사용하여 RetrieveContexts 요청에 metadata_filter 표현식을 추가합니다 (예: year == 2024 && month == "May"). 필터 표현식과 일치하는 메타데이터가 있는 파일만 검색 대상으로 간주됩니다.

다음 REST 샘플은 메타데이터 필터를 사용하여 컨텍스트를 검색하는 방법을 보여줍니다.

REST

다음 변수를 바꿉니다.

  • PROJECT_ID: 프로젝트 ID.
  • LOCATION: 요청을 처리하는 리전.
  • RAG_CORPUS_ID: RAG 코퍼스의 ID.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
QUERY="except share amounts"
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}:retrieveContexts -d '{
    "vertex_rag_store": {
       "rag_resources": [
         {
           "rag_corpus": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'"
         }
       ]
    },    
    "query": {
      "text": "'"${QUERY}"'", 
      "rag_retrieval_config": {
         "top_k": 10,
         "filter": {
            "vector_distance_threshold": 0.5,
            "metadata_filter": "year == 2024 && month == \"May\""
         }
      }
    }
}'

다음 단계