스키마 업데이트

구조화된 데이터, 구조화된 데이터가 포함된 웹사이트 데이터 또는 기타 메타데이터가 포함된 구조화되지 않은 데이터와 같이 스키마를 지원하는 데이터가 포함된 모든 데이터의 스키마를 업데이트할 수 있습니다.

Google Cloud 콘솔에서 또는 schemas.patch API 메서드를 사용하여 스키마를 업데이트할 수 있습니다. 웹사이트의 스키마 업데이트는 REST API를 통해서만 지원됩니다.

스키마를 업데이트하려면 새 필드를 추가하거나, 필드에 색인 생성 가능, 검색 가능, 검색 가능 주석을 변경하거나, 필드를 키 속성(예: title, uri, description)으로 표시하면 됩니다.

중요: 특히 title의 경우 키 속성 매핑으로 스키마를 업데이트하는 것이 좋습니다. 이렇게 하면 결과가 올바르게 표시되고 Vertex AI Agent Builder가 더 나은 결과를 생성하는 데 도움이 되는 중요한 정보를 식별할 수 있습니다.

스키마 업데이트

Google Cloud 콘솔에서 또는 API를 사용하여 스키마를 업데이트할 수 있습니다.

참고: 스키마를 수정하면 데이터 스토어의 색인이 다시 생성됩니다. 대규모 데이터 스토어의 경우 색인을 생성하는 데 몇 시간이 걸릴 수 있습니다.

콘솔

Google Cloud 콘솔에서 스키마를 업데이트하려면 다음 단계를 따르세요.

1. 요구사항 및 제한사항 섹션을 검토하여 스키마 업데이트가 유효한지 확인합니다.

2. 필드 주석을 업데이트하는 경우 (필드를 색인 생성 가능, 검색 가능, 동적 얼굴 표, 검색 가능 또는 완료 가능으로 설정) 각 주석 유형의 제한사항 및 요구사항에 관한 필드 설정 구성을 검토하세요.

3. 데이터 수집이 완료되었는지 확인합니다. 그렇지 않으면 아직 스키마를 수정할 수 없을 수 있습니다.

4. Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.

   Agent Builder를 사용하여 이 모든 것을 자체 데이터에 그라운딩하세요.

5. 탐색 메뉴에서 데이터 스토어를 클릭합니다.

6. 이름 열에서 업데이트할 스키마가 있는 데이터 스토어를 클릭합니다.

7. 스키마 탭을 클릭하여 데이터의 스키마를 확인합니다.

   필드를 처음 수정하는 경우 이 탭이 비어 있을 수 있습니다.

8. 수정 버튼을 클릭합니다.

9. 스키마 업데이트

   • 키 속성 매핑: 스키마의 키 속성 열에서 필드를 매핑할 키 속성을 선택합니다. 예를 들어 details라는 필드에 항상 문서의 설명이 포함되는 경우 이 필드를 키 속성 Description에 매핑합니다.

   • 측정기준 수 업데이트(고급): Vertex AI Search에서 맞춤 벡터 임베딩을 사용하는 경우 이 설정을 업데이트할 수 있습니다. 고급: 커스텀 임베딩 사용을 참고하세요.

   • 필드 주석 업데이트: 필드의 주석을 업데이트하려면 필드의 주석 설정을 선택하거나 선택 해제합니다. 사용 가능한 주석은 검색 가능, 색인 생성 가능, 동적 얼굴 표, 검색 가능, 완성 가능입니다. 일부 필드 설정에는 제한사항이 있습니다. 각 주석 유형에 관한 설명과 요구사항은 필드 설정 구성을 참고하세요.

   • 새 필드 추가: 이러한 필드가 포함된 새 문서를 가져오기 전에 스키마에 새 필드를 추가하면 가져오기 후 Vertex AI Agent Builder가 데이터의 색인을 다시 생성하는 데 걸리는 시간이 단축될 수 있습니다.

     1. 새 필드 추가를 클릭하여 섹션을 펼칩니다.

     2. add_box 노드 추가를 클릭하고 새 필드의 설정을 지정합니다.

        배열을 표시하려면 배열을 예로 설정합니다. 예를 들어 문자열 배열을 추가하려면 type을 string으로, Array를 Yes로 설정합니다.

        웹사이트 데이터 스토어 색인의 경우 추가하는 모든 필드는 기본적으로 배열입니다.

10. 저장을 클릭하여 스키마 변경사항을 적용합니다.

    스키마를 변경하면 색인 재생성이 트리거됩니다. 대규모 데이터 스토어의 경우 색인을 다시 생성하는 데 몇 시간이 걸릴 수 있습니다.

REST

API를 사용하여 스키마를 업데이트하려면 다음 단계를 따르세요.

1. 요구사항 및 제한사항 및 제한사항 예시(REST만 해당) 섹션을 검토하여 스키마 변경사항이 유효한지 확인합니다.

   웹사이트 또는 메타데이터가 포함된 구조화되지 않은 데이터가 있는 데이터 스토어의 스키마를 업데이트하려면 5단계로 건너뛰어 schema.patch 메서드를 호출합니다.

2. 필드 주석을 업데이트하는 경우(필드를 색인 생성 가능, 검색 가능, 동적 얼굴 표, 검색 가능으로 설정) 각 주석 유형의 제한사항 및 요구사항에 관한 필드 설정 구성을 검토하세요.

3. 자동 감지된 스키마를 수정하는 경우 데이터 수집이 완료되었는지 확인합니다. 그렇지 않으면 아직 스키마를 수정할 수 없습니다.

4. 데이터 스토어 ID를 찾습니다. 데이터 스토어 ID가 이미 있는 경우 다음 단계로 건너뜁니다.

   1. Google Cloud 콘솔에서 Agent Builder 페이지로 이동하고 탐색 메뉴에서 데이터 스토어를 클릭합니다.

      데이터 스토어 페이지로 이동

   2. 데이터 스토어 이름을 클릭합니다.

   3. 데이터 스토어의 데이터 페이지에서 데이터 스토어 ID를 가져옵니다.

5. schemas.patch API 메서드를 사용하여 새 JSON 스키마를 JSON 객체로 제공합니다.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
   -d '{
     "structSchema": JSON_SCHEMA_OBJECT
   }'
   

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 ID
   • DATA_STORE_ID: Vertex AI Search 데이터 스토어 ID

   • JSON_SCHEMA_OBJECT: JSON 객체로 된 새 JSON 스키마. 예를 들면 다음과 같습니다.

     {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "type": "object",
       "properties": {
         "title": {
           "type": "string",
           "keyPropertyMapping": "title"
         },
         "categories": {
           "type": "array",
           "items": {
             "type": "string",
             "keyPropertyMapping": "category"
           }
         },
         "uri": {
           "type": "string",
           "keyPropertyMapping": "uri"
         }
       }
     }

     명령어 및 결과 예시

     curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
     "structSchema": {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "type": "object",
     "properties": {
     "title": {
     "type": "string",
     "keyPropertyMapping": "title"
     },
     "categories": {
     "type": "array",
     "items": {
     "type": "string",
     "keyPropertyMapping": "category"
     }
     },
     "uri": {
     "type": "string",
     "keyPropertyMapping": "uri"
     }
     }
     }
     }'
     
     {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
     "metadata": {
     "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
     }
     }
     

6. (선택사항) 스키마 정의 보기 절차를 수행하여 스키마를 검토합니다.

C#

자세한 내용은 Vertex AI Agent Builder C# API 참고 문서를 확인하세요.

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

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;

public sealed partial class GeneratedSchemaServiceClientSnippets
{
    /// <summary>Snippet for UpdateSchema</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void UpdateSchemaRequestObject()
    {
        // Create client
        SchemaServiceClient schemaServiceClient = SchemaServiceClient.Create();
        // Initialize request argument(s)
        UpdateSchemaRequest request = new UpdateSchemaRequest
        {
            Schema = new Schema(),
            AllowMissing = false,
        };
        // Make the request
        Operation<Schema, UpdateSchemaMetadata> response = schemaServiceClient.UpdateSchema(request);

        // Poll until the returned long-running operation is complete
        Operation<Schema, UpdateSchemaMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Schema result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Schema, UpdateSchemaMetadata> retrievedResponse = schemaServiceClient.PollOnceUpdateSchema(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Schema retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

자세한 내용은 Vertex AI Agent Builder Go API 참고 문서를 확인하세요.

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

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewSchemaClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.UpdateSchemaRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#UpdateSchemaRequest.
	}
	op, err := c.UpdateSchema(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

자세한 내용은 Vertex AI Agent Builder Java API 참고 문서를 확인하세요.

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

import com.google.cloud.discoveryengine.v1.Schema;
import com.google.cloud.discoveryengine.v1.SchemaServiceClient;
import com.google.cloud.discoveryengine.v1.UpdateSchemaRequest;

public class SyncUpdateSchema {

  public static void main(String[] args) throws Exception {
    syncUpdateSchema();
  }

  public static void syncUpdateSchema() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
      UpdateSchemaRequest request =
          UpdateSchemaRequest.newBuilder()
              .setSchema(Schema.newBuilder().build())
              .setAllowMissing(true)
              .build();
      Schema response = schemaServiceClient.updateSchemaAsync(request).get();
    }
  }
}

Python

자세한 내용은 Vertex AI Agent Builder Python API 참고 문서를 확인하세요.

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

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_update_schema():
    # Create a client
    client = discoveryengine_v1.SchemaServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.UpdateSchemaRequest(
    )

    # Make the request
    operation = client.update_schema(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

자세한 내용은 Vertex AI Agent Builder Ruby API 참고 문서를 확인하세요.

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

require "google/cloud/discovery_engine/v1"

##
# Snippet for the update_schema call in the SchemaService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::SchemaService::Client#update_schema.
#
def update_schema
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::SchemaService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::UpdateSchemaRequest.new

  # Call the update_schema method.
  result = client.update_schema request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

요구사항 및 제한사항

스키마를 업데이트할 때는 새 스키마가 업데이트 중인 스키마와 하위 호환되는지 확인하세요. 하위 호환되지 않는 새 스키마로 스키마를 업데이트하려면 데이터 스토어의 모든 문서를 삭제하고 스키마를 삭제한 후 새 스키마를 만들어야 합니다.

스키마를 업데이트하면 모든 문서의 색인 재생성이 트리거됩니다. 이 과정에서 시간이 걸리고 추가 비용이 발생할 수 있습니다.

• 시간. 대규모 데이터 스토어의 색인을 다시 생성하는 데 몇 시간 또는 며칠이 걸릴 수 있습니다.

• 비용. 색인 재생성은 파서에 따라 비용이 발생할 수 있습니다. 예를 들어 OCR 파서 또는 레이아웃 파서를 사용하는 데이터 스토어의 색인을 다시 생성하면 비용이 발생합니다. 자세한 내용은 Document AI 기능 가격 책정을 참고하세요.

스키마 업데이트는 다음을 지원하지 않습니다.

• 필드 유형 변경. 스키마 업데이트는 필드 유형 변경을 지원하지 않습니다. 예를 들어 정수에 매핑된 필드는 문자열로 변경할 수 없습니다.
• 필드 삭제. 필드는 정의한 후에는 삭제할 수 없습니다. 새 필드를 계속 추가할 수 있지만 기존 필드는 삭제할 수 없습니다.

제한사항 예시(REST만 해당)

이 섹션에서는 유효한 스키마 업데이트 유형과 잘못된 스키마 업데이트 유형의 예시를 보여줍니다. 다음 예에서는 다음 JSON 스키마 예시를 사용합니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    }
  }
}

지원되는 업데이트의 예시

다음과 같은 예시 스키마 업데이트가 지원됩니다.

• 필드 추가. 이 예시에서는 properties.uri 필드가 스키마에 추가되었습니다.

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      },
      "description": {
        "type": "string",
        "keyPropertyMapping": "description"
      },
      "uri": { // Added field. This is supported.
        "type": "string",
        "keyPropertyMapping": "uri"
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string",
          "keyPropertyMapping": "category"
        }
      }
    }
  }
  

• title, description 또는 uri의 키 속성 주석을 추가하거나 삭제. 이 예시에서는 keyPropertyMapping이 title 필드에 추가되었습니다.

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "keyPropertyMapping": "title" // Added "keyPropertyMapping". This is supported.
      },
      "description": {
        "type": "string",
        "keyPropertyMapping": "description"
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string",
          "keyPropertyMapping": "category"
        }
      }
    }
  }
  

잘못된 스키마 업데이트의 예시

다음과 같은 스키마 예시 업데이트는 지원되지 않습니다.

• 필드 유형 변경. 이 예시에서 title 필드의 유형이 문자열에서 숫자로 변경되었습니다. 이 기능은 지원되지 않습니다.

    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "title": {
          "type": "number" // Changed from string. Not allowed.
        },
        "description": {
          "type": "string",
          "keyPropertyMapping": "description"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string",
            "keyPropertyMapping": "category"
          }
        }
      }
    }
  

• 필드 삭제. 이 예시에서는 title 필드가 삭제되었습니다. 이 기능은 지원되지 않습니다.

    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        // "title" is removed. Not allowed.
        "description": {
          "type": "string",
          "keyPropertyMapping": "description"
        },
        "uri": {
          "type": "string",
          "keyPropertyMapping": "uri"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string",
            "keyPropertyMapping": "category"
          }
        }
      }
    }
  

다음 단계

• 구조화된 데이터의 스키마 정의 보기
• 구조화된 데이터의 스키마 삭제
• 검색결과 미리보기