Crear un origen de conocimiento remoto de SharePoint

Un origen de conocimiento remoto de SharePoint usa la API de recuperación de Copilot para consultar contenido textual directamente desde SharePoint en Microsoft 365, devolviendo resultados al motor de recuperación agente para combinar, clasificar y formular respuestas. Este origen de conocimiento no usa ningún índice de búsqueda y solo se consulta el contenido textual.

En el momento de la consulta, el origen de conocimiento remoto de SharePoint llama a la API de recuperación de Copilot en nombre de la identidad del usuario, por lo que no se necesitan cadenas de conexión en la definición del origen de conocimiento. Todo el contenido al que un usuario tiene acceso está en el ámbito de la recuperación de conocimiento. Para limitar sitios o restringir la búsqueda, establezca una expresión de filtro. El arrendatario de Azure y el arrendatario de Microsoft 365 deben usar el mismo arrendatario de Microsoft Entra ID, y la identidad del llamante debe ser reconocida por ambos arrendatarios.

• Puede usar filtros para definir el ámbito de la búsqueda por direcciones URL, intervalos de fechas, tipos de archivo y otros metadatos.

• Los permisos de SharePoint y las etiquetas de Purview se respetan en las solicitudes de contenido.

• El uso se factura a través de Microsoft 365 y una licencia de Copilot.

Al igual que cualquier otro origen de conocimiento, especifique un origen de conocimiento remoto de SharePoint en una base de conocimiento y use los resultados como datos de base cuando un agente o bot de chat llama a una acción de recuperación en el momento de la consulta.

Prerrequisitos

• Azure AI Search en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico.

• SharePoint en un entorno de Microsoft 365 que está bajo el mismo entorno de Microsoft Entra ID que Azure.

• Un token de acceso personal para el desarrollo local o la identidad de un usuario desde una aplicación cliente.

• La versión preliminar más reciente de la Azure.Search.Documents biblioteca cliente para el SDK de .NET.

• Permiso para crear y usar objetos en Azure AI Search. Se recomienda el acceso basado en roles, pero puede usar claves de API si una asignación de roles no es factible.

Para el desarrollo local, el motor de recuperación de agentes utiliza su token de acceso para llamar a SharePoint en su nombre. Para más información sobre el uso de un token de acceso personal en las solicitudes, consulte Conexión a Azure AI Search.

Limitaciones

Las siguientes limitaciones de la API de recuperación de Copilot se aplican a los orígenes de conocimiento remotos de SharePoint.

• No hay compatibilidad con conectores de Copilot ni contenido de OneDrive. El contenido solo se recupera de sitios de SharePoint.

• Límite de 200 solicitudes por usuario por hora.

• Límite de caracteres de consulta de 1500 caracteres.

• Las consultas híbridas solo se admiten para las siguientes extensiones de archivo: .doc, .docx, .pptx, .pdf, .aspx y .one.

• No se admite la recuperación multilingüe (contenido notextual, incluidas tablas, imágenes y gráficos).

• Máximo de 25 resultados de una consulta.

• La API de recuperación de Copilot devuelve los resultados como desordenados.

• Las expresiones de filtro del lenguaje de consulta de palabras clave (KQL) no válidas se omiten y la consulta continúa ejecutándose sin el filtro.

Comprobación de fuentes de conocimiento existentes

Una fuente de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Ejecute el código siguiente para enumerar los orígenes de conocimiento por nombre y tipo.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

También puede devolver una única fuente de conocimiento por nombre para revisar su definición json.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

El siguiente JSON es una respuesta de ejemplo para un origen de conocimiento remoto de SharePoint.

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

Creación de una fuente de conocimiento

Ejecute el código siguiente para crear un origen de conocimiento remoto de SharePoint.

Las claves de API se usan para la conexión de cliente a Azure AI Search y Azure OpenAI. Azure AI Search usa el token de acceso para conectarse a SharePoint en Microsoft 365 en su nombre. Solo puede recuperar el contenido al que tiene permiso para acceder. Para más información sobre cómo obtener un token de acceso personal y otros valores, consulte Conexión a Azure AI Search.

// Create a remote SharePoint knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

var knowledgeSource = new RemoteSharePointKnowledgeSource(name: "my-remote-sharepoint-ks")
{
    Description = "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    RemoteSharePointParameters = new RemoteSharePointKnowledgeSourceParameters()
    {
        FilterExpression = "filetype:docx",
        ResourceMetadata = { "Author", "Title" }
    }
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Propiedades específicas del origen

Puede pasar las siguientes propiedades para crear un origen de conocimiento remoto de SharePoint.

Ejemplos de expresiones de filtro

No todas las propiedades de SharePoint se admiten en el filterExpression. Para obtener una lista de las propiedades admitidas, consulte la referencia de la API. A continuación se muestra más información sobre las propiedades consultables que puede usar en el filtro: propiedades consultables.

Obtenga más información sobre los filtros KQL en la referencia de sintaxis.

Asignar a una base de conocimiento

Si está satisfecho con el origen de conocimiento, continúe con el paso siguiente: especifique el origen de conocimiento en una base de conocimiento.

Una vez configurada la base de conocimiento, use la acción recuperar para consultar el origen de conocimiento.

Consulta de una base de conocimiento

La acción de recuperación de la base de conocimiento proporciona la identidad de usuario que autoriza el acceso al contenido de Microsoft 365.

Azure AI Search usa el token de acceso para llamar a la API de recuperación de Copilot en representación de la identidad del usuario. El token de acceso se proporciona en el punto de conexión de recuperación como encabezado xMsQuerySourceAuthorization HTTP.

using Azure;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

// Get access token
var credential = new DefaultAzureCredential();
var tokenRequestContext = new Azure.Core.TokenRequestContext(new[] { "https://search.azure.com/.default" });
var accessToken = await credential.GetTokenAsync(tokenRequestContext);
string token = accessToken.Token;

// Create knowledge base retrieval client
var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    credential: new AzureKeyCredential()
);

var spMessages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "user" },
        { "content", @"contoso product planning" }
    }
};

// Create retrieval request
var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in spMessages) {
    if (message["role"] != "system") {
        retrievalRequest.Messages.Add(new KnowledgeBaseMessage(content: new[] { new KnowledgeBaseMessageTextContent(message["content"]) }) { Role = message["role"] });
    }
}
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
var retrievalResult = await baseClient.RetrieveAsync(retrievalRequest, xMsQuerySourceAuthorization: token);

Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text);

La respuesta podría ser similar a la siguiente:

Contoso's product planning for the NextGen Camera includes a 2019 launch with a core package design and minor modifications for three product versions, featuring Wi-Fi enabled technology and a new mobile app for photo organization and sharing, aiming for 100,000 users within six months [ref_id:0][ref_id:1]. Research and forecasting are central to their planning, with phase two research focusing on feedback from a diverse user group to shape deliverables and milestones [ref_id:0][ref_id:1].

La solicitud de recuperación también toma un filtro KQL (filterExpressionAddOn) si desea aplicar restricciones en el momento de la consulta. Si especifica filterExpressionAddOn tanto en la acción de recuperación del origen de conocimiento como en la de la base de conocimiento, los filtros se combinarán utilizando una operación lógica AND.

Las consultas que hacen preguntas sobre el propio contenido son más eficaces que las preguntas sobre dónde se encuentra un archivo o cuándo se actualizó por última vez. Por ejemplo, si le pregunta, "Where is the keynote doc for Ignite 2024", podría obtener "No se encontró ningún contenido relevante para la consulta" porque el propio contenido no divulga su ubicación. Un filtro de metadatos es una mejor solución para las consultas específicas de fecha o ubicación de archivos.

Una mejor pregunta que formular es "¿Cuál es la documentación principal de Ignite 2024". La respuesta incluye la respuesta sintetizada, la actividad de consulta y los recuentos de tokens, además de la dirección URL y otros metadatos.

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

Eliminación de una fuente de conocimiento

Para poder eliminar un origen de conocimiento, debe eliminar cualquier base de conocimiento que haga referencia a ella o actualizar la definición de la base de conocimiento para quitar la referencia. En el caso de los orígenes de conocimiento que generan una canalización de índice e indexador, también se eliminan todos los objetos generados . Sin embargo, si usó un índice existente para crear un origen de conocimiento, el índice no se eliminará.

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

1. Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

   using Azure.Search.Documents.Indexes;
   
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
   
   Console.WriteLine("Knowledge Bases:");
   
   await foreach (var kb in knowledgeBases)
   {
       Console.WriteLine($"  - {kb.Name}");
   }
   

   Una respuesta de ejemplo podría ser similar a la siguiente:

    Knowledge Bases:
      - earth-knowledge-base
      - hotels-sample-knowledge-base
      - my-demo-knowledge-base
   

2. Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

   using Azure.Search.Documents.Indexes;
   using System.Text.Json;
   
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   
   // Specify the knowledge base name to retrieve
   string kbNameToGet = "earth-knowledge-base";
   
   // Get a specific knowledge base definition
   var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
   var kb = knowledgeBaseResponse.Value;
   
   // Serialize to JSON for display
   string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
   Console.WriteLine(json);
   

   Una respuesta de ejemplo podría ser similar a la siguiente:

    {
      "Name": "earth-knowledge-base",
      "KnowledgeSources": [
        {
          "Name": "earth-knowledge-source"
        }
      ],
      "Models": [
        {}
      ],
      "RetrievalReasoningEffort": {},
      "OutputMode": {},
      "ETag": "\u00220x8DE278629D782B3\u0022",
      "EncryptionKey": null,
      "Description": null,
      "RetrievalInstructions": null,
      "AnswerInstructions": null
    }
   

3. Elimine la base de conocimiento o actualice la base de conocimiento para quitar el origen de conocimiento si tiene varios orígenes. En este ejemplo se muestra la eliminación.

   using Azure.Search.Documents.Indexes;
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   
   await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
   System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");
   

4. Elimine la fuente de conocimiento.

   await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
   System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
   

Un origen de conocimiento remoto de SharePoint usa la API de recuperación de Copilot para consultar contenido textual directamente desde SharePoint en Microsoft 365, devolviendo resultados al motor de recuperación agente para combinar, clasificar y formular respuestas. Este origen de conocimiento no usa ningún índice de búsqueda y solo se consulta el contenido textual.

En el momento de la consulta, el origen de conocimiento remoto de SharePoint llama a la API de recuperación de Copilot en nombre de la identidad del usuario, por lo que no se necesitan cadenas de conexión en la definición del origen de conocimiento. Todo el contenido al que un usuario tiene acceso está en el ámbito de la recuperación de conocimiento. Para limitar sitios o restringir la búsqueda, establezca una expresión de filtro. El arrendatario de Azure y el arrendatario de Microsoft 365 deben usar el mismo arrendatario de Microsoft Entra ID, y la identidad del llamante debe ser reconocida por ambos arrendatarios.

• Puede usar filtros para definir el ámbito de la búsqueda por direcciones URL, intervalos de fechas, tipos de archivo y otros metadatos.

• Los permisos de SharePoint y las etiquetas de Purview se respetan en las solicitudes de contenido.

• El uso se factura a través de Microsoft 365 y una licencia de Copilot.

Al igual que cualquier otro origen de conocimiento, especifique un origen de conocimiento remoto de SharePoint en una base de conocimiento y use los resultados como datos de base cuando un agente o bot de chat llama a una acción de recuperación en el momento de la consulta.

Prerrequisitos

• Azure AI Search en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico.

• SharePoint en un entorno de Microsoft 365 que está bajo el mismo entorno de Microsoft Entra ID que Azure.

• Un token de acceso personal para el desarrollo local o la identidad de un usuario desde una aplicación cliente.

• La versión preliminar más reciente de la azure-search-documents biblioteca cliente para Python.

• Permiso para crear y usar objetos en Azure AI Search. Se recomienda el acceso basado en roles, pero puede usar claves de API si una asignación de roles no es factible.

Para el desarrollo local, el motor de recuperación de agentes utiliza su token de acceso para llamar a SharePoint en su nombre. Para más información sobre el uso de un token de acceso personal en las solicitudes, consulte Conexión a Azure AI Search.

Limitaciones

Las siguientes limitaciones de la API de recuperación de Copilot se aplican a los orígenes de conocimiento remotos de SharePoint.

• No hay compatibilidad con conectores de Copilot ni contenido de OneDrive. El contenido solo se recupera de sitios de SharePoint.

• Límite de 200 solicitudes por usuario por hora.

• Límite de caracteres de consulta de 1500 caracteres.

• Las consultas híbridas solo se admiten para las siguientes extensiones de archivo: .doc, .docx, .pptx, .pdf, .aspx y .one.

• No se admite la recuperación multilingüe (contenido notextual, incluidas tablas, imágenes y gráficos).

• Máximo de 25 resultados de una consulta.

• La API de recuperación de Copilot devuelve los resultados como desordenados.

• Las expresiones de filtro del lenguaje de consulta de palabras clave (KQL) no válidas se omiten y la consulta continúa ejecutándose sin el filtro.

Comprobación de fuentes de conocimiento existentes

Una fuente de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Ejecute el código siguiente para enumerar los orígenes de conocimiento por nombre y tipo.

# List knowledge sources by name and type
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

También puede devolver una única fuente de conocimiento por nombre para revisar su definición json.

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

El siguiente JSON es una respuesta de ejemplo para un origen de conocimiento remoto de SharePoint.

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

Creación de una fuente de conocimiento

Ejecute el código siguiente para crear un origen de conocimiento remoto de SharePoint.

Las claves de API se usan para la conexión de cliente a Azure AI Search y Azure OpenAI. Azure AI Search usa el token de acceso para conectarse a SharePoint en Microsoft 365 en su nombre. Solo puede recuperar el contenido al que tiene permiso para acceder. Para más información sobre cómo obtener un token de acceso personal y otros valores, consulte Conexión a Azure AI Search.

# Create a remote SharePoint knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import RemoteSharePointKnowledgeSource, RemoteSharePointKnowledgeSourceParameters

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

knowledge_source = RemoteSharePointKnowledgeSource(
    name = "my-remote-sharepoint-ks",
    description= "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    encryption_key = None,
    remote_share_point_parameters = RemoteSharePointKnowledgeSourceParameters(
        filter_expression = "filetype:docx",
        resource_metadata = ["Author", "Title"],
        container_type_id = None
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Propiedades específicas del origen

Puede pasar las siguientes propiedades para crear un origen de conocimiento remoto de SharePoint.

Ejemplos de expresiones de filtro

No todas las propiedades de SharePoint se admiten en el filterExpression. Para obtener una lista de las propiedades admitidas, consulte la referencia de la API. A continuación se muestra más información sobre las propiedades consultables que puede usar en el filtro: propiedades consultables.

Obtenga más información sobre los filtros KQL en la referencia de sintaxis.

Asignar a una base de conocimiento

Si está satisfecho con el origen de conocimiento, continúe con el paso siguiente: especifique el origen de conocimiento en una base de conocimiento.

Una vez configurada la base de conocimiento, use la acción recuperar para consultar el origen de conocimiento.

Consulta de una base de conocimiento

La acción de recuperación de la base de conocimiento proporciona la identidad de usuario que autoriza el acceso al contenido de Microsoft 365.

Azure AI Search usa el token de acceso para llamar a la API de recuperación de Copilot en representación de la identidad del usuario. El token de acceso se proporciona en el punto de conexión de recuperación como encabezado x-ms-query-source-authorization HTTP.

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, RemoteSharePointKnowledgeSourceParams

# Get access token
identity_token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://search.azure.com/.default")
token = identity_token_provider()

# Create knowledge base retrieval client
kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

# Create retrieval request
request = KnowledgeBaseRetrievalRequest(
    include_activity = True,
    messages = [
        KnowledgeBaseMessage(role = "user", content = [KnowledgeBaseMessageTextContent(text = "What was covered in the keynote doc for Ignite 2024?")])
    ],
    knowledge_source_params = [
        RemoteSharePointKnowledgeSourceParams(
            knowledge_source_name = "my-remote-sharepoint-ks",
            filter_expression_add_on = "ModifiedBy:\"Adele Vance\"",
            include_references = True,
            include_reference_source_data = True
        )
    ]
)

# Pass access token to retrieve from knowledge base
result = kb_client.retrieve(retrieval_request = request, x_ms_query_source_authorization = token)
print(result.response[0].content[0].text)

La solicitud de recuperación también toma un filtro KQL (filter_expression_add_on) si desea aplicar restricciones en el momento de la consulta. Si especifica filter_expression_add_on tanto en la acción de recuperación del origen de conocimiento como en la de la base de conocimiento, los filtros se combinarán utilizando una operación lógica AND.

Las consultas que hacen preguntas sobre el propio contenido son más eficaces que las preguntas sobre dónde se encuentra un archivo o cuándo se actualizó por última vez. Por ejemplo, si le pregunta, "Where is the keynote doc for Ignite 2024", podría obtener "No se encontró ningún contenido relevante para la consulta" porque el propio contenido no divulga su ubicación. Un filtro de metadatos es una mejor solución para las consultas específicas de fecha o ubicación de archivos.

Una mejor pregunta que formular es "¿Cuál es la documentación principal de Ignite 2024". La respuesta incluye la respuesta sintetizada, la actividad de consulta y los recuentos de tokens, además de la dirección URL y otros metadatos.

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

Eliminación de una fuente de conocimiento

Para poder eliminar un origen de conocimiento, debe eliminar cualquier base de conocimiento que haga referencia a ella o actualizar la definición de la base de conocimiento para quitar la referencia. En el caso de los orígenes de conocimiento que generan una canalización de índice e indexador, también se eliminan todos los objetos generados . Sin embargo, si usó un índice existente para crear un origen de conocimiento, el índice no se eliminará.

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

1. Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

   # Get knowledge bases
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases"
   params = {"api-version": "2025-11-01-preview", "$select": "name"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   Una respuesta de ejemplo podría ser similar a la siguiente:

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

   # Get a knowledge base definition
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
   params = {"api-version": "2025-11-01-preview"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   Una respuesta de ejemplo podría ser similar a la siguiente:

    {
      "name": "my-kb",
      "description": null,
      "retrievalInstructions": null,
      "answerInstructions": null,
      "outputMode": null,
      "knowledgeSources": [
        {
          "name": "my-blob-ks",
        }
      ],
      "models": [],
      "encryptionKey": null,
      "retrievalReasoningEffort": {
        "kind": "low"
      }
    }
   

3. Elimine la base de conocimiento o actualice la base de conocimiento para quitar el origen de conocimiento si tiene varios orígenes. En este ejemplo se muestra la eliminación.

   # Delete a knowledge base
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_base("knowledge_base_name")
   print(f"Knowledge base deleted successfully.")
   

4. Elimine la fuente de conocimiento.

   # Delete a knowledge source
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_source("knowledge_source_name")
   print(f"Knowledge source deleted successfully.")
   

Un origen de conocimiento remoto de SharePoint usa la API de recuperación de Copilot para consultar contenido textual directamente desde SharePoint en Microsoft 365, devolviendo resultados al motor de recuperación agente para combinar, clasificar y formular respuestas. Este origen de conocimiento no usa ningún índice de búsqueda y solo se consulta el contenido textual.

En el momento de la consulta, el origen de conocimiento remoto de SharePoint llama a la API de recuperación de Copilot en nombre de la identidad del usuario, por lo que no se necesitan cadenas de conexión en la definición del origen de conocimiento. Todo el contenido al que un usuario tiene acceso está en el ámbito de la recuperación de conocimiento. Para limitar sitios o restringir la búsqueda, establezca una expresión de filtro. El arrendatario de Azure y el arrendatario de Microsoft 365 deben usar el mismo arrendatario de Microsoft Entra ID, y la identidad del llamante debe ser reconocida por ambos arrendatarios.

• Puede usar filtros para definir el ámbito de la búsqueda por direcciones URL, intervalos de fechas, tipos de archivo y otros metadatos.

• Los permisos de SharePoint y las etiquetas de Purview se respetan en las solicitudes de contenido.

• El uso se factura a través de Microsoft 365 y una licencia de Copilot.

Al igual que cualquier otro origen de conocimiento, especifique un origen de conocimiento remoto de SharePoint en una base de conocimiento y use los resultados como datos de base cuando un agente o bot de chat llama a una acción de recuperación en el momento de la consulta.

Prerrequisitos

• Azure AI Search en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico.

• SharePoint en un entorno de Microsoft 365 que está bajo el mismo entorno de Microsoft Entra ID que Azure.

• Un token de acceso personal para el desarrollo local o la identidad de un usuario desde una aplicación cliente.

• La versión 2025-11-01-preview de las API REST del servicio de búsqueda.

• Permiso para crear y usar objetos en Azure AI Search. Se recomienda el acceso basado en roles, pero puede usar claves de API si una asignación de roles no es factible.

Para el desarrollo local, el motor de recuperación de agentes utiliza su token de acceso para llamar a SharePoint en su nombre. Para más información sobre el uso de un token de acceso personal en las solicitudes, consulte Conexión a Azure AI Search.

Limitaciones

Las siguientes limitaciones de la API de recuperación de Copilot se aplican a los orígenes de conocimiento remotos de SharePoint.

• No hay compatibilidad con conectores de Copilot ni contenido de OneDrive. El contenido solo se recupera de sitios de SharePoint.

• Límite de 200 solicitudes por usuario por hora.

• Límite de caracteres de consulta de 1500 caracteres.

• Las consultas híbridas solo se admiten para las siguientes extensiones de archivo: .doc, .docx, .pptx, .pdf, .aspx y .one.

• No se admite la recuperación multilingüe (contenido notextual, incluidas tablas, imágenes y gráficos).

• Máximo de 25 resultados de una consulta.

• La API de recuperación de Copilot devuelve los resultados como desordenados.

• Las expresiones de filtro del lenguaje de consulta de palabras clave (KQL) no válidas se omiten y la consulta continúa ejecutándose sin el filtro.

Comprobación de fuentes de conocimiento existentes

Una fuente de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Usar Fuentes de conocimiento - Obtener (API REST) para listar las fuentes de conocimiento por nombre y tipo.

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

También puede devolver una única fuente de conocimiento por nombre para revisar su definición json.

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

El siguiente JSON es una respuesta de ejemplo para un origen de conocimiento remoto de SharePoint.

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

Creación de una fuente de conocimiento

Usar orígenes de conocimiento: crear o actualizar (API REST) para crear un origen de conocimiento remoto de SharePoint.

Las claves de API se usan para la conexión de cliente a Azure AI Search y Azure OpenAI. Azure AI Search usa el token de acceso para conectarse a SharePoint en Microsoft 365 en su nombre. Solo puede recuperar el contenido al que tiene permiso para acceder. Para más información sobre cómo obtener un token de acceso personal y otros valores, consulte Conexión a Azure AI Search.

POST {{search-url}}/knowledgesources/my-remote-sharepoint-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-remote-sharepoint-ks",
    "kind": "remoteSharePoint",
    "description": "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    "encryptionKey": null,
    "remoteSharePointParameters": {
        "filterExpression": "filetype:docx",
        "resourceMetadata": [ "Author", "Title" ],
        "containerTypeId": null
    }
}

Propiedades específicas del origen

Puede pasar las siguientes propiedades para crear un origen de conocimiento remoto de SharePoint.

Ejemplos de expresiones de filtro

No todas las propiedades de SharePoint se admiten en el filterExpression. Para obtener una lista de las propiedades admitidas, consulte la referencia de la API. A continuación se muestra más información sobre las propiedades consultables que puede usar en el filtro: propiedades consultables.

Obtenga más información sobre los filtros KQL en la referencia de sintaxis.

Asignar a una base de conocimiento

Si está satisfecho con el origen de conocimiento, continúe con el paso siguiente: especifique el origen de conocimiento en una base de conocimiento.

Una vez configurada la base de conocimiento, use la acción recuperar para consultar el origen de conocimiento.

Consulta de una base de conocimiento

La acción de recuperación de la base de conocimiento proporciona la identidad de usuario que autoriza el acceso al contenido de Microsoft 365.

Azure AI Search usa el token de acceso para llamar a la API de recuperación de Copilot en representación de la identidad del usuario. El token de acceso se proporciona en el punto de conexión de recuperación como encabezado x-ms-query-source-authorization HTTP.

Asegúrese de generar un token de acceso para el inquilino que tiene el servicio de búsqueda.

POST {{search-url}}/knowledgebases/remote-sp-kb/retrieve?api-version={{api-version}}
api-key: {{api-key}}
Content-Type: application/json
x-ms-query-source-authorization: {{access-token}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What was covered in the keynote doc for Ignite 2024?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "filterExpressionAddOn": "ModifiedBy:\"Adele Vance\"",
            "knowledgeSourceName": "my-remote-sharepoint-ks",
            "kind": "remoteSharePoint",
            "includeReferences": true,
            "includeReferenceSourceData": true
        }
    ]
}

La solicitud de recuperación también toma un filtro KQL (filterExpressionAddOn) si desea aplicar restricciones en el momento de la consulta. Si especifica filterExpressionAddOn tanto en la acción de recuperación del origen de conocimiento como en la de la base de conocimiento, los filtros se combinarán utilizando una operación lógica AND.

Las consultas que hacen preguntas sobre el propio contenido son más eficaces que las preguntas sobre dónde se encuentra un archivo o cuándo se actualizó por última vez. Por ejemplo, si le pregunta, "Where is the keynote doc for Ignite 2024", podría obtener "No se encontró ningún contenido relevante para la consulta" porque el propio contenido no divulga su ubicación. Un filtro de metadatos es una mejor solución para las consultas específicas de fecha o ubicación de archivos.

Una mejor pregunta que formular es "¿Cuál es la documentación principal de Ignite 2024". La respuesta incluye la respuesta sintetizada, la actividad de consulta y los recuentos de tokens, además de la dirección URL y otros metadatos.

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

Eliminación de una fuente de conocimiento

Para poder eliminar un origen de conocimiento, debe eliminar cualquier base de conocimiento que haga referencia a ella o actualizar la definición de la base de conocimiento para quitar la referencia. En el caso de los orígenes de conocimiento que generan una canalización de índice e indexador, también se eliminan todos los objetos generados . Sin embargo, si usó un índice existente para crear un origen de conocimiento, el índice no se eliminará.

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

1. Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

   ### Get knowledge bases
   GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
   api-key: {{api-key}}
   

   Una respuesta de ejemplo podría ser similar a la siguiente:

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

   ### Get a knowledge base definition
   GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}
   

   Una respuesta de ejemplo podría ser similar a la siguiente:

    {
      "name": "my-kb",
      "description": null,
      "retrievalInstructions": null,
      "answerInstructions": null,
      "outputMode": null,
      "knowledgeSources": [
        {
          "name": "my-blob-ks",
        }
      ],
      "models": [],
      "encryptionKey": null,
      "retrievalReasoningEffort": {
        "kind": "low"
      }
    }
   

3. Elimine la base de conocimiento o actualice la base de conocimiento quitando el origen de conocimiento si tiene varios orígenes. En este ejemplo se muestra la eliminación.

   ### Delete a knowledge base
   DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}
   

4. Elimine la fuente de conocimiento.

   ### Delete a knowledge source
   DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}