View a markdown version of this page

Use a recuperação agente para consultar uma base de conhecimento - Amazon Bedrock
Como funciona a recuperação de agentesPré-requisitosConsulte uma base de conhecimento com recuperação agenteResposta de recuperação agentePermissões necessárias para recuperação de agentesConsiderações

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

Use a recuperação agente para consultar uma base de conhecimento

A recuperação agente usa um modelo básico para decompor de forma inteligente consultas complexas em subconsultas, recuperar iterativamente informações relevantes de suas bases de conhecimento e avaliar se os resultados recuperados são suficientes para responder à consulta original. Essa abordagem melhora a precisão da recuperação para questões complexas de várias etapas que uma única etapa de recuperação pode não resolver totalmente.

Por exemplo, dada a pergunta “Qual revista foi criada primeiro, Arthur's Magazine ou First for Women?” , a recuperação agente divide isso em subconsultas separadas, como “Quando foi fundada a Arthur's Magazine?” e “Quando foi fundada a First for Women?” , recupera os resultados de cada um e avalia se os resultados combinados são suficientes.

Como funciona a recuperação de agentes

Quando você envia uma solicitação para a AgenticRetrieveStream API, ocorre o seguinte processo:

  1. Planejamento — O modelo básico analisa sua consulta e cria um plano para decompô-la em uma ou mais subconsultas. Cada subconsulta tem como alvo um recuperador específico que você configurou. Depois que os resultados da recuperação são coletados, o modelo básico avalia se eles são suficientes para responder à consulta original. Caso contrário, ele planeja e executa iterações de recuperação adicionais, até o máximo configurado.

  2. Recuperação — As subconsultas são executadas nos recuperadores da base de conhecimento configurados. Os resultados são coletados de cada recuperação.

  3. Expansão total do documento — quando o modelo básico determina que o conteúdo completo de um documento é necessário (por exemplo, para resumir, verificar a integridade ou acessar seções específicas), ele chama a GetDocumentContent API para recuperar o conteúdo completo do documento.

  4. Geração de resposta — Quando generateResponse definido como true (o padrão), o modelo básico sintetiza uma resposta em linguagem natural a partir dos resultados recuperados. A resposta é transmitida de volta para você por meio de responseEvent eventos.

  5. Evento de resultado — Os resultados da recuperação desduplicada de todas as iterações, a resposta completa em linguagem natural sintetizada e as citações são devolvidas a você. Os eventos de rastreamento são transmitidos durante todo o processo para fins de observabilidade.

Pré-requisitos

Antes de usar a recuperação agente, você deve ter o seguinte:

  • Uma base de conhecimento totalmente gerenciada do Amazon Bedrock. Atualmente, a recuperação de agentes oferece suporte somente a bases de conhecimento gerenciadas.

  • Acesso a um modelo básico no Amazon Bedrock para uso no planejamento e avaliação de consultas.

  • As permissões necessárias do IAM. Para obter mais informações, consulte Permissões necessárias para recuperação de agentes.

Consulte uma base de conhecimento com recuperação agente

Para usar a recuperação agente, envie uma AgenticRetrieveStreamsolicitação. A resposta é um fluxo que inclui resultados de recuperação e eventos de rastreamento.

A tabela a seguir descreve os principais campos de solicitação:

Campos obrigatórios
Campo Description
mensagens A consulta de entrada e o histórico da conversa. Cada mensagem contém um content campo com um text valor e um role campo (userouassistant).
retrievers A base de conhecimento recupera os dados. Você pode especificar até 5 recuperadores, cada um apontando para uma base de conhecimento gerenciada por sua ID. Cada recuperador pode, opcionalmente, incluir filtros de metadados e um número máximo de resultados.
agêntico RetrieveConfiguration A configuração de recuperação do agente, incluindo o modelo básico a ser usado para planejamento e avaliação de consultas e, opcionalmente, um modelo de reclassificação e a contagem máxima de iterações do agente.
Campos opcionais
Campo Description
Configuração da política Configura uma grade de proteção Amazon Bedrock para ser aplicada durante a recuperação do agente. Especifique um guardrailId guardrailVersion e.
Contexto do usuário Fornece um contexto de usuário para filtragem de controle de acesso.
Gerar resposta Um campo booleano que, quando definido como true (o padrão), instrui o modelo básico a gerar uma resposta em linguagem natural a partir dos resultados recuperados. A resposta é transmitida de volta como pedaços de texto e incluída no evento resultante.

Para ver a sintaxe completa da solicitação e da resposta, consulte AgenticRetrieveStreama referência da API.

Resposta de recuperação agente

A AgenticRetrieveStream resposta é um fluxo que contém os seguintes tipos de eventos:

  • Evento resultante (AgenticRetrieveResultEvent) — O evento final entregue quando o processamento é concluído. Contém os resultados da recuperação e, quando a geração de resposta está ativada, a resposta gerada. O evento resultante inclui:

    • Resultados da recuperação (results) — Os fragmentos de origem recuperados em todas as iterações. Cada resultado inclui conteúdo, identificador do recuperador de origem e metadados opcionais. Quando o mesmo fragmento é recuperado por várias subconsultas, ele aparece apenas uma vez nos resultados finais.

    • Resposta gerada (generatedResponse) — Quando generateResponse definido como true (o padrão), o evento resultante inclui um generatedResponse objeto contendo:

      • answer— O texto completo da resposta em linguagem natural sintetizado.

      • citations— Uma lista opcional que mapeia extensões da resposta para apoiar os resultados de recuperação. Cada citação contém:

        • startIndex— O deslocamento de caracteres em que a passagem citada começa dentro da answer string.

        • endIndex— O deslocamento de caracteres onde a passagem citada termina (exclusivo — o texto citado vai de startIndex até, mas não incluiendIndex).

        • references— Uma lista em que cada referência tem um resultIndex campo indexado na results matriz no mesmo evento de resultado, indicando qual resultado de recuperação suporta o intervalo citado.

  • Eventos de resposta (AgenticRetrieveResponseEvent) — Quando generateResponse definido como true (o padrão), os responseEvent eventos são transmitidos durante a geração da resposta. Cada evento contém um text campo com uma parte incremental da resposta sintetizada em linguagem natural.

  • Trace events (AgenticRetrieveTraceEvent) — Eventos transmitidos durante o processo de recuperação agente que fornecem visibilidade de cada etapa. Estes são os tipos de eventos de rastreamento:

    • Planejamento — Indica que o modelo básico está analisando a consulta e criando subconsultas. Inclui as ações planejadas e os recuperadores de alvos.

    • Recuperação — Indica que uma recuperação está sendo executada em uma base de conhecimento. Inclui a entrada de recuperação, a saída e quaisquer avisos ou falhas.

    • Recuperação especulativa — Uma recuperação inicial que é executada antes da primeira etapa de planejamento para reduzir a latência. Para uma única base de conhecimento, isso recupera os resultados usando a consulta bruta do usuário. Para várias bases de conhecimento, isso executa uma pesquisa de sondagem para ajudar a encaminhar as consultas para os recuperadores apropriados.

    • Expansão total do documento — indica que o agente está recuperando o conteúdo completo de um documento específico. Inclui a ID do documento, o recuperador de origem e o status (InProgress, Sucesso ou Falha).

Permissões necessárias para recuperação de agentes

Para usar a AgenticRetrieveStream API, a identidade do IAM de chamada precisa ter as seguintes permissões:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "bedrock:AgenticRetrieveStream",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:Retrieve",
                "bedrock:GetDocumentContent"
            ],
            "Resource": "arn:aws:bedrock:region:account-id:knowledge-base/*"
        },
        {
            "Effect": "Allow",
            "Action": "bedrock:InvokeModelWithResponseStream",
            "Resource": "*"
        }
    ]
}

Se você usa grades de proteção com recuperação agente, adicione as seguintes permissões:

{
    "Effect": "Allow",
    "Action": [
        "bedrock:GetGuardrail",
        "bedrock:ApplyGuardrail"
    ],
    "Resource": "*"
}

Considerações

Lembre-se do seguinte ao usar a recuperação agente:

  • A recuperação por agentes só oferece suporte às bases de conhecimento gerenciadas do Amazon Bedrock.

  • Para cotas de recuperadores por solicitação, resultados por chamada de recuperação e número máximo de iterações de agentes, consulte. Cotas de serviço para bases de conhecimento gerenciadas

  • Reduzir a contagem máxima de iterações pode fazer com que o agente pare mais cedo, potencialmente reduzindo a precisão de consultas complexas.

  • Ao configurar grades de proteção, somente a BLOCK ação é suportada. A MASK ação não é compatível com a recuperação de agentes.

  • O cliente fornece e possui o modelo básico, o modelo de incorporação e o modelo de reclassificação usados durante a recuperação do agente, se fornecido. Suas credenciais do IAM são usadas para invocar esses modelos.