Erstellen einer Work IQ-Wissensquelle (Vorschau)

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

Important

Work IQ-Wissensquelle befindet sich in der Public Preview und unterliegt den zusätzlichen Nutzungsbedingungen für Microsoft Azure Previews.

Die für dieses Feature geltenden Vorschaubedingungen finden Sie unter Previewfunktionalität.

Ausdrücke, die beim Herstellen einer Verbindung mit externen Datenquellen gelten, finden Sie unter "Externe Datenquellen".

Wenn Sie eine Verbindung mit Work IQ herstellen, entstehen möglicherweise Kosten, und Daten werden möglicherweise außerhalb der Azure Compliancegrenze gesendet und gemäß den geltenden Dienstbedingungen und Datenverarbeitungsrichtlinien verarbeitet.

Eine Work IQ-Wissensquelle (Vorschau) verbindet Work IQ mit einer agentischen Retrieval-Pipeline in Foundry IQ (Azure KI-Suche). Wissensquellen werden unabhängig erstellt, in einer Wissensbasis referenziert und als Erdungsdaten verwendet, wenn die Wissensbasis zur Laufzeit abgefragt wird.

Work IQ macht organisatorische Erkenntnisse aus Ihren Microsoft 365-Inhalten sichtbar, darunter Dokumente, E-Mails, Besprechungen und Aktivitäten in Microsoft 365-Apps.

Im Gegensatz zu indizierten Wissensquellen fragen Work IQ-Wissensquellen Live-Daten direkt zum Zeitpunkt des Abrufs ab. Es ist keine Aufnahmepipeline erforderlich. Abfragen erfordern ein Für Ihre Microsoft Entra App-Registrierung ausgestelltes Benutzerzugriffstoken. Foundry IQ tauscht dieses Token gegen ein delegiertes Work IQ-Token aus und ruft Work IQ im Auftrag des Benutzers auf.

Warning

In dieser Vorschau könnte eine Work IQ-Wissensquelle Work IQ-Funktionen verwenden, mit denen Aktionen ausgeführt und nicht nur Informationen abgerufen werden können. Verwenden Sie sie mit Bedacht, beschränken Sie den Zugriff auf vertrauenswürdige Anwendungen und Benutzer, und überprüfen Sie die Berechtigungen und Governance-Steuerelemente Ihres Szenarios, bevor Sie es aktivieren.

Nutzungssupport

Azure Portal Microsoft Foundry-Portal .NET SDK Python SDK Java SDK JavaScript SDK REST-API
❌ ❌ ✔️ ✔️ ❌ ❌ ✔️

Voraussetzungen

  • Das neueste Azure.Search.Documents Vorschaupaket: dotnet add package Azure.Search.Documents --prerelease

  • Für die schlüssellose Authentifizierung das Paket Azure.Identity: dotnet add package Azure.Identity

  • Das neueste azure-search-documents Vorschaupaket: pip install --pre azure-search-documents

  • Für die schlüssellose Authentifizierung das Paket azure-identity: pip install azure-identity

Datenverwaltung und Compliance

Bevor Sie das Abrufen von Work IQ aktivieren, überprüfen Sie Daten, Datenschutz und Sicherheit für Microsoft Copilot.

Datennutzung und Datenschutz

Aufforderungen, Antworten und Daten, auf die über Microsoft Graph zugegriffen wird, werden nicht zum Trainieren von Foundation-Sprachmodellen verwendet.

Zugriffskontrolle

Work IQ wendet Microsoft 365 Berechtigungen auf jede Anfrage an. Der Abruf gibt nur Organisationsdaten zurück, auf die der angemeldete Benutzer über die Berechtigung zum Zugriff verfügt.

Datenstandort und Compliance

Lesen Sie die Microsoft 365-Dokumentation zu Datenresidenz, Datenschutz, Sicherheit und Compliance-Zusagen, die für Ihre Organisation und Ihr Szenario gelten.

Einrichten der Microsoft Entra-Authentifizierung

Ab der 2026-08-01-preview API-Version verwendet jede Work IQ-Wissensquelle eine kundeneigene Microsoft Entra App-Registrierung für die Authentifizierung. Zum Zeitpunkt der Abfrage funktioniert die Authentifizierung wie folgt:

  1. Die Client-App meldet den Benutzer an und sendet eine Benutzerassertion an Foundry IQ.
  2. Die verwaltete Identität des Foundry IQ-Diensts authentifiziert sich als kundeneigene App über eine Verbundanmeldeinformation.
  3. Foundry IQ austauscht die Benutzer assertion für ein delegiertes Work IQ-Token und ruft Work IQ im Namen des angemeldeten Benutzers auf.

Kein geheimer Clientschlüssel wird auf der Work IQ-Wissensquelle gespeichert. Konfigurieren Sie die App und ihre Berechtigungen einmal, und erstellen Sie dann eine Verbundanmeldeinformationen für jede Foundry IQ-Dienstidentität, die die App verwendet.

Konfigurieren der Work IQ-App-Registrierung

So konfigurieren Sie die kundeneigene App, die Foundry IQ zum Aufrufen von Work IQ verwendet:

  1. Registrieren Sie eine Anwendung im Microsoft Entra Mandanten, in dem Sie die Work IQ-Zustimmung verwalten möchten. Wählen Sie für Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus.

  2. Kopieren Sie auf der Seite "Übersicht" der App-Registrierung die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant). Sie benötigen die Anwendungs-ID, um die Work IQ-Authentifizierung und die Mandanten-ID zu konfigurieren, um sich beim Mandanten anzumelden, der die App-Registrierung enthält.

  3. Fügen Sie auf der Seite " Verfügbarmachen einer API" der App-Registrierungden erforderlichen delegierten Bereich mit dem Namen genau access_as_userhinzu. Verwenden Sie diesen Kleinbuchstabennamen; ersetzen Sie keinen anderen Bereichsnamen. Der vollständige Bereich ist api://<application-client-id>/access_as_user.

  4. Wählen Sie auf der API-Berechtigungsseite der App-Registrierungdie Option "Berechtigungs-APIs>hinzufügen" aus, die meine Organisation verwendet.

  5. Suchen Sie nach Work IQ (Anwendungs-ID fdcc1f02-fc51-4226-8753-f668596af7f7), wählen Sie delegierte Berechtigungen>WorkIQAgent.Ask aus, und wählen Sie dann "Berechtigungen hinzufügen" aus.

  6. Bitten Sie einen Administrator mit einer in den Voraussetzungen aufgeführten Rolle zum Erteilen von Zustimmungen, auf derselben Seite Administratoreinwilligung für [Ihren Mandanten] erteilen auszuwählen. Mit dieser Zustimmung kann die App eine Assertion eines Benutzers gegen ein delegiertes Work IQ-Token eintauschen.

Konfigurieren Sie die Dienstidentität von Foundry IQ

So konfigurieren Sie die Identität, die Foundry IQ zur Authentifizierung als Ihre Work IQ-App verwendet:

  1. Aktivieren Sie eine vom System zugewiesene verwaltete Identität in Ihrem Foundry IQ-Dienst. Wenn Sie keine vom System zugewiesene Identität verwenden können, konfigurieren Sie genau eine vom Benutzer zugewiesene Identität. Ein Foundry IQ-Dienst mit mehreren vom Benutzer zugewiesenen Identitäten und ohne vom System zugewiesene Identität wird nicht unterstützt.

  2. Kopieren Sie auf der Seite „Identity“ des Foundry IQ-Diensts die Objekt-ID (Prinzipal). Die Verbundanmeldeinformation verwendet diesen Wert als subject.

  3. Wechseln Sie zu Microsoft Entra ID>Overview, und kopieren Sie die Mandanten-ID. Die Verbundanmeldeinformation verwendet diesen Wert in der issuer URL.

Erstellen einer Verbundanmeldeinformation

So erstellen Sie eine Verbundanmeldeinformation für die Foundry IQ-Dienstidentität:

  1. Erstellen Sie eine Datei mit dem Namen credential.json. Ersetzen Sie <search-service-name>, <search-service-tenant-id> und <search-service-principal-id> durch die Werte für Ihren Foundry IQ-Dienst.

    {
      "name": "<search-service-name>-identity",
      "issuer": "https://login.microsoftonline.com/<search-service-tenant-id>/v2.0",
      "subject": "<search-service-principal-id>",
      "audiences": ["api://AzureADTokenExchange"]
    }
    

    Der Anmeldeinformationsname muss für die App-Registrierung eindeutig sein. Der subject Wert muss exakt mit der Prinzipal-ID der verwalteten Identität übereinstimmen. Eine Nichtübereinstimmung tritt auf, wenn Sie eine Abfrage ausführen, nicht wenn Sie die Wissensquelle erstellen.

  2. Melden Sie sich bei der Azure CLI mit dem Mandanten an, in dem sich die App-Registrierung befindet.

    az login --tenant <app-tenant-id> --allow-no-subscriptions
    
  3. Erstellen einer Verbundanmeldeinformation.

    az ad app federated-credential create --id <application-client-id> --parameters credential.json --query id --output tsv
    
  4. Kopieren Sie die Befehlsausgabe. Verwenden Sie diesen Wert für federatedCredentialId, wenn Sie die Work-IQ-Wissensquelle erstellen.

Jede Verbundanmeldeinformation vertraut einer verwalteten Identitätsprinzipal-ID. Wenn eine andere Findry IQ-Dienstidentität die App-Registrierung verwendet, wiederholen Sie dieses Verfahren mit einem eindeutigen Anmeldeinformationsnamen und den Mandanten- und Prinzipal-IDs dieser Identität. Verwenden Sie bei jeder Work IQ-Wissensquelle die entsprechende Anmelde-ID.

Konfigurieren der Client-App

So konfigurieren Sie die App, die Benutzer anmeldet und Abrufanforderungen sendet:

  1. Wählen Sie auf der API-Berechtigungsseite der Client-Appdie Option "Berechtigungs-APIs>hinzufügen" aus, die meine Organisation verwendet.

  2. Fügen Sie die Zuvor kopierte Anwendungs-ID (Client) in das Suchfeld ein, und wählen Sie dann die Registrierung der Work IQ-App aus.

  3. Wählen Sie delegierte Berechtigungen>access_as_user und dann "Berechtigungen hinzufügen" aus.

  4. Erteilen Sie alle Einwilligungen, die gemäß der Benutzereinwilligungsrichtlinie Ihres Mandanten erforderlich sind. Wenn die Administratoreinwilligung erforderlich ist, lassen Sie einen Administrator Administratoreinwilligung für [Ihren Mandanten] erteilen auswählen.

Die Client-App kann jetzt eine Benutzer assertion für die Work IQ-App-Registrierung anfordern. Die access_as_user Berechtigung gewährt der Client-App keinen direkten Zugriff auf Work IQ.

Authentifizierungswerte

Wenn Sie eine Work IQ-Wissensquelle erstellen, verwenden Sie die folgenden entraAppAuthentication Werte aus Ihrem Microsoft Entra App-Setup. Jeder von Ihnen bereitgestellte Wert muss eine GUID sein.

Property Erforderlich Value
applicationId Ja Anwendungs-ID (Client) Ihrer Work IQ-App-Registrierung.
federatedCredentialId Ja Objekt-ID der föderierten Anmeldeinformationen, die Sie für die App erstellt haben. Es handelt sich nicht um den Anmeldeinformationsnamen und nicht um die Prinzipal-ID des Foundry IQ-Diensts.
tenantId No Verzeichnis-ID (Mandant) der App-Registrierung. Lassen Sie diese Eigenschaft aus, wenn sich die App-Registrierung und der Foundry IQ-Dienst im selben Mandanten befinden. Wenn sie sich in verschiedenen Mandanten befinden, ist diese Eigenschaft erforderlich.

Überprüfen auf vorhandene Wissensquellen

Eine Wissensquelle ist ein wiederverwendbares Objekt auf oberster Ebene. Das Wissen über vorhandene Wissensquellen ist hilfreich, um neue Objekte wiederzuverwenden oder zu benennen.

Führen Sie den folgenden Code aus, um Wissensquellen nach Namen und Typ auflisten.

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

Reference:SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

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

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

Reference:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

Referenz:Wissensquellen - Liste

Sie können auch eine einzelne Wissensquelle anhand des Namens zurückgeben, um die JSON-Definition zu überprüfen.

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

Reference:SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

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

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

Reference:SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}

Referenz:Wissensquellen - Abrufen

Der folgende JSON-Code ist eine Beispielantwort für eine Work IQ-Wissensquelle.

{
  "name": "my-workiq-ks",
  "kind": "workIQ",
  "description": "A sample Work IQ knowledge source.",
  "workIQParameters": {
    "entraAppAuthentication": {
      "applicationId": "11111111-1111-1111-1111-111111111111",
      "federatedCredentialId": "22222222-2222-2222-2222-222222222222",
      "tenantId": null
    }
  },
  "encryptionKey": null
}

Erstellen einer Wissensquelle

Führen Sie den folgenden Code aus, um eine Work IQ-Wissensquelle zu erstellen.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

Uri searchEndpoint =
    new("https://<search-service-name>.search.windows.net");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var entraAuthentication = new EntraAppAuthentication(
    Guid.Parse("<application-client-id>"),
    Guid.Parse("<federated-credential-id>"));
var knowledgeSource = new WorkIQKnowledgeSource(
    "my-workiq-ks",
    new WorkIQKnowledgeSourceParameters(entraAuthentication))
{
    Description = "A sample Work IQ knowledge source."
};

KnowledgeSource createdSource =
    await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Created knowledge source '{createdSource.Name}'.");

Reference:SearchIndexClient, WorkIQKnowledgeSource

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    EntraAppAuthentication,
    WorkIQKnowledgeSource,
    WorkIQKnowledgeSourceParameters,
)

endpoint = "https://<search-service-name>.search.windows.net"
credential = DefaultAzureCredential()

knowledge_source = WorkIQKnowledgeSource(
    name="my-workiq-ks",
    description="A sample Work IQ knowledge source.",
    work_iq_parameters=WorkIQKnowledgeSourceParameters(
        entra_app_authentication=EntraAppAuthentication(
            application_id="<application-client-id>",
            federated_credential_id="<federated-credential-id>",
        )
    ),
)

with SearchIndexClient(endpoint, credential) as index_client:
    created_source = index_client.create_or_update_knowledge_source(
        knowledge_source
    )
print(f"Created knowledge source '{created_source.name}'.")

Reference:SearchIndexClient, WorkIQKnowledgeSource

@search-endpoint = <search-endpoint> // Example: https://my-service.search.windows.net
@search-access-token = <search-access-token> // Run: az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv

### Create a Work IQ knowledge source
PUT {{search-endpoint}}/knowledgesources/my-workiq-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation

{
  "name": "my-workiq-ks",
  "kind": "workIQ",
  "description": "A sample Work IQ knowledge source.",
  "workIQParameters": {
    "entraAppAuthentication": {
      "applicationId": "<application-client-id>",
      "federatedCredentialId": "<federated-credential-id>"
    }
  }
}

Referenz:Wissensquellen – Erstellen oder Aktualisieren

Zuweisen zu einer Wissensbasis

Wenn Sie mit der Wissensquelle zufrieden sind, fügen Sie sie einer Wissensbasis hinzu.

Abfragen einer Wissensbasis

Rufen Sie nach der Konfiguration der Knowledge Base die Abrufaktion oder den MCP-Endpunkt auf, um Work IQ-Inhalte abzufragen. Diese Wissensquelle verfügt über eindeutige Erzwingungs- und Antwortmerkmale für Abfragezeitberechtigungen.

Important

Work IQ kann 40 bis 60 Sekunden oder länger für eine Antwort benötigen. Stellen Sie bei der Abrufanforderung maxRuntimeInSeconds auf 120 oder höher ein, um Timeoutfehler zu vermeiden.

Erzwingen von Berechtigungen während der Abfrage

Ab Version 2026-08-01-preview der API verwenden Wissensquellen von Work IQ einen On-Behalf-Of-(OBO)-Tokenfluss über Ihre kundeneigene Microsoft Entra-App-Registrierung. Neben der Authentifizierung der Abrufanforderung an Foundry IQ muss Ihr Client eine App-Zielgruppenbenutzer-Assertion für den angemeldeten Benutzer bereitstellen.

Ihre Client-App muss den Benutzer anmelden und die Benutzerassertion abrufen. Wie Sie die Assertion erwerben, hängt von der Plattform und Sprache der App ab. Verwenden Sie Microsoft Authentication Library (MSAL) (MSAL) und den Autorisierungscodefluss mit Proof Key for Code Exchange (PKCE), um den genauen Bereich api://<application-client-id>/access_as_useranzufordern.

Bevor Sie die Benutzer-Assertion senden, vergewissern Sie sich, dass:

  • aud identifiziert Ihre Work IQ-App-Registrierung.
  • scp enthält access_as_user.
  • oid und tid identifizieren den angemeldeten Benutzer und den App-Mandanten.

Senden Sie beide Anmeldeinformationen in derselben Abrufanforderung, wie im folgenden Beispiel gezeigt. Verwenden Sie ein Foundry IQ-Token oder API-Schlüssel für die Dienstauthentifizierung. Übergeben Sie die rohe Benutzerassertion im Header x-ms-query-work-iq-source-authorization, nicht x-ms-query-source-authorization.

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

Uri searchEndpoint =
    new("https://<search-service-name>.search.windows.net");
string userAssertion = "<user-assertion>";
var credential = new DefaultAzureCredential();
var options = new SearchClientOptions();
options.Retry.NetworkTimeout = TimeSpan.FromSeconds(130);
var retrievalClient = new KnowledgeBaseRetrievalClient(
    searchEndpoint,
    "my-kb",
    credential,
    options);

var request = new KnowledgeBaseRetrievalRequest
{
    IncludeActivity = true,
    MaxRuntimeInSeconds = 120
};
request.Intents.Add(
    new KnowledgeRetrievalSemanticIntent("Find my project status."));
request.KnowledgeSourceParams.Add(
    new WorkIQKnowledgeSourceParams("my-workiq-ks")
    {
        IncludeReferences = true,
        IncludeReferenceSourceData = true
    });

var response = await retrievalClient.RetrieveAsync(
    request,
    querySourceAuthorization: null,
    queryWorkIQSourceAuthorization: userAssertion);
Console.WriteLine(response.Value);

Referenz:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalSemanticIntent,
    WorkIQKnowledgeSourceParams,
)

endpoint = "https://<search-service-name>.search.windows.net"
user_assertion = "<user-assertion>"
credential = DefaultAzureCredential()

request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search="Find my project status."
        )
    ],
    knowledge_source_params=[
        WorkIQKnowledgeSourceParams(
            knowledge_source_name="my-workiq-ks",
            include_references=True,
            include_reference_source_data=True,
        )
    ],
    include_activity=True,
    max_runtime_in_seconds=120,
)

with KnowledgeBaseRetrievalClient(
    endpoint,
    credential,
    knowledge_base_name="my-kb",
) as retrieval_client:
    response = retrieval_client.retrieve(
        request,
        query_work_iq_source_authorization=user_assertion,
        timeout=130,
    )

print(response)

Referenz:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

@search-endpoint = <search-endpoint>
@search-access-token = <search-access-token>
@user-assertion = <user-assertion>

### Query a knowledge base with a Work IQ knowledge source
POST {{search-endpoint}}/knowledgebases/my-kb/retrieve?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
x-ms-query-work-iq-source-authorization: {{user-assertion}}
Content-Type: application/json

{
  "messages": [{
    "role": "user",
    "content": [{
      "type": "text",
      "text": "Find my project status."
    }]
  }],
  "knowledgeSourceParams": [{
    "knowledgeSourceName": "my-workiq-ks",
    "kind": "workIQ",
    "includeReferences": true,
    "includeReferenceSourceData": true
  }],
  "includeActivity": true,
  "maxRuntimeInSeconds": 120
}

Reference:Knowledge Retrieval - Abrufen

Eine erfolgreiche Anforderung gibt zurück 200 OK. Vergewissern Sie sich, dass activity einen Eintrag enthält, dessen typeknowledgeSourceName ist und dessen workIQ mit Ihrer Work-IQ-Wissensquelle übereinstimmt. Vergewissern Sie sich außerdem, dass references einen workIQ-Eintrag enthält.

In der folgenden Tabelle sind häufige Konfigurationsfehler aufgeführt.

Status Ursache
400 Der Arbeits-IQ-Autorisierungsheader fehlt oder ist falsch formatiert, erforderliche Benutzeransprüche fehlen, oder der Foundry IQ-Dienst verfügt nicht über eine unterstützte Verwaltete Identitätskonfiguration.
206 oder 502 Die Work IQ-Quelle ist fehlgeschlagen, weil der Tokenaustausch, die Einwilligung, die delegierte Berechtigung, die Verbundanmeldeinformation, die nachgelagerte Autorisierung oder die Work IQ-Anforderung fehlgeschlagen ist oder zu einer Zeitüberschreitung geführt hat. Überprüfen Sie den Fehler der Quellaktivität. Eine 206 Antwort bedeutet, dass eine andere Quelle erfolgreich war. Eine 502 Antwort bedeutet, dass jede ausgewählte Quelle fehlgeschlagen ist oder eine erforderliche Quelle fehlgeschlagen ist.

Arbeits-IQ-spezifische Antwortfelder

Work IQ-Wissensquellen geben Ergebnisse im Array references und Abfragediagnosen im Array activity zurück. Jeder Verweiseintrag enthält:

  • sourceData.parts[].text: Belegte Textpassagen von Work IQ.
  • sourceData.parts[].data: Work IQ Zitatdaten. Zitatteile weisen den Medientyp application/vnd.ms-workiq-referenceauf.

Das folgende Beispiel zeigt eine Antwort auf einen Abruf, die einen Verweis auf eine Work IQ-Wissensquelle und den zugehörigen Aktivitätsdatensatz enthält. Weiterführende Hinweise zum Interpretieren von Retrieve-Antworten finden Sie unter Antwort überprüfen.

Tip

Um sourceData für Verweise zu erhalten, legen Sie includeReferenceSourceData beim Wissensquelleneintrag in true der Abrufanforderung auf knowledgeSourceParams fest.

{
  "response": [],
  "activity": [
    {
      "type": "workIQ",
      "id": 0,
      "knowledgeSourceName": "my-workiq-ks",
      "queryTime": "2026-08-01T19:25:23.683Z",
      "count": 1,
      "elapsedMs": 1137,
      "workIQArguments": {
        "search": "my query"
      }
    }
  ],
  "references": [
    {
      "type": "workIQ",
      "id": "83dd7d40",
      "activitySource": 0,
      "rerankerScore": 3.5,
      "sourceData": {
        "parts": [
          {
            "text": "Have your VPN username and password ready."
          },
          {
            "data": {
              "1-abc123": {
                "targetLink": "https://contoso.sharepoint.com/doc.docx",
                "isCitedInResponse": true,
                "isSourceFiltered": false
              }
            },
            "mediaType": "application/vnd.ms-workiq-reference"
          }
        ]
      }
    }
  ]
}

Löschen einer Wissensquelle

Bevor Sie eine Wissensquelle löschen können, müssen Sie alle Knowledge Basen löschen, die darauf verweisen, oder die Knowledge Base-Definition aktualisieren, um den Verweis zu entfernen. Für Wissensquellen, die eine Index- und Indexerpipeline generieren, werden auch alle generierten Objekte gelöscht. Wenn Sie jedoch einen vorhandenen Index zum Erstellen einer Wissensquelle verwendet haben, wird Ihr Index nicht gelöscht.

Wenn Sie versuchen, eine verwendete Wissensquelle zu löschen, schlägt die Aktion fehl und gibt eine Liste der betroffenen Wissensdatenbanken zurück.

So löschen Sie eine Wissensquelle:

  1. Erhalten Sie eine Liste aller Wissensdatenbanken in Ihrem Foundry IQ-Dienst.

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

    Reference:SearchIndexClient

    Eine Beispielantwort könnte wie folgt aussehen:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

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

    Reference:SearchIndexClient

    Eine Beispielantwort könnte wie folgt aussehen:

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.

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

    Reference:SearchIndexClient

  4. Löschen Sie die Wissensquelle.

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

    Reference:SearchIndexClient

  1. Erhalten Sie eine Liste aller Wissensbasen auf Ihrem Foundry IQ Service.

    # Get knowledge bases
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    
    print("Knowledge Bases:")
    for kb in index_client.list_knowledge_bases():
        print(f"  - {kb.name}")
    

    Reference:SearchIndexClient

    Eine Beispielantwort könnte wie folgt aussehen:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

    # Get a knowledge base definition
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    kb = index_client.get_knowledge_base("knowledge_base_name")
    print(kb)
    

    Reference:SearchIndexClient

    Eine Beispielantwort könnte wie folgt aussehen:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.

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

    Reference:SearchIndexClient

  4. Löschen Sie die Wissensquelle.

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

    Reference:SearchIndexClient

  1. Erhalten Sie eine Liste aller Wissensbasen auf Ihrem Foundry IQ Service.

    ### Get knowledge bases
    GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
    Authorization: Bearer {{token}}
    

    Referenz:Wissensdatenbanken - Liste

    Eine Beispielantwort könnte wie folgt aussehen:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

    ### Get a knowledge base definition
    GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Referenz:Wissensdatenbanken – Abrufen

    Eine Beispielantwort könnte wie folgt aussehen:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.

    ### Delete a knowledge base
    DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Referenz:Knowledge Bases - Löschen

  4. Löschen Sie die Wissensquelle.

    ### Delete a knowledge source
    DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Referenz:Wissensquellen - Löschen