Conectarse a fuentes de conocimiento personalizadas

Copilot Studio incluye fuentes de conocimientos integradas como SharePoint y Dataverse. Muchas organizaciones también utilizan sus propios endpoints de búsqueda, como APIs personalizadas, sistemas de búsqueda empresariales existentes o Búsqueda de Azure AI, manteniendo el control total sobre la consulta que se ejecuta.

Copilot Studio admite este escenario con el desencadenador OnKnowledgeRequested. Cualquier tema que use este desencadenador actúa como una fuente de conocimientos personalizada y aporta resultados a las respuestas generativas.

Este artículo explica cómo crear e integrar fuentes de conocimientos personalizadas en Copilot Studio usando el desencadenador OnKnowledgeRequested. Aprenda cómo Copilot Studio reescribe consultas, cómo conectar su propia API de búsqueda, cómo formatear los resultados para respuestas generativas y las mejores prácticas al trabajar con conocimiento personalizado.

Desencadenador OnKnowledgeRequested

Use el desencadenador OnKnowledgeRequested en estas dos situaciones:

  • Cuando el orquestador determina que se requiere recuperación de conocimiento para responder a una consulta del usuario.
  • Cuando se invoca explícitamente un nodo de respuesta generativa en la conversación.

Importante

Solo puede configurar ese desencadenador en vista de código usando YAML. No hay compatibilidad con el diseñador visual.

Los temas que usan OnKnowledgeRequested tienen acceso a variables del sistema que no están disponibles en los temas regulares:

  • System.SearchQuery: Una versión sensible al contexto y reescrita de la consulta del usuario, optimizada para la búsqueda semántica.
  • System.KeywordSearchQuery: Una consulta reescrita que está optimizada para motores de búsqueda por palabras clave.
  • System.SearchResults: Donde el tema almacena fragmentos de conocimiento formateados.

Copilot Studio vuelve a escribir consultas de forma inteligente mediante el historial de conversaciones, lo que garantiza que conserva el contexto de varios turnos.

Crear una fuente de conocimientos personalizada

Para crear una fuente de conocimientos personalizada, cree un tema con el desencadenador OnKnowledgeRequested que llama a su API de búsqueda y transforma los resultados en el formato que espera Copilot Studio.

Paso 1: Crear el desencadenador

Cree un nuevo tema en Copilot Studio, cambie a vista de código y defina el desencadenador OnKnowledgeRequested.

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

Esta estructura indica a Copilot Studio que este tema es responsable de satisfacer las solicitudes de conocimiento.

Paso 2: Agregar una petición HTTP

Agregue una acción HTTP que llame a su punto de conexión de búsqueda.

Ejemplo:

- 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

Concatene System.KeywordSearchQuery a su URL base porque Copilot Studio reescribe automáticamente la consulta del usuario con el contexto de la conversación antes de hacer la solicitud de búsqueda. Este paso es importante para mantener el contexto a lo largo de conversaciones de varios turnos.

Sugerencia

En lugar de una solicitud HTTP sin procesar, puede utilizar cualquier método para obtener resultados desde un punto de acceso de búsqueda, incluidos conectores personalizados, conectores integrados como Búsqueda de Azure AI o flujos de agentes.

Ejemplo de reescritura de consultas

  • Consulta del usuario 1: "¿Cuál es nuestro periodo oficial de retención de datos para los registros de clientes?"
  • Consulta de seguimiento: "¿Cambia para información financiera?"
  • Consulta de seguimiento: "¿Y existen excepciones?"

La consulta reescrita se convierte en: "excepciones a la política de retención de datos de clientes y excepciones de retención de datos financieros excepciones de políticas de exenciones regulatorias manejo de excepciones de políticas directrices de cumplimiento"

Observe que la consulta reescrita:

  • Resuelve "allí" según directiva de retención de datos
  • Recupera el contexto de ambos turnos anteriores: datos del cliente + datos financieros
  • Agrega lenguaje de política empresarial: excepciones, exenciones, regulatorio, directrices

Paso 3: Transformar los resultados

Una fuente de conocimientos personalizada debe generar resultados en el formato que Copilot Studio espera. Este formato utiliza:

  • Contenido: fragmento o extracto.
  • ContentLocation (opcional): URL.
  • Título (opcional): Título del resultado.

Para definir la estructura de la respuesta HTTP, configure el esquema de respuesta en la interfaz de usuario de Copilot Studio.

  • Seleccione A partir de datos de muestra para el tipo de datos de respuesta.
  • Seleccione Obtener esquema de JSON de ejemplo.
  • Pegue la carga del JSON de muestra para generar automáticamente el esquema.

Este proceso genera el esquema de respuesta en el archivo YAML.

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

A continuación, transforme la respuesta de la API para que se ajuste a este formato. Asigne los datos transformados a System.SearchResults.

Transformación de ejemplo

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

La acción SetVariable ejecuta ambas operaciones:

  • La función ForAll transforma cada resultado de búsqueda, asignando snippet a Content, url a ContentLocation, y title a Title.
  • La tabla transformada se asigna a System.SearchResults, que es la variable que Copilot Studio utiliza para generar respuestas.

Consideraciones

Tenga en cuenta estas consideraciones clave cuando construyas fuentes de conocimientos personalizadas.

Límites de resultados

Copilot Studio utiliza hasta 15 fragmentos de System.SearchResults para generar una respuesta. Si su API devuelve más resultados, considere:

  • Implementar la puntuación de relevancia para obtener los mejores resultados primero.
  • Limitar la respuesta de su API a 15 resultados.
  • Ordenar los resultados por relevancia antes de la transformación.

Múltiples temas de conocimiento personalizado

Puede crear múltiples temas usando OnKnowledgeRequested, y cada tema puede consultar diferentes sistemas de back-end. Copilot Studio los invoca simultáneamente a todos cuando requiere información. Este enfoque permite consultar diferentes puntos de conexión de búsqueda o implementar estrategias de respaldo.

Advertencia

El límite de resultados se aplica en conjunto a todos los temas de conocimiento. Si el Tema A devuelve 10 resultados y el Tema B 8, solo se utilizan los 15 resultados con mayor puntuación en conjunto.

Recomendaciones

  • Ordenar o asignar puntuación a los resultados antes de devolverlos.
  • Mantenga los esquemas de respuesta uniformes.
  • Utilice nombres y descripciones claros de los temas. Esta práctica resulta útil cuando se requiere aplicar filtrado por relevancia en grandes conjuntos de resultados.
  • Last updated on