Tworzenie zdalnego źródła wiedzy programu SharePoint

Zdalne źródło wiedzy SharePoint używa interfejsu API pobierania Copilot do wykonywania zapytań dotyczących zawartości tekstowej bezpośrednio z SharePoint na platformie Microsoft 365, zwracając wyniki do aparatu pobierania agentniczego do scalania, klasyfikowania i formułowania odpowiedzi. Nie jest używany żaden indeks wyszukiwania przez to źródło wiedzy, a zapytania są kierowane tylko do zawartości tekstowej.

Podczas wykonywania zapytania, zdalne źródło wiedzy SharePoint wywołuje interfejs API pobierania Copilot w imieniu tożsamości użytkownika, więc w definicji źródła wiedzy nie są potrzebne żadne ciągi połączenia. Cała zawartość, do której użytkownik ma dostęp, jest w zakresie pobierania wiedzy. Aby ograniczyć witryny lub zawęzić wyszukiwanie, ustaw wyrażenie filtru. Dzierżawa platformy Azure i dzierżawa platformy Microsoft 365 muszą używać tej samej dzierżawy Microsoft Entra ID, a tożsamość dzwoniącego musi być rozpoznawana przez obie dzierżawy.

• Filtry umożliwiają określanie zakresu wyszukiwania według adresów URL, zakresów dat, typów plików i innych metadanych.

• Uprawnienia programu SharePoint i etykiety usługi Purview są honorowane w żądaniach dotyczących zawartości.

• Opłaty za użycie są naliczane za pośrednictwem platformy Microsoft 365 i licencji Copilot.

Podobnie jak w przypadku dowolnego innego źródła wiedzy, należy określić zdalne źródło wiedzy programu SharePoint w bazie wiedzy i użyć wyników jako danych uziemowych, gdy agent lub czatbot wywołuje akcję pobierania w czasie zapytania.

Wymagania wstępne

• Usługa Azure AI Search w dowolnym regionie, który zapewnia agentowe wyszukiwanie. Musisz mieć włączony semantyczny ranker.

• SharePoint w dzierżawie Microsoft 365, która znajduje się pod tym samym dzierżawcą Microsoft Entra ID co Azure.

• Osobisty token dostępu do lokalnego programowania lub tożsamości użytkownika z aplikacji klienckiej.

• Najnowsza wersja Azure.Search.Documents zapoznawcza biblioteki klienta zestawu SDK platformy .NET.

• Uprawnienie do tworzenia obiektów i używania ich w usłudze Azure AI Search. Zalecamy dostęp oparty na rolach, ale możesz użyć kluczy interfejsu API , jeśli przypisanie roli nie jest możliwe.

W przypadku programowania lokalnego aparat pobierania agentów używa tokenu dostępu do wywoływania programu SharePoint w Twoim imieniu. Aby uzyskać więcej informacji na temat korzystania z osobistego tokenu dostępu na żądaniach, zobacz Connect to Azure AI Search (Nawiązywanie połączenia z usługą Azure AI Search).

Ograniczenia

Następujące ograniczenia w Copilot Retrieval API mają zastosowanie do zdalnych źródeł wiedzy SharePoint.

• Nie ma obsługi łączników Copilot ani zawartości usługi OneDrive. Zawartość jest pobierana tylko z witryn programu SharePoint.

• Limit 200 żądań na użytkownika na godzinę.

• Limit znaków zapytania wynosi 1500 znaków.

• Zapytania hybrydowe są obsługiwane tylko w przypadku następujących rozszerzeń plików: .doc, .docx, .pptx, .pdf, .aspx i .one.

• Pobieranie wielomodalne (zawartość nietekstowa, w tym tabele, obrazy i wykresy) nie jest obsługiwana.

• Maksymalnie 25 wyników z zapytania.

• Wyniki są zwracane przez interfejs API pobierania Copilot jako nieuporządkowany.

• Nieprawidłowe wyrażenia filtru języka zapytań słów kluczowych (KQL) są ignorowane, a zapytanie będzie nadal wykonywane bez filtru.

Sprawdzanie istniejących źródeł wiedzy

Źródłem wiedzy jest obiekt najwyższego poziomu wielokrotnego użytku. Znajomość istniejących źródeł wiedzy jest przydatna w przypadku ponownego użycia lub nazewnictwa nowych obiektów.

Uruchom następujący kod, aby wyświetlić listę źródeł wiedzy według nazwy i typu.

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

Możesz również zwrócić pojedyncze źródło wiedzy według nazwy, aby przejrzeć jego definicję 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));

Poniższy kod JSON to przykładowa odpowiedź dla zdalnego źródła wiedzy programu 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"
    ]
  }
}

Tworzenie źródła wiedzy

Uruchom następujący kod, aby utworzyć zdalne źródło wiedzy programu SharePoint.

Klucze interfejsu API są używane na potrzeby połączenia klienta z usługą Azure AI Search i usługą Azure OpenAI. Token dostępu jest używany przez usługę Azure AI Search do nawiązywania połączenia z programem SharePoint na platformie Microsoft 365 w Twoim imieniu. Możesz pobrać tylko zawartość, do której masz dostęp. Aby uzyskać więcej informacji na temat uzyskiwania osobistego tokenu dostępu i innych wartości, zobacz Connect to Azure AI Search (Nawiązywanie połączenia z usługą 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.");

Właściwości specyficzne dla źródła

Aby utworzyć zdalne źródło wiedzy programu SharePoint, możesz przekazać następujące właściwości.

Przykłady wyrażeń filtru

Nie wszystkie właściwości programu SharePoint są obsługiwane w pliku filterExpression. Aby uzyskać listę obsługiwanych właściwości, zobacz dokumentację interfejsu API. Oto kilka dodatkowych informacji na temat właściwości z możliwością wykonywania zapytań, których można użyć w filtrze: właściwości z możliwością wykonywania zapytań.

Dowiedz się więcej o filtrach KQL w dokumentacji składni.

Przypisywanie do bazy wiedzy

Jeśli źródło wiedzy jest zadowalające, przejdź do następnego kroku: określ źródło wiedzy w bazie wiedzy.

Po skonfigurowaniu bazy wiedzy użyj akcji pobierania , aby wysłać zapytanie do źródła wiedzy.

Wykonywanie zapytań w bazie wiedzy

Akcja pobierania w bazie wiedzy zapewnia tożsamość użytkownika, która autoryzuje dostęp do zawartości na platformie Microsoft 365.

Usługa Azure AI Search używa tokenu dostępu do wywoływania Copilot Retrieval API w imieniu użytkownika. Token dostępu jest udostępniany w punkcie końcowym pobierania xMsQuerySourceAuthorization jako nagłówek 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);

Odpowiedź może wyglądać następująco:

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

Żądanie pobierania przyjmuje również filtr KQL (filterExpressionAddOn), jeśli chcesz zastosować ograniczenia w czasie zapytania. Jeśli określisz filterExpressionAddOn zarówno źródło wiedzy, jak i akcję pobierania bazy wiedzy, filtry zostaną połączone ze sobą za pomocą operacji logicznej AND.

Zapytania zadając pytania dotyczące samej zawartości są bardziej skuteczne niż pytania dotyczące lokalizacji pliku lub ostatniej aktualizacji. Na przykład, jeśli zapytasz "Gdzie jest dokument z kluczowym przemówieniem na Ignite 2024", możesz otrzymać komunikat "Nie znaleziono odpowiedniej zawartości dla twojego zapytania", ponieważ sam dokument nie ujawnia swojej lokalizacji. Filtr metadanych jest lepszym rozwiązaniem dla lokalizacji pliku lub zapytań specyficznych dla daty.

Lepszym pytaniem do zadawania jest "Co to jest główny dokument dotyczący konferencji Ignite 2024". Odpowiedź zawiera syntetyzowana odpowiedź, aktywność zapytań i liczbę tokenów oraz adres URL i inne metadane.

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

Usuwanie źródła wiedzy

Aby można było usunąć źródło wiedzy, należy usunąć dowolną bazę wiedzy, która odwołuje się do źródła wiedzy, lub zaktualizować definicję bazy wiedzy, aby usunąć odwołanie. W przypadku źródeł wiedzy, które generują potok indeksu i indeksatora, wszystkie wygenerowane obiekty również są usuwane. Jeśli jednak użyto istniejącego indeksu do utworzenia źródła wiedzy, indeks nie zostanie usunięty.

Jeśli spróbujesz usunąć używane źródło wiedzy, akcja zakończy się niepowodzeniem i zwróci listę baz wiedzy, których dotyczy problem.

Aby usunąć źródło wiedzy:

1. Pobierz listę wszystkich baz wiedzy w usłudze wyszukiwania.

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

   Przykładowa odpowiedź może wyglądać następująco:

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

2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

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

   Przykładowa odpowiedź może wyglądać następująco:

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

3. Usuń bazę wiedzy lub zaktualizuj bazę wiedzy , aby usunąć źródło wiedzy, jeśli masz wiele źródeł. W tym przykładzie pokazano usunięcie.

   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. Usuń źródło wiedzy.

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

Zdalne źródło wiedzy SharePoint używa interfejsu API pobierania Copilot do wykonywania zapytań dotyczących zawartości tekstowej bezpośrednio z SharePoint na platformie Microsoft 365, zwracając wyniki do aparatu pobierania agentniczego do scalania, klasyfikowania i formułowania odpowiedzi. Nie jest używany żaden indeks wyszukiwania przez to źródło wiedzy, a zapytania są kierowane tylko do zawartości tekstowej.

Podczas wykonywania zapytania, zdalne źródło wiedzy SharePoint wywołuje interfejs API pobierania Copilot w imieniu tożsamości użytkownika, więc w definicji źródła wiedzy nie są potrzebne żadne ciągi połączenia. Cała zawartość, do której użytkownik ma dostęp, jest w zakresie pobierania wiedzy. Aby ograniczyć witryny lub zawęzić wyszukiwanie, ustaw wyrażenie filtru. Dzierżawa platformy Azure i dzierżawa platformy Microsoft 365 muszą używać tej samej dzierżawy Microsoft Entra ID, a tożsamość dzwoniącego musi być rozpoznawana przez obie dzierżawy.

• Filtry umożliwiają określanie zakresu wyszukiwania według adresów URL, zakresów dat, typów plików i innych metadanych.

• Uprawnienia programu SharePoint i etykiety usługi Purview są honorowane w żądaniach dotyczących zawartości.

• Opłaty za użycie są naliczane za pośrednictwem platformy Microsoft 365 i licencji Copilot.

Podobnie jak w przypadku dowolnego innego źródła wiedzy, należy określić zdalne źródło wiedzy programu SharePoint w bazie wiedzy i użyć wyników jako danych uziemowych, gdy agent lub czatbot wywołuje akcję pobierania w czasie zapytania.

Wymagania wstępne

• Usługa Azure AI Search w dowolnym regionie, który zapewnia agentowe wyszukiwanie. Musisz mieć włączony semantyczny ranker.

• SharePoint w dzierżawie Microsoft 365, która znajduje się pod tym samym dzierżawcą Microsoft Entra ID co Azure.

• Osobisty token dostępu do lokalnego programowania lub tożsamości użytkownika z aplikacji klienckiej.

• Najnowsza wersja azure-search-documents zapoznawcza biblioteki klienta języka Python.

• Uprawnienie do tworzenia obiektów i używania ich w usłudze Azure AI Search. Zalecamy dostęp oparty na rolach, ale możesz użyć kluczy interfejsu API , jeśli przypisanie roli nie jest możliwe.

W przypadku programowania lokalnego aparat pobierania agentów używa tokenu dostępu do wywoływania programu SharePoint w Twoim imieniu. Aby uzyskać więcej informacji na temat korzystania z osobistego tokenu dostępu na żądaniach, zobacz Connect to Azure AI Search (Nawiązywanie połączenia z usługą Azure AI Search).

Ograniczenia

Następujące ograniczenia w Copilot Retrieval API mają zastosowanie do zdalnych źródeł wiedzy SharePoint.

• Nie ma obsługi łączników Copilot ani zawartości usługi OneDrive. Zawartość jest pobierana tylko z witryn programu SharePoint.

• Limit 200 żądań na użytkownika na godzinę.

• Limit znaków zapytania wynosi 1500 znaków.

• Zapytania hybrydowe są obsługiwane tylko w przypadku następujących rozszerzeń plików: .doc, .docx, .pptx, .pdf, .aspx i .one.

• Pobieranie wielomodalne (zawartość nietekstowa, w tym tabele, obrazy i wykresy) nie jest obsługiwana.

• Maksymalnie 25 wyników z zapytania.

• Wyniki są zwracane przez interfejs API pobierania Copilot jako nieuporządkowany.

• Nieprawidłowe wyrażenia filtru języka zapytań słów kluczowych (KQL) są ignorowane, a zapytanie będzie nadal wykonywane bez filtru.

Sprawdzanie istniejących źródeł wiedzy

Źródłem wiedzy jest obiekt najwyższego poziomu wielokrotnego użytku. Znajomość istniejących źródeł wiedzy jest przydatna w przypadku ponownego użycia lub nazewnictwa nowych obiektów.

Uruchom następujący kod, aby wyświetlić listę źródeł wiedzy według nazwy i typu.

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

Możesz również zwrócić pojedyncze źródło wiedzy według nazwy, aby przejrzeć jego definicję 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))

Poniższy kod JSON to przykładowa odpowiedź dla zdalnego źródła wiedzy programu 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"
    ]
  }
}

Tworzenie źródła wiedzy

Uruchom następujący kod, aby utworzyć zdalne źródło wiedzy programu SharePoint.

Klucze interfejsu API są używane na potrzeby połączenia klienta z usługą Azure AI Search i usługą Azure OpenAI. Token dostępu jest używany przez usługę Azure AI Search do nawiązywania połączenia z programem SharePoint na platformie Microsoft 365 w Twoim imieniu. Możesz pobrać tylko zawartość, do której masz dostęp. Aby uzyskać więcej informacji na temat uzyskiwania osobistego tokenu dostępu i innych wartości, zobacz Connect to Azure AI Search (Nawiązywanie połączenia z usługą 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.")

Właściwości specyficzne dla źródła

Aby utworzyć zdalne źródło wiedzy programu SharePoint, możesz przekazać następujące właściwości.

Przykłady wyrażeń filtru

Nie wszystkie właściwości programu SharePoint są obsługiwane w pliku filterExpression. Aby uzyskać listę obsługiwanych właściwości, zobacz dokumentację interfejsu API. Oto kilka dodatkowych informacji na temat właściwości z możliwością wykonywania zapytań, których można użyć w filtrze: właściwości z możliwością wykonywania zapytań.

Dowiedz się więcej o filtrach KQL w dokumentacji składni.

Przypisywanie do bazy wiedzy

Jeśli źródło wiedzy jest zadowalające, przejdź do następnego kroku: określ źródło wiedzy w bazie wiedzy.

Po skonfigurowaniu bazy wiedzy użyj akcji pobierania , aby wysłać zapytanie do źródła wiedzy.

Wykonywanie zapytań w bazie wiedzy

Akcja pobierania w bazie wiedzy zapewnia tożsamość użytkownika, która autoryzuje dostęp do zawartości na platformie Microsoft 365.

Usługa Azure AI Search używa tokenu dostępu do wywoływania Copilot Retrieval API w imieniu użytkownika. Token dostępu jest udostępniany w punkcie końcowym pobierania x-ms-query-source-authorization jako nagłówek 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)

Żądanie pobierania przyjmuje również filtr KQL (filter_expression_add_on), jeśli chcesz zastosować ograniczenia w czasie zapytania. Jeśli określisz filter_expression_add_on zarówno źródło wiedzy, jak i akcję pobierania bazy wiedzy, filtry zostaną połączone ze sobą za pomocą operacji logicznej AND.

Zapytania zadając pytania dotyczące samej zawartości są bardziej skuteczne niż pytania dotyczące lokalizacji pliku lub ostatniej aktualizacji. Na przykład, jeśli zapytasz "Gdzie jest dokument z kluczowym przemówieniem na Ignite 2024", możesz otrzymać komunikat "Nie znaleziono odpowiedniej zawartości dla twojego zapytania", ponieważ sam dokument nie ujawnia swojej lokalizacji. Filtr metadanych jest lepszym rozwiązaniem dla lokalizacji pliku lub zapytań specyficznych dla daty.

Lepszym pytaniem do zadawania jest "Co to jest główny dokument dotyczący konferencji Ignite 2024". Odpowiedź zawiera syntetyzowana odpowiedź, aktywność zapytań i liczbę tokenów oraz adres URL i inne metadane.

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

Usuwanie źródła wiedzy

Aby można było usunąć źródło wiedzy, należy usunąć dowolną bazę wiedzy, która odwołuje się do źródła wiedzy, lub zaktualizować definicję bazy wiedzy, aby usunąć odwołanie. W przypadku źródeł wiedzy, które generują potok indeksu i indeksatora, wszystkie wygenerowane obiekty również są usuwane. Jeśli jednak użyto istniejącego indeksu do utworzenia źródła wiedzy, indeks nie zostanie usunięty.

Jeśli spróbujesz usunąć używane źródło wiedzy, akcja zakończy się niepowodzeniem i zwróci listę baz wiedzy, których dotyczy problem.

Aby usunąć źródło wiedzy:

1. Pobierz listę wszystkich baz wiedzy w usłudze wyszukiwania.

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

   Przykładowa odpowiedź może wyglądać następująco:

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

2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

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

   Przykładowa odpowiedź może wyglądać następująco:

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

3. Usuń bazę wiedzy lub zaktualizuj bazę wiedzy , aby usunąć źródło wiedzy, jeśli masz wiele źródeł. W tym przykładzie pokazano usunięcie.

   # 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. Usuń źródło wiedzy.

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

Zdalne źródło wiedzy SharePoint używa interfejsu API pobierania Copilot do wykonywania zapytań dotyczących zawartości tekstowej bezpośrednio z SharePoint na platformie Microsoft 365, zwracając wyniki do aparatu pobierania agentniczego do scalania, klasyfikowania i formułowania odpowiedzi. Nie jest używany żaden indeks wyszukiwania przez to źródło wiedzy, a zapytania są kierowane tylko do zawartości tekstowej.

Podczas wykonywania zapytania, zdalne źródło wiedzy SharePoint wywołuje interfejs API pobierania Copilot w imieniu tożsamości użytkownika, więc w definicji źródła wiedzy nie są potrzebne żadne ciągi połączenia. Cała zawartość, do której użytkownik ma dostęp, jest w zakresie pobierania wiedzy. Aby ograniczyć witryny lub zawęzić wyszukiwanie, ustaw wyrażenie filtru. Dzierżawa platformy Azure i dzierżawa platformy Microsoft 365 muszą używać tej samej dzierżawy Microsoft Entra ID, a tożsamość dzwoniącego musi być rozpoznawana przez obie dzierżawy.

• Filtry umożliwiają określanie zakresu wyszukiwania według adresów URL, zakresów dat, typów plików i innych metadanych.

• Uprawnienia programu SharePoint i etykiety usługi Purview są honorowane w żądaniach dotyczących zawartości.

• Opłaty za użycie są naliczane za pośrednictwem platformy Microsoft 365 i licencji Copilot.

Podobnie jak w przypadku dowolnego innego źródła wiedzy, należy określić zdalne źródło wiedzy programu SharePoint w bazie wiedzy i użyć wyników jako danych uziemowych, gdy agent lub czatbot wywołuje akcję pobierania w czasie zapytania.

Wymagania wstępne

• Usługa Azure AI Search w dowolnym regionie, który zapewnia agentowe wyszukiwanie. Musisz mieć włączony semantyczny ranker.

• SharePoint w dzierżawie Microsoft 365, która znajduje się pod tym samym dzierżawcą Microsoft Entra ID co Azure.

• Osobisty token dostępu do lokalnego programowania lub tożsamości użytkownika z aplikacji klienckiej.

• Wersja 2025-11-01-preview interfejsów REST API usługi wyszukiwania.

• Uprawnienie do tworzenia obiektów i używania ich w usłudze Azure AI Search. Zalecamy dostęp oparty na rolach, ale możesz użyć kluczy interfejsu API , jeśli przypisanie roli nie jest możliwe.

W przypadku programowania lokalnego aparat pobierania agentów używa tokenu dostępu do wywoływania programu SharePoint w Twoim imieniu. Aby uzyskać więcej informacji na temat korzystania z osobistego tokenu dostępu na żądaniach, zobacz Connect to Azure AI Search (Nawiązywanie połączenia z usługą Azure AI Search).

Ograniczenia

Następujące ograniczenia w Copilot Retrieval API mają zastosowanie do zdalnych źródeł wiedzy SharePoint.

• Nie ma obsługi łączników Copilot ani zawartości usługi OneDrive. Zawartość jest pobierana tylko z witryn programu SharePoint.

• Limit 200 żądań na użytkownika na godzinę.

• Limit znaków zapytania wynosi 1500 znaków.

• Zapytania hybrydowe są obsługiwane tylko w przypadku następujących rozszerzeń plików: .doc, .docx, .pptx, .pdf, .aspx i .one.

• Pobieranie wielomodalne (zawartość nietekstowa, w tym tabele, obrazy i wykresy) nie jest obsługiwana.

• Maksymalnie 25 wyników z zapytania.

• Wyniki są zwracane przez interfejs API pobierania Copilot jako nieuporządkowany.

• Nieprawidłowe wyrażenia filtru języka zapytań słów kluczowych (KQL) są ignorowane, a zapytanie będzie nadal wykonywane bez filtru.

Sprawdzanie istniejących źródeł wiedzy

Źródłem wiedzy jest obiekt najwyższego poziomu wielokrotnego użytku. Znajomość istniejących źródeł wiedzy jest przydatna w przypadku ponownego użycia lub nazewnictwa nowych obiektów.

Użyj Knowledge Sources - Get (REST API), aby wyświetlić listę źródeł wiedzy według nazwy i typu.

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

Możesz również zwrócić pojedyncze źródło wiedzy według nazwy, aby przejrzeć jego definicję JSON.

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

Poniższy kod JSON to przykładowa odpowiedź dla zdalnego źródła wiedzy programu 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"
    ]
  }
}

Tworzenie źródła wiedzy

Użyj źródeł wiedzy — utwórz lub zaktualizuj (interfejs API REST), aby utworzyć zdalne źródło wiedzy programu SharePoint.

Klucze interfejsu API są używane na potrzeby połączenia klienta z usługą Azure AI Search i usługą Azure OpenAI. Token dostępu jest używany przez usługę Azure AI Search do nawiązywania połączenia z programem SharePoint na platformie Microsoft 365 w Twoim imieniu. Możesz pobrać tylko zawartość, do której masz dostęp. Aby uzyskać więcej informacji na temat uzyskiwania osobistego tokenu dostępu i innych wartości, zobacz Connect to Azure AI Search (Nawiązywanie połączenia z usługą 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
    }
}

Właściwości specyficzne dla źródła

Aby utworzyć zdalne źródło wiedzy programu SharePoint, możesz przekazać następujące właściwości.

Przykłady wyrażeń filtru

Nie wszystkie właściwości programu SharePoint są obsługiwane w pliku filterExpression. Aby uzyskać listę obsługiwanych właściwości, zobacz dokumentację interfejsu API. Oto kilka dodatkowych informacji na temat właściwości z możliwością wykonywania zapytań, których można użyć w filtrze: właściwości z możliwością wykonywania zapytań.

Dowiedz się więcej o filtrach KQL w dokumentacji składni.

Przypisywanie do bazy wiedzy

Jeśli źródło wiedzy jest zadowalające, przejdź do następnego kroku: określ źródło wiedzy w bazie wiedzy.

Po skonfigurowaniu bazy wiedzy użyj akcji pobierania , aby wysłać zapytanie do źródła wiedzy.

Wykonywanie zapytań w bazie wiedzy

Akcja pobierania w bazie wiedzy zapewnia tożsamość użytkownika, która autoryzuje dostęp do zawartości na platformie Microsoft 365.

Usługa Azure AI Search używa tokenu dostępu do wywoływania Copilot Retrieval API w imieniu użytkownika. Token dostępu jest udostępniany w punkcie końcowym pobierania x-ms-query-source-authorization jako nagłówek HTTP.

Upewnij się, że wygenerujesz token dostępu dla dzierżawcy, który ma usługę wyszukiwania.

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

Żądanie pobierania przyjmuje również filtr KQL (filterExpressionAddOn), jeśli chcesz zastosować ograniczenia w czasie zapytania. Jeśli określisz filterExpressionAddOn zarówno źródło wiedzy, jak i akcję pobierania bazy wiedzy, filtry zostaną połączone ze sobą za pomocą operacji logicznej AND.

Zapytania zadając pytania dotyczące samej zawartości są bardziej skuteczne niż pytania dotyczące lokalizacji pliku lub ostatniej aktualizacji. Na przykład, jeśli zapytasz "Gdzie jest dokument z kluczowym przemówieniem na Ignite 2024", możesz otrzymać komunikat "Nie znaleziono odpowiedniej zawartości dla twojego zapytania", ponieważ sam dokument nie ujawnia swojej lokalizacji. Filtr metadanych jest lepszym rozwiązaniem dla lokalizacji pliku lub zapytań specyficznych dla daty.

Lepszym pytaniem do zadawania jest "Co to jest główny dokument dotyczący konferencji Ignite 2024". Odpowiedź zawiera syntetyzowana odpowiedź, aktywność zapytań i liczbę tokenów oraz adres URL i inne metadane.

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

Usuwanie źródła wiedzy

Aby można było usunąć źródło wiedzy, należy usunąć dowolną bazę wiedzy, która odwołuje się do źródła wiedzy, lub zaktualizować definicję bazy wiedzy, aby usunąć odwołanie. W przypadku źródeł wiedzy, które generują potok indeksu i indeksatora, wszystkie wygenerowane obiekty również są usuwane. Jeśli jednak użyto istniejącego indeksu do utworzenia źródła wiedzy, indeks nie zostanie usunięty.

Jeśli spróbujesz usunąć używane źródło wiedzy, akcja zakończy się niepowodzeniem i zwróci listę baz wiedzy, których dotyczy problem.

Aby usunąć źródło wiedzy:

1. Pobierz listę wszystkich baz wiedzy w usłudze wyszukiwania.

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

   Przykładowa odpowiedź może wyglądać następująco:

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

2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

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

   Przykładowa odpowiedź może wyglądać następująco:

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

3. Usuń bazę wiedzy lub zaktualizuj bazę wiedzy , usuwając źródło wiedzy, jeśli masz wiele źródeł. W tym przykładzie pokazano usunięcie.

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

4. Usuń źródło wiedzy.

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