更新結構定義

您可以更新結構定義結構化資料，以及含中繼資料的非結構化資料 (須支援結構定義)。

您可以在 Google Cloud 控制台或使用 schemas.patch API 方法更新結構定義。

如要更新結構定義，您可以新增欄位、變更欄位的可建立索引、可供搜尋和可擷取註解，或將欄位標示為主要屬性，例如 title、uri 和 description。

重要事項： Google 強烈建議您使用重要屬性對應關係更新結構定義，尤其是 title。這可確保結果正確顯示，並協助 Gemini Enterprise 找出重要資訊，生成更優質的結果。

更新結構定義

您可以在 Google Cloud 控制台或使用 API 更新結構定義。

注意： 編輯結構定義會重新建立資料儲存庫的索引。如果資料儲存庫較大，建立索引可能需要數小時。

控制台

如要在 Google Cloud 控制台更新結構定義，請按照下列步驟操作：

1. 請參閱「需求條件和限制」一節，確認結構定義更新是否有效。

2. 如要更新欄位註解 (將欄位設為可建立索引、可擷取、可動態做為 facet、可搜尋或可自動完成)，請參閱「調整欄位設定」，瞭解各註解類型的限制和規定。

3. 確認您已完成資料擷取。否則，結構定義可能還無法編輯。

4. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

5. 點按導覽選單中的「Data Stores」(資料儲存庫)。

6. 在「Name」(名稱) 欄中，按一下要更新結構定義的資料儲存庫。

7. 點選「結構定義」分頁標籤，查看資料的結構定義。

   如果這是您第一次編輯欄位，這個分頁可能會是空白。

8. 按一下 [Edit] (編輯) 按鈕。

9. 更新結構定義：

   • 對應主要屬性：在結構定義的「Key properties」(主要屬性) 欄中，選取要對應欄位的主要屬性。舉例來說，如果名為 details 的欄位一律包含文件說明，請將該欄位對應至重要屬性「Description」。

   • 更新維度數量 (進階)：如果您搭配 Gemini Enterprise 使用自訂向量嵌入，可以更新這項設定。請參閱 Agent Search 說明文件的「使用自訂嵌入」一節。

   • 更新欄位註解：如要更新欄位註解，請選取或取消選取欄位的註解設定。可用的註解包括「Retrievable」(可擷取)、「Indexable」(可建立索引)、「Dynamic Facetable」(可使用動態商情項目)、「Searchable」(可供搜尋)和「Completable」(可自動完成)。部分欄位設定有限制。如要瞭解各註解類型的說明和規定，請參閱「調整欄位設定」。

   • 新增欄位：先在結構定義中新增欄位，再匯入含有這些欄位的新文件，可縮短 Gemini Enterprise 在匯入後重新建立資料索引的時間。

     1. 按一下「新增欄位」展開該部分。

     2. 按一下 add_box「Add node」(新增節點)，然後指定新欄位的設定。

        如要指定陣列，請將「陣列」設為「是」。舉例來說，如要新增字串陣列，請將「type」設為 string，並將「Array」設為 Yes。

10. 按一下「Save」(儲存)，套用結構定義變更。

    變更結構定義會觸發重新建立索引。如果資料儲存庫較大，重新建立索引可能需要數小時。

REST

如要使用 API 更新結構定義，請按照下列步驟操作：

1. 請參閱「需求條件和限制」和「限制範例 (僅限 REST)」部分，確認結構定義變更是否有效。

   如要更新資料儲存庫的結構定義，其中包含含中繼資料的非結構化資料，請跳至步驟 5 呼叫 schema.patch 方法。

2. 如要更新欄位註解 (將欄位設為可建立索引、可擷取、可動態建立 facet 或可搜尋)，請參閱「調整欄位設定」，瞭解各註解類型的限制和規定。

3. 如果您要編輯自動偵測的結構定義，請確認已完成資料擷取。否則，結構定義可能還無法編輯。

4. 找出資料儲存庫 ID。如果您已有資料儲存庫 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面，然後點按導覽選單中的「Data Stores」(資料儲存庫)。

      前往「Data Stores」(資料儲存庫) 頁面

   2. 點按資料儲存庫的名稱。

   3. 在資料儲存庫的「Data」(資料) 頁面，取得資料儲存庫 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：專案 ID。
   • DATA_STORE_ID：資料儲存庫的 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#

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 C# 設定說明操作。詳情請參閱 Gemini Enterprise C# API 參考文件。

如要向 Gemini Enterprise 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Gemini Enterprise Go API 參考文件。

如要向 Gemini Enterprise 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

//go:build examples

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Gemini Enterprise Java API 參考文件。

如要向 Gemini Enterprise 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Gemini Enterprise Python API 參考文件。

如要向 Gemini Enterprise 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Ruby 設定說明操作。詳情請參閱 Gemini Enterprise Ruby API 參考文件。

如要向 Gemini Enterprise 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

需求條件和限制

更新結構定義時，請務必確認新的結構定義與您要更新的結構定義回溯相容。如要使用不回溯相容的新結構定義更新結構定義，您必須刪除資料儲存庫中的所有文件、刪除結構定義，然後建立新的結構定義。

更新結構定義會觸發所有文件的重新建立索引作業。大型資料儲存庫可能需要數小時或數天才能完成重新建立索引。

結構定義更新不支援下列項目：

• 變更欄位類型。結構定義更新不支援變更欄位類型。例如，對應至 integer 的欄位無法變更為 string。
• 移除欄位。欄位定義後即無法移除。您可以繼續新增欄位，但無法移除現有欄位。

限制範例 (僅限 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"
          }
        }
      }
    }
  

後續步驟

• 查看結構化資料的結構定義
• 刪除結構化資料的結構定義
• 預覽搜尋結果