Se connecter à des sources de connaissances personnalisées

Copilot Studio inclut des sources de connaissances intégrées telles que SharePoint et Dataverse. De nombreuses organisations utilisent également leurs propres points de terminaison de recherche, tels que des API personnalisées, des systèmes de recherche d’entreprise existants ou Azure AI Search, tout en conservant un contrôle total sur la requête exécutée.

Copilot Studio prend en charge ce scénario avec le déclencheur OnKnowledgeRequested. Toute rubrique qui utilise ce déclencheur agit comme une source de connaissances personnalisée et contribue aux résultats aux réponses génératives.

Cet article explique comment créer et intégrer des sources de connaissances personnalisées dans Copilot Studio à l’aide du OnKnowledgeRequested déclencheur. Vous découvrez comment Copilot Studio réécrit des requêtes, comment se connecter à votre propre API de recherche, mettre en forme les résultats pour les réponses génératives et les meilleures pratiques lors de l’utilisation de connaissances personnalisées.

Déclencheur OnKnowledgeRequested

Utilisez le OnKnowledgeRequested déclencheur dans ces deux situations :

  • Lorsque l’orchestrateur détermine que la récupération des connaissances est nécessaire pour répondre à une requête utilisateur.
  • Lorsqu’un nœud de réponses génératives est explicitement appelé dans la conversation.

Important

Vous pouvez uniquement configurer ce déclencheur en mode code à l’aide de YAML. Il n’existe aucune prise en charge du concepteur visuel.

Les rubriques qui utilisent OnKnowledgeRequested ont accès aux variables système qui ne sont pas disponibles dans les rubriques régulières :

  • System.SearchQuery: version réécrite de la requête de l’utilisateur optimisée pour la recherche sémantique.
  • System.KeywordSearchQuery: requête réécrite optimisée pour les moteurs de recherche basés sur des mots clés.
  • System.SearchResults: Où la rubrique stocke les extraits de connaissances mis en forme.

Copilot Studio réécrit intelligemment les requêtes à l’aide de l’historique des conversations, ce qui permet de préserver le contexte de plusieurs échanges.

Création d’une source de connaissances personnalisée

Pour créer une source de connaissances personnalisée, vous créez une rubrique avec le OnKnowledgeRequested déclencheur qui appelle votre API de recherche et transforme les résultats dans le format attendu par Copilot Studio.

Étape 1 : Créer le déclencheur

Créez une rubrique dans Copilot Studio, basculez vers la vue de code et définissez le OnKnowledgeRequested déclencheur.

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

Cette structure indique à Copilot Studio que cette rubrique est chargée de répondre aux demandes de connaissances.

Étape 2 : Ajouter une requête HTTP

Ajoutez une action HTTP qui appelle votre point de terminaison de recherche.

Exemple :

- 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

Concaténer System.KeywordSearchQuery à votre URL de base, car Copilot Studio réécrit automatiquement la requête utilisateur avec le contexte de conversation avant d’effectuer la requête de recherche. Cette étape est importante pour maintenir le contexte entre les conversations à plusieurs étapes.

Tip

Au lieu d’une requête HTTP brute, vous pouvez utiliser n’importe quelle méthode qui obtient des résultats à partir d’un point de terminaison de recherche, y compris des connecteurs personnalisés, des connecteurs intégrés tels qu’Azure AI Search ou des flux d’agent.

Exemple de réécriture de requête

  • Requête utilisateur 1 : « Quelle est notre période de rétention officielle des données pour les enregistrements clients ? »
  • Requête de suivi : « Est-ce que cela change pour les informations financières ? »
  • Requête de suivi : « Et y a-t-il des exceptions ? »

La requête réécrite devient : « exceptions à la politique de rétention des données client et exceptions de rétention des données financières, exemptions réglementaires, gestion des exceptions, directives de conformité »

Notez que la requête réécrite :

  • Résout « there » en stratégie de conservation des données
  • Met en avant le contexte des deux interactions précédentes : données client + données financières
  • Ajoute le langage de stratégie d’entreprise : exceptions, exemptions, réglementation, instructions

Étape 3 : Transformer les résultats

Une source de connaissances personnalisée doit générer des résultats dans le format attendu par Copilot Studio. Ce format utilise :

  • Contenu : Extrait ou extrait de texte.
  • ContentLocation (facultatif) : URL.
  • Titre (facultatif) : titre du résultat.

Pour définir la structure de la réponse HTTP, configurez le schéma de réponse dans l’interface utilisateur de Copilot Studio.

  • Sélectionnez Parmi les exemples de données pour le type de données de réponse.
  • Sélectionnez Obtenir le schéma à partir de l’exemple JSON.
  • Collez votre exemple de charge utile JSON pour générer automatiquement le schéma.

Ce processus génère le schéma de réponse dans votre fichier YAML.

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

Ensuite, transformez la réponse de votre API pour qu’elle corresponde à ce format. Affectez les données transformées à System.SearchResults.

Exemple de transformation

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

L’action SetVariable effectue les deux opérations :

  • La ForAll fonction transforme chaque résultat de recherche, en mappant snippetContent, url en ContentLocationet title en Title.
  • La table transformée est affectée à System.SearchResults, qui est la variable Que Copilot Studio utilise pour générer des réponses.

Considérations

Gardez ces considérations clés à l’esprit lorsque vous créez des sources de connaissances personnalisées.

Limites des résultats

Copilot Studio utilise jusqu’à 15 extraits de System.SearchResults code pour générer une réponse. Si votre API retourne d’autres résultats, envisagez les éléments suivants :

  • Le scoring de pertinence est implémenté pour retourner d'abord les meilleurs résultats.
  • Limitation de la réponse de votre API à 15 résultats.
  • Tri des résultats par pertinence avant la transformation.

Plusieurs sujets de connaissances personnalisées

Vous pouvez créer plusieurs rubriques à l’aide OnKnowledgeRequestedde , et chaque rubrique peut interroger différents systèmes back-end. Copilot Studio les appelle simultanément lorsqu’il a besoin de connaissances. Cette approche vous permet d’interroger différents points de terminaison de recherche ou d’implémenter des stratégies de secours.

Avertissement

La limite de résultats s’applique à toutes les rubriques de connaissances combinées. Si la rubrique A retourne 10 résultats et que la rubrique B retourne 8, seuls les 15 premiers résultats combinés sont utilisés.

Recommendations

  • Triez ou notez les résultats avant de les retourner.
  • Maintenir la cohérence des schémas de réponse.
  • Utilisez des noms de rubriques et des descriptions clairs. Cette pratique est utile lorsque les jeux de résultats volumineux nécessitent un filtrage de pertinence.
  • Last updated on