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 Search, terwijl de volledige controle over de uitgevoerde query behouden blijft.

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

In dit artikel wordt uitgelegd hoe u aangepaste kennisbronnen in Copilot Studio bouwt en integreert met behulp van de OnKnowledgeRequested trigger. U leert hoe Copilot Studio query's herschrijft, hoe u verbinding maakt met uw eigen zoek-API, hoe u resultaten kunt opmaken voor generatieve antwoorden en aanbevolen procedures bij het werken met aangepaste kennis.

De OnKnowledgeRequested-trigger

Gebruik de OnKnowledgeRequested trigger in deze twee situaties:

  • Wanneer de orchestrator bepaalt dat het ophalen van kennis vereist is om een gebruikersquery te beantwoorden.
  • Wanneer een generatief antwoordknooppunt expliciet wordt aangeroepen in het gesprek.

Belangrijk

U kunt deze trigger alleen configureren in de codeweergave met behulp van YAML. Er is geen ondersteuning voor visualontwerpers.

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

  • System.SearchQuery: Een contextbewuste, herschreven versie van de query van de gebruiker die is geoptimaliseerd voor semantische zoekopdrachten.
  • System.KeywordSearchQuery: Een herschreven query die is geoptimaliseerd voor zoekprogramma's op basis van trefwoorden.
  • System.SearchResults: waar het onderwerp opgemaakte kennisfragmenten opslaat.

Copilot Studio herschrijft op intelligente wijze query's met behulp van de gespreksgeschiedenis, zodat het de context over meerdere conversatierondes behoudt.

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 resultaten transformeert in de indeling die Copilot Studio verwacht.

Stap 1: De trigger maken

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

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

Deze structuur vertelt Copilot Studio dat dit onderwerp verantwoordelijk is voor het uitvoeren van kennisaanvragen.

Stap 2: Een HTTP-aanvraag toevoegen

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

System.KeywordSearchQuery Voeg deze samen met uw basis-URL, omdat Copilot Studio de gebruikersquery automatisch herschrijft met gesprekscontext voordat de zoekaanvraag wordt ingediend. Deze stap is belangrijk om context te behouden voor gesprekken met meerdere beurten.

Tip

In plaats van een onbewerkte HTTP-aanvraag kunt u elke methode gebruiken die resultaten ophaalt van een zoekeindpunt, inclusief aangepaste connectors, ingebouwde connectors zoals Azure AI Search of agentstromen.

Voorbeeld van het herschrijven van query's

  • Gebruikersquery 1: "Wat is onze officiële gegevensretentieperiode voor klantrecords?"
  • Vervolgquery: 'Wordt deze gewijzigd voor financiële informatie?'
  • Vervolgquery: 'En zijn er uitzonderingen?'

Herschreven query wordt: "Uitzonderingen op het gegevens- en financieel retentiebeleid voor klanten, uitzonderingen op regelgeving, beleidsuitzonderingen, uitzonderingafhandeling, nalevingsrichtlijnen"

U ziet dat de herschreven query:

  • Hiermee wordt 'daar' omgezet in het bewaarbeleid voor gegevens
  • Hiermee wordt context van beide eerdere beurten opgehaald: klantgegevens + financiële gegevens
  • Voegt taal voor ondernemingsbeleid toe: uitzonderingen, vrijstellingen, regelgeving, richtlijnen

Stap 3: Resultaten transformeren

Een aangepaste kennisbron moet resultaten opleveren in de indeling die Copilot Studio verwacht. In deze indeling wordt het volgende gebruikt:

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

Als u de structuur van het HTTP-antwoord wilt definiëren, configureert u het antwoordschema in de Copilot Studio-gebruikersinterface.

  • Selecteer uit voorbeeldgegevens voor het antwoordgegevenstype.
  • Selecteer Schema ophalen uit voorbeeld-JSON.
  • Plak je voorbeeld JSON-payload en genereer automatisch het schema.

Met dit proces wordt het antwoordschema in uw YAML-bestand gegenereerd.

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

Transformeer vervolgens het antwoord van uw API zodat deze overeenkomt met deze indeling. Wijs de getransformeerde gegevens toe aan System.SearchResults.

Voorbeeldtransformatie

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

Met de SetVariable actie worden beide bewerkingen uitgevoerd:

  • De ForAll functie transformeert elk zoekresultaat en wijst snippet toe aan Content, url aan ContentLocation, en title aan Title.
  • De getransformeerde tabel wordt toegewezen aan System.SearchResultsde variabele die Copilot Studio gebruikt om antwoorden te genereren.

Overwegingen

Houd rekening met deze belangrijke overwegingen wanneer u aangepaste kennisbronnen bouwt.

Resultaatlimieten

Copilot Studio maakt gebruik van maximaal 15 fragmenten van System.SearchResults om een antwoord te genereren. Als uw API meer resultaten retourneert, kunt u het volgende overwegen:

  • Relevantiescore implementeren om eerst de beste resultaten te retourneren.
  • Uw API-antwoord beperken tot 15 resultaten.
  • Resultaten sorteren op relevantie vóór transformatie.

Meerdere aangepaste kennisonderwerpen

U kunt meerdere onderwerpen maken met behulp van OnKnowledgeRequesteden elk onderwerp kan een query uitvoeren op verschillende back-endsystemen. Copilot Studio roept ze allemaal tegelijk aan wanneer het kennis nodig heeft. Met deze aanpak kunt u verschillende zoekeindpunten opvragen of terugvalstrategieën implementeren.

Waarschuwing

De resultaatlimiet is van toepassing op alle kennisonderwerpen gecombineerd. Als onderwerp A 10 resultaten retourneert en Onderwerp B 8 retourneert, worden alleen de tien belangrijkste gecombineerde resultaten gebruikt.

Aanbevelingen

  • Sorteer of beoordeel resultaten voordat ze worden geretourneerd.
  • Houd antwoordschema's consistent houden.
  • Gebruik duidelijke onderwerpnamen en beschrijvingen. Deze procedure is handig wanneer voor grote resultatensets relevantiefilters zijn vereist.
  • Last updated on