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 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.