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á.
# Configure e personalize consultas para bases de conhecimento gerenciadas
Você pode configurar e personalizar a recuperação, melhorando ainda mais a relevância dos resultados. Por exemplo, você pode aplicar filtros aos metadados do documento fields/attributes para usar os documentos atualizados mais recentemente ou documentos com horários de modificação recentes.
**nota**
Todas as configurações a seguir são aplicáveis somente a fontes de dados não estruturadas.
Para saber mais sobre essas configurações no console ou na API, selecione um dos seguintes tópicos:
## Número de fragmentos de origem
Quando você consulta uma base de conhecimento, o Amazon Bedrock retorna até cinco resultados na resposta por padrão. Cada resultado corresponde a um fragmento de origem.
**nota**
O número real de resultados na resposta pode ser menor que o valor `numberOfResults` especificado, pois esse parâmetro define o número máximo de resultados a serem exibidos. Se você configurou a fragmentação hierárquica para sua estratégia de fragmentação, o parâmetro `numberOfResults` será associado ao número de fragmentos secundários que a base de conhecimento recuperará. Como os fragmentos secundários que compartilham o mesmo fragmento principal são substituídos pelo fragmento principal na resposta final, o número de resultados exibidos pode ser menor do que o valor solicitado.
Para modificar o número máximo de resultados a serem exibidos, escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ Console ]
Siga as etapas do console em [Consultar uma base de conhecimento e recuperar dados](kb-test-retrieve.md). No painel **Configurações**, expanda a seção **Fragmentos de origem** e insira o número máximo de fragmentos de origem a serem exibidos.
------
#### [ API ]
Ao fazer uma [RetrieveAndGenerate](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) solicitação [Retrieve](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) ou, inclua um `retrievalConfiguration` campo mapeado para um [ KnowledgeBaseRetrievalConfiguration ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_KnowledgeBaseRetrievalConfiguration.html) objeto. Para ver a localização desse campo, consulte os corpos de solicitação [Retrieve](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) e [RetrieveAndGenerate](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) na referência de API.
O objeto JSON a seguir mostra os campos mínimos necessários no [ KnowledgeBaseRetrievalConfiguration ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_KnowledgeBaseRetrievalConfiguration.html) objeto para definir o número máximo de resultados a serem retornados:
```
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"numberOfResults": number
}
}
```
Especifique o número máximo de resultados recuperados (consulte o `numberOfResults` campo em [ KnowledgeBaseRetrievalConfiguration ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_KnowledgeBaseRetrievalConfiguration.html) para ver o intervalo de valores aceitos) a serem retornados no `numberOfResults` campo.
------
## Filtragem manual de metadados
Você pode aplicar filtros ao documento fields/attributes para ajudá-lo a melhorar ainda mais a relevância das respostas. Suas fontes de dados podem incluir metadados de documentos attributes/fields para filtrar e especificar quais campos incluir nas incorporações.
**Considerações sobre a base de conhecimento gerenciada**
Ao usar a filtragem de metadados com uma base de conhecimento gerenciada:
Os filtros `startsWith` e `stringContains` metadados não são suportados. Em vez disso `equals` `greaterThan``lessThan`, use `notIn` operadores`in`,,, ou.
Os operadores de intervalo (`greaterThan`, `greaterThanOrEquals``lessThan`, e`lessThanOrEquals`) aceitam um número ou um valor de data e hora. Para filtrar por data e hora, forneça o valor como uma string no formato ISO-8601 offset de data e hora. Use o formulário de compensação completo, por exemplo,`2026-03-02T19:02:18Z`. Os operadores de intervalo suportam valores de string de data e hora somente para bases de conhecimento gerenciadas.
Para bases de conhecimento personalizadas, os campos de metadados prefixados com `x-amz-bedrock` são reservados pelo serviço. Para bases de conhecimento totalmente gerenciadas, os campos de metadados reservados usam um prefixo de sublinhado (por exemplo,,`_source_uri`). `_data_source_id` Você não pode substituir os campos de metadados reservados em nenhum dos tipos de base de conhecimento.
Por exemplo, “epoch\_modification\_time” representa o tempo em segundos desde 1.º de janeiro de 1970 (UTC), quando o documento foi atualizado pela última vez. Você pode filtrar os dados mais recentes, em que “epoch\_modification\_time” *é maior que* um determinado número. Esses documentos mais recentes podem ser usados na consulta.
Para usar filtros ao consultar uma base de conhecimento, verifique se a base de conhecimento atende aos seguintes requisitos:
+ Ao configurar o conector da fonte de dados, a maioria dos conectores rastreia os principais campos de metadados dos documentos. Se estiver usando um bucket do Amazon S3 como fonte de dados, o bucket deverá incluir pelo menos um `fileName.extension.metadata.json` para o arquivo ou o documento ao qual está associado. Consulte **Campos de metadados do documento** em [Configuração de conexão](s3-data-source-connector.md#configuration-s3-connector) para ter mais informações sobre como configurar o arquivo de metadados.
+ Se o índice vetorial da sua base de conhecimento estiver em um armazenamento vetorial Amazon OpenSearch Serverless, verifique se o índice vetorial está configurado com o `faiss` mecanismo. Se o índice de vetores estiver configurado com o mecanismo `nmslib`, será necessário fazer o seguinte:
+ [Crie uma nova base de conhecimento ](knowledge-base-create.md) no console e deixe o Amazon Bedrock criar automaticamente um índice vetorial no Amazon OpenSearch Serverless para você.
+ [Criar outro índice de vetores](knowledge-base-setup.md) no armazenamento de vetores e selecionar `faiss` como o **mecanismo**. Em seguida, [criar uma base de conhecimento](knowledge-base-create.md) e especificar o novo índice de vetores.
+ Se sua base de conhecimento usa um índice de vetores em um bucket de vetores do S3, não é possível usar os filtros `startsWith` e `stringContains`.
+ Se estiver adicionando metadados a um índice de vetores existente em um cluster de banco de dados do Amazon Aurora, recomendamos que você forneça o nome do campo da coluna de metadados personalizados para armazenar todos os metadados em uma única coluna. Durante a [ingestão de dados](kb-data-source-sync-ingest.md), essa coluna será usada para preencher todas as informações em os arquivos de metadados de suas fontes de dados. Se você optar por fornecer esse campo, deverá criar um índice nessa coluna.
+ Quando você [cria uma base de conhecimento](knowledge-base-create.md) no console e permite que o Amazon Bedrock configure o banco de dados do Amazon Aurora, ele cria automaticamente uma única coluna para você e a preenche com as informações dos seus arquivos de metadados.
+ Ao optar por [criar outro índice de vetores](knowledge-base-setup.md) no armazenamento de vetores, é necessário fornecer o nome do campo de metadados personalizados para armazenar informações dos arquivos de metadados. Se você não fornecer esse nome de campo, crie uma coluna para cada atributo de metadados nos arquivos e especifique o tipo de dados (texto, número ou booliano). Por exemplo, se o atributo `genre` existir na fonte de dados, você deve adicionar uma coluna chamada `genre` e especificar `text` como o tipo de dados. Durante a ingestão, essas colunas separadas serão preenchidas com os valores dos atributos correspondentes.
Se você tiver documentos PDF em sua fonte de dados e usar o Amazon OpenSearch Serverless ou o Amazon Aurora para seu armazenamento vetorial: as bases de conhecimento da Amazon Bedrock gerarão números de páginas de documentos e os armazenarão em um metadado chamado x-amz-bedrock-kb-document-page-number. field/attribute * * Observe que não será possível ter números de página armazenados em um campo de metadados se você optar por não agrupar seus documentos.
Você pode usar os operadores de filtragem para filtrar os resultados ao consultar:
**Operadores de filtragem**
| Operador | Console | Nome do filtro da API | Tipos de dados de atributo compatíveis | Resultados filtrados |
| --- | --- | --- | --- | --- |
| Igual | = | [equals](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-equals) | string, número, booliano | O atributo corresponde ao valor fornecido por você |
| Não é igual a | \!= | [notEquals](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-notEquals) | string, número, booliano | O atributo não corresponde ao valor fornecido por você |
| Maior que | > | [greaterThan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-greaterThan) | número | O atributo é maior que o valor fornecido por você |
| É maior que ou igual a | >= | [maior ThanOrEquals ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-greaterThanOrEquals) | número | O atributo é maior que ou igual ao valor fornecido por você |
| Menor que | < | [lessThan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-lessThan) | número | O atributo é menor que o valor fornecido por você |
| Menor ou igual a | <= | [menos ThanOrEquals ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-lessThanOrEquals) | número | O atributo é menor que ou igual ao valor fornecido por você |
| Em | : | [in](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-in) | lista de strings | O atributo está na lista que você fornece (atualmente é mais compatível com os armazenamentos vetoriais Amazon OpenSearch Serverless e Neptune Analytics GraphRag) |
| Não está em | \!: | [notIn](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-notIn) | lista de strings | O atributo não está na lista que você fornece (atualmente é melhor suportado pelos armazenamentos vetoriais Amazon OpenSearch Serverless e Neptune Analytics GraphRag) |
| A string contém | Indisponível | [stringContains](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-stringContains) | string | O atributo deve ser uma string. O nome do atributo corresponde à chave e cujo valor é uma string que contém o valor que você forneceu como uma substring ou uma lista com um membro que contém o valor que você forneceu como uma substring (atualmente é melhor suportada pelo Amazon OpenSearch Serverless Vector Store). O armazenamento vetorial do Neptune Analytics GraphRag suporta a variante de string (mas não a variante de lista desse filtro). |
| A lista contém | Indisponível | [listContains](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-listContains) | string | O atributo deve ser uma lista de strings. O nome do atributo corresponde à chave e cujo valor é uma lista que contém o valor que você forneceu como um de seus membros (atualmente é melhor suportado pelos armazenamentos vetoriais Amazon OpenSearch Serverless). |
Para combinar operadores de filtragem, você pode usar os seguintes operadores lógicos:
**Operadores lógicos**
| Operador | Console | Nome do campo de filtro da API | Resultados filtrados |
| --- | --- | --- | --- |
| E | and | [andAll](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-andAll) | Os resultados atendem a todas as expressões de filtragem no grupo |
| Ou | or | [orAll](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html#bedrock-Type-agent-runtime_RetrievalFilter-orAll) | Os resultados atendem a pelo menos uma das expressões de filtragem no grupo |
Para saber como filtrar os resultados usando metadados, escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ Console ]
Siga as etapas do console em [Consultar uma base de conhecimento e recuperar dados](kb-test-retrieve.md). Ao abrir o painel **Configurações**, você verá uma seção **Filtros**. Os seguintes procedimentos descrevem casos de uso diferentes:
+ Para adicionar um filtro, crie uma expressão de filtragem inserindo um atributo de metadados, um operador de filtragem e um valor na caixa. Separe cada parte da expressão com um espaço em branco. Pressione **Enter** para adicionar o filtro.
Para obter uma lista dos operadores de filtragem aceitos, consulte a tabela **Operadores de filtragem** acima. Você também pode ver uma lista dos operadores de filtragem ao adicionar um espaço em branco após o atributo de metadados.
**nota**
Você deve colocar as strings entre aspas.
Por exemplo, você pode filtrar resultados dos documentos de origem que contenham um atributo de metadados `genre` cujo valor é `"entertainment"` adicionando o seguinte filtro: **genre = "entertainment"**.
+ Para adicionar outro filtro, insira outra expressão de filtragem na caixa e pressione **Enter**. Você pode adicionar até cinco filtros no grupo.
+ Por padrão, a consulta retorna resultados que atendam a todas as expressões de filtragem fornecidas por você. Para retornar resultados que atendam a pelo menos uma das expressões de filtragem, escolha o menu suspenso **e** entre duas operações de filtragem e selecione **ou**.
+ Para combinar operadores lógicos diferentes, selecione **\+ Adicionar grupo** para adicionar um grupo de filtros. Insira expressões de filtragem no novo grupo. Você pode adicionar até 5 grupos de filtros.
+ Para alterar o operador lógico usado entre todos os grupos de filtragem, escolha o menu suspenso **E** entre dois grupos de filtros e selecione **OU**.
+ Para editar um filtro, selecione-o, modifique a operação de filtragem e escolha **Aplicar**.
+ Para remover um grupo de filtros, escolha o ícone de lixeira () ao lado do grupo. Para remover um filtro, escolha o ícone de exclusão () ao lado do filtro.
A imagem a seguir mostra um exemplo de configuração do filtro que mostra todos os documentos gravados depois de **2018** cujo gênero é **"entertainment"**, além de documentos cujo gênero é **"cooking"** ou **"sports"** cujo autor começa com **"C"**.
------
#### [ API ]
Ao fazer uma [RetrieveAndGenerate](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) solicitação [Retrieve](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) ou, inclua um `retrievalConfiguration` campo mapeado para um [ KnowledgeBaseRetrievalConfiguration ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_KnowledgeBaseRetrievalConfiguration.html) objeto. Para ver a localização desse campo, consulte os corpos de solicitação [Retrieve](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) e [RetrieveAndGenerate](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) na referência de API.
Os objetos JSON a seguir mostram os campos mínimos necessários no [ KnowledgeBaseRetrievalConfiguration ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_KnowledgeBaseRetrievalConfiguration.html) objeto para definir filtros para diferentes casos de uso:
1. Use um operador de filtragem (consulte a tabela **Operadores de filtragem** acima).
```
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"filter": {
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
}
}
}
}
```
1. Use um operador lógico (consulte a tabela **Operadores lógicos** acima) para combinar até cinco.
```
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"filter": {
"{{andAll | orAll}}": [
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
...
]
}
}
}
```
1. Use um operador lógico para combinar até cinco operadores de filtragem em um grupo de filtros e um segundo operador lógico para combinar esse grupo de filtros com outro operador de filtragem.
```
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"filter": {
"{{andAll | orAll}}": [
"{{andAll | orAll}}": [
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
...
],
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
}
]
}
}
}
```
1. Combine até cinco grupos de filtros incorporando-os em outro operador lógico. Você pode criar um nível de incorporação.
```
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"filter": {
"{{andAll | orAll}}": [
"{{andAll | orAll}}": [
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
...
],
"{{andAll | orAll}}": [
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
"{{}}": {
"key": "string",
"value": "string" | number | boolean | ["string", "string", ...]
},
...
]
]
}
}
}
```
A seguinte tabela descreve os tipos de filtro que você pode usar:
| Campo | Tipos de dados de valor compatíveis | Resultados filtrados |
| --- | --- | --- |
| equals | string, número, booliano | O atributo corresponde ao valor fornecido por você |
| notEquals | string, número, booliano | O atributo não corresponde ao valor fornecido por você |
| greaterThan | número | O atributo é maior que o valor fornecido por você |
| greaterThanOrEquals | número | O atributo é maior que ou igual ao valor fornecido por você |
| lessThan | número | O atributo é menor que o valor fornecido por você |
| lessThanOrEquals | número | O atributo é menor que ou igual ao valor fornecido por você |
| in | lista de strings | O atributo está na lista fornecida por você |
| notIn | lista de strings | O atributo não está na lista fornecida por você |
| startsWith | string | O atributo começa com a string que você fornece (compatível apenas com lojas vetoriais Amazon OpenSearch Serverless) |
Para combinar tipos de filtro, você pode usar um dos seguintes operadores lógicos:
| Campo | Está associado a | Resultados filtrados |
| --- | --- | --- |
| andAll | Lista de até cinco tipos de filtro | Os resultados atendem a todas as expressões de filtragem no grupo |
| orAll | Lista de até cinco tipos de filtro | Os resultados atendem a pelo menos uma das expressões de filtragem no grupo |
Para obter exemplos, consulte [ Enviar uma consulta e incluir filtros (Recuperar) ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html#API_agent-runtime_Retrieve_Example_2) e [ Enviar uma consulta e incluir filtros (RetrieveAndGenerate)](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html#API_agent-runtime_RetrieveAndGenerate_Example_2).
------
## Barreiras de proteção
Você pode implementar barreiras para a base de conhecimento nos casos de uso e políticas de IA responsável. Você pode criar várias barreiras de proteção personalizadas para diferentes casos de uso e aplicá-las em várias condições de solicitação e resposta, proporcionando uma experiência do usuário consistente e padronizando controles de segurança em toda a base de conhecimento. Você pode configurar tópicos negados para evitar tópicos indesejáveis e filtros de conteúdo para bloquear conteúdo prejudicial em entradas e respostas do modelo. Para obter mais informações, consulte [Detectar e filtrar conteúdo nocivo usando as Barreiras de Proteção do Amazon Bedrock](guardrails.md).
**nota**
Não é possível usar barreiras de proteção com base contextual para bases de conhecimento no Claude 3 Sonnet e no Haiku.
Para obter diretrizes gerais de engenharia de prompts, consulte [Conceitos de engenharia de prompts](prompt-engineering-guidelines.md).
Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ Console ]
Siga as etapas do console em [Consultar uma base de conhecimento e recuperar dados](kb-test-retrieve.md). Na janela de teste, ative **Gerar respostas**. Em seguida, no painel **Configurações**, expanda a seção **Barreiras de proteção**.
1. Na seção **Barreiras de proteção**, escolha o **Nome** e a **Versão** da barreira de proteção. Se você quiser ver os detalhes da barreira de proteção e da versão escolhidas, escolha **Exibir**.
Você também pode criar uma nova escolhendo o link **Barreira de proteção**.
1. Quando terminar de editar, escolha **Save changes** (Salvar alterações). Para sair sem salvar, escolha **Descartar alterações**.
------
#### [ API ]
Ao fazer uma solicitação [RetrieveAndGenerate](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html), inclua o campo `guardrailConfiguration` em `generationConfiguration` para usar a barreira de proteção com a solicitação. Para ver a localização desse campo, consulte o corpo da solicitação [RetrieveAndGenerate](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) na referência de API.
O objeto JSON a seguir mostra os campos mínimos necessários [ GenerationConfiguration ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GenerationConfiguration.html) para definir o`guardrailConfiguration`:
```
"generationConfiguration": {
"guardrailConfiguration": {
"guardrailId": "{{string}}",
"guardrailVersion": "{{string}}"
}
}
```
Especifique `guardrailId` e `guardrailVersion` das barreiras de proteção escolhidas.
------
## Reclassificar
Você pode usar um modelo reclassificador para reclassificar os resultados da consulta à base de conhecimento. Siga as etapas do console em [Consultar uma base de conhecimento e recuperar dados](kb-test-retrieve.md). Ao abrir o painel **Configurações**, expanda a seção **Reclassificação**. Selecione um modelo reclassificador, atualize as permissões, se necessário, e modifique as opções adicionais. Insira um prompt e selecione **Executar** para testar os resultados após a reclassificação.