Ligar a fontes de conhecimento personalizadas

O Copilot Studio inclui fontes de conhecimento incorporadas, como o SharePoint e o Dataverse. Muitas organizações também utilizam os seus próprios pontos finais de pesquisa, como APIs personalizadas, sistemas de pesquisa empresariais existentes ou a Pesquisa de IA do Azure, mantendo controlo total sobre a consulta que é executada.

O Copilot Studio suporta este cenário com o acionador OnKnowledgeRequested. Qualquer tópico que utilize este acionador funciona como uma fonte de conhecimento personalizada e contribui com resultados para respostas generativas.

Este artigo explica como criar e integrar fontes de conhecimento personalizadas no Copilot Studio através do acionador OnKnowledgeRequested. Irá ficar a saber como o Copilot Studio reescreve consultas, como estabelecer ligação à sua própria API de pesquisa, como formatar os resultados para respostas generativas e quais são as melhores práticas ao trabalhar com conhecimento personalizado.

O acionador OnKnowledgeRequested

Utilize o acionador OnKnowledgeRequested nestas duas situações:

  • Quando o orquestrador determina que é necessária a obtenção de conhecimento para responder a uma consulta do utilizador.
  • Quando um nó de resposta generativa é invocado explicitamente na conversação.

Importante

Só pode configurar este acionador em vista de código utilizando YAML. Não existe suporte para estruturador visual.

Os tópicos que usam OnKnowledgeRequested têm acesso a variáveis do sistema que não estão disponíveis nos tópicos regulares:

  • System.SearchQuery: Uma versão reescrita, sensível ao contexto, da consulta do utilizador, otimizada para pesquisa semântica.
  • System.KeywordSearchQuery: Uma consulta reescrita otimizada para motores de pesquisa baseados em palavras-chave.
  • System.SearchResults: Onde o tópico armazena fragmentos de conhecimento formatados.

O Copilot Studio reescreve inteligentemente as consultas utilizando o histórico da conversação, assegurando que preserva o contexto de vários turnos.

Criar uma fonte de conhecimento personalizada

Para criar uma fonte de conhecimento personalizada, crie um tópico com o acionador OnKnowledgeRequested que chama a sua API de pesquisa e transforma os resultados no formato que o Copilot Studio espera.

Passo 1: Criar o acionador

Crie um novo tópico no Copilot Studio, mude para a vista de código e defina o acionador OnKnowledgeRequested.

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  intent: {}
  actions:
    # Actions go here
inputType: {}
outputType: {}

Esta estrutura informa o Copilot Studio que este tópico é responsável por responder a pedidos de conhecimento.

Passo 2: Adicionar um pedido HTTP

Adicione uma ação HTTP que chame o seu ponto final de pesquisa.

Exemplo:

- kind: HttpRequestAction
  id: searchRequest
  url: = "https://search-api.contoso.com/search?q=" & System.KeywordSearchQuery
  response: Topic.searchResults
  responseSchema:
    kind: Record
    properties:
      query: String
      results:
        type:
          kind: Table
          properties:
            snippet: String
            title: String
            url: String

Concatene System.KeywordSearchQuery ao seu URL de base, porque o Copilot Studio reescreve automaticamente a consulta do utilizador com o contexto da conversação antes de efetuar o pedido de pesquisa. Este passo é importante para manter o contexto em conversações com vários turnos.

Sugestão

Em vez de um pedido HTTP não processado, pode usar qualquer método que obtenha resultados de um ponto final de pesquisa, incluindo conectores personalizados, conectores incorporados como Pesquisa de IA do Azure ou fluxos de agente.

Exemplo de reformulação de consultas

  • Consulta de utilizador 1: "Qual é o nosso período de retenção de dados oficial para registos de clientes?"
  • Pergunta de seguimento: "Muda para informações financeiras?"
  • Pergunta de seguimento: "E há exceções?"

A consulta reescrita torna-se: "exceções à política de retenção de dados exceções de retenção de dados de clientes e financeiros isenções regulamentares processamento de exceções de políticas diretrizes de conformidade"

Observe que a consulta reescrita:

  • Resolve "there" para política de retenção de dados
  • Extrai o contexto das rondas anteriores: dados do cliente + dados financeiros
  • Adiciona linguagem de política empresarial: exceções, isenções, regulamentação, diretrizes

Passo 3: Transformar resultados

Uma fonte de conhecimento personalizada deve apresentar os resultados no formato esperado pelo Copilot Studio. Este formato utiliza:

  • Conteúdo: Fragmento ou excerto.
  • ContentLocation (opcional): URL.
  • Título (opcional): Título do resultado.

Para definir a estrutura da resposta HTTP, configure o esquema de resposta na interface de utilizador do Copilot Studio.

  • Selecione A partir de dados de exemplo para o tipo de dados de resposta.
  • Selecione Obter esquema a partir de exemplo de JSON.
  • Cole o seu payload JSON de exemplo para gerar automaticamente o esquema.

Este processo gera o esquema de resposta no seu ficheiro YAML.

responseSchema:
  kind: Record
  properties:
    query: String
    results:
      type:
        kind: Table
        properties:
          snippet: String
          title: String
          url: String

De seguida, transforme a resposta da sua API para corresponder a este formato. Atribua os dados transformados a System.SearchResults.

Exemplo de transformação

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  intent: {}
  actions:
    - kind: HttpRequestAction
      id: searchRequest
      url: ="https://search-api.contoso.com/search?q=" & System.KeywordSearchQuery
      response: Topic.searchResults
      responseSchema:
        kind: Record
        properties:
          query: String
          results:
            type:
              kind: Table
              properties:
                snippet: String
                title: String
                url: String
    
    - kind: SetVariable
      id: setSearchResults
      variable: System.SearchResults
      value: |-
        =ForAll(Topic.searchResults.results,
        {
          Content: snippet,
          ContentLocation: url,
          Title: title
        })

inputType: {}
outputType: {}

A ação SetVariable executa ambas as operações:

  • A função ForAll transforma cada resultado de pesquisa, mapeando snippet para Content, url para ContentLocation e title para Title.
  • A tabela transformada é atribuída a System.SearchResults, que é a variável que o Copilot Studio usa para gerar respostas.

Considerações

Tenha estas considerações importantes em mente ao criar fontes de conhecimento personalizadas.

Limites de resultados

O Copilot Studio utiliza até 15 fragmentos de System.SearchResults para gerar uma resposta. Se a sua API devolver mais resultados, considere:

  • Implementar pontuação de relevância para devolver os melhores resultados primeiro.
  • Limitar a resposta da API a 15 resultados.
  • Ordenar os resultados por relevância antes da transformação.

Vários tópicos de conhecimento personalizados

Pode criar vário tópicos usando OnKnowledgeRequested, e cada tópico pode consultar diferentes sistemas de back-end. O Copilot Studio invoca todos simultaneamente quando precisa de conhecimento. Esta abordagem permite consultar diferentes pontos finais de pesquisa ou implementar estratégias de contingência.

Aviso

O limite de resultados aplica-se ao conjunto de todos os tópicos de conhecimento. Se o Tópico A devolver 10 resultados e o Tópico B 8, apenas os 15 principais resultados combinados são utilizados.

Recomendações

  • Ordene ou pontue os resultados antes de os devolver.
  • Mantenha os esquemas de resposta consistentes.
  • Use nomes e descrições claras para os tópicos. Esta prática é útil quando grandes conjuntos de resultados requerem filtragem de relevância.
  • Last updated on