本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 建立連線至結構化資料存放區的知識庫 若要將知識庫連線至結構化資料存放區，請指定下列元件： + **查詢引擎組態** 將執行所產生 SQL 查詢之運算服務的組態。查詢引擎用於將自然語言使用者查詢轉換為 SQL 查詢，可用於從資料存放區擷取資料。您可以選擇 Amazon Redshift 作為查詢引擎。選擇此組態時，您必須指定： + 運算連線中繼資料，例如叢集 ID 或工作群組 ARN，視選擇的查詢引擎而定。 + 使用查詢引擎的身分驗證方法，可使用具有適當許可的 IAM 服務角色、查詢引擎資料庫使用者或連結至資料庫憑證的 AWS Secrets Manager 秘密。 + **儲存組態** 包含您資料的資料存放區的組態。您可以連線至 Amazon Redshift Provisioned 或 Amazon Redshift Serverless，並使用 Amazon Redshift 或 AWS Glue Data Catalog 做為您的資料存放區。 + **(選用) 查詢組態** 您可以使用選用的查詢組態來提高 SQL 生成的準確性： + **查詢時間上限** – 經過這段時間後，查詢就會逾時。 + **說明** – 提供有關表格或欄的中繼資料或補充資訊。您可以包括表格或資料欄的說明、使用情形附註，或任何其他屬性。您新增的說明可透過提供有關表格或資料欄結構的額外內容和資訊，來改善 SQL 查詢生成。 + **包含項目和排除項目** – 指定要針對 SQL 生成包含或排除的一組表格或資料欄。如果您想要將 SQL 查詢的範圍限於一組定義的可用表格或資料欄的子集，則此欄位會非常重要。此選項可透過減少不必要的表格或資料欄參考，協助最佳化生成過程。 如果您指定包含項目，則會忽略所有其他表格和資料欄。如果您指定排除項目，則會忽略您指定的表格和資料欄。 **注意** 包含項目和排除項目無法替代防護機制，僅用於提高模型準確性。 + **策劃的查詢** – 一組預先定義的問題和答案範例。問題會編寫成自然語言查詢 (NLQ)，答案則是對應的 SQL 查詢。這些範例透過提供應生成的查詢類型範例，來協助 SQL 生成過程。這些範例可作為參考點來提高生成式 SQL 輸出的準確性和相關性。 展開與使用案例對應的區段： ## 使用主控台 若要使用 連線至結構化資料存放區 AWS 管理主控台，請執行下列動作： 1. AWS 管理主控台 使用具有使用 Amazon Bedrock 主控台之許可的 IAM 身分登入 。接著，開啟位於 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock) 的 Amazon Bedrock 主控台。 1. 在左側導覽窗格中選擇**知識庫**。 1. 在**知識庫**區段中，選擇**建立**，然後選取**具有結構化資料存放區的知識庫**。 1. 設定知識庫的下列詳細資訊： 1. (選用) 變更預設名稱並提供知識庫的描述。 1. 選取要用於從資料存放區擷取資料的查詢引擎。 1. 選擇具有適當許可的 IAM 服務角色，以建立和管理此知識庫。您可以讓 Amazon Bedrock 建立服務角色，或選擇已建立的自訂角色。如需建立自訂角色的詳細資訊，請參閱 [設定查詢引擎和建立具有結構化資料存放區之知識庫的許可](knowledge-base-prereq-structured.md)。 1. (選用) 新增標籤以與您的知識庫建立關聯。如需詳細資訊，請參閱[標記 Amazon Bedrock 資源](tagging.md)。 1. 選擇**下一步**。 1. 設定您的查詢引擎： 1. 選取您在其中建立叢集或工作群組的服務。然後選擇要使用的叢集或工作群組。 1. 選取身分驗證方法，並提供必要的欄位。 1. 選取要存放中繼資料的資料存放區。然後，選擇或輸入資料庫的名稱。 1. (選用) 視需要修改查詢組態。如需不同組態的詳細資訊，請參閱本主題的開頭。 1. 選擇**下一步**。 1. 檢閱您的知識庫組態，並視需要編輯任何區段。確認以建立您的知識庫。 ## 使用 API 若要使用 Amazon Bedrock API 連線至結構化資料存放區，請使用 [Amazon Bedrock 代理人建置時期端點](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)搭配下列一般請求內文來傳送 [CreateKnowledgeBase](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateKnowledgeBase.html) 請求： ``` { "name": "string", "roleArn": "string", "knowledgeBaseConfiguration": { "type": "SQL", "sqlKnowledgeBaseConfiguration": [SqlKnowledgeBaseConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_SqlKnowledgeBaseConfiguration.html) }, "description": "string", "clientToken": "string", "tags": { "string": "string" } } ``` 下列是必要欄位。 **** | 欄位 | 基本描述 | | --- | --- | | 名稱 | 知識庫的名稱 | | roleArn | 具有適當許可的[知識庫服務角色](kb-permissions.md)。您可以使用主控台自動建立具有適當許可的服務角色。 | | knowledgeBaseConfiguration | 包含知識庫的組態。對於結構化資料庫，指定 SQL 為 type 並包含 sqlKnowledgeBaseConfiguration 欄位。 | 以下是選填欄位。 **** | 欄位 | 使用 | | --- | --- | | description | 包含知識庫的描述。 | | clientToken | 為確保 API 請求，僅完成一次。如需詳細資訊，請參閱[確保冪等性](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)。 | | 標籤 | 將標籤與流程建立關聯。如需詳細資訊，請參閱[標記 Amazon Bedrock 資源](tagging.md)。 | `SQLKnowledgeBaseConfiguration` 取決於您使用的查詢引擎。對於 Amazon Redshift，將 `type` 欄位指定為 `REDSHIFT`，並包含 `redshiftConfiguration` 欄位，該欄位會對應至 [RedshiftConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftConfiguration.html)。對於 [RedshiftConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftConfiguration.html)，您可以設定下列欄位： ### queryEngineConfiguration 您可以設定下列類型的查詢引擎： #### Amazon Redshift 佈建 如果您的 Amazon Redshift 資料庫佈建在專用運算節點上，`queryEngineConfiguration` 欄位的值應為 [RedshiftQueryEngineConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftQueryEngineConfiguration.html)，格式如下： ``` { "type": "PROVISIONED", "provisionedConfiguration": { "clusterIdentifier": "string", "authConfiguration": [RedshiftProvisionedAuthConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftProvisionedAuthConfiguration.html) }, } ``` 在 `clusterIdentifier` 欄位中指定叢集的 ID。[RedshiftProvisionedAuthConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftProvisionedAuthConfiguration.html) 取決於您使用的授權類型。選取符合您授權方法的標籤： ------ #### [ IAM role ] 如果您使用 IAM 角色授權，則只需要在 [RedshiftProvisionedAuthConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftProvisionedAuthConfiguration.html) 中指定 `IAM` 類型，而不需要其他欄位。 ``` { "type": "IAM" } ``` ------ #### [ Temporary credentials user name ] 如果您使用資料庫使用者名稱授權，請將 `type` 指定為 `USERNAME`，並在 `RedshiftProvisionedAuthConfig` 中的 `databaseUser` 欄位中指定使用者名稱： ``` { "type": "USERNAME", "databaseUser": "string" } ``` ------ #### [ AWS Secrets Manager ] 如果您使用 授權 AWS Secrets Manager，請將 指定`type`為 ，`USERNAME_PASSWORD`並在 的 `usernamePasswordSecretArn` 欄位中指定秘密的 ARN`RedshiftProvisionedAuthConfig`： ``` { "type": "USERNAME_PASSWORD", "usernamePasswordSecretArn": "string" } ``` ------ #### Amazon Redshift Serverless 如果您使用的是 Amazon Redshift Serverless，`queryConfiguration` 欄位的值應為 [RedshiftQueryEngineConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftQueryEngineConfiguration.html)，格式如下： ``` { "type": "SERVERLESS", "serverlessConfiguration": { "workgroupArn": "string", "authConfiguration": } } ``` 在 `workgroupArn` 欄位中指定工作群組的 ARN。[RedshiftServerlessAuthConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftServerlessAuthConfiguration.html) 取決於您使用的授權類型。選取符合您授權方法的標籤： ------ #### [ IAM role ] 如果您使用 IAM 角色授權，則只需要在 `RedshiftServerlessAuthConfiguration` 中指定 `IAM` 類型，而不需要其他欄位。 ``` { "type": "IAM" } ``` ------ #### [ AWS Secrets Manager ] 如果您使用 授權 AWS Secrets Manager，請將 指定`type`為 ，`USERNAME_PASSWORD`並在 的 `usernamePasswordSecretArn` 欄位中指定秘密的 ARN`RedshiftServerlessAuthConfiguration`： ``` { "type": "USERNAME_PASSWORD", "usernamePasswordSecretArn": "string" } ``` ------ ### storageConfigurations 此欄位會對應至包含單一 [RedshiftQueryEngineStorageConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftQueryEngineStorageConfiguration.html) 的陣列，其格式取決於資料的存放位置。 #### AWS Glue Data Catalog 如果您的資料存放在 中 AWS Glue Data Catalog， `RedshiftQueryEngineStorageConfiguration`應該採用下列格式： ``` { "type": "AWS_DATA_CATALOG", "awsDataCatalogConfiguration": { "tableNames": ["string"] } } ``` 在 `tableNames` 要對應到的陣列中，新增您要將知識庫連線至的每個資料表的名稱。 **注意** 以[跨資料庫查詢](https://docs.aws.amazon.com/redshift/latest/dg/cross-database-overview.html) (`${databaseName}.${tableName}`) 中所述的模式輸入資料表名稱。您可以透過指定 `${databaseName.*}` 來包含所有資料表。 #### Amazon Redshift 資料庫 如果您的資料存放在 Amazon Redshift 資料庫中，`RedshiftQueryEngineStorageConfiguration` 應該採用下列格式： ``` { "type": "string", "redshiftConfiguration": { "databaseName": "string" } } ``` 在 `databaseName` 欄位中指定 Amazon Redshift 資料庫的名稱。 **注意** 以[跨資料庫查詢](https://docs.aws.amazon.com/redshift/latest/dg/cross-database-overview.html) (`${databaseName}.${tableName}`) 中所述的模式輸入資料表名稱。您可以透過指定 `${databaseName.*}` 來包含所有資料表。 如果您的資料庫是透過 Amazon SageMaker AI 資料湖倉掛載，則資料庫名稱的格式為 *\$1\$1db\$1@\$1\$1schema\$1*。 ### queryGenerationConfiguration 此欄位會對應至下列 [QueryGenerationConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationConfiguration.html)，您可以用來設定查詢資料的方式： ``` { "executionTimeoutSeconds": number, "generationContext": { "tables": [ { "name": "string", "description": "string", "inclusion": "string", "columns": [ { "name": "string", "description": "string", "inclusion": "string" }, ... ] }, ... ], "curatedQueries": [ { "naturalLanguage": "string", "sql": "string" }, ... ] } } ``` 如果您希望查詢逾時，請在 `executionTimeoutSeconds` 欄位中以秒為單位指定逾時持續時間。 `generationContext` 欄位會對應至 [QueryGenerationContext](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationContext.html) 物件，您可以在其中視需要設定下列任意數量的選項。 **重要** 如果您包含產生內容，查詢引擎會盡可能在產生 SQL 時嘗試套用內容。產生內容是非確定性的，僅用於改善模型準確性。為了確保準確性，請驗證產生的 SQL 查詢。 如需有關您可以包含的產生內容的資訊，請展開下列區段： #### 新增資料庫中資料表或資料欄的描述 若要改善查詢資料庫的 SQL 產生準確性，您可以提供資料表或資料欄的描述，以提供比簡短資料表或資料欄名稱更多的內容。您可以執行下列動作： + 若要新增資料表的描述，請在 `tables` 陣列中包含 [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html) 物件。在該物件中，指定 `name` 欄位中的資料表名稱和 `description` 欄位中的描述，如下列範例所示： ``` { "name": "database.schema.tableA", "description": "Description for Table A" } ``` + 若要新增資料欄的描述，請在 `tables` 陣列中包含 [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html) 物件。在該物件中，在 `name` 欄位中指定資料表的名稱，並包含 `columns` 欄位，該欄位會對應至 [QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html) 的陣列。在 `QueryGenerationColumn` 物件中，在 `name` 欄位中包含資料欄的名稱，並在 `description` 欄位中包含描述，如下列範例所示： ``` { "name": "database.schema.tableA", "columns": [ { "name": "Column A", "description": "Description for Column A" } ] } ``` + 您可以新增資料表和其中資料欄的描述，如下列範例所示： ``` { "name": "database.schema.tableA", "description": "Description for Table A", "columns": [ { "name": "columnA", "description": "Description for Column A" } ] } ``` **注意** 以[跨資料庫查詢](https://docs.aws.amazon.com/redshift/latest/dg/cross-database-overview.html)中所述的模式輸入資料表和資料欄名稱。如果您的資料庫位於 AWS Glue Data Catalog，則格式為 `awsdatacatalog.gluedatabase.table`。 #### 在資料庫中包含或排除資料表或資料欄 您可以使用 [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html) 和 [QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html) 物件中的 `inclusion` 欄位，建議在產生 SQL 時包含或排除的資料表或資料欄。您可以在 `inclusion` 欄位中指定下列其中一個值： + INCLUDE – 產生 SQL 時，只會包含您指定的資料表或資料欄作為內容。 + EXCLUDE – 產生 SQL 時，會將您指定的資料表或資料欄排除為內容。 您可以透過以下方式指定是否包含或排除資料表或資料欄： + 若要包含或排除資料表，請在 `tables` 陣列中包含 [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html) 物件。在該物件中，指定 `name` 欄位中資料表的名稱，以及是否要在 `inclusion` 欄位中包含或排除，如下列範例所示： ``` { "name": "database.schema.tableA", "inclusion": "EXCLUDE" } ``` 查詢引擎不會在用於產生 SQL 的其他內容中新增 `Table A`。 + 若要包含或排除資料欄，請在 `tables` 陣列中包含 [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html) 物件。在該物件中，在 `name` 欄位中指定資料表的名稱，並包含 `columns` 欄位，該欄位會對應至 [QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html) 的陣列。在 `QueryGenerationColumn` 物件中，在 `name` 欄位中包含資料欄的名稱，以及是否要在 `inclusion` 欄位中包含或排除，如下列範例所示： ``` { "name": "database.schema.tableA", "columns": [ { "name": "database.schema.tableA.columnA", "inclusion": "EXCLUDE" } ] } ``` 產生 SQL 時，SQL 產生會在內容的 `Table A` 中忽略 `Column A`。 + 您可以在指定包含或排除項目時合併資料表和資料欄，如下列範例所示： ``` { "name": "database.schema.tableA", "inclusion": "INCLUDE", "columns": [ { "name": "database.schema.tableA.columnA", "inclusion": "EXCLUDE" } ] } ``` SQL 產生包含 `Table A`，但在新增產生 SQL 的內容時會在其中排除 `Column A`。 **重要** 資料表和資料欄排除無法取代防護機制。這些資料表和資料欄包含和排除會用作模型在產生 SQL 時要考慮的其他內容。 #### 將自然語言的查詢引擎範例對應提供給 SQL 查詢 若要改善查詢引擎將使用者查詢轉換為 SQL 查詢的準確性，您可以在 [QueryGenerationContext](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationContext.html) 物件的 `curatedQueries` 欄位中提供範例，其會對應至 [CuratedQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CuratedQuery.html) 物件的陣列。每個物件皆包含下列欄位： + naturalLanguage – 自然語言查詢的範例。 + sql – 對應至自然語言查詢的 SQL 查詢。