Verbinding maken met aangepaste kennisbronnen

Copilot Studio bevat ingebouwde kennisbronnen zoals SharePoint en Dataverse. Veel organisaties gebruiken ook hun eigen zoekeindpunten, zoals aangepaste API's, bestaande zoeksystemen voor ondernemingen of Azure AI Zoeken, terwijl ze volledige controle behouden over de uitgevoerde zoekopdracht.

Copilot Studio ondersteunt dit scenario met de trigger OnKnowledgeRequested. Elk onderwerp dat deze trigger gebruikt, fungeert als een aangepaste kennisbron en levert resultaten aan generatieve antwoorden.

In dit artikel wordt uitgelegd hoe u aangepaste kennisbronnen kunt bouwen en integreren in Copilot Studio met behulp van de trigger OnKnowledgeRequested. U leert hoe Copilot Studio zoekopdrachten herschrijft, hoe u verbinding maakt met uw eigen zoek-API, hoe u resultaten formatteert voor generatieve antwoorden, en wat best practices zijn bij het werken met aangepaste kennisbronnen.

De OnKnowledgeRequested-trigger

Gebruik de trigger OnKnowledgeRequested in deze twee situaties:

  • Wanneer de orkestrator bepaalt dat ophalen van kennis vereist is om een gebruikersvraag te beantwoorden.
  • Wanneer een generatief antwoord-knooppunt expliciet wordt geactiveerd in het gesprek.

Belangrijk

Deze trigger alleen kan worden geconfigureerd in codeweergave met YAML. Er geen ondersteuning is voor de visuele ontwerper.

Onderwerpen die gebruikmaken van OnKnowledgeRequested hebben toegang tot systeemvariabelen die niet beschikbaar zijn in reguliere onderwerpen:

  • System.SearchQuery: een contextbewuste, herschreven versie van de zoekopdracht van de gebruiker die geoptimaliseerd is voor semantisch zoeken.
  • System.KeywordSearchQuery: Een herschreven zoekopdracht die is geoptimaliseerd voor zoekmachines op basis van zoekwoorden.
  • System.SearchResults: waar het onderwerp opgemaakte kennisfragmenten opslaat.

Copilot Studio herschrijft zoekopdrachten intelligent door gebruik te maken van gespreksgeschiedenis, zodat de context van meerdere beurten behouden blijft.

Een aangepaste kennisbron bouwen

Als u een aangepaste kennisbron wilt maken, maakt u een onderwerp met de OnKnowledgeRequested-trigger die uw zoek-API aanroept en de resultaten transformeert naar het formaat dat Copilot Studio verwacht.

Stap 1: De trigger maken

Maak een nieuw onderwerp in Copilot Studio, schakel over naar codeweergave en definieer de OnKnowledgeRequested-trigger.

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

Deze structuur geeft aan Copilot Studio door dat dit onderwerp verantwoordelijk is voor het afhandelen van kennisverzoeken.

Stap 2: Voeg een HTTP-verzoek toe

Voeg een HTTP-actie toe die uw zoekeindpunt aanroept.

Voorbeeld:

- 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

Voeg System.KeywordSearchQuery toe aan uw basis-URL, omdat Copilot Studio de gebruikersquery automatisch herschrijft met de context van het gesprek voordat het zoekverzoek wordt uitgevoerd. Deze stap is belangrijk om de context te behouden tijdens gesprekken die uit meerdere paden bestaan.

Fooi

In plaats van een ruw HTTP-verzoek kunt u elke methode gebruiken die resultaten oplevert van een zoekeindpunt, waaronder aangepaste connectors, ingebouwde connectors zoals Azure AI Zoeken of agentstromen.

Voorbeeld van herschrijven van query's

  • Gebruikersquery 1: "Wat is onze officiële gegevensretentieperiode voor klantenrecords?"
  • Vervolgquery: "Verandert het voor financiële informatie?"
  • Vervolgquery: "En zijn er uitzonderingen?"

Herschreven query wordt: "uitzonderingen op gegevensretentiebeleid klant- en wettelijke uitzonderingen op financiële gegevensretentie beleid uitzonderingen op naleving van compliance"

Merk het volgende op bij de herschreven query:

  • Hiermee wordt 'daar' omgezet in het bewaarbeleid voor gegevens
  • Neemt context mee uit beide eerdere paden: klantgegevens + financiële gegevens
  • Voegt taal uit het bedrijfsbeleid toe: uitzonderingen, vrijstellingen, regelgeving, richtlijnen

Stap 3: Transformeer resultaten

Een aangepaste kennisbron moet resultaten opleveren in het formaat dat Copilot Studio verwacht. Deze indeling gebruikt:

  • Inhoud: Fragment of uittreksel.
  • ContentLocation (optioneel): URL.
  • Titel (optioneel): titel van het resultaat.

Om de structuur van de HTTP-respons te definiëren, configureert u het responsschema in de gebruikersinterface van Copilot Studio.

  • Selecteer Uit voorbeeldgegevens voor het type responsgegevens.
  • Selecteer Schema ophalen uit voorbeeld-JSON.
  • Plak een voorbeeld van een JSON-payload om automatisch het schema te genereren.

Dit proces genereert het responsschema in uw YAML-bestand.

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

Vervolgens moet de respons van uw API worden getransformeerd zodat deze overeenkomt met dit formaat. Wijs de getransformeerde gegevens toe aan System.SearchResults.

Voorbeeld van een transformatie

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

De SetVariable-actie voert beide bewerkingen uit:

  • De ForAll-functie transformeert elk zoekresultaat door toewijzing van snippet aan Content, url aan ContentLocation en title aan Title.
  • De getransformeerde tabel wordt toegewezen aan System.SearchResults, wat de variabele is die Copilot Studio gebruikt om antwoorden te genereren.

Overwegingen

Houd deze sleuteloverwegingen in gedachten wanneer u aangepaste kennisbronnen bouwt.

Resultaatlimieten

Copilot Studio gebruikt maximaal 15 fragmenten uit System.SearchResults om een respons te genereren. Als uw API meer resultaten oplevert, overweeg dan:

  • Implementeer relevantiescores om de beste resultaten als eerste weer te geven.
  • Beperk uw API-respons tot 15 resultaten.
  • Resultaten sorteren op relevantie vóór transformatie.

Meerdere aangepaste kennisonderwerpen

U kunt meerdere onderwerpen aanmaken door OnKnowledgeRequested te gebruiken en elk onderwerp kan verschillende back-endsystemen bevragen. Copilot Studio roept ze allemaal tegelijk aan wanneer kennis nodig is. Met deze aanpak kunt u een query op verschillende zoekeindpunten uitvoeren of fallbackstrategieën implementeren.

Waarschuwing

De resultaatlimiet geldt voor alle kennisonderwerpen samen. Als Onderwerp A 10 resultaten oplevert en Onderwerp B 8, worden alleen de top 15 gecombineerde resultaten gebruikt.

Aanbevelingen

  • Sorteer of beoordeel resultaten voordat u ze terugstuurt.
  • Houd responsschema's consistent.
  • Gebruik duidelijke onderwerpnamen en beschrijvingen. Deze werkwijze is nuttig wanneer grote resultatensets relevantiefiltering vereisen.
  • Last updated on