View a markdown version of this page

Usar a recuperação com agente para consultar uma base de conhecimentos - Amazon Bedrock
Como funciona a recuperação de agentesPré-requisitosConsulte uma base de conhecimento com recuperação de agentesResposta de recuperação de agentesPermissõ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á.

Usar a recuperação com agente para consultar uma base de conhecimentos

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 de questões complexas de várias etapas que um único passe 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 configurados da base de conhecimento. 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 ao longo do processo para fins de observação.

Pré-requisitos

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

  • Uma base de conhecimento totalmente gerenciada da Amazon Bedrock. Atualmente, a recuperação agente 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 de IAM necessárias. Para obter mais informações, consulte Permissões necessárias para recuperação de agentes.

Consulte uma base de conhecimento com recuperação de agentes

Para usar a recuperação agente, envie uma solicitação. AgenticRetrieveStream 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).
recuperadores A base de conhecimento é recuperada para buscar dados. Você pode especificar até 5 recuperadores, cada um apontando para uma base de conhecimento gerenciada por meio de seu ID. Opcionalmente, cada recuperador pode incluir filtros de metadados e um número máximo de resultados.
agente 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 de 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 de solicitação e resposta, consulte AgenticRetrieveStream na referência da API.

Resposta de recuperação de agentes

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

  • Evento de resultado (AgenticRetrieveResultEvent) — O evento final entregue quando o processamento é concluído. Contém os resultados da recuperação e, quando a geração de respostas 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 bloco é 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 da 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 idioma natural.

  • Trace events (AgenticRetrieveTraceEvent) — Eventos transmitidos durante o processo de recuperação do 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 alvo.

    • 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 resultados usando a consulta bruta do usuário. Para várias bases de conhecimento, isso realiza uma pesquisa de sonda para ajudar a encaminhar as consultas para os recuperadores apropriados.

    • Expansão completa do documento — Indica que o agente está recuperando todo o conteúdo de um documento específico. Inclui a ID do documento, o recuperador de origem e o status (InProgresssucesso ou falha).

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

Para usar a AgenticRetrieveStream API, a identidade do IAM de chamada deve 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ê usar grades de proteção com recuperação de agentes, 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 agente só oferece suporte às bases de conhecimento gerenciadas do Amazon Bedrock.

  • Para obter cotas de recuperadores por solicitação, resultados por chamada de recuperação e 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 guardrails, somente a BLOCK ação é suportada. A MASK ação não é suportada pela recuperação de agentes.

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