翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 構造化データストアに接続してナレッジベースを構築する Amazon Bedrock ナレッジベースを使用すると、事前定義されたスキーマに準拠したデータを含む構造化データストアに接続できます。構造化データの例には、テーブルとデータベースなどがあります。Amazon Bedrock ナレッジベースは、サポートされている構造化データストアからデータを抽出するのに適した言語に、ユーザークエリを変換できます。その後、変換されたクエリを使用して、クエリに関連するデータを取得し、適切なレスポンスを生成できます。これにより、既存の構造化データを別の形式に変換したり、独自の SQL クエリを生成したりすることなく、直接使用できます。 ナレッジベースの設定後は、[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) オペレーションを使用してナレッジベースからデータを取得するクエリを送信したり、[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) オペレーションを使用して取得したデータからレスポンスを生成したりできます。これらのオペレーションでは、ユーザーのクエリをナレッジベースに接続された構造化データストアに適したクエリに背後で変換します。 [GenerateQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GenerateQuery.html) API オペレーションを使用して、データの取得に依存せずに、独立してクエリを変換することもできます。このオペレーションは、自然言語クエリを、クエリ対象のデータソースに適した SQL クエリに変換します。このオペレーションは単独で使用することも、ワークフローに挿入することもできます。 ナレッジベースを構造化データストアに接続するための前提条件とプロセスについて確認するには、各トピックを選択してください。 **Topics** + [構造化データストアを使用してナレッジベースを作成するためのクエリエンジンとアクセス許可を設定します](knowledge-base-prereq-structured.md) + [構造化データストアに接続してナレッジベースを作成する](knowledge-base-structured-create.md) + [構造化データストアを Amazon Bedrock ナレッジベースと同期する](kb-data-source-structured-sync-ingest.md) # 構造化データストアを使用してナレッジベースを作成するためのクエリエンジンとアクセス許可を設定します このトピックでは、ナレッジベースを構造化データストアに接続するときに必要なアクセス許可について説明します。Amazon Bedrock ナレッジベースを構造化データストアに接続する場合は、前提条件を満たす必要があります。一般的なアクセス許可要件を満たすには、「[ユーザーまたはロールがナレッジベースを作成および管理するためのアクセス許可を設定する](knowledge-base-prereq-permissions-general.md)」を参照してください。 **重要** 任意の SQL クエリを実行すると、Text-to-SQL アプリケーションにとってセキュリティリスクになる可能性があります。制限されたロール、読み取り専用データベース、サンドボックスの使用など、必要に応じて予防措置を講じることをお勧めします。 Amazon Bedrock ナレッジベースは、データストアにクエリを実行するためのクエリエンジンとして Amazon Redshift を使用します。クエリエンジンは構造化データストアからメタデータにアクセスし、そのメタデータを使用して SQL クエリを生成します。Amazon Redshift は、SQL を使用してデータウェアハウス、データベース、データレイク全体の構造化データを分析するデータウェアハウスサービスです。 ## Amazon Redshift クエリエンジンを作成する ユースケースに応じて Amazon Redshift Serverless または Amazon Redshift Provisioned を使用して、データウェアハウスのワークグループまたはクラスターに接続できます。Amazon Redshift エンジンがクエリできる基盤となるデータは、Amazon Redshift クラスターにネイティブに保存されるデータでも、デフォルト AWS Glue Data Catalog (Amazon S3 など) にあるデータでもかまいません。 クエリエンジンを既に作成している場合は、この前提条件をスキップできます。それ以外の場合は、次の手順を実行して Amazon Redshift Provisioned または Amazon Redshift Serverless のクエリエンジンを設定します。 **Amazon Redshift Provisioned でクエリエンジンを設定するには** 1. 「Amazon Redshift 入門ガイド」の「[ステップ 1: サンプルの Amazon Redshift クラスターを作成する](https://docs.aws.amazon.com/redshift/latest/gsg/new-user.html#rs-gsg-launch-sample-cluster)」に記載されている手順に従います。 1. クラスター ID を書き留めます。 1. (オプション) Amazon Redshift Provisioned クラスター の詳細については、「Amazon Redshift 管理ガイド」の「[Amazon Redshift でプロビジョニングされたクラスター](https://docs.aws.amazon.com/redshift/latest/mgmt/working-with-clusters.html)」を参照してください。 **Amazon Redshift Serverless でクエリエンジンを設定するには** 1. 「Amazon Redshift 入門ガイド」の「[Amazon Redshift Serverless によるデータウェアハウスの作成](https://docs.aws.amazon.com/redshift/latest/gsg/new-user-serverless.html#serverless-console-resource-creation)」の設定手順のみに従い、デフォルト設定で設定します。 1. ワークグループ ARN を書き留めます。 1. (オプション) Amazon Redshift Serverless ワークグループの詳細については、「Amazon Redshift 管理ガイド」の「[ワークグループと名前空間](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-workgroup-namespace.html)」を参照してください。 ## Amazon Redshift クエリエンジンのアクセス許可を設定する 選択した Amazon Redshift クエリエンジンに応じて、特定のアクセス許可を設定できます。設定するアクセス許可は、認証方法によって異なります。次の表は、さまざまなクエリエンジンに使用できる認証方法を示しています。 **** | 認証方法 | Amazon Redshift Provisioned | Amazon Redshift Serverless | | --- | --- | --- | | IAM | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | | データベースユーザー名 | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | ![\[Red circular icon with an X symbol, indicating cancellation or denial.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-no.png)なし | | AWS Secrets Manager | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | Amazon Bedrock ナレッジベースは、[サービスロール](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)を使用してナレッジベースを構造化データストアに接続し、これらのデータストアからデータを取得して、ユーザークエリとデータストアの構造に基づいて SQL クエリを生成します。 **注記** を使用してナレッジベース AWS マネジメントコンソール を作成する場合は、この前提条件をスキップできます。コンソールは、適切なアクセス許可を持つ Amazon Bedrock ナレッジベースサービスロールを作成します。 適切なアクセス許可を持つカスタム IAM サービスロールを作成するには、「[AWS のサービスにアクセス許可を委任するロールを作成する](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)」の手順に従い、[信頼関係](kb-permissions.md#kb-permissions-trust) で定義されている信頼関係をアタッチします。 次に、ナレッジベースが Amazon Redshift クエリエンジンとデータベースにアクセスするためのアクセス許可を追加します。ユースケースに該当するセクションを展開します。 ### クエリエンジンは Amazon Redshift Provisioned である カスタムサービスロールに次のポリシーをアタッチして、データにアクセスし、それを使用してクエリを生成できるようにします。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RedshiftDataAPIStatementPermissions", "Effect": "Allow", "Action": [ "redshift-data:GetStatementResult", "redshift-data:DescribeStatement", "redshift-data:CancelStatement" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "redshift-data:statement-owner-iam-userid": "${aws:userid}" } } }, { "Sid": "RedshiftDataAPIExecutePermissions", "Effect": "Allow", "Action": [ "redshift-data:ExecuteStatement" ], "Resource": [ "arn:aws:redshift:us-east-1:123456789012:cluster:${Cluster}" ] }, { "Sid": "SqlWorkbenchAccess", "Effect": "Allow", "Action": [ "sqlworkbench:GetSqlRecommendations", "sqlworkbench:PutSqlGenerationContext", "sqlworkbench:GetSqlGenerationContext", "sqlworkbench:DeleteSqlGenerationContext" ], "Resource": "*" }, { "Sid": "GenerateQueryAccess", "Effect": "Allow", "Action": [ "bedrock:GenerateQuery" ], "Resource": "*" } ] } ``` ------ また、サービスロールがクエリエンジンに対して認証できるようにするアクセス許可を追加する必要があります。セクションを展開すると、その方法のアクセス許可が表示されます。 ------ #### [ IAM ] サービスロールが IAM を使用して Amazon Redshift Provisioned クエリエンジンに対して認証できるようにするには、カスタムサービスロールに次のポリシーをアタッチします。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "GetCredentialsWithFederatedIAMCredentials", "Effect": "Allow", "Action": "redshift:GetClusterCredentialsWithIAM", "Resource": [ "arn:aws:redshift:us-east-1:123456789012:dbname:Cluster/database" ] } ] } ``` ------ ------ #### [ Database user ] Amazon Redshift データベースユーザーとして認証するには、サービスロールに次のポリシーをアタッチします。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "GetCredentialsWithClusterCredentials", "Effect": "Allow", "Action": [ "redshift:GetClusterCredentials" ], "Resource": [ "arn:aws:redshift:us-east-1:123456789012:dbuser:${cluster}/${dbuser}", "arn:aws:redshift:us-east-1:123456789012:dbname:${cluster}/${database}" ] } ] } ``` ------ ------ #### [ AWS Secrets Manager ] サービスロールが AWS Secrets Manager シークレットを使用して Amazon Redshift でプロビジョニングされたクエリエンジンに対して認証できるようにするには、次の手順を実行します。 + 次のポリシーをロールにアタッチします。 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "GetSecretPermissions", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:${region}:${account}:secret:${secretName}" ] } ] } ``` ------ ### クエリエンジンが Amazon Redshift Serverless である アタッチするアクセス許可は、認証方法によって異なります。セクションを展開して、方法のアクセス許可を表示します。 ------ #### [ IAM ] サービスロールが IAM を使用して Amazon Redshift Serverless クエリエンジンに対して認証できるようにするには、カスタムサービスロールに次のポリシーをアタッチします。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RedshiftServerlessGetCredentials", "Effect": "Allow", "Action": "redshift-serverless:GetCredentials", "Resource": [ "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/WorkgroupId" ] } ] } ``` ------ ------ #### [ AWS Secrets Manager ] サービスロールが AWS Secrets Manager シークレットを使用して Amazon Redshift でプロビジョニングされたクエリエンジンに対して認証できるようにするには、次の手順を実行します。 + 次のポリシーをロールにアタッチします。 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "GetSecretPermissions", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:${region}:${account}:secret:${secretName}" ] } ] } ``` ------ ## データストアへのアクセスをナレッジベースサービスロールに許可する 次の[サポートされている構造化データストア](knowledge-base-structured-create.md)のいずれかにデータが保存されていることを確認します。 + Amazon Redshift + AWS Glue Data Catalog (AWS Lake Formation) 次の表は、データストアに応じて、クエリエンジンで使用できる認証方法をまとめたものです。 **** | 認証方法 | Amazon Redshift | AWS Glue Data Catalog (AWS Lake Formation) | | --- | --- | --- | | IAM | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | | データベースユーザー名 | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | ![\[Red circular icon with an X symbol, indicating cancellation or denial.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-no.png)なし | | AWS Secrets Manager | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-yes.png) あり | ![\[Red circular icon with an X symbol, indicating cancellation or denial.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/icon-no.png)なし | Amazon Bedrock ナレッジベースサービスロールがデータストアにアクセスし、それに基づいてクエリを生成するためのアクセス許可を設定する方法については、データストアがあるサービスに対応するセクションを展開します。 ### Amazon Redshift Amazon Bedrock ナレッジベースサービスロールに Amazon Redshift データベースへのアクセスを許可するには、[Amazon Redshift query editor v2](https://docs.aws.amazon.com/redshift/latest/mgmt/query-editor-v2.html) を使用して、次の SQL コマンドを実行します。 1. (IAM で認証し、ユーザーがデータベース用にまだ作成されていない場合) 次のコマンドを実行します。このコマンドでは、[CREATE USER](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_USER.html) を使用してデータベースユーザーを作成し、IAM による認証を許可します。*\$1\$1service-role\$1* を、作成したカスタム Amazon Bedrock ナレッジベースサービスロールの名前に置き換えます。 ``` CREATE USER "IAMR:${service-role}" WITH PASSWORD DISABLE; ``` **重要** コンソールで作成した Amazon Bedrock ナレッジベースサービスロールを使用し、このステップを実行する前に[データストアを同期](kb-data-source-structured-sync-ingest.md)すると、ユーザーは自動的に作成されますが、データストアへのアクセス許可がユーザーに付与されていないため、同期は失敗します。同期する前に、次のステップを実行する必要があります。 1. [GRANT](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html) コマンドを実行して、データベースから情報を取得するアクセス許可を ID に付与します。 ------ #### [ IAM ] ``` GRANT SELECT ON ALL TABLES IN SCHEMA ${schemaName} TO "IAMR:${serviceRole}"; ``` ------ #### [ Database user ] ``` GRANT SELECT ON ALL TABLES IN SCHEMA ${schemaName} TO "${dbUser}"; ``` ------ #### [ AWS Secrets Manager username ] ``` GRANT SELECT ON ALL TABLES IN SCHEMA ${schemaName} TO "${secretsUsername}"; ``` ------ **重要** `CREATE`、`UPDATE`、または `DELETE` アクセスを付与しないでください。これらのアクションを付与すると、データの意図しない変更につながる可能性があります。 アクセス可能なテーブルをよりきめ細かく制御するには、`ALL TABLES` の特定のテーブル名を *\$1\$1schemaName\$1**\$1\$1tableName\$1* という表記に置き換えます。この表記の詳細については、「[データベース間でのクエリ](https://docs.aws.amazon.com/redshift/latest/dg/cross-database-overview.html)」の「**オブジェクトをクエリします**」セクションを参照してください。 ------ #### [ IAM ] ``` GRANT SELECT ON ${schemaName}.${tableName} TO "IAMR:${serviceRole}"; ``` ------ #### [ Database user ] ``` GRANT SELECT ON ${schemaName}.${tableName} TO "${dbUser}"; ``` ------ #### [ AWS Secrets Manager username ] ``` GRANT SELECT ON ${schemaName}.${tableName} TO "${secretsUsername}"; ``` ------ 1. Redshift データベースで新しいスキーマを作成した場合は、次のコマンドを実行して、新しいスキーマに対する ID アクセス許可を付与します。 ``` GRANT USAGE ON SCHEMA ${schemaName} TO "IAMR:${serviceRole}"; ``` ### AWS Glue Data Catalog Amazon Bedrock ナレッジベースサービスロールに AWS Glue Data Catalog データストアへのアクセスを許可するには、[Amazon Redshift クエリエディタ v2](https://docs.aws.amazon.com/redshift/latest/mgmt/query-editor-v2.html) を使用して、次の SQL コマンドを実行します。 1. 次のコマンドを実行します。このコマンドは [CREATE USER](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_USER.html) を使用してデータベースユーザーを作成し、IAM による認証を許可します。*\$1\$1service-role\$1* を、作成したカスタム Amazon Bedrock ナレッジベースサービスロールの名前に置き換えます。 ``` CREATE USER "IAMR:${service-role}" WITH PASSWORD DISABLE; ``` **重要** コンソールで作成した Amazon Bedrock ナレッジベースサービスロールを使用し、このステップを実行する前に[データストアを同期](kb-data-source-structured-sync-ingest.md)すると、ユーザーは自動的に作成されますが、データストアへのアクセス許可がユーザーに付与されていないため、同期は失敗します。同期する前に、次のステップを実行する必要があります。 1. 次の [GRANT](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html) コマンドを実行して、データベースから情報を取得するアクセス許可をサービスロールに付与します。 ``` GRANT USAGE ON DATABASE awsdatacatalog TO "IAMR:${serviceRole}"; ``` **重要** `CREATE`、`UPDATE`、または `DELETE` アクセスを付与しないでください。これらのアクションを付与すると、データの意図しない変更につながる可能性があります。 1. AWS Glue Data Catalog データベースへのアクセスを許可するには、サービスロールに次のアクセス許可をアタッチします。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "glue:GetDatabases", "glue:GetDatabase", "glue:GetTables", "glue:GetTable", "glue:GetPartitions", "glue:GetPartition", "glue:SearchTables" ], "Resource": [ "arn:aws:glue:us-east-1:123456789012:table/${DatabaseName}/${TableName}", "arn:aws:glue:us-east-1:123456789012:database/${DatabaseName}", "arn:aws:glue:us-east-1:123456789012:catalog" ] } ] } ``` ------ 1. 以下を実行して AWS Lake Formation 、 (Lake Formation とその Amazon Redshift との関係の詳細については、[「Redshift のデータソース](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source.html)」を参照) を通じてサービスロールにアクセス許可を付与します。 1. にサインインし AWS マネジメントコンソール、[https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/) で Lake Formation コンソールを開きます。 1. 左側のナビゲーションペインで **[データのアクセス許可]**を選択します。 1. Amazon Bedrock ナレッジベースに使用しているサービスロールにアクセス許可を付与します。 1. データベースとテーブルの **Describe** アクセス許可と **Select** アクセス許可を付与します。 1. 使用するデータソースによっては AWS Glue Data Catalog、そのデータソースにアクセスするためのアクセス許可を追加する必要がある場合があります (詳細については、[AWS Glue 「他の への依存関係 AWS のサービス](https://docs.aws.amazon.com/glue/latest/dg/dependency-on-other-services.html)」を参照してください）。例えば、データソースが Amazon S3 の場所にある場合は、上記のポリシーに次のステートメントを追加する必要があります。 ``` { "Sid": "Statement1", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::${BucketName}", "arn:aws:s3:::${BucketName}/*" ] } ``` 1. (オプション) AWS KMS を使用して Amazon S3 または のデータを暗号化する場合は AWS Glue Data Catalog、KMS キーのデータを復号化するためのアクセス許可をロールに追加する必要があります。 ``` { "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:${Region}:${Account}:key/{KmsId}", "arn:aws:kms:${Region}:${Account}:key/{KmsId}" ], "Effect": "Allow" } ``` # 構造化データストアに接続してナレッジベースを作成する ナレッジベースを構造化データストアに接続するには、次のコンポーネントを指定します。 + **クエリエンジンの設定** 生成された 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. Amazon Bedrock コンソールを使用するアクセス許可を持つ IAM ID AWS マネジメントコンソール を使用して にサインインします。Amazon Bedrock コンソール ([https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)) を開きます。 1. 左側のナビゲーションペインで **[ナレッジベース]** を選択します。 1. **[ナレッジベース]** セクションで、**[作成]** を選択し、次に **[構造化データストアを含むナレッジベース]**を選択します。 1. ナレッジベースに以下の詳細を設定します。 1. (オプション) ナレッジベースのデフォルトの名前を変更し、説明を入力します。 1. データストアからデータを取得するために使用するクエリエンジンを選択します。 1. このナレッジベースを作成して管理するための適切なアクセス許可を持つ IAM サービスロールを選択します。Amazon Bedrock にサービスロールを作成させることも、作成したカスタムロールを選択することもできます。カスタムロールの作成方法の詳細については、「[構造化データストアを使用してナレッジベースを作成するためのクエリエンジンとアクセス許可を設定します](knowledge-base-prereq-structured.md)」を参照してください。 1. (オプション) ナレッジベースに関連付けるタグを追加します。詳細については、「[Amazon Bedrock リソースにタグ付け](tagging.md)」を参照してください。 1. **[Next]** (次へ) を選択します。 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 フィールドを含めます。 | 次のフィールドはオプションです。 **** | フィールド | 使用アイテム | | --- | --- | | 説明 | ナレッジベースの説明を含めるため。 | | clientToken | API リクエストが 1 回だけ完了するようにします。詳細については、「[べき等性の確保](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)」を参照してください。 | | タグ | タグをエイリアスに関連付ける場合に指定します。詳細については、「[Amazon Bedrock リソースにタグ付け](tagging.md)」を参照してください。 | `SQLKnowledgeBaseConfiguration` は、使用するクエリエンジンによって異なります。Amazon Redshift の場合、`type` フィールドを `REDSHIFT` と指定し、[RedshiftConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftConfiguration.html) にマッピングされる `redshiftConfiguration` フィールドを含めます。[RedshiftConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftConfiguration.html) では、次のフィールドを設定します。 ### queryEngineConfiguration 以下のタイプのクエリエンジンを設定できます。 #### Amazon Redshift Provisioned 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 Lakehouse を介してマウントされている場合、データベース名は *\$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` フィールドにテーブルの名前を指定し、[QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html) の配列にマッピングされる `columns` フィールドを含めます。`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` フィールドにテーブルの名前を指定し、[QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html) の配列にマッピングされる `columns` フィールドを含めます。`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 クエリに変換する際のクエリエンジンの精度を向上させるには、[CuratedQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CuratedQuery.html) オブジェクトの配列にマッピングされる [QueryGenerationContext](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationContext.html) オブジェクトの `curatedQueries` フィールドに例を指定できます。各オブジェクトには、以下のフィールドが含まれています。 + naturalLanguage – 自然言語でのクエリの例 + sql – 自然言語クエリに対応する SQL クエリ # 構造化データストアを Amazon Bedrock ナレッジベースと同期する ナレッジベースを構造化データストアに接続したら、データを取得できるように、同期を実行してメタデータ取り込みプロセスを開始します。メタデータにより、Amazon Bedrock ナレッジベースはユーザーのプロンプトを接続されたデータベースへのクエリに変換できます。 データベーススキーマを変更する都度、変更を同期する必要があります。 メタデータをナレッジベースに取り込み、最新のデータと同期する方法を確認するには、使用する方法のタブを選択して、手順に従います。 ------ #### [ Console ] **データをナレッジベースに取り込み、最新のデータと同期するには** 1. Amazon Bedrock コンソール ([https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/)) を開きます。 1. 左側のナビゲーションペインの **[ナレッジベース]** でナレッジベースを選択します。 1. **[データソース]** セクションで **[同期]** を選択して、メタデータデータの取り込みを開始します。同期中のデータソースを停止するには、**[停止]** を選択します。停止できるのは、同期中のデータソースだけです。**[同期]** をもう一度選択すると、残りのデータを取り込むことができます。 1. データインジェストが正常に完了すると、緑色の成功バナーが表示されます。 1. データソースを選択して、そのデータソースの **[同期履歴]** を表示することができます。**[警告を表示]** を選択すると、データインジェストジョブが失敗した理由を確認できます。 ------ #### [ API ] ナレッジベースにデータを取り込み、最新のデータと同期するには、[Amazon Bedrock エージェントのビルドタイムエンドポイント](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)で [StartIngestionJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_StartIngestionJob.html) リクエストを送信します。 取り込みジョブのステータスを追跡するには、レスポンスで返された `ingestionJobId` を使用して、[Amazon Bedrock エージェントのビルドタイムエンドポイント](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)で [GetIngestionJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetIngestionJob.html) リクエストを送信します。 [Amazon Bedrock エージェントのビルドタイムエンドポイント](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)で [ListIngestionJobs](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ListIngestionJobs.html) リクエストを送信すると、データソースのすべての取り込みジョブに関する情報を確認することもできます。 現在実行中のデータインジェストジョブを停止するには、[Amazon Bedrock エージェントのビルドタイムエンドポイント](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)を使用して [StopIngestionJobs](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_StopIngestionJob.html) リクエストを送信します。準備ができたら、`StartIngestionJob` リクエストを再送信して、残りのデータを取り込むことができます。 ------ **重要** コンソールで作成した Amazon Bedrock ナレッジベースのサービスロールを使用する場合、使用する認証ロールにデータベースへのアクセス権を付与する前にデータストアを同期すると、データストアへのアクセス許可がユーザーに付与されていないため、同期は失敗します。データストアにアクセスするためのアクセス許可をロールに付与する方法については、「[データストアへのアクセスをナレッジベースサービスロールに許可する](knowledge-base-prereq-structured.md#knowledge-base-prereq-structured-db-access)」を参照してください。