As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Criar uma base de conhecimento conectando-se a um armazenamento de dados estruturados As Bases de Conhecimento do Amazon Bedrock permitem que você se conecte a armazenamentos de dados estruturados, que contêm dados que estão em conformidade com um esquema predefinido. Exemplos de dados estruturados incluem tabelas e bancos de dados. As Bases de Conhecimento do Amazon Bedrock podem converter consultas de usuários em uma linguagem adequada para extrair dados de armazenamentos de dados estruturados compatíveis. Em seguida, elas podem usar a consulta convertida para recuperar dados relevantes para a consulta e gerar respostas apropriadas. Isso permite que você use os dados estruturados existentes diretamente sem precisar convertê-los em um formato diferente ou gerar suas próprias consultas SQL. Depois de configurar sua base de conhecimento, você pode enviar consultas para recuperar dados dela por meio da operação [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) ou gerar respostas com base nos dados recuperados por meio da operação [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). Essas operações convertem subjacentemente as consultas do usuário em consultas apropriadas ao armazenamento de dados estruturados conectado à base de conhecimento. Você também tem a opção de converter consultas independentemente da recuperação de dados usando a operação de API [GenerateQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GenerateQuery.html). Essa operação converte consultas em linguagem natural em consultas SQL apropriadas à fonte de dados que está sendo consultada. É possível usar essa operação de forma independente e inseri-la em seu fluxo de trabalho. Selecione um tópico para saber mais sobre os pré-requisitos e o processo para conectar a base de conhecimento a um armazenamento de dados estruturados. **Topics** + [Configurar um mecanismo de consulta e permissões para criar uma base de conhecimento](knowledge-base-prereq-structured.md) + [Criar uma base de conhecimento conectando-se a um armazenamento de dados estruturados](knowledge-base-structured-create.md) + [Sincronizar o armazenamento de dados estruturados com sua base de conhecimento do Amazon Bedrock](kb-data-source-structured-sync-ingest.md) # Configurar um mecanismo de consulta e permissões para criar uma base de conhecimento Este tópico descreve as permissões das quais você precisa ao conectar sua base de conhecimento a um armazenamento de dados estruturados. Se você planeja conectar uma base de conhecimento do Amazon Bedrock a um armazenamento de dados estruturados, precisa cumprir os pré-requisitos. Para atender aos requisitos gerais de permissão, consulte [Configurar permissões para um usuário ou perfil para criar e gerenciar bases de conhecimento](knowledge-base-prereq-permissions-general.md). **Importante** A execução de consultas SQL arbitrárias pode ser um risco de segurança para qualquer aplicativo. Text-to-SQL Recomendamos que você tome medidas preventivas conforme necessário, como usar perfis restritos, bancos de dados somente para leitura e sandbox. As Bases de Conhecimento do Amazon Bedrock usam o Amazon Redshift como mecanismos de consulta para consultar seu datastore. Um mecanismo de consulta acessa metadados de um armazenamento de dados estruturados e usa os metadados para ajudar a gerar consultas SQL. O Amazon Redshift é um serviço de data warehouse que usa SQL para analisar dados estruturados em data warehouses, bancos de dados e data lakes. ## Criar um mecanismo de consulta do Amazon Redshift Você pode usar o Amazon Redshift sem servidor ou o Amazon Redshift provisionado, dependendo do seu caso de uso, e conectar-se a grupos de trabalho ou clusters para seu data warehouse. Os dados subjacentes que o mecanismo do Amazon Redshift pode consultar podem ser dados armazenados nativamente em clusters do Amazon Redshift ou dados localizados abaixo do padrão AWS Glue Data Catalog (como no Amazon S3, entre outros). Se já tiver criado um mecanismo de consulta, você poderá ignorar esse pré-requisito. Do contrário, execute as seguintes etapas para configurar o mecanismo de consulta do Amazon Redshift provisionado ou do Amazon Redshift sem servidor: **Como configurar um mecanismo de consulta no Amazon Redshift provisionado** 1. Siga o procedimento em [Etapa 1: Criar um cluster de amostra do Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/gsg/new-user.html#rs-gsg-launch-sample-cluster) no “Guia de conceitos básicos do Amazon Redshift” para criar um cluster. 1. Anote o ID do cluster. 1. (Opcional) Para ter mais informações sobre clusters provisionados do Amazon Redshift, consulte [Cluster provisionados do Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/working-with-clusters.html) no “Guia de gerenciamento de clusters do Amazon Redshift”. **Como configurar um mecanismo de consulta no Amazon Redshift sem servidor** 1. Siga somente o procedimento de configuração em [Criar um data warehouse com o Amazon Redshift sem servidor](https://docs.aws.amazon.com/redshift/latest/gsg/new-user-serverless.html#serverless-console-resource-creation) no “Guia de conceitos básicos do Amazon Redshift” e configure-o com as configurações padrão. 1. Anote o ARN do grupo de trabalho. 1. (Opcional) Para ter mais informações sobre grupos de trabalho do Amazon Redshift sem servidor, consulte [Grupos de trabalho e namespaces](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-workgroup-namespace.html) no “Guia de gerenciamento do Amazon Redshift”. ## Configurar permissões do mecanismo de consulta do Amazon Redshift Dependendo do mecanismo de consulta do Amazon Redshift que escolher, você poderá configurar determinadas permissões. As permissões que você configura dependem do método de autenticação. A seguinte tabela mostra os métodos de autenticação que podem ser usados para diferentes mecanismos de consulta: **** | Método de autenticação | Amazon Redshift provisionado | Amazon Redshift Sem Servidor | | --- | --- | --- | | IAM | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | | Nome de usuário do banco de dados | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | ![\[Red circular icon with an X symbol, indicating cancellation or denial.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-no.png)Não | | AWS Secrets Manager | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | As Bases de Conhecimento do Amazon Bedrock usam um [perfil de serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) para conectar bases de conhecimento a armazenamentos de dados estruturados, recuperar dados desses armazenamentos de dados e gerar consultas SQL com base nas consultas do usuário e na estrutura dos datastores. **nota** Se você planeja usar o Console de gerenciamento da AWS para criar uma base de conhecimento, pode ignorar esse pré-requisito. O console criará um perfil de serviço das Bases de Conhecimento do Amazon Bedrock com as permissões adequadas. Para criar um perfil de serviço personalizado do IAM com as permissões adequadas, siga as etapas em [Criar um perfil para delegar permissões a um AWS service (Serviço da AWS)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) e anexar a relação de confiança definida em [Relação de confiança](kb-permissions.md#kb-permissions-trust). Em seguida, adicione permissões para que a base de conhecimento acesse seu mecanismo de consulta e bancos de dados do Amazon Redshift. Expanda a seção que se aplica ao seu caso de uso: ### Seu mecanismo de consulta é provisionado pelo Amazon Redshift Anexe a seguinte política ao perfil de serviço personalizado para permitir que ele acesse seus dados e gere consultas usando esses dados: ------ #### [ 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": "*" } ] } ``` ------ Também é necessário adicionar permissões para possibilitar que o perfil de serviço se autentique no mecanismo de consulta. Expanda uma seção para ver as permissões do respectivo método. ------ #### [ IAM ] Para permitir que o perfil de serviço se autentique em seu mecanismo de consulta provisionado do Amazon Redshift com o IAM, anexe a seguinte política ao perfil de serviço personalizado: ------ #### [ 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 ] Para se autenticar como usuário do banco de dados do Amazon Redshift, anexe a seguinte política ao perfil de serviço: ------ #### [ 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 ] Para permitir que sua função de serviço se autentique em seu mecanismo de consulta provisionado do Amazon Redshift com AWS Secrets Manager um segredo, faça o seguinte: + Anexe a seguinte política ao perfil: ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "GetSecretPermissions", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:${region}:${account}:secret:${secretName}" ] } ] } ``` ------ ### Seu mecanismo de consulta é o Amazon Redshift sem servidor As permissões para anexar dependem do método de autenticação. Expanda uma seção para ver as permissões do método em questão. ------ #### [ IAM ] Para permitir que o perfil de serviço se autentique em seu mecanismo de consulta do Amazon Redshift sem servidor com o IAM, anexe a seguinte política ao perfil de serviço personalizado: ------ #### [ 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 ] Para permitir que sua função de serviço se autentique em seu mecanismo de consulta provisionado do Amazon Redshift com AWS Secrets Manager um segredo, faça o seguinte: + Anexe a seguinte política ao perfil: ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "GetSecretPermissions", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:${region}:${account}:secret:${secretName}" ] } ] } ``` ------ ## Permitir que o perfil de serviço da base de conhecimento acesse seu datastore Seus dados devem estar armazenados em um dos seguintes [armazenamentos de dados estruturados compatíveis](knowledge-base-structured-create.md): + banco de dados de origem + AWS Glue Data Catalog (AWS Lake Formation) A seguinte tabela resume os métodos de autenticação disponíveis para o mecanismo de consulta, dependendo do datastore: **** | Método de autenticação | banco de dados de origem | AWS Glue Data Catalog (AWS Lake Formation) | | --- | --- | --- | | IAM | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | | Nome de usuário do banco de dados | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | ![\[Red circular icon with an X symbol, indicating cancellation or denial.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-no.png)Não | | AWS Secrets Manager | ![\[Green circular icon with a white checkmark symbol inside.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-yes.png)Sim | ![\[Red circular icon with an X symbol, indicating cancellation or denial.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/icon-no.png)Não | Para saber como configurar permissões para que o perfil de serviço das Bases de Conhecimento do Amazon Bedrock acesse o datastore e gere consultas com base nele, expanda a seção que corresponde ao serviço em que o datastore está: ### banco de dados de origem Para conceder ao perfil de serviço das Bases de Conhecimento do Amazon Bedrock acesso ao banco de dados do Amazon Redshift, use o [Editor de consultas V2 do Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/query-editor-v2.html) e execute os seguintes comandos SQL: 1. (Se você se autenticar com o IAM e um usuário ainda não tiver sido criado para seu banco de dados) Execute o comando a seguir, que usa [CREATE USER para criar um usuário](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_USER.html) de banco de dados e permitir que ele se autentique por meio do IAM, *\$1\$1service-role\$1* substituindo-o pelo nome da função de serviço personalizada do Amazon Bedrock Knowledge Bases que você criou: ``` CREATE USER "IAMR:${service-role}" WITH PASSWORD DISABLE; ``` **Importante** Se você usar o perfil de serviço das Bases de Conhecimento do Amazon Bedrock criado para você no console e depois [sincronizar o datastore](kb-data-source-structured-sync-ingest.md) antes de executar essa etapa, o usuário será criado para você, mas a sincronização falhará porque o usuário não recebeu permissões para acessar seu datastore. Você deve executar a etapa a seguir antes de sincronizar. 1. Conceda permissões de identidade para recuperar informações do banco de dados executando o comando [GRANT](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html). ------ #### [ 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}"; ``` ------ **Importante** Não acesso para `CREATE`, `UPDATE` ou `DELETE`. Ao conceder essas ações, seus poderão ser modificados de maneira não desejada. Para um controle mais refinado das tabelas que podem ser acessadas, você pode substituir nomes `ALL TABLES` específicos de tabelas pela seguinte notação:. *\$1\$1schemaName\$1* *\$1\$1tableName\$1* Para ter mais informações sobre essa notação, consulte a seção **Objetos de consulta** em [Consultas entre bancos de dados](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. Se você criou um esquema no banco de dados do Redshift, execute o comando a seguir para conceder permissões de identidade em relação ao novo esquema. ``` GRANT USAGE ON SCHEMA ${schemaName} TO "IAMR:${serviceRole}"; ``` ### AWS Glue Data Catalog Para conceder à sua função de serviço do Amazon Bedrock Knowledge Bases acesso ao seu armazenamento de AWS Glue Data Catalog dados, use o [editor de consultas v2 do Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/query-editor-v2.html) e execute os seguintes comandos SQL: 1. Execute o comando a seguir, que usa [CREATE USER para criar um usuário](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_USER.html) de banco de dados e permitir que ele se autentique por meio do IAM, *\$1\$1service-role\$1* substituindo-o pelo nome da função de serviço personalizada do Amazon Bedrock Knowledge Bases que você criou: ``` CREATE USER "IAMR:${service-role}" WITH PASSWORD DISABLE; ``` **Importante** Se você usar o perfil de serviço das Bases de Conhecimento do Amazon Bedrock criado para você no console e depois [sincronizar o datastore](kb-data-source-structured-sync-ingest.md) antes de executar essa etapa, o usuário será criado para você, mas a sincronização falhará porque o usuário não recebeu permissões para acessar seu datastore. Você deve executar a etapa a seguir antes de sincronizar. 1. Conceda ao perfil de serviço permissões para recuperar informações do banco de dados executando o seguinte comando [GRANT](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html): ``` GRANT USAGE ON DATABASE awsdatacatalog TO "IAMR:${serviceRole}"; ``` **Importante** Não acesso para `CREATE`, `UPDATE` ou `DELETE`. Ao conceder essas ações, seus poderão ser modificados de maneira não desejada. 1. Para permitir o acesso aos seus AWS Glue Data Catalog bancos de dados, anexe as seguintes permissões à função de serviço: ------ #### [ 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. Conceda permissões para sua função de serviço por meio AWS Lake Formation (para saber mais sobre o Lake Formation e seu relacionamento com o Amazon Redshift, consulte [Fontes de dados para Redshift) fazendo](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source.html) o seguinte: 1. Faça login no Console de gerenciamento da AWS, e abra o console do Lake Formation em [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/). 1. Selecione **Permissões de dados** no painel de navegação à esquerda. 1. Conceda permissões ao perfil de serviço que você está usando para as Bases de Conhecimento do Amazon Bedrock. 1. Conceda as permissões **Descrever** e **Selecionar** para seus bancos de dados e tabelas. 1. Dependendo da fonte de dados em que você usa AWS Glue Data Catalog, talvez seja necessário adicionar permissões para acessar essa fonte de dados (para obter mais informações, consulte [AWS Glue dependência de outras Serviços da AWS](https://docs.aws.amazon.com/glue/latest/dg/dependency-on-other-services.html)). Por exemplo, se a fonte de dados estiver em um local do Amazon S3, você precisará adicionar a declaração a seguir à política acima. ``` { "Sid": "Statement1", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::${BucketName}", "arn:aws:s3:::${BucketName}/*" ] } ``` 1. (Opcional) Se você usa AWS KMS para criptografar os dados no Amazon S3 AWS Glue Data Catalog ou, então você precisa adicionar permissões à função para descriptografar os dados na chave KMS. ``` { "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:${Region}:${Account}:key/{KmsId}", "arn:aws:kms:${Region}:${Account}:key/{KmsId}" ], "Effect": "Allow" } ``` # Criar uma base de conhecimento conectando-se a um armazenamento de dados estruturados Para conectar uma base de conhecimento a um armazenamento de dados estruturados, especifique os seguintes componentes: + **Configuração do mecanismo de consulta** A configuração do serviço de computação que executará as consultas SQL geradas. O mecanismo de consulta é usado para converter consultas de usuários em linguagem natural em consultas SQL que podem ser usadas para extrair dados do datastore. É possível escolher o Amazon Redshift como mecanismo de consulta. Ao escolher essa configuração, é necessário especificar: + Os metadados da conexão computacional, como o ID do cluster ou o ARN do grupo de trabalho, dependendo do mecanismo de consulta escolhido. + O método de autenticação para usar o mecanismo de consulta, que pode ser usar uma função de serviço do IAM com as permissões apropriadas, um usuário do banco de dados do mecanismo de consulta ou um AWS Secrets Manager segredo vinculado às suas credenciais do banco de dados. + **Configuração de armazenamento** A configuração do datastore que contém seus dados. Você pode se conectar ao Amazon Redshift Provisioned ou ao Amazon Redshift Serverless e usar o Amazon Redshift ou como seu armazenamento de dados. AWS Glue Data Catalog + **(Opcional) Configurações de consulta** É possível usar configurações de consulta opcionais para melhorar a precisão da geração de SQL: + **Tempo máximo de consulta**: o tempo após o qual a consulta expira. + **Descrições**: esse campo fornece metadados ou informações complementares sobre tabelas ou colunas. É possível incluir descrições de tabelas ou colunas, notas de uso ou quaisquer atributos adicionais. As descrições que você adiciona podem melhorar a geração de consultas SQL ao fornecer contexto e informações adicionais sobre a estrutura de tabelas ou colunas. + **Inclusões e exclusões**: especifica um conjunto de tabelas ou colunas a serem incluídas ou excluídas para geração de SQL. Esse campo é crucial quando você quer limitar o escopo das consultas SQL a um subconjunto definido de tabelas ou colunas disponíveis. Essa opção pode ajudar a otimizar o processo de geração reduzindo referências desnecessárias de tabelas ou colunas. Se você especificar inclusões, todas as outras tabelas e colunas serão ignoradas. Se você especificar exclusões, as tabelas e colunas especificadas serão ignoradas. **nota** As inclusões e exclusões não substituem as barreiras de proteção e se destinam apenas a melhorar a precisão do modelo. + **Consultas selecionadas**: um conjunto de exemplos predefinidos de perguntas e respostas. As perguntas são escritas como consultas em linguagem natural (NLQ) e as respostas são a consulta SQL correspondente. Esses exemplos ajudam o processo de geração de SQL fornecendo exemplos dos tipos de consulta que devem ser gerados. Eles servem como pontos de referência para melhorar a precisão e a relevância das saídas SQL generativas. Expanda a seção que corresponde ao seu caso de uso: ## Usar o console Para se conectar a um armazenamento de dados estruturado usando o Console de gerenciamento da AWS, faça o seguinte: 1. Faça login no Console de gerenciamento da AWS com uma identidade do IAM que tenha permissões para usar o console Amazon Bedrock. Em seguida, abra o console Amazon Bedrock em [https://console.aws.amazon.com/bedrock.](https://console.aws.amazon.com/bedrock) 1. No painel de navegação à esquerda, selecione **Bases de conhecimento**. 1. Na seção **Bases de conhecimento**, escolha **Criar** e selecione **Base de conhecimento com armazenamento de dados estruturados**. 1. Configure os seguintes detalhes para a base de conhecimento: 1. (Opcional) Altere o nome padrão e dê uma descrição para a base de conhecimento. 1. Selecione o mecanismo de consulta a ser usado para recuperar dados do datastore. 1. Escolha um perfil de serviço do IAM com as permissões adequadas para criar e gerenciar essa base de conhecimento. Você pode permitir que o Amazon Bedrock crie o perfil de serviço ou escolher um perfil personalizado criado por você. Para ter mais informações sobre como criar um perfil personalizado, consulte [Configurar um mecanismo de consulta e permissões para criar uma base de conhecimento](knowledge-base-prereq-structured.md). 1. (Opcional) Adicione tags para associá-las à base de conhecimento. Para obter mais informações, consulte [Marcação de recursos do Amazon Bedrock](tagging.md). 1. Escolha **Próximo**. 1. Configure seu mecanismo de consulta: 1. Selecione o serviço no qual você criou um cluster ou grupo de trabalho. Escolha o cluster ou o grupo de trabalho a ser usado. 1. Selecione o método de autenticação e preencha os campos necessários. 1. Selecione o datastore no qual seus metadados devem ser armazenados. Em seguida, escolha ou digite o nome do banco de dados. 1. (Opcional) Modifique as configurações de consulta conforme necessário. Consulte o início deste tópico para ter mais informações sobre diferentes configurações. 1. Escolha **Próximo**. 1. Analise as configurações da base de conhecimento e edite todas as seções conforme necessário. Confirme para criar sua base de conhecimento. ## Usar a API Para se conectar a um armazenamento de dados estruturado usando a API do Amazon Bedrock, envie uma [CreateKnowledgeBase](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateKnowledgeBase.html)solicitação com um [endpoint de tempo de construção do Agents for Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) com o seguinte corpo de solicitação geral: ``` { "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" } } ``` Os campos a seguir são obrigatórios. **** | Campo | Descrição básica | | --- | --- | | Nome | Um nome para a base de conhecimento. | | roleArn | Um [perfil de serviço da base de conhecimento](kb-permissions.md) com as permissões adequadas. Você pode usar o console para criar automaticamente um perfil de serviço com as permissões adequadas. | | knowledgeBaseConfiguration | Contém as configurações da base de conhecimento. Para um banco de dados estruturado, especifique SQL como type e inclua o campo sqlKnowledgeBaseConfiguration. | Os campos a seguir são opcionais. **** | Campo | Use | | --- | --- | | descrição | Para incluir uma descrição para a base de conhecimento. | | clientToken | Para garantir que a solicitação de API seja concluída apenas uma vez. Para obter mais informações, consulte [Ensuring idempotency](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html). | | tags | Para associar tags ao fluxo. Para obter mais informações, consulte [Marcação de recursos do Amazon Bedrock](tagging.md). | A `SQLKnowledgeBaseConfiguration` depende do mecanismo de consulta que você usa. Para o Amazon Redshift, especifique o `type` campo como `REDSHIFT` e inclua o `redshiftConfiguration` campo, que mapeia para a. [RedshiftConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftConfiguration.html) Para o [RedshiftConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftConfiguration.html), você configura os seguintes campos: ### queryEngineConfiguration Você pode configurar os seguintes tipos de mecanismo de consulta: #### Amazon Redshift provisionado Se seus bancos de dados do Amazon Redshift forem provisionados em nós de computação dedicados, o valor do `queryEngineConfiguration` campo deverá ser a no seguinte formato: [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) }, } ``` Especifique o ID do cluster no campo `clusterIdentifier`. [RedshiftProvisionedAuthConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftProvisionedAuthConfiguration.html)Depende do tipo de autorização que você está usando. Selecione a guia que corresponde ao seu método de autorização: ------ #### [ IAM role ] Se você autorizar com seu perfil do IAM, precisará especificar somente o `IAM` como o tipo na [RedshiftProvisionedAuthConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftProvisionedAuthConfiguration.html) sem campos adicionais. ``` { "type": "IAM" } ``` ------ #### [ Temporary credentials user name ] Se você autorizar com o nome de usuário do banco de dados, especifique o `type` como `USERNAME` e o nome do usuário no campo `databaseUser` na `RedshiftProvisionedAuthConfig`: ``` { "type": "USERNAME", "databaseUser": "string" } ``` ------ #### [ AWS Secrets Manager ] Se você autorizar com AWS Secrets Manager, especifique o `type` como `USERNAME_PASSWORD` e especifique o ARN do segredo `usernamePasswordSecretArn` no campo em: `RedshiftProvisionedAuthConfig` ``` { "type": "USERNAME_PASSWORD", "usernamePasswordSecretArn": "string" } ``` ------ #### Amazon Redshift Sem Servidor Se você estiver usando o Amazon Redshift Serverless, o valor do `queryConfiguration` campo deve ser a [RedshiftQueryEngineConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftQueryEngineConfiguration.html)no seguinte formato: ``` { "type": "SERVERLESS", "serverlessConfiguration": { "workgroupArn": "string", "authConfiguration": } } ``` Especifique o ARN do grupo de trabalho no campo `workgroupArn`. [RedshiftServerlessAuthConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftServerlessAuthConfiguration.html)Depende do tipo de autorização que você está usando. Selecione a guia que corresponde ao seu método de autorização: ------ #### [ IAM role ] Se você autorizar com seu perfil do IAM, precisará especificar somente o `IAM` como o tipo na `RedshiftServerlessAuthConfiguration` sem campos adicionais. ``` { "type": "IAM" } ``` ------ #### [ AWS Secrets Manager ] Se você autorizar com AWS Secrets Manager, especifique o `type` como `USERNAME_PASSWORD` e especifique o ARN do segredo `usernamePasswordSecretArn` no campo em: `RedshiftServerlessAuthConfiguration` ``` { "type": "USERNAME_PASSWORD", "usernamePasswordSecretArn": "string" } ``` ------ ### storageConfigurations Esse campo é mapeado para uma matriz contendo um único [RedshiftQueryEngineStorageConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_RedshiftQueryEngineStorageConfiguration.html), cujo formato depende de onde seus dados estão armazenados. #### AWS Glue Data Catalog Se seus dados estiverem armazenados AWS Glue Data Catalog, eles `RedshiftQueryEngineStorageConfiguration` devem estar no seguinte formato: ``` { "type": "AWS_DATA_CATALOG", "awsDataCatalogConfiguration": { "tableNames": ["string"] } } ``` Adicione o nome de cada tabela à qual você deseja conectar a base de conhecimento na matriz associada a `tableNames`. **nota** Insira o nome das tabelas no padrão descrito em [Consultas entre bancos de dados](https://docs.aws.amazon.com/redshift/latest/dg/cross-database-overview.html) (`${databaseName}.${tableName}`). Você pode incluir todas as tabelas especificando `${databaseName.*}`. #### Bancos de dados do Amazon Redshift Se os dados estiverem armazenados em um banco de dados do Amazon Redshift, a `RedshiftQueryEngineStorageConfiguration` deve seguir o seguinte formato: ``` { "type": "string", "redshiftConfiguration": { "databaseName": "string" } } ``` Especifique o nome do banco de dados do Amazon Redshift no campo `databaseName`. **nota** Insira o nome das tabelas no padrão descrito em [Consultas entre bancos de dados](https://docs.aws.amazon.com/redshift/latest/dg/cross-database-overview.html) (`${databaseName}.${tableName}`). Você pode incluir todas as tabelas especificando `${databaseName.*}`. Se seu banco de dados for montado por meio do Amazon SageMaker AI Lakehouse, o nome do banco de dados está no formato. *\$1\$1db\$1@\$1\$1schema\$1* ### queryGenerationConfiguration Esse campo é mapeado para o seguinte, [QueryGenerationConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationConfiguration.html)que você pode usar para configurar como seus dados são consultados: ``` { "executionTimeoutSeconds": number, "generationContext": { "tables": [ { "name": "string", "description": "string", "inclusion": "string", "columns": [ { "name": "string", "description": "string", "inclusion": "string" }, ... ] }, ... ], "curatedQueries": [ { "naturalLanguage": "string", "sql": "string" }, ... ] } } ``` Se você quiser que a consulta atinja o tempo limite, especifique a duração do tempo limite em segundos no campo `executionTimeoutSeconds`. O `generationContext` campo mapeia para um [QueryGenerationContext](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationContext.html)objeto no qual você pode configurar quantas das opções a seguir forem necessárias. **Importante** Se você incluir um contexto de geração, o mecanismo de consulta fará o possível para aplicá-lo ao gerar SQL. O contexto de geração não é determinístico e se destina apenas a melhorar a precisão do modelo. Para garantir a precisão, verifique as consultas SQL geradas. Para ter informações sobre contextos de geração que você pode incluir, expanda as seguintes seções: #### Adicionar descrições para tabelas ou colunas no banco de dados Para melhorar a precisão da geração de SQL para consultar o banco de dados, é possível fornecer uma descrição para a tabela ou coluna que cujo contexto seja maior que um nome curto de tabela ou coluna. Você pode fazer o seguinte: + Para adicionar uma descrição para uma tabela, inclua um [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html)objeto na `tables` matriz. Nesse objeto, especifique o nome da tabela no campo `name` e uma descrição no campo `description`, como no seguinte exemplo: ``` { "name": "database.schema.tableA", "description": "Description for Table A" } ``` + Para adicionar uma descrição para uma coluna, inclua um [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html)objeto na `tables` matriz. Nesse objeto, especifique o nome da tabela no `name` campo e inclua o `columns` campo, que mapeia para uma matriz de [QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html). Em um objeto `QueryGenerationColumn`, inclua o nome da coluna no campo `name` e uma descrição no campo `description`, como no seguinte exemplo: ``` { "name": "database.schema.tableA", "columns": [ { "name": "Column A", "description": "Description for Column A" } ] } ``` + É possível adicionar uma descrição para uma tabela e uma coluna, como no seguinte exemplo: ``` { "name": "database.schema.tableA", "description": "Description for Table A", "columns": [ { "name": "columnA", "description": "Description for Column A" } ] } ``` **nota** Insira o nome das tabelas e colunas no padrão descrito em [Consultas entre bancos de dados](https://docs.aws.amazon.com/redshift/latest/dg/cross-database-overview.html). Se seu banco de dados estiver em AWS Glue Data Catalog, o formato é`awsdatacatalog.gluedatabase.table`. #### Incluir ou excluir tabelas ou colunas no banco de dados Você pode sugerir tabelas ou colunas para incluir ou excluir ao gerar SQL usando o `inclusion` campo nos [QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html)objetos [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html)e. Você pode especificar um dos seguintes valores no campo `inclusion`: + INCLUDE: somente as tabelas ou colunas que você especifica são incluídas como contexto ao gerar SQL. + EXCLUDE: as tabelas ou colunas que você especifica são excluídas como contexto ao gerar SQL. Você pode especificar se deseja incluir ou excluir tabelas ou colunas das seguintes formas: + Para incluir ou excluir uma tabela, inclua um [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html)objeto na `tables` matriz. Nesse objeto, especifique o nome da tabela no campo `name` e especifique se é necessário incluí-la ou excluí-la no campo `inclusion`, como no exemplo a seguir: ``` { "name": "database.schema.tableA", "inclusion": "EXCLUDE" } ``` O mecanismo de consulta não adiciona a `Table A` no contexto complementar para gerar SQL. + Para incluir ou excluir uma coluna, inclua um [QueryGenerationTable](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationTable.html)objeto na `tables` matriz. Nesse objeto, especifique o nome da tabela no `name` campo e inclua o `columns` campo, que mapeia para uma matriz de [QueryGenerationColumn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationColumn.html). Em um objeto `QueryGenerationColumn`, inclua o nome da coluna no campo `name` e especifique se deseja incluí-la ou excluí-la no campo `inclusion`, como no seguinte exemplo: ``` { "name": "database.schema.tableA", "columns": [ { "name": "database.schema.tableA.columnA", "inclusion": "EXCLUDE" } ] } ``` A geração de SQL ignora a `Column A` na `Table A` no contexto ao gerar SQL. + É possível combinar tabelas e colunas ao especificar inclusões ou exclusões, como no seguinte exemplo: ``` { "name": "database.schema.tableA", "inclusion": "INCLUDE", "columns": [ { "name": "database.schema.tableA.columnA", "inclusion": "EXCLUDE" } ] } ``` A geração de SQL inclui a `Table A`, mas exclui a `Column A` dentro dela ao adicionar contexto para gerar SQL. **Importante** As exclusões de tabelas e colunas não substituem as barreiras de proteção. Essas inclusões e exclusões de tabelas e colunas são usadas como contexto adicional a ser considerado pelo modelo ao gerar SQL. #### Dar ao mecanismo de consulta exemplos de mapeamentos em linguagem natural para consultas SQL Para melhorar a precisão de um mecanismo de consulta na conversão de consultas de usuários em consultas SQL, você pode fornecer exemplos no `curatedQueries` campo do [QueryGenerationContext](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_QueryGenerationContext.html)objeto, que mapeia para uma matriz de objetos. [CuratedQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CuratedQuery.html) Cada objeto contém os seguintes campos: + naturalLanguage: um exemplo de consulta em linguagem natural. + sql: a consulta SQL que corresponde à consulta em linguagem natural. # Sincronizar o armazenamento de dados estruturados com sua base de conhecimento do Amazon Bedrock Depois de conectar sua base de conhecimento a um armazenamento de dados estruturados, execute uma sincronização para iniciar o processo de ingestão de metadados e permitir que os dados sejam recuperados. Os metadados permitem que as Bases de Conhecimento do Amazon Bedrock convertam os prompts do usuário em uma consulta ao banco de dados conectado. Sempre que você fizer modificações no esquema do banco de dados, precisará sincronizar as alterações. Para saber como ingerir metadados na base de conhecimento e sincronizar com os dados mais recentes, escolha a guia correspondente ao método de sua escolha e siga as etapas: ------ #### [ Console ] **Saiba como ingerir dados na base de conhecimento e sincronizar com os dados mais recentes.** 1. Abra o console do Amazon Bedrock em [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/). 1. No painel de navegação à esquerda, selecione **Base de conhecimento** e escolha a base de conhecimento. 1. Na seção **Fonte de dados**, selecione **Sincronizar** para iniciar o processo de ingestão de metadados. Para interromper a sincronização de uma fonte de dados em andamento, selecione **Parar**. Uma fonte de dados deve estar em sincronização para que a sincronização da fonte de dados seja interrompida. É possível selecionar **Sincronizar** novamente para ingerir o resto dos dados. 1. Quando a ingestão de dados for concluída, um banner verde de sucesso será exibido se ela tiver sido bem-sucedida. 1. Você pode escolher uma fonte de dados para ver o **Histórico de sincronização**. Selecione **Visualizar avisos** para ver por que um trabalho de ingestão de dados falhou. ------ #### [ API ] Para ingerir os dados na base de conhecimento e sincronizar com os dados mais recentes, envie uma solicitação [StartIngestionJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_StartIngestionJob.html) com um [endpoint de tempo de compilação do recurso Agentes para Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Use o `ingestionJobId` exibido na resposta em uma solicitação [GetIngestionJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetIngestionJob.html) com um [endpoint de tempo de compilação do recurso Agentes para Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) para rastrear o status do trabalho de ingestão. Também é possível ver as informações de todos os trabalhos de ingestão de uma fonte de dados enviando uma solicitação [ListIngestionJobs](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ListIngestionJobs.html) com um [endpoint de tempo de compilação do recurso Agentes para Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Para interromper um trabalho de ingestão de dados que está em execução no momento, envie uma solicitação [StopIngestionJobs](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_StopIngestionJob.html) com um [endpoint de tempo de compilação do recurso Agentes para Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). É possível enviar uma solicitação `StartIngestionJob` novamente para ingerir o resto dos seus dados quando tudo estiver pronto. ------ **Importante** Se você usar o perfil de serviço das Bases de Conhecimento do Amazon Bedrock criado para você no console e depois sincronizar o datastore antes de permitir que o perfil de autenticação que você usa acesse o seu banco de dados, o usuário será criado para você, mas a sincronização falhará porque o usuário não recebeu permissões para acessar seu datastore. Para ter informações sobre como conceder permissões a um perfil para acessar o datastore, consulte [Permitir que o perfil de serviço da base de conhecimento acesse seu datastore](knowledge-base-prereq-structured.md#knowledge-base-prereq-structured-db-access).