Tutorial do NerdGraph: Configurar integração RAG

O ID da organização identifica exclusivamente sua conta e garante que qualquer ferramenta RAG que você criar, documentos que você enviar ou relacionamentos que você estabelecer sejam associados à sua organização no New Relic.

O ID da organização é necessário para executar mutações e consultas no NerdGraph ao configurar e gerenciar ferramentas e documentos do RAG. Execute a seguinte consulta e mantenha o ID da organização em mãos para etapas posteriores.

Exemplo de consulta

{
  actor {
    organization {
      id
    }
  }
}

Uma ferramenta RAG atua como um contêiner especializado para organizar documentos e recursos relacionados no New Relic. Um nome claro e uma descrição precisa para suas ferramentas RAG ajudam o LLM a selecionar a ferramenta certa para cada prompt, garantindo respostas relevantes e contextualizadas.

Para criar uma nova ferramenta RAG na sua conta New Relic, execute a seguinte mutação entityManagementCreateRagTool :

1. Certifique-se de substituir ${ORGANIZATION_ID} pelo ID real da sua organização obtido na etapa anterior.

2. Se for bem-sucedido, você receberá um id para sua ferramenta RAG.

   Parâmetro de entrada

   Nome do parâmetro	Tipo de dados	É obrigatório?	Descrição
   ragToolEntity	Objeto	Sim	O objeto de entrada que contém a configuração para a nova ferramenta RAG.
   description	Corda	Sim	Uma descrição clara e precisa do propósito da ferramenta RAG.
   name	Corda	Sim	O nome exclusivo para sua ferramenta RAG.
   scope	Objeto	Sim	Um objeto que define o contexto no qual a ferramenta será criada.
   scope.id	Corda	Sim	O ID único da sua organização ( ${ORGANIZATION_ID} ).
   scope.type	Corda	Sim	O tipo do escopo, que deve ser ORGANIZATION .

   Mutação de amostra

   mutation {
     entityManagementCreateRagTool(
       ragToolEntity: {
         description: "Runbooks for resolving incidents with APIs",
         name: "API Runbooks",
         scope: {id: `${ORGANIZATION_ID}`, type: ORGANIZATION}
       }
     ) {
       entity {
         id
       }
     }
   }

   Copiar

   Você deve salvar o id retornado, pois precisará dele em etapas posteriores para vincular documentos à ferramenta, verificar relacionamentos e consultar a ferramenta para obter informações relevantes no New Relic.

A API Blob e sua finalidade

A Blob API é um serviço da New Relic projetado para enviar arquivos, como documentação e runbooks, para sua conta. O NerdGraph é otimizado para consultas e mutações de dados estruturados e não para transferência eficiente de arquivos, então a API Blob é necessária para carregar documentos.

Requisitos de autenticação

Você precisa de uma chave de API válida do New Relic com permissões para fazer upload de documentos. Para obter a chave de API para enviar um documento para o New Relic usando a API Blob:

1. Entre na sua conta New Relic.

2. Crie e gerencie sua chave de API na página de interface da chave de API .

3. Clique em Create a key e preencha os detalhes necessários (ou use uma existente com as permissões necessárias).

4. Clique em Create a key e copie a chave gerada (ela se parecerá com NRAK-XXXXXXXXXX).

   Aqui está um exemplo de como fazer upload de um documento usando um comando curl bash :

   Parâmetro de entrada

   Nome do parâmetro	Tipo de dados	É obrigatório?	Descrição
   Api-Key	Corda	Sim	Sua chave de API do New Relic para autenticação.
   NewRelic-Entity	Objeto JSON	Sim	Informações sobre o documento, como seu nome.
   Content-Type	Corda	Sim	O formato do arquivo que está sendo carregado (por exemplo, application/json ).
   payload ( @incidents.json )	Arquivo	Sim	O arquivo de documento que você está carregando, especificado pelo caminho do arquivo.

   Exemplo de consulta

   bash

   Copiar

   $
   curl -X POST https://blob-api.one-service.newrelic.com/v1/e/organizations/$ORGANIZATION_ID/RagDocuments \
   >
        -H 'Api-Key: NRAK-XXXXXXXXXX' \
   >
        -H 'NewRelic-Entity: {"name": "Runbooks for API service" }' \
   >
        -H 'Content-Type: application/json' \
   >
        -d @incidents.json

   Resposta de amostra

   Resposta	Tipo de dados	Descrição
   entityGuid	Corda	O identificador exclusivo para o documento RAG carregado.
   blobVersionEntity	Objeto	Representa a versão do blob carregado.

   {
     "entityGuid": "MTIyODU0NTN8TkdFUHxSQUdfRE9DVU1FTlR8MDE5NGUyOTgtYmQzMS03NzA4LWI3NzItYzQ4MTZlYjNhYThk",
     "blobVersionEntity": null
   }

   Copiar

   Próximos passos

   Após o upload do seu documento, ele é indexado e fica disponível para o New Relic AI pesquisar e recuperar. Você deve salvar o entityGuid da resposta para criar um relacionamento com sua ferramenta RAG ou para consultar o documento no NerdGraph.

Depois que um documento é carregado por meio da API Blob, a execução desta consulta confirma que o carregamento foi bem-sucedido e que o documento foi registrado corretamente como uma entidade de documento RAG com seu próprio identificador e propriedades exclusivos.

Parâmetro de entrada

Exemplo de consulta

Na consulta abaixo, substitua o espaço reservado ${RAG_DOCUMENT_GUID} pelo entityGuid que você recebeu na etapa anterior.

{
  actor {
    entityManagement {
      entity(
        id: `${RAG_DOCUMENT_GUID}`
      ) {
        ... on EntityManagementRagDocumentEntity {
          id
          name
          blob {
            url
          }
          type
        }
      }
    }
  }
}

Esta consulta retornará os seguintes detalhes sobre seu documento RAG:

• id: O ID único do documento RAG.
• name: O nome do documento RAG.
• blob { url }: A URL para acessar o documento carregado.
• type: O tipo da entidade, que neste caso é EntityManagementRagDocumentEntity.

Agora que você criou uma ferramenta RAG, carregou seu documento e verificou que o upload foi bem-sucedido, a próxima etapa é associar a ferramenta RAG e o documento RAG, tornando seu documento pesquisável e utilizável pelo New Relic AI. Para fazer isso, execute a mutação entityManagementCreateRelationship :

1. Substitua ${RAG_DOCUMENT_GUID} por entityGuid da resposta do upload do documento via API Blob.

2. Substitua ${RAG_TOOL_GUID} por id da resposta da mutação de criação da ferramenta RAG.

   Parâmetro de entrada

   Nome do parâmetro	Tipo de dados	É obrigatório?	Descrição
   relationship	Objeto	Sim	O objeto de entrada que contém os detalhes do relacionamento.
   source	Objeto	Sim	A entidade de origem do relacionamento, que é o documento RAG.
   source.scope	Corda	Sim	O escopo da entidade de origem, que deve ser ORGANIZATION .
   source.id	Corda	Sim	O GUID exclusivo do documento RAG ( ${RAG_DOCUMENT_GUID} ).
   target	Objeto	Sim	O destino entidade do relacionamento, que é a ferramenta RAG.
   target.scope	Corda	Sim	O escopo da entidade de destino, que deve ser ORGANIZATION .
   target.id	Corda	Sim	O GUID exclusivo da ferramenta RAG ( ${RAG_TOOL_GUID} ).
   type	Corda	Sim	O tipo de relacionamento, que deve ser "INDEXED_FOR" .

   Mutação de amostra

   mutation {
     entityManagementCreateRelationship(
       relationship: {
         source: {
           scope: ORGANIZATION,
           id: `${RAG_DOCUMENT_GUID}`
         },
         target: {
           scope: ORGANIZATION,
           id: `${RAG_TOOL_GUID}`
         },
         type: "INDEXED_FOR"
       }
     ) {
       relationship {
         type
         target {
           id
           type
         }
         source {
           id
           type
         }
       }
     }
   }

   Copiar

Depois de criar um relacionamento entre seu documento RAG e a ferramenta RAG, você pode verificar a associação consultando relacionamentos no NerdGraph. Isso ajuda a garantir que seu documento esteja devidamente vinculado e disponível para uso pelo New Relic AI.

• Substitua ${RAG_DOCUMENT_ID} pelo entityGuid do seu documento carregado.

  Parâmetro de entrada

  Nome do parâmetro	Tipo de dados	É obrigatório?	Descrição
  relationships	Consulta	Sim	A consulta para recuperar relacionamentos entre entidades.
  filter	Objeto	Não	Um objeto usado para filtrar relacionamentos com base em atributos.
  filter.sourceId	Objeto	Não	Um objeto a ser filtrado pelo identificador exclusivo da entidade de origem.
  filter.sourceId.eq	Corda	Não	O GUID exclusivo do documento RAG a ser correspondido.

  Exemplo de consulta

  {
    actor {
      entityManagement {
        relationships(
          filter: {sourceId: {eq: `${RAG_DOCUMENT_ID}`}}
        ) {
          items {
            type
            target {
              id
              type
            }
          }
        }
      }
    }
  }

  Copiar

Depois de configurar sua ferramenta RAG e indexar os documentos, você pode consultá-la para recuperar informações relevantes com base em seu prompt. Isso permite que a New Relic AI revele respostas contextuais usando a documentação da sua organização.

Parâmetro de entrada

Exemplo de consulta

{
  actor {
    machineLearning {
      ragQueryData(
        prompt: "tell me about the incident", 
        toolId: `${RAG_TOOL_GUID}`
      ) {
        blobId
        chunk
        documentId
        score
        toolId
      }
    }
  }
}

A resposta incluirá correspondências fragmentadas dos seus documentos indexados, que você pode usar diretamente ou resumir com o New Relic AI.