Configurar integração RAG

Com New Relic, você pode aprimorar o agente New Relic AI com geração de recuperação de recuperação (RAG) associando sua documentação, runbooks, retros de incidentes e até mesmo código-fonte aos seus serviços. Esse processo fornece à New Relic AI melhores insights sobre problemas no seu sistema. O tutorial descreve como obter o ID da sua organização, criar uma ferramenta RAG e adicionar seus documentos à plataforma usando a API Blob.

Depois de adicionar seus documentos, você criará um relacionamento para associá-los à ferramenta RAG. Você pode então verificar sua configuração consultando os relacionamentos entre os documentos RAG e a ferramenta RAG. A etapa final é consultar a própria ferramenta RAG para recuperar informações relevantes e indexadas.

Para saber mais sobre o conector de conhecimento, consulte o Conector de conhecimento do New Relic AI.

Importante

Antes de executar as etapas a seguir, certifique-se de ter permissões de "Administrador de produto da organização".

Para começar a indexar seu conteúdo e se beneficiar do conector de conhecimento com o New Relic AI, siga estas etapas mencionadas:

Tarefa 1: Crie sua ferramenta 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 :

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

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
    }
  }
}

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.

Tarefa 2

Você tem duas opções para fornecer contexto à sua ferramenta de RAG. Você pode fazer upload manual de arquivos estáticos ou configurar um conector automatizado para documentação viva.

Opção A: Indexe seus documentos

Se você tiver documentos estáticos, como PDFs, arquivos do Word ou CSVs locais que não estão hospedados em uma base de conhecimento na nuvem, use o Document Knowledge Connector. Este método utiliza a API Blob para fazer upload de arquivos individuais diretamente para o New Relic. Use esta opção para:

**Contexto de uso único:** Upload de runbooks específicos ou diagramas de arquitetura que raramente mudam.
Dados locais: Indexação de arquivos proprietários ou internos que residem em sua máquina local em vez de em um wiki.
Testes agênticos: Fornecer rapidamente um conjunto específico de documentos a um agente de IA para um fluxo de trabalho focado.

Importante

Todos os documentos indexados ficam visíveis para todos os usuários da sua organização. Certifique-se de que os documentos indexados estejam em conformidade com suas políticas internas e não carregue dados confidenciais ou privados.

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:

Entre na sua conta New Relic.
Crie e gerencie sua chave de API na página de interface da chave de API .
Clique em Create a key e preencha os detalhes necessários (ou use uma existente com as permissões necessárias).

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

$curl -X POST https://blob-api.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
}

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

Nome do parâmetro	Tipo de dados	É obrigatório?	Descrição
`id`	Corda	Sim	O GUID exclusivo do documento RAG a ser recuperado.

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 :

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

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
      }
    }
  }
}

Opção B: Indexar seus documentos do Confluence

Se sua organização usa o Confluence para documentação, você pode indexar seus documentos do Confluence no New Relic sem precisar usar a API Blob. Esta opção permite que você conecte sua instância do Confluence e selecione documentos ou espaços específicos para serem indexados e associados à sua ferramenta RAG. Use esta opção para garantir que a New Relic AI sempre tenha a versão mais recente de suas páginas do Confluence.

O conector requer um token de API da Atlassian para buscar suas páginas. Armazene isso com segurança no gerenciador de segredos da New Relic.

Parâmetro de entrada

Nome do parâmetro	Tipo de dados	Obrigatório?	Descrição
descrição	Corda	Não	Um breve resumo para que o segredo é usado.
chave	Corda	Sim	O nome exclusivo usado para referenciar este segredo (por exemplo, `CONFLUENCE_API_TOKEN` ).
namespace	Corda	Sim	Deve ser definido como rag-datafetching para que o serviço de indexação RAG possa acessá-lo.
valor	Corda	Sim	O valor real do token da API do Confluence ou senha.
escopo	Objeto	Sim	Define o contexto organizacional; o tipo deve ser ORGANIZATION .

Mutação de amostra

mutation createSecretKey {
  secretsManagementCreateSecret(
    description: "Confluence API token for RAG indexing"
    key: "CONFLUENCE_API_TOKEN"
    namespace: "rag-datafetching"
    scope: { id: "YOUR_ORGANIZATION_ID", type: ORGANIZATION }
    value: "YOUR_CONFLUENCE_API_TOKEN"
  ) {
    key
  }
}

Defina a conexão com sua instância do Confluence. Isso atua como a ponte entre a New Relic e a Atlassian.

Parâmetro de entrada

Nome do parâmetro	Tipo de dados	Obrigatório?	Descrição
nome	Corda	Sim	Um nome descritivo para a integração (por exemplo, "Confluence de Engenharia").
url	Corda	Sim	Sua URL base do Confluence (por exemplo, https://example.atlassian.net/wiki ).
confluenceUserId	Corda	Sim	O endereço de e-mail ou ID associado ao seu token de API da Atlassian.
Chave secreta	Corda	Sim	O nome da chave que você definiu na etapa anterior ( `CONFLUENCE_API_TOKEN` ).
escopo	Objeto	Sim	Define o contexto da integração. O tipo deve ser definido como ORGANIZATION .
tags	Objeto	Não	Metadados opcionais usados para categorizar a integração por departamento ou equipe.

Mutação de amostra

mutation {
  entityManagementCreateConfluenceIntegration(
    confluenceIntegration: {
      name: "Engineering Confluence Integration"
      url: "https://your-company.atlassian.net/wiki"
      confluenceUserId: "your-confluence-user-id"
      secretKey: "CONFLUENCE_API_TOKEN" # From Step 2
      scope: { id: "YOUR_ORGANIZATION_ID", type: ORGANIZATION }
      tags: { key: "department", values: "engineering" }
    }
  ) {
    entity {
      id
    }
  }
}

Crie uma entidade de configurações de RAG para definir qual conteúdo buscar e como ele deve ser fragmentado.

Parâmetro de entrada

Nome do parâmetro	Tipo de dados	Obrigatório?	Descrição
confluenceIntegrationId	Corda	Sim	O ID exclusivo da integração do Confluence criada na etapa anterior.
confluenceQuery	Corda	Sim	Um filtro CQL (Confluence Query Language) (por exemplo, space = 'ENG')..
intervalSeconds	Interno	Sim	O número de segundos entre as execuções de indexação (por exemplo, 3600 a cada hora).
chunkSize	Interno	Sim	O número máximo de caracteres em cada segmento de texto (por exemplo, 4000).
Sobreposição de blocos	Interno	Sim	O número de caracteres para sobrepor entre segmentos de texto (por exemplo, 100) para manter o contexto.
Tipo de divisor de texto	Enum	Sim	O tipo de divisor de texto a ser usado (por exemplo, `MARKDOWN_TEXT_SPLITTER` ).
markdownTextSplitterOptions	Objeto	Não	Configuração para divisão de markdown, como em quais níveis de cabeçalho (#, ##) dividir.
Opções do divisor de texto por token	Objeto	Não	Configuração para divisão de tokens, incluindo o modelo de codificação (por exemplo, `O200K_BASE` ).
tags	Objeto	Não	Metadados opcionais para categorizar configurações (por exemplo, chave: `knowledge_category` , valores: `documentation` ).

Tipos de divisores de texto

Use estes tipos para definir o parâmetro textSplitterType:

TOKEN_TEXT_SPLITTER: Divisão precisa baseada em tokens.
MARKDOWN_TEXT_SPLITTER: Dividir por cabeçalhos markdown.
CHARACTER_TEXT_SPLITTER: Dividir por contagem de caracteres.
JSON_TEXT_SPLITTER: Dividir JSON recursivamente.
Se estiver usando TOKEN_TEXT_SPLITTER, defina a codificação em tokenTextSplitterOptions:
O200K_BASE: Para GPT-4o e modelos mais recentes (recomendado).

CL100K_BASE: Para GPT-4 e GPT-3.5.

Mutação de amostra

mutation {
  entityManagementCreateConfluenceRagSettings(
    confluenceRagSettingsEntity: {
      name: "Engineering Docs RAG Settings"
      scope: { id: "YOUR_ORGANIZATION_ID", type: ORGANIZATION }
      confluenceIntegrationId: "INTEGRATION_ID_FROM_STEP_3"
      confluenceQuery: "space = ENG AND type = page"
      intervalSeconds: 3600 # Re-index every hour
      # Chunking Configuration
      chunkSize: 4000
      chunkOverlap: 100
      textSplitterType: MARKDOWN_TEXT_SPLITTER
      # Optional: Markdown-specific options
      markdownTextSplitterOptions: {
        headersToSplitOn: "#,##,###"
        returnEachLine: false
      }
      # Optional: Token splitter options (if using TOKEN_TEXT_SPLITTER)
      # tokenTextSplitterOptions: {
      #   encodingName: O200K_BASE
      # }

      # Optional: Character splitter options (if using CHARACTER_TEXT_SPLITTER)
      # characterTextSplitterOptions: {
      #   separator: "\n\n"
      #   isSeparatorRegex: false
      # }

      tags: { key: "knowledge_category", values: "documentation" }
    }
  ) {
    entity {
      id
    }
  }
}

Vincular suas configurações de RAG à sua ferramenta de RAG via um relacionamento APPLY_TO ativa a indexação automatizada.

Parâmetro de entrada

Nome do parâmetro	Tipo de dados	Obrigatório?	Descrição
source.id	Corda	Sim	O ID das configurações de RAG criadas na etapa anterior.
target.id	Corda	Sim	O ID da ferramenta RAG criada na Tarefa 1.
tipo	Corda	Sim	Deve ser definido como `APPLY_TO` para conexões de configurações para ferramenta.
tags	Corda	Sim	Metadados opcionais usados para rotular o relacionamento (por exemplo, chave: " `auto_created` ", valores: " `true` ")

Mutação de amostra

mutation {
  entityManagementCreateRelationship(
    relationship: {
      source: { id: "RAG_SETTINGS_ID_FROM_STEP_4", scope: ORGANIZATION }
      target: { id: "RAG_TOOL_ID_FROM_STEP_1", scope: ORGANIZATION }
      type: "APPLY_TO"
      tags: { key: "auto_created", values: "true" }
    }
  ) {
    relationship {
      type
    }
  }
}

Resultado: Indexação automática acionada

A indexação agora ocorrerá automaticamente!

Quando o relacionamento APPLY_TO é criado entre suas configurações de RAG e sua ferramenta de RAG, o serviço de indexador RAG da New Relic inicia o seguinte processo em segundo plano:

O serviço usa seu confluenceQuery para pesquisar conteúdo correspondente em sua instância do Confluence.
Recupera todas as páginas correspondentes e as transforma em um formato processável.
O conteúdo é dividido em segmentos menores com base na sua configuração de chunkSize, chunkOverlap e textSplitterType.
O serviço gera embeddings densos e esparsos para cada fragmento e os indexa no banco de dados vetorial (Pinecone).
O conector reindexará seu conteúdo periodicamente com base no intervalSeconds que você definiu para garantir que a IA tenha acesso à documentação mais atualizada.

Tarefa 3: Recuperar informações relevantes

Após estabelecer um relacionamento (seja vinculando um documento RAG específico via INDEXED_FOR ou aplicando uma configuração do Confluence via APPLY_TO), você pode verificar a associação e consultar a ferramenta. Isso garante que seu conhecimento interno seja devidamente indexado e esteja disponível para a New Relic AI apresentar respostas sensíveis ao contexto.

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
          }
        }
      }
    }
  }
}

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

Nome do parâmetro	Tipo de dados	É obrigatório?	Descrição
`prompt`	Corda	Sim	A consulta em linguagem natural que você deseja que a ferramenta RAG processe.
`toolId`	Corda	Sim	O GUID exclusivo da ferramenta RAG a ser consultado.

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.

Esta tradução de máquina é fornecida para sua comodidade.

Importante

Tarefa 1: Crie sua ferramenta RAG .css-21sua1{background:none;border:none;width:0;padding:0;}

Criar uma ferramenta RAG

Tarefa 2

Opção A: Indexe seus documentos

Carregar um documento por meio da API Blob

Visualize a entidade do documento RAG representada no NerdGraph

Crie um relacionamento entre a ferramenta RAG e o documento RAG

Opção B: Indexar seus documentos do Confluence

Armazene seu token de API do Confluence

Criar a integração do Confluence

Configurar lógica de indexação (configurações de RAG)

Criar relacionamento

Resultado: Indexação automática acionada

Tarefa 3: Recuperar informações relevantes

consulta para ver as relações entre os documentos RAG e as ferramentas RAG

consulte a ferramenta RAG

Tarefa 1: Crie sua ferramenta RAG