Создание удаленного источника знаний SharePoint

Удаленный источник знаний SharePoint использует API извлечения Copilot для запроса текстового содержимого непосредственно из SharePoint в Microsoft 365, возвращая результаты агентскому механизму извлечения для объединения, ранжирования и формулировки ответа. Нет индекса поиска, используемого этим источником знаний, и запрашивается только текстовое содержимое.

Во время запроса источник знаний SharePoint, находящийся удаленно, вызывает API Copilot Retrieval от имени идентичности пользователя, без необходимости использования строк подключения в определении источника знаний. Все содержимое, к которому у пользователя есть доступ, находится в области получения знаний. Чтобы ограничить сайты или ограничить поиск, задайте выражение фильтра. Клиент Azure и клиент Microsoft 365 должны использовать один и тот же тенант Идентификатора Microsoft Entra, а удостоверение вызывающего пользователя должно распознаваться обоими тенантами.

• Фильтры можно использовать для поиска по URL-адресам, диапазонам дат, типам файлов и другим метаданным.

• Разрешения SharePoint и метки Purview учитываются в запросах на содержимое.

• Плата за использование взимается через Microsoft 365 и лицензию Copilot.

Как и любой другой источник знаний, вы указываете удаленный источник знаний SharePoint в базе знаний и используете результаты в качестве заземления данных, когда агент или чат-бот вызывает действие извлечения во время запроса.

Предпосылки

• Поиск по искусственному интеллекту Azure в любом регионе, который предоставляет агентское извлечение. Необходимо включить семантику ранжирования.

• SharePoint в клиенте Microsoft 365, который находится под тем же клиентом Идентификатора Microsoft Entra, что и Azure.

• Токен доступа для локальной разработки или идентификатор пользователя из клиентского приложения.

• Последняя предварительная версия клиентской библиотекиAzure.Search.Documents для пакета SDK для .NET.

• Разрешение на создание и использование объектов в службе "Поиск ИИ Azure". Рекомендуем использовать доступ на основе ролей, но вы можете использовать ключи API, если назначение роли невозможно.

Для локальной разработки агентская система извлечения использует ваш токен доступа для вызова SharePoint от вашего имени. Дополнительные сведения об использовании персонального токена доступа для запросов см. статью "Подключение к поиску ИИ Azure".

Ограничения

Следующие ограничения в API извлечения Copilot применяются к источникам знаний SharePoint, работающим удалённо.

• Нет поддержки соединителей Copilot или содержимого OneDrive. Содержимое извлекается только из сайтов SharePoint.

• Ограничение в 200 запросов на пользователя в час.

• Ограничение символов запроса в 1500 символов.

• Гибридные запросы поддерживаются только для следующих расширений файлов: .doc, .docx, .pptx, .pdf, .aspx и .one.

• Многомодальное извлечение (нетекстовое содержимое, включая таблицы, изображения и диаграммы) не поддерживается.

• Не более 25 результатов из запроса.

• Результаты возвращаются API извлечения Copilot как неупорядоченные.

• Недопустимые выражения фильтра языка запросов ключевых слов (KQL) игнорируются, и запрос продолжает выполняться без фильтра.

Проверка существующих источников знаний

Источник знаний — это объект верхнего уровня, который можно использовать повторно. Знание существующих источников знаний полезно для повторного использования или именования новых объектов.

Выполните следующий код, чтобы перечислить источники знаний по имени и типу.

// 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}");
}

Вы также можете вернуть один источник знаний по имени, чтобы просмотреть его определение 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));

Следующий код JSON является примером ответа для удаленного источника знаний 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"
    ]
  }
}

Создание источника знаний

Выполните следующий код, чтобы создать удаленный источник знаний SharePoint.

Ключи API используются для подключения клиента к службе "Поиск ИИ Azure" и Azure OpenAI. Маркер доступа используется поиском ИИ Azure для подключения к SharePoint в Microsoft 365 от вашего имени. Вы можете получить только содержимое, к которому разрешен доступ. Дополнительные сведения о получении персонального токена доступа и других значений см. в статье Connect to 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.");

Свойства, относящиеся к источнику

Чтобы создать удаленный источник знаний SharePoint, можно передать следующие свойства.

Примеры выражений фильтра

Некоторые свойства SharePoint не поддерживаются в filterExpression. Список поддерживаемых свойств см. в справочнике по API. Ниже приведены дополнительные сведения о запрашиваемых свойствах, которые можно использовать в фильтре: запрашиваемые свойства.

Дополнительные сведения о фильтрах KQL см. в справочнике по синтаксису.

Назначение базе знаний

Если вы удовлетворены источником знаний, перейдите к следующему шагу: укажите источник знаний в базе знаний.

После настройки базы знаний используйте действие извлечения для запроса источника знаний.

Запрос к базе знаний

Действие получения в базе знаний предоставляет идентификацию пользователя, которая дает разрешение на доступ к содержимому в Microsoft 365.

Служба "Поиск ИИ Azure" использует маркер доступа для вызова API Извлечения Copilot от имени пользователя. Маркер доступа предоставляется в конечной точке извлечения в виде заголовка 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);

Ответ может выглядеть следующим образом:

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].

Запрос на получение также принимает фильтр KQL (filterExpressionAddOn), если вы хотите применить ограничения во время запроса. Если вы указываете filterExpressionAddOn как на действие извлечения из источника знаний, так и на действие извлечения из базы знаний, фильтры объединяются с использованием операции "И".

Запросы, задающие вопросы о самом содержимом, более эффективны, чем вопросы о расположении файла или о последнем обновлении файла. Например, если вы спросите: "Где находится основной документ для Ignite 2024", вы можете получить ответ "Нет подходящего содержимого для вашего запроса", так как само содержимое не раскрывает его местоположение. Фильтрация по метаданным является лучшим решением для запросов, связанных с местоположением файлов или определённой датой.

Лучше задать вопрос: "Что такое ключевой документ для Ignite 2024". Ответ включает синтезированный ответ, активность запросов и количество маркеров, а также URL-адрес и другие метаданные.

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

Удаление источника знаний

Прежде чем удалить источник знаний, необходимо удалить любую базу знаний, которая ссылается на нее или обновить определение базы знаний, чтобы удалить ссылку. Для источников знаний, которые создают индекс и конвейер индексатора, все созданные объекты также удаляются. Однако если вы использовали существующий индекс для создания источника знаний, индекс не удаляется.

Если вы пытаетесь удалить используемый источник знаний, действие завершается ошибкой и возвращает список затронутых баз знаний.

Удаление источника знаний:

1. Получите список всех баз знаний в службе поиска.

   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}");
   }
   

   Пример ответа может выглядеть следующим образом:

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

2. Получите отдельное определение базы знаний для проверки ссылок на источники знаний.

   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);
   

   Пример ответа может выглядеть следующим образом:

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

3. Удалите базу знаний или обновите базу знаний, чтобы удалить источник знаний при наличии нескольких источников. В этом примере показано удаление.

   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. Удалите источник знаний.

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

Удаленный источник знаний SharePoint использует API извлечения Copilot для запроса текстового содержимого непосредственно из SharePoint в Microsoft 365, возвращая результаты агентскому механизму извлечения для объединения, ранжирования и формулировки ответа. Нет индекса поиска, используемого этим источником знаний, и запрашивается только текстовое содержимое.

Во время запроса источник знаний SharePoint, находящийся удаленно, вызывает API Copilot Retrieval от имени идентичности пользователя, без необходимости использования строк подключения в определении источника знаний. Все содержимое, к которому у пользователя есть доступ, находится в области получения знаний. Чтобы ограничить сайты или ограничить поиск, задайте выражение фильтра. Клиент Azure и клиент Microsoft 365 должны использовать один и тот же тенант Идентификатора Microsoft Entra, а удостоверение вызывающего пользователя должно распознаваться обоими тенантами.

• Фильтры можно использовать для поиска по URL-адресам, диапазонам дат, типам файлов и другим метаданным.

• Разрешения SharePoint и метки Purview учитываются в запросах на содержимое.

• Плата за использование взимается через Microsoft 365 и лицензию Copilot.

Как и любой другой источник знаний, вы указываете удаленный источник знаний SharePoint в базе знаний и используете результаты в качестве заземления данных, когда агент или чат-бот вызывает действие извлечения во время запроса.

Предпосылки

• Поиск по искусственному интеллекту Azure в любом регионе, который предоставляет агентское извлечение. Необходимо включить семантику ранжирования.

• SharePoint в клиенте Microsoft 365, который находится под тем же клиентом Идентификатора Microsoft Entra, что и Azure.

• Токен доступа для локальной разработки или идентификатор пользователя из клиентского приложения.

• Последняя предварительная версия клиентской библиотекиazure-search-documents для Python.

• Разрешение на создание и использование объектов в службе "Поиск ИИ Azure". Рекомендуем использовать доступ на основе ролей, но вы можете использовать ключи API, если назначение роли невозможно.

Для локальной разработки агентская система извлечения использует ваш токен доступа для вызова SharePoint от вашего имени. Дополнительные сведения об использовании персонального токена доступа для запросов см. статью "Подключение к поиску ИИ Azure".

Ограничения

Следующие ограничения в API извлечения Copilot применяются к источникам знаний SharePoint, работающим удалённо.

• Нет поддержки соединителей Copilot или содержимого OneDrive. Содержимое извлекается только из сайтов SharePoint.

• Ограничение в 200 запросов на пользователя в час.

• Ограничение символов запроса в 1500 символов.

• Гибридные запросы поддерживаются только для следующих расширений файлов: .doc, .docx, .pptx, .pdf, .aspx и .one.

• Многомодальное извлечение (нетекстовое содержимое, включая таблицы, изображения и диаграммы) не поддерживается.

• Не более 25 результатов из запроса.

• Результаты возвращаются API извлечения Copilot как неупорядоченные.

• Недопустимые выражения фильтра языка запросов ключевых слов (KQL) игнорируются, и запрос продолжает выполняться без фильтра.

Проверка существующих источников знаний

Источник знаний — это объект верхнего уровня, который можно использовать повторно. Знание существующих источников знаний полезно для повторного использования или именования новых объектов.

Выполните следующий код, чтобы перечислить источники знаний по имени и типу.

# 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))

Вы также можете вернуть один источник знаний по имени, чтобы просмотреть его определение 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))

Следующий код JSON является примером ответа для удаленного источника знаний 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"
    ]
  }
}

Создание источника знаний

Выполните следующий код, чтобы создать удаленный источник знаний SharePoint.

Ключи API используются для подключения клиента к службе "Поиск ИИ Azure" и Azure OpenAI. Маркер доступа используется поиском ИИ Azure для подключения к SharePoint в Microsoft 365 от вашего имени. Вы можете получить только содержимое, к которому разрешен доступ. Дополнительные сведения о получении персонального токена доступа и других значений см. в статье Connect to 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.")

Свойства, относящиеся к источнику

Чтобы создать удаленный источник знаний SharePoint, можно передать следующие свойства.

Примеры выражений фильтра

Некоторые свойства SharePoint не поддерживаются в filterExpression. Список поддерживаемых свойств см. в справочнике по API. Ниже приведены дополнительные сведения о запрашиваемых свойствах, которые можно использовать в фильтре: запрашиваемые свойства.

Дополнительные сведения о фильтрах KQL см. в справочнике по синтаксису.

Назначение базе знаний

Если вы удовлетворены источником знаний, перейдите к следующему шагу: укажите источник знаний в базе знаний.

После настройки базы знаний используйте действие извлечения для запроса источника знаний.

Запрос к базе знаний

Действие получения в базе знаний предоставляет идентификацию пользователя, которая дает разрешение на доступ к содержимому в Microsoft 365.

Служба "Поиск ИИ Azure" использует маркер доступа для вызова API Извлечения Copilot от имени пользователя. Маркер доступа предоставляется в конечной точке извлечения в виде заголовка 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)

Запрос на получение также принимает фильтр KQL (filter_expression_add_on), если вы хотите применить ограничения во время запроса. Если вы указываете filter_expression_add_on как на действие извлечения из источника знаний, так и на действие извлечения из базы знаний, фильтры объединяются с использованием операции "И".

Запросы, задающие вопросы о самом содержимом, более эффективны, чем вопросы о расположении файла или о последнем обновлении файла. Например, если вы спросите: "Где находится основной документ для Ignite 2024", вы можете получить ответ "Нет подходящего содержимого для вашего запроса", так как само содержимое не раскрывает его местоположение. Фильтрация по метаданным является лучшим решением для запросов, связанных с местоположением файлов или определённой датой.

Лучше задать вопрос: "Что такое ключевой документ для Ignite 2024". Ответ включает синтезированный ответ, активность запросов и количество маркеров, а также URL-адрес и другие метаданные.

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

Удаление источника знаний

Прежде чем удалить источник знаний, необходимо удалить любую базу знаний, которая ссылается на нее или обновить определение базы знаний, чтобы удалить ссылку. Для источников знаний, которые создают индекс и конвейер индексатора, все созданные объекты также удаляются. Однако если вы использовали существующий индекс для создания источника знаний, индекс не удаляется.

Если вы пытаетесь удалить используемый источник знаний, действие завершается ошибкой и возвращает список затронутых баз знаний.

Удаление источника знаний:

1. Получите список всех баз знаний в службе поиска.

   # 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))
   

   Пример ответа может выглядеть следующим образом:

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

2. Получите отдельное определение базы знаний для проверки ссылок на источники знаний.

   # 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))
   

   Пример ответа может выглядеть следующим образом:

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

3. Удалите базу знаний или обновите базу знаний, чтобы удалить источник знаний при наличии нескольких источников. В этом примере показано удаление.

   # 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. Удалите источник знаний.

   # 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.")
   

Удаленный источник знаний SharePoint использует API извлечения Copilot для запроса текстового содержимого непосредственно из SharePoint в Microsoft 365, возвращая результаты агентскому механизму извлечения для объединения, ранжирования и формулировки ответа. Нет индекса поиска, используемого этим источником знаний, и запрашивается только текстовое содержимое.

Во время запроса источник знаний SharePoint, находящийся удаленно, вызывает API Copilot Retrieval от имени идентичности пользователя, без необходимости использования строк подключения в определении источника знаний. Все содержимое, к которому у пользователя есть доступ, находится в области получения знаний. Чтобы ограничить сайты или ограничить поиск, задайте выражение фильтра. Клиент Azure и клиент Microsoft 365 должны использовать один и тот же тенант Идентификатора Microsoft Entra, а удостоверение вызывающего пользователя должно распознаваться обоими тенантами.

• Фильтры можно использовать для поиска по URL-адресам, диапазонам дат, типам файлов и другим метаданным.

• Разрешения SharePoint и метки Purview учитываются в запросах на содержимое.

• Плата за использование взимается через Microsoft 365 и лицензию Copilot.

Как и любой другой источник знаний, вы указываете удаленный источник знаний SharePoint в базе знаний и используете результаты в качестве заземления данных, когда агент или чат-бот вызывает действие извлечения во время запроса.

Предпосылки

• Поиск по искусственному интеллекту Azure в любом регионе, который предоставляет агентское извлечение. Необходимо включить семантику ранжирования.

• SharePoint в клиенте Microsoft 365, который находится под тем же клиентом Идентификатора Microsoft Entra, что и Azure.

• Токен доступа для локальной разработки или идентификатор пользователя из клиентского приложения.

• Версия REST API службы поиска 2025-11-01-preview .

• Разрешение на создание и использование объектов в службе "Поиск ИИ Azure". Рекомендуем использовать доступ на основе ролей, но вы можете использовать ключи API, если назначение роли невозможно.

Для локальной разработки агентская система извлечения использует ваш токен доступа для вызова SharePoint от вашего имени. Дополнительные сведения об использовании персонального токена доступа для запросов см. статью "Подключение к поиску ИИ Azure".

Ограничения

Следующие ограничения в API извлечения Copilot применяются к источникам знаний SharePoint, работающим удалённо.

• Нет поддержки соединителей Copilot или содержимого OneDrive. Содержимое извлекается только из сайтов SharePoint.

• Ограничение в 200 запросов на пользователя в час.

• Ограничение символов запроса в 1500 символов.

• Гибридные запросы поддерживаются только для следующих расширений файлов: .doc, .docx, .pptx, .pdf, .aspx и .one.

• Многомодальное извлечение (нетекстовое содержимое, включая таблицы, изображения и диаграммы) не поддерживается.

• Не более 25 результатов из запроса.

• Результаты возвращаются API извлечения Copilot как неупорядоченные.

• Недопустимые выражения фильтра языка запросов ключевых слов (KQL) игнорируются, и запрос продолжает выполняться без фильтра.

Проверка существующих источников знаний

Источник знаний — это объект верхнего уровня, который можно использовать повторно. Знание существующих источников знаний полезно для повторного использования или именования новых объектов.

Используйте Knowledge Sources - Get (REST API) для перечисления источников знаний по имени и типу.

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

Вы также можете вернуть один источник знаний по имени, чтобы просмотреть его определение JSON.

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

Следующий код JSON является примером ответа для удаленного источника знаний 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"
    ]
  }
}

Создание источника знаний

Использование источников знаний — создание или обновление (REST API) для создания удаленного источника знаний SharePoint.

Ключи API используются для подключения клиента к службе "Поиск ИИ Azure" и Azure OpenAI. Маркер доступа используется поиском ИИ Azure для подключения к SharePoint в Microsoft 365 от вашего имени. Вы можете получить только содержимое, к которому разрешен доступ. Дополнительные сведения о получении персонального токена доступа и других значений см. в статье Connect to 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
    }
}

Свойства, относящиеся к источнику

Чтобы создать удаленный источник знаний SharePoint, можно передать следующие свойства.

Примеры выражений фильтра

Некоторые свойства SharePoint не поддерживаются в filterExpression. Список поддерживаемых свойств см. в справочнике по API. Ниже приведены дополнительные сведения о запрашиваемых свойствах, которые можно использовать в фильтре: запрашиваемые свойства.

Дополнительные сведения о фильтрах KQL см. в справочнике по синтаксису.

Назначение базе знаний

Если вы удовлетворены источником знаний, перейдите к следующему шагу: укажите источник знаний в базе знаний.

После настройки базы знаний используйте действие извлечения для запроса источника знаний.

Запрос к базе знаний

Действие получения в базе знаний предоставляет идентификацию пользователя, которая дает разрешение на доступ к содержимому в Microsoft 365.

Служба "Поиск ИИ Azure" использует маркер доступа для вызова API Извлечения Copilot от имени пользователя. Маркер доступа предоставляется в конечной точке извлечения в виде заголовка x-ms-query-source-authorization HTTP.

Убедитесь, что вы создаете маркер доступа для клиента, имеющего службу поиска.

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
        }
    ]
}

Запрос на получение также принимает фильтр KQL (filterExpressionAddOn), если вы хотите применить ограничения во время запроса. Если вы указываете filterExpressionAddOn как на действие извлечения из источника знаний, так и на действие извлечения из базы знаний, фильтры объединяются с использованием операции "И".

Запросы, задающие вопросы о самом содержимом, более эффективны, чем вопросы о расположении файла или о последнем обновлении файла. Например, если вы спросите: "Где находится основной документ для Ignite 2024", вы можете получить ответ "Нет подходящего содержимого для вашего запроса", так как само содержимое не раскрывает его местоположение. Фильтрация по метаданным является лучшим решением для запросов, связанных с местоположением файлов или определённой датой.

Лучше задать вопрос: "Что такое ключевой документ для Ignite 2024". Ответ включает синтезированный ответ, активность запросов и количество маркеров, а также URL-адрес и другие метаданные.

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

Удаление источника знаний

Прежде чем удалить источник знаний, необходимо удалить любую базу знаний, которая ссылается на нее или обновить определение базы знаний, чтобы удалить ссылку. Для источников знаний, которые создают индекс и конвейер индексатора, все созданные объекты также удаляются. Однако если вы использовали существующий индекс для создания источника знаний, индекс не удаляется.

Если вы пытаетесь удалить используемый источник знаний, действие завершается ошибкой и возвращает список затронутых баз знаний.

Удаление источника знаний:

1. Получите список всех баз знаний в службе поиска.

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

   Пример ответа может выглядеть следующим образом:

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

2. Получите отдельное определение базы знаний для проверки ссылок на источники знаний.

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

   Пример ответа может выглядеть следующим образом:

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

3. Удалите базу знаний или обновите базу знаний, удалив источник знаний, если у вас несколько источников. В этом примере показано удаление.

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

4. Удалите источник знаний.

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