Condividi tramite

Collegarsi a fonti di conoscenza personalizzate

Copilot Studio include fonti di conoscenza integrate, ad esempio SharePoint e Dataverse. Molte organizzazioni usano anche endpoint di ricerca personalizzati, ad esempio API personalizzate, sistemi di ricerca aziendali esistenti o Ricerca di intelligenza artificiale di Azure, mantenendo al tempo stesso il controllo completo sulla query eseguita.

Copilot Studio supporta questo scenario con il OnKnowledgeRequested trigger . Qualsiasi argomento che usa questo trigger funge da fonte di conoscenze personalizzata e contribuisce alla generazione di risposte.

Questo articolo illustra come creare fonti di conoscenza personalizzate e integrarle in Copilot Studio utilizzando il OnKnowledgeRequested trigger. Si apprenderà come Copilot Studio riscrive le query, come connettersi all'API di ricerca, come formattare i risultati per le risposte generative e le procedure consigliate quando si lavora con conoscenze personalizzate.

Trigger OnKnowledgeRequested

Usa il trigger OnKnowledgeRequested in queste due situazioni:

  • Quando l'agente di orchestrazione determina che il recupero delle informazioni è necessario per rispondere a una query dell'utente.
  • Quando un nodo di risposte generative viene richiamato in modo esplicito nella conversazione.

Importante

È possibile configurare questo trigger solo nella visualizzazione codice usando YAML. Non c'è supporto per il progettista visivo.

Argomenti che usano OnKnowledgeRequested hanno accesso alle variabili di sistema che non sono disponibili negli argomenti regolari:

  • System.SearchQuery: versione riscritta e compatibile con il contesto della query dell'utente ottimizzata per la ricerca semantica.
  • System.KeywordSearchQuery: query riscritta ottimizzata per i motori di ricerca basati su parole chiave.
  • System.SearchResults: dove l'argomento archivia frammenti di informazioni formattati.

Copilot Studio riscrive in modo intelligente le query usando la cronologia delle conversazioni, assicurandosi che mantenga il contesto a più turni.

Creazione di un'origine personalizzata di conoscenza

Per creare un'origine di conoscenza personalizzata, crea un argomento con il trigger OnKnowledgeRequested che attiva il richiamo dell'API di ricerca e trasforma i risultati nel formato previsto da Copilot Studio.

Passaggio 1: Creare il trigger

Creare un nuovo argomento in Copilot Studio, passare alla visualizzazione codice e definire il OnKnowledgeRequested trigger.

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

Questa struttura indica a Copilot Studio che questo argomento è responsabile dell'adempimento delle richieste di informazioni.

Passaggio 2: Aggiungere una richiesta HTTP

Aggiungere un'azione HTTP che chiama l'endpoint di ricerca.

Esempio:

- 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

Concatenare System.KeywordSearchQuery all'URL di base perché Copilot Studio riscrive automaticamente la query dell'utente con il contesto di conversazione prima di effettuare la richiesta di ricerca. Questo passaggio è importante per mantenere il contesto nelle conversazioni a più turni.

Suggerimento

Anziché una richiesta HTTP non elaborata, è possibile usare qualsiasi metodo che ottiene i risultati da un endpoint di ricerca, inclusi connettori personalizzati, connettori predefiniti come Ricerca di intelligenza artificiale di Azure o flussi agente.

Esempio di riscrittura delle query

  • Query utente 1: "Qual è il periodo di conservazione dei dati ufficiale per i record dei clienti?"
  • Query di completamento: "Cambia per informazioni finanziarie?"
  • Query di completamento: "E ci sono eccezioni?"

La query riscritta diventa: "Eccezioni ai criteri di conservazione dei dati cliente e eccezioni di conservazione dei dati finanziarie eccezioni normative per la gestione delle eccezioni ai criteri di conformità"

Si noti che la query riscritta:

  • Risolve "there" nei criteri di conservazione dei dati
  • Recupera il contesto dalle interazioni precedenti: dati dei clienti e dati finanziari
  • Aggiunge il linguaggio dei criteri aziendali: eccezioni, esenzioni, normative, linee guida

Passaggio 3: Trasformare i risultati

Una fonte di conoscenza personalizzata deve restituire i risultati nel formato previsto da Copilot Studio. Questo formato usa:

  • Contenuto: frammento o estratto.
  • ContentLocation (facoltativo): URL.
  • Titolo (facoltativo): titolo del risultato.

Per definire la struttura della risposta HTTP, configurare lo schema di risposta nell'interfaccia utente di Copilot Studio.

  • Selezionare Da dati di esempio per il tipo di dati di risposta.
  • Selezionare Recupera schema da JSON di esempio.
  • Incollare il payload JSON di esempio per generare automaticamente lo schema.

Questo processo genera lo schema di risposta nel file YAML.

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

Successivamente, trasformare la risposta dell'API in modo che corrisponda a questo formato. Assegnare i dati trasformati a System.SearchResults.

Trasformazione di esempio

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'azione SetVariable esegue entrambe le operazioni:

  • La ForAll funzione trasforma ogni risultato della ricerca, mappando snippet a Content, url a ContentLocation, e title a Title.
  • La tabella trasformata viene assegnata a System.SearchResults, ovvero la variabile usata da Copilot Studio per generare risposte.

Considerazioni

Tenere presenti queste considerazioni chiave quando si creano origini di conoscenze personalizzate.

Limiti dei risultati

Copilot Studio usa fino a 15 frammenti di codice da System.SearchResults per generare una risposta. Se l'API restituisce più risultati, prendere in considerazione:

  • Implementazione del punteggio di pertinenza per restituire prima i risultati migliori.
  • Limitare la risposta dell'API a 15 risultati.
  • Ordinamento dei risultati per pertinenza prima della trasformazione.

Più argomenti di knowledge base personalizzati

È possibile creare più argomenti usando OnKnowledgeRequestede ogni argomento può eseguire query su sistemi back-end diversi. Copilot Studio richiama tutti contemporaneamente quando è necessaria una conoscenza. Questo approccio consente di eseguire query su endpoint di ricerca diversi o implementare strategie di fallback.

Avviso

Il limite dei risultati si applica a tutti gli argomenti della base di conoscenza insieme. Se l'argomento A restituisce 10 risultati e l'argomento B restituisce 8, vengono utilizzati solo i primi 15 risultati combinati.

Raccomandazioni

  • Ordinare o assegnare un punteggio ai risultati prima di restituirli.
  • Mantenere coerenti gli schemi di risposta.
  • Usare nomi e descrizioni di argomenti chiari. Questa procedura è utile quando i set di risultati di grandi dimensioni richiedono filtri per pertinenza.
  • Last updated on