Connettersi a fonti delle informazioni personalizzate

Copilot Studio include fonti delle informazioni integrate come SharePoint e Dataverse. Molte organizzazioni utilizzano anche i propri endpoint di ricerca, come API personalizzate, sistemi di ricerca aziendali esistenti o Azure AI Search, mantenendo il pieno controllo sulla query eseguita.

Copilot Studio supporta questo scenario con il trigger OnKnowledgeRequested. Qualsiasi argomento che utilizza questo trigger agisce come una fonte delle informazioni personalizzata e fornisce risultati per risposte generative.

Questo articolo spiega come creare e integrare fonti delle informazioni personalizzate in Copilot Studio utilizzando il trigger OnKnowledgeRequested. Puoi apprendere come Copilot Studio riscrive le query, come collegarti alla tua API di ricerca, come formattare i risultati per le risposte generative e le procedure consigliate quando si lavora con le informazioni personalizzate.

Trigger OnKnowledgeRequested

Usa il trigger OnKnowledgeRequested in queste due situazioni:

  • Quando l'orchestratore determina che è necessario recuperare informazioni per rispondere a una richiesta dell'utente.
  • Quando un nodo di risposta generativa viene esplicitamente invocato nella conversazione.

Importante

Puoi configurare questo trigger solo nella vista codice usando YAML. Il supporto per il la finestra di progettazione di oggetti visivi non è disponibile.

Gli argomenti che utilizzano OnKnowledgeRequested hanno accesso a variabili di sistema che non sono disponibili negli argomenti normali:

  • System.SearchQuery: una versione contestualizzata e riscritta della query dell'utente, ottimizzata per la ricerca semantica.
  • System.KeywordSearchQuery: una query riscritta ottimizzata per motori di ricerca basati su parole chiave.
  • System.SearchResults: dove l'argomento memorizza frammenti di conoscenza formattati.

Copilot Studio riscrive le query in modo intelligente utilizzando la cronologia della conversazione, garantendo la conservazione del contesto su più turni.

Creazione di una fonte delle informazioni personalizzata

Per creare una fonte delle informazioni 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

Crea un nuovo argomento in Copilot Studio, passa alla vista codice e definisci il trigger OnKnowledgeRequested.

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

Questa struttura indica a Copilot Studio che questo argomento è responsabile di soddisfare le richieste di conoscenza.

Passaggio 2: aggiungere una richiesta HTTP

Aggiungi un'azione HTTP che richiami il tuo 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

Concatena System.KeywordSearchQuery al tuo URL base perché Copilot Studio riscrive automaticamente la query utente con il contesto della conversazione prima di effettuare la richiesta di ricerca. Questo passaggio è importante per mantenere il contesto nelle conversazioni multi-turno.

Suggerimento

Invece di una semplice richiesta HTTP, puoi utilizzare qualsiasi metodo che ottenga risultati da un endpoint di ricerca, inclusi connettori personalizzati, connettori integrati come Azure AI Search o flusso dell'agente.

Esempio di riscrittura delle query

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

La query riscritta diventa: "eccezioni ai criteri di conservazione dei dati, eccezioni sulla conservazione dei dati dei clienti e finanziari, esenzioni normative, gestione delle eccezioni nella policy, linee guida sulla conformità"

Nota che la query riscritta:

  • Risolve "there" nei criteri di conservazione dei dati
  • Recupera il contesto da entrambe le interazioni precedenti: dati del cliente e dati finanziari
  • Aggiunge la terminologia dei criteri aziendali: eccezioni, esenzioni, normative, linee guida

Passaggio 3: trasformare i risultati

Una fonte delle informazioni personalizzata deve fornire risultati nel formato richiesto da Copilot Studio. Questo formato utilizza:

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

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

  • Seleziona Da dati campione per il tipo di dati della risposta.
  • Seleziona Ottieni schema da JSON di esempio.
  • Incolla il tuo payload JSON di esempio per generare automaticamente lo schema.

Questo processo genera lo schema di risposta nel tuo file YAML.

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

Successivamente, trasforma la risposta della tua API per adattarla a questo formato. Assegna 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 SetVariableesegue entrambe le operazioni:

  • La funzione ForAll trasforma ciascun risultato di ricerca, mappando snippet su Content, url su ContentLocation e title su Title.
  • La tabella trasformata viene assegnata a System.SearchResults, la variabile utilizzata da Copilot Studio per generare le risposte.

Considerazioni

Prendi in considerazione questi aspetti chiave quando crei fonti delle informazioni personalizzate.

Limiti dei risultati

Copilot Studio utilizza fino a 15 frammenti da System.SearchResults per generare una risposta. Se la tua API restituisce più risultati, considera:

  • L'implementazione di un sistema di punteggio di pertinenza per restituire prima i risultati più pertinenti.
  • La limitazione della risposta dell'API a 15 risultati.
  • L'ordinamento dei risultati per pertinenza prima della trasformazione.

Argomenti di conoscenza personalizzati multipli

Puoi creare più argomenti usando OnKnowledgeRequested e ogni argomento può interrogare diversi sistemi back-end. Copilot Studio li richiama tutti contemporaneamente quando ha bisogno di conoscenza. Questo approccio consente di interrogare diversi endpoint di ricerca o di implementare strategie di fallback.

Avviso

Il limite dei risultati si applica complessivamente a tutti gli argomenti di conoscenza. Se l’argomento A restituisce 10 risultati e l’argomento B 8, vengono utilizzati solo i primi 15 risultati totali.

Suggerimenti

  • Ordina o assegna un punteggio ai risultati prima di restituirli.
  • Mantieni coerenti gli schemi di risposta.
  • Utilizza nomi e descrizioni chiare per gli argomenti. Questa pratica è utile quando set di risultati estesi richiedono l'applicazione di filtri basati sulla pertinenza.
  • Last updated on