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á.
# Crie um aplicativo RAG usando as bases de conhecimento Amazon Bedrock
Muitas empresas acumulam grandes repositórios de documentos em seus compartilhamentos de arquivos NFS e SMB — manuais de produtos, documentos de políticas, contratos, relatórios de pesquisa, especificações de engenharia e conteúdo gerado pelo usuário.
Com um ponto de acesso Amazon S3 conectado ao volume FSx for ONTAP, o Amazon Bedrock Knowledge Bases ingere conteúdo diretamente do volume. Foundation-model as respostas são baseadas nos documentos em que suas equipes as salvam via NFS ou SMB. O conteúdo que os escritores atualizam no compartilhamento fica disponível para a base de conhecimento na próxima sincronização.
Neste tutorial, você carrega um pequeno conjunto de exemplos de PDFs no volume FSx for ONTAP por meio de um ponto de acesso do Amazon S3, cria uma base de conhecimento do Amazon Bedrock que aponta para o ponto de acesso, ingere os documentos e executa uma pergunta por meio da API. `RetrieveAndGenerate`
**nota**
Este tutorial leva aproximadamente **35 a 45 minutos** para ser concluído. Os Serviços da AWS usados incorrem em cobranças pelos recursos que você cria. Se você concluir todas as etapas, incluindo a seção **Limpeza** imediatamente, o custo esperado é inferior a **$1** no Leste dos EUA (Norte da Virgínia) Região da AWS. Essa estimativa não inclui cobranças contínuas do FSx para o volume do ONTAP em si.
## Pré-requisitos
Antes de começar, você deve ter o seguinte:
+ Um volume FSx for ONTAP com um ponto de acesso Amazon S3 conectado. O ponto de acesso deve ter uma origem de rede **na Internet** para que o serviço Amazon Bedrock possa alcançá-lo. Para obter instruções sobre como criar um ponto de acesso, consulte[Criar um ponto de acesso](fsxn-creating-access-points.md).
+ Acesso ao modelo habilitado para um modelo de incorporação suportado pelas Bases de Conhecimento Amazon Bedrock e pelo menos um modelo de geração de texto (por exemplo,`amazon.nova-lite-v1:0`) no Região da AWS qual você criará a base de conhecimento. Este tutorial usa `amazon.titan-embed-text-v2:0` (1024 dimensões) como modelo de incorporação; modelos Cohere Embed também são suportados. Se você escolher um modelo de incorporação diferente, ajuste a dimensão do índice vetorial na Etapa 2 para corresponder à dimensão de saída do modelo. O acesso ao modelo é ativado no console do Amazon Bedrock em **Acesso ao modelo**. Para obter mais informações, consulte [Acesse os modelos da Amazon Bedrock Foundation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) no Guia do *usuário do Amazon Bedrock*.
+ AWS CLI versão 2 instalada e configurada com credenciais que podem criar funções do IAM, recursos do Amazon S3 Vectors e bases de conhecimento do Amazon Bedrock.
## Etapa 1: fazer upload de documentos de amostra para o ponto de acesso
Baixe alguns PDFs públicos para usar como amostra de corpus e, em seguida, carregue-os em seu ponto de acesso usando o alias de ponto de acesso do Amazon S3.
1. Crie um diretório local e baixe exemplos de PDFs.
```
$ mkdir -p ~/kb-pdfs && cd ~/kb-pdfs
curl -sSL -o aws-overview.pdf https://d1.awsstatic.com/whitepapers/aws-overview.pdf
curl -sSL -o wellarchitected-framework.pdf https://docs.aws.amazon.com/pdfs/wellarchitected/latest/framework/wellarchitected-framework.pdf
curl -sSL -o s3-userguide.pdf https://docs.aws.amazon.com/pdfs/AmazonS3/latest/userguide/s3-userguide.pdf
```
1. Faça upload de cada arquivo para o ponto de acesso. {{access-point-alias}}Substitua pelo alias do seu ponto de acesso (por exemplo,`my-kb-ap-a1b2c3d4e5f6g7h8i9j0kl1mnop2uuse1a-ext-s3alias`). Você pode encontrar o alias no console do Amazon FSx em Pontos de **acesso anexados do Amazon S3** para seu volume ou executando. `aws fsx describe-s3-access-point-attachments`
```
$ for f in *.pdf; do
aws s3 cp "$f" "s3://{{access-point-alias}}/$f"
done
```
1. Verifique se os arquivos chegaram ao volume.
```
$ aws s3 ls s3://{{access-point-alias}}/
```
**nota**
O Amazon Bedrock Knowledge Bases impõe um tamanho máximo de arquivo de 50 MB por documento. Arquivos maiores que 50 MB são ignorados durante a ingestão.
## Etapa 2: criar um armazenamento de vetores
A base de conhecimento armazena incorporações de documentos em um repositório vetorial. O Amazon Bedrock Knowledge Bases oferece suporte a vários armazenamentos de vetores; este tutorial usa os vetores do Amazon S3 como padrão, pois é otimizado em termos de custo para cargas de trabalho do RAG e requer configuração mínima. O Amazon OpenSearch Serverless também é compatível; consulte a seção dobrável no final desta etapa para obter essas instruções.
### Para criar o armazenamento vetorial usando o console
**Se você usar o console para criar a base de conhecimento no[Etapa 4: criar a base de conhecimento e a fonte de dados](#tutorial-bedrock-kb-create-kb), escolha **Criar rapidamente um novo armazenamento vetorial** na etapa do **banco de dados vetoriais** e selecione **Amazon S3 Vectors** (recomendado) ou Amazon Serverless. OpenSearch ** O Amazon Bedrock cria automaticamente o armazenamento vetorial e todas as configurações necessárias. Avance para [Etapa 3: criar uma função do IAM para a base de conhecimento](#tutorial-bedrock-kb-iam-role).
### Para criar um armazenamento vetorial do Amazon S3 Vectors usando o AWS CLI
1. Crie um bucket vetorial do Amazon S3. Os nomes de buckets vetoriais seguem as mesmas regras de exclusividade global dos buckets padrão do Amazon S3. Este tutorial usa`fsxn-kb-vectors`; substitua por um nome exclusivo.
```
$ aws s3vectors create-vector-bucket --vector-bucket-name fsxn-kb-vectors
```
1. Crie um índice vetorial no bucket. A dimensão do índice deve corresponder à dimensão de saída do modelo de incorporação; o Titan Text Embeddings v2 gera 1024 dimensões. A `nonFilterableMetadataKeys` configuração marca os campos de metadados do Bedrock como não filtráveis, o que os mantém fora do limite de metadados filtráveis de 2 KB por vetor.
```
$ aws s3vectors create-index --vector-bucket-name fsxn-kb-vectors \
--index-name bedrock-kb-index \
--dimension 1024 --distance-metric cosine --data-type float32 \
--metadata-configuration '{"nonFilterableMetadataKeys":["AMAZON_BEDROCK_METADATA","AMAZON_BEDROCK_TEXT"]}'
```
Observe o `indexArn` na resposta; você o usa em[Etapa 4: criar a base de conhecimento e a fonte de dados](#tutorial-bedrock-kb-create-kb).
### Alternativa: Crie um armazenamento vetorial OpenSearch Service Serverless usando o AWS CLI
Se você preferir o OpenSearch Service Serverless (para maiores consultas por segundo, recursos de pesquisa avançada ou familiaridade operacional existente), use as etapas a seguir em vez do procedimento Amazon S3 Vectors acima.
1. Crie políticas de criptografia e segurança de rede para a coleção.
```
$ aws opensearchserverless create-security-policy --name kb-enc --type encryption \
--policy '{"Rules":[{"ResourceType":"collection","Resource":["collection/fsxn-kb"]}],"AWSOwnedKey":true}'
aws opensearchserverless create-security-policy --name kb-net --type network \
--policy '[{"Rules":[{"ResourceType":"collection","Resource":["collection/fsxn-kb"]},{"ResourceType":"dashboard","Resource":["collection/fsxn-kb"]}],"AllowFromPublic":true}]'
```
1. Crie uma política de acesso a dados que conceda à função da base de conhecimento e ao seu usuário atual permissão para ler e gravar a coleção. Substitua {{account-id}} e {{current-user}} pelos seus valores.
```
$ aws opensearchserverless create-access-policy --name kb-data --type data --policy '[{
"Rules":[
{"ResourceType":"index","Resource":["index/fsxn-kb/*"],"Permission":["aoss:*"]},
{"ResourceType":"collection","Resource":["collection/fsxn-kb"],"Permission":["aoss:*"]}
],
"Principal":[
"arn:aws:iam::{{account-id}}:role/fsxn-kb-role",
"arn:aws:iam::{{account-id}}:user/{{current-user}}"
]
}]'
```
1. Crie a coleção e espere que ela se torne`ACTIVE`.
```
$ aws opensearchserverless create-collection --name fsxn-kb --type VECTORSEARCH
aws opensearchserverless batch-get-collection --names fsxn-kb \
--query 'collectionDetails[0].{status:status,endpoint:collectionEndpoint}'
```
1. Crie o índice vetorial na coleção usando um script Python com solicitações assinadas. O índice deve usar a dimensão 1024 (para Titan Text Embeddings v2) e os nomes de campo que o Amazon Bedrock Knowledge Bases espera. Para ver o script completo e as etapas de configuração subsequentes, consulte [Pré-requisitos para usar o OpenSearch Service Serverless](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-setup-oss.html) no Guia do usuário do *Amazon* Bedrock. Use o ARN da coleção resultante e o nome do índice na Etapa 4 com um `storage-configuration` do tipo of. `OPENSEARCH_SERVERLESS`
## Etapa 3: criar uma função do IAM para a base de conhecimento
A base de conhecimento precisa de uma função do IAM que ela possa assumir para invocar o modelo de incorporação, ler objetos por meio do ponto de acesso do Amazon S3 e acessar o armazenamento vetorial. A política mostrada abaixo concede acesso a uma loja de vetores do Amazon S3 Vectors. Se você usar OpenSearch Service Serverless em vez disso, substitua a `S3Vectors` instrução por uma que conceda `aoss:APIAccessAll` no ARN da coleção.
### Para criar a função usando o console
Ao criar a base de conhecimento usando o console Amazon Bedrock em[Etapa 4: criar a base de conhecimento e a fonte de dados](#tutorial-bedrock-kb-create-kb), escolha **Criar e use uma nova função de serviço**. O Amazon Bedrock cria uma função com a confiança e as permissões necessárias, com base em sua base de conhecimento, modelo de incorporação, armazenamento vetorial e fonte de dados. Avance para [Etapa 4: criar a base de conhecimento e a fonte de dados](#tutorial-bedrock-kb-create-kb).
### Para criar a função usando o AWS CLI
1. Salve a seguinte política de confiança como`kb-trust-policy.json`. Isso permite que o Amazon Bedrock assuma o papel. {{account-id}}Substitua pelo seu Conta da AWS ID.
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "bedrock.amazonaws.com"},
"Action": "sts:AssumeRole",
"Condition": {"StringEquals": {"aws:SourceAccount": "{{account-id}}"}}
}]
}
```
1. Salve a seguinte política de permissões como`kb-permissions.json`. Ele concede acesso ao modelo de incorporação, ao ponto de acesso Amazon S3 e ao armazenamento vetorial. Substitua os espaços reservados por seus valores.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "FoundationModel",
"Effect": "Allow",
"Action": ["bedrock:InvokeModel"],
"Resource": ["arn:aws:bedrock:{{region}}::foundation-model/amazon.titan-embed-text-v2:0"]
},
{
"Sid": "S3AccessPoint",
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:{{region}}:{{account-id}}:accesspoint/{{access-point-name}}",
"arn:aws:s3:{{region}}:{{account-id}}:accesspoint/{{access-point-name}}/object/*"
]
},
{
"Sid": "S3Vectors",
"Effect": "Allow",
"Action": [
"s3vectors:GetIndex",
"s3vectors:PutVectors",
"s3vectors:GetVectors",
"s3vectors:ListVectors",
"s3vectors:DeleteVectors",
"s3vectors:QueryVectors"
],
"Resource": [
"arn:aws:s3vectors:{{region}}:{{account-id}}:bucket/fsxn-kb-vectors",
"arn:aws:s3vectors:{{region}}:{{account-id}}:bucket/fsxn-kb-vectors/index/*"
]
}
]
}
```
1. Crie a função e anexe a política de permissões.
```
$ aws iam create-role --role-name fsxn-kb-role \
--assume-role-policy-document file://kb-trust-policy.json
aws iam put-role-policy --role-name fsxn-kb-role --policy-name kb-access \
--policy-document file://kb-permissions.json
```
## Etapa 4: criar a base de conhecimento e a fonte de dados
A fonte de dados aponta para o alias do ponto de acesso do Amazon S3. O Amazon Bedrock Knowledge Bases aceita o alias do ponto de acesso no lugar do nome de um bucket.
### Para criar a base de conhecimento usando o console
1. Abra o console Amazon Bedrock em [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/).
1. No painel de navegação esquerdo, escolha **Bases de conhecimento** e, em seguida, escolha **Criar base de conhecimento**.
1. Em **Detalhes da base de conhecimento**, insira um nome (por exemplo,`fsxn-kb`) e uma descrição.
1. Em **Permissões do IAM**, escolha **Criar e usar uma nova função de serviço**.
1. **Em **Fonte de dados**, escolha **Amazon S3** e, em seguida, escolha Avançar.**
1. Insira o nome da fonte de dados (por exemplo,`fsxn-s3ap-source`).
1. Para **URI do S3**, digite `s3://` seguido pelo alias do seu ponto de acesso, por exemplo. `s3://my-kb-ap-a1b2c3d4e5f6g7h8i9j0kl1mnop2uuse1a-ext-s3alias` O console não faz distinção entre um nome de bucket e um alias de ponto de acesso nesse campo; o alias do ponto de acesso é aceito no estado em que se encontra.
1. Escolha **Próximo**.
1. Em **Modelo de incorporações**, escolha **Titan Text Embeddings** v2.
1. Em **Banco de dados vetoriais**, escolha **Criar rapidamente um novo armazenamento de vetores** e selecione **Amazon S3** Vectors. Escolha **Próximo**.
1. Revise a configuração e escolha **Criar base de conhecimento**. A base de conhecimento pode levar vários minutos para ser criada.
### Para criar a base de conhecimento usando o AWS CLI
1. Crie a base de conhecimento. Substitua os espaços reservados por seus valores. `indexArn`É o ARN do índice vetorial do Amazon S3 que você criou na Etapa 2.
```
$ aws bedrock-agent create-knowledge-base --name fsxn-kb \
--role-arn arn:aws:iam::{{account-id}}:role/fsxn-kb-role \
--knowledge-base-configuration '{
"type":"VECTOR",
"vectorKnowledgeBaseConfiguration":{
"embeddingModelArn":"arn:aws:bedrock:{{region}}::foundation-model/amazon.titan-embed-text-v2:0"
}
}' \
--storage-configuration '{
"type":"S3_VECTORS",
"s3VectorsConfiguration":{
"indexArn":"{{index-arn}}"
}
}'
```
Observe o `knowledgeBaseId` na resposta.
1. Crie a fonte de dados. Passe o alias do ponto de acesso Amazon S3 como o nome do bucket no `bucketArn` campo, usando o formulário. `arn:aws:s3:::{{access-point-alias}}`
```
$ aws bedrock-agent create-data-source \
--knowledge-base-id {{knowledge-base-id}} \
--name fsxn-s3ap-source \
--data-source-configuration '{
"type":"S3",
"s3Configuration":{"bucketArn":"arn:aws:s3:::{{access-point-alias}}"}
}'
```
Observe o `dataSourceId` na resposta.
## Etapa 5: ingerir os documentos
Execute um trabalho de ingestão para rastrear os documentos pelo ponto de acesso, gerar incorporações e indexá-los no armazenamento vetorial.
### Para executar a ingestão usando o console
1. No console do Amazon Bedrock, abra sua base de conhecimento.
1. Na seção **Fonte de dados**, selecione sua fonte de dados e escolha **Sincronizar**.
1. Aguarde até que **o status de sincronização** apareça **Pronto**.
### Para executar a ingestão usando o AWS CLI
1. Inicie o trabalho de ingestão.
```
$ aws bedrock-agent start-ingestion-job \
--knowledge-base-id {{knowledge-base-id}} \
--data-source-id {{data-source-id}}
```
Observe o `ingestionJobId` na resposta.
1. Pesquise o trabalho até que ele seja concluído.
```
$ aws bedrock-agent get-ingestion-job \
--knowledge-base-id {{knowledge-base-id}} \
--data-source-id {{data-source-id}} \
--ingestion-job-id {{ingestion-job-id}}
```
O `status` campo faz a transição de `IN_PROGRESS` para`COMPLETE`. O `statistics` campo mostra quantos documentos foram digitalizados e indexados.
## Etapa 6: consultar a base de conhecimento
Faça uma pergunta à base de conhecimento com base nos documentos ingeridos. A resposta inclui citações que fazem referência aos documentos de origem por meio do alias do ponto de acesso Amazon S3.
### Para consultar usando o console
1. No console do Amazon Bedrock, abra sua base de conhecimento.
1. Escolha **Testar a base de conhecimento**.
1. Em **Gerar respostas**, selecione um modelo de geração de texto (por exemplo, **Nova Lite**).
1. Insira uma pergunta como `What are the pillars of the AWS Well-Architected Framework?` e escolha **Executar**. A resposta é exibida com referências de citação vinculadas aos documentos de origem no ponto de acesso do Amazon S3.
### Para consultar usando o AWS CLI
Use o comando `retrieve-and-generate`. Substitua os espaços reservados por seus valores. `modelArn`Deve se referir a um perfil de inferência para um modelo de geração de texto ao qual você tem acesso.
```
$ aws bedrock-agent-runtime retrieve-and-generate \
--input '{"text":"What are the pillars of the AWS Well-Architected Framework?"}' \
--retrieve-and-generate-configuration '{
"type":"KNOWLEDGE_BASE",
"knowledgeBaseConfiguration":{
"knowledgeBaseId":"{{knowledge-base-id}}",
"modelArn":"arn:aws:bedrock:{{region}}:{{account-id}}:inference-profile/us.amazon.nova-lite-v1:0"
}
}'
```
A resposta contém a resposta gerada `output.text` e uma lista de citações na `citations` matriz. Cada citação inclui um `s3Location.uri` campo que aponta para o documento fonte por meio do alias do ponto de acesso, no formulário. `s3://{{access-point-alias}}/{{file.pdf}}`
## Solução de problemas
Os arquivos de relatórios de tarefas de ingestão foram ignorados
O Amazon Bedrock Knowledge Bases impõe um tamanho máximo de arquivo de 50 MB por documento. Arquivos maiores que 50 MB são listados `failureReasons` e ignorados. Divida ou comprima documentos grandes antes de fazer o upload.
`ValidationException`: modelo marcado como Legacy
O modelo de geração de texto que você especificou foi descontinuado para sua conta. Escolha um perfil de inferência ativo, como `us.amazon.nova-lite-v1:0` ou outro modelo atualmente compatível. Execute `aws bedrock list-inference-profiles` para listar os perfis disponíveis.
`AccessDeniedException`durante a ingestão
Verifique se a função do IAM da base de conhecimento tem `s3:GetObject` e está `s3:ListBucket` no ARN do ponto de acesso (não no volume subjacente) e se o ponto de acesso tem uma origem de rede na Internet para que o serviço Amazon Bedrock possa alcançá-lo. Se você escolheu a alternativa OpenSearch Service Serverless na Etapa 2, verifique também se a política de acesso a dados lista a função como principal.
O trabalho de ingestão foi bem-sucedido, mas as consultas não retornam passagens relevantes
Confirme se o índice vetorial foi criado com `dimension: 1024` (para Titan Text Embeddings v2) e se os nomes dos campos no mapeamento do índice correspondem aos nomes dos campos configurados na base de conhecimento.
## Limpeza
Para evitar cobranças contínuas, exclua os recursos que você criou:
+ Base de conhecimento e fonte de dados do Amazon Bedrock
+ Índice vetorial e bucket vetorial do Amazon S3 (ou coleção OpenSearch Service Serverless, se você usou a alternativa na Etapa 2)
+ Função e política em linha do IAM
+ Objetos enviados para o ponto de acesso (se não forem mais necessários)
```
$ aws bedrock-agent delete-data-source --knowledge-base-id {{knowledge-base-id}} --data-source-id {{data-source-id}}
aws bedrock-agent delete-knowledge-base --knowledge-base-id {{knowledge-base-id}}
aws s3vectors delete-index --vector-bucket-name fsxn-kb-vectors --index-name bedrock-kb-index
aws s3vectors delete-vector-bucket --vector-bucket-name fsxn-kb-vectors
aws iam delete-role-policy --role-name fsxn-kb-role --policy-name kb-access
aws iam delete-role --role-name fsxn-kb-role
```
### Alternativa: limpar os recursos do OpenSearch Service Serverless
Se você escolheu a alternativa OpenSearch Service Serverless na Etapa 2, substitua os `s3vectors` comandos acima pelos seguintes. As coleções do Idle OpenSearch Service Serverless acumulam OCU-hour cobranças, portanto, exclua-as imediatamente quando terminar o tutorial.
```
$ # Get the collection ID (required by delete-collection; the name is not accepted)
COLLECTION_ID=$(aws opensearchserverless batch-get-collection --names fsxn-kb \
--query 'collectionDetails[0].id' --output text)
# Delete the collection, then the policies
aws opensearchserverless delete-collection --id "$COLLECTION_ID"
aws opensearchserverless delete-access-policy --name kb-data --type data
aws opensearchserverless delete-security-policy --name kb-net --type network
aws opensearchserverless delete-security-policy --name kb-enc --type encryption
```