Créer une source de connaissances Fabric Ontology (préversion)

Note

Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.

Important

Les fonctionnalités, capacités ou propriétés marquées (préversion) ne sont pas couvertes par un accord de niveau de service, ne sont pas recommandées pour les workloads de production et peuvent être modifiées ou faire l’objet de restrictions avant leur mise à disposition générale. Les Recherche Azure AI termes de la préversion s'appliquent à toutes les fonctionnalités d'aperçu, qu'il s'agisse d'une fonctionnalité autonome ou d'une partie d'une fonctionnalité généralement disponible.

Lorsque vous vous connectez à Fabric IQ, vous risquez d’entraîner des coûts, et les données peuvent être envoyées en dehors de la limite de conformité Azure et traitées en fonction des conditions de service et des stratégies de gestion des données applicables.

Une source de connaissances Fabric Ontology (version préliminaire) relie votre ontologie Microsoft Fabric à un pipeline de récupération piloté par agent dans Recherche Azure AI. Les sources de connaissances sont créées indépendamment, référencées dans une base de connaissances et utilisées comme données de base lorsque la base de connaissances est interrogée lors de l’exécution.

Les ontologies capturent la façon dont votre entreprise définit ses données, ses entités et ses relations, ce qui permet aux agents de répondre en termes métier plutôt que de raisonnement sur les tables et colonnes brutes.

Contrairement aux sources de connaissances indexées, les sources de connaissances Fabric Ontology interrogent directement des données en direct lors de la récupération. Aucun pipeline d’ingestion n’est nécessaire. Les requêtes nécessitent un jeton d'accès de l'utilisateur final, que le moteur de récupération utilise pour s'authentifier avec Microsoft Fabric au nom de l'appelant.

Assistance à l'utilisation

portail Azure	portail Microsoft Foundry	Kit de développement logiciel (SDK) .NET	Kit de développement logiciel (SDK) Python	SDK Java	SDK JavaScript	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

Un service Recherche Azure AI dans n’importe quelle région qui fournit une recherche agentique.
Un espace de travail Microsoft Fabric avec les paramètres de locataire requis pour l’ontologie et un élément d’ontologie.
Votre service de recherche et votre espace de travail doivent se trouver dans le même locataire Microsoft Entra ID.
Autorisation de créer des sources de connaissances. Configurez l’authentification sans clé avec le rôle Contributeur de service de recherche affecté à votre compte d’utilisateur (recommandé) ou utilisez une clé API d’administration.

Le dernier paquet Azure.Search.Documents (préversion) : dotnet add package Azure.Search.Documents --prerelease
Pour l’authentification sans clé, le Azure.Identity package : dotnet add package Azure.Identity

Le dernier paquet azure-search-documents (préversion) : pip install --pre azure-search-documents
Pour l’authentification sans clé, le azure-identity package : pip install azure-identity

La version 2026-08-01-preview de l’API REST du service de recherche.
Pour l’authentification sans clé, incluez un jeton de Microsoft Entra ID dans l’en-tête Authorization de chaque requête HTTP.

Gouvernance et conformité des données

Fabric IQ traite les demandes dans la limite de conformité Microsoft Fabric pour la région de votre espace de travail. Les engagements suivants s’appliquent lorsque vous routez des requêtes d’agent via Fabric IQ.

Résidence des données

Fabric IQ récupère et traite les données dans la région où réside votre espace de travail Microsoft Fabric. Les données ne dépassent pas les limites régionales pendant l’exécution de la requête. La région applicable et son étendue de conformité sont déterminées par votre emplacement d’espace de travail. Pour obtenir la liste des régions prises en charge et des cadres de conformité auxquels chaque région est conforme, consultez Disponibilité des régions Microsoft Fabric.

Note

Si votre service Recherche Azure AI se trouve dans une autre région Azure que votre espace de travail Fabric, les résultats des requêtes sont retournés entre régions. Consultez la disponibilité régionale de Microsoft Fabric ainsi que les exigences de résidence des données de votre organisation avant de connecter un espace de travail Fabric situé dans une autre région.

Certifications de conformité

Fabric IQ hérite des certifications de conformité de Microsoft Fabric pour la région de l'espace de travail. Pour obtenir la documentation de conformité, les rapports d’audit et les frameworks applicables à chaque région, consultez Microsoft Fabric disponibilité de la région.

Rechercher les sources de connaissances existantes

Une source de connaissances est un objet réutilisable de niveau supérieur. Connaître les sources de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets.

Exécutez le code suivant pour répertorier les sources de connaissances par nom et par type.

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

Référence :Sources de connaissances - Liste

Vous pouvez également retourner une source de connaissances unique par nom pour passer en revue sa définition 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));

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

Référence :Sources de connaissances - Obtenir

Le code JSON suivant est un exemple de réponse pour une source de connaissances Fabric Ontology.

{
  "name": "my-fabric-ontology-ks",
  "kind": "fabricOntology",
  "description": "A Fabric Ontology knowledge source.",
  "encryptionKey": null,
  "fabricOntologyParameters": {
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "ontologyId": "00000000-0000-0000-0000-000000000001"
  }
}

Créer une source de connaissances

Exécutez le code suivant pour créer une source de connaissances Fabric Ontology.

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

Uri searchEndpoint = new Uri("<search-endpoint>");
DefaultAzureCredential credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var fabricOntology = new FabricOntologyKnowledgeSource(
    "<knowledge-source-name>",
    new FabricOntologyKnowledgeSourceParameters("<fabric-workspace-id>", "<fabric-ontology-id>"))
{
    Description = "A Fabric Ontology knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(fabricOntology);

Reference :SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    FabricOntologyKnowledgeSource,
    FabricOntologyKnowledgeSourceParameters,
)

index_client = SearchIndexClient(
    endpoint="<search-endpoint>",
    credential=DefaultAzureCredential()
)

knowledge_source = FabricOntologyKnowledgeSource(
    name="<knowledge-source-name>",
    description="A Fabric Ontology knowledge source.",
    fabric_ontology_parameters=FabricOntologyKnowledgeSourceParameters(
        workspace_id="<fabric-workspace-id>",
        ontology_id="<fabric-ontology-id>"
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)

Reference :SearchIndexClient

### Create a Fabric Ontology knowledge source
PUT {{search-endpoint}}/knowledgesources/my-fabric-ontology-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "my-fabric-ontology-ks",
  "kind": "fabricOntology",
  "description": "A Fabric Ontology knowledge source.",
  "fabricOntologyParameters": {
    "workspaceId": "{fabric-workspace-id}",
    "ontologyId": "{fabric-ontology-id}"
  }
}

Référence :Sources de connaissances - Créer ou mettre à jour

Attribuer à une base de connaissances

Si vous êtes satisfait de la source de connaissances, ajoutez-la à une base de connaissances.

Note

Les sources de connaissances de Fabric Ontology ne prennent pas en charge l'effort de raisonnement minimalde recherche. Utilisez plutôt low ou medium.

Interroger une base de connaissances

Une fois la base de connaissances configurée, appelez l’action Retrieve ou le point de terminaison MCP pour interroger le contenu de Fabric Ontology. Cette source de connaissances présente une application des autorisations lors de l’exécution de la requête et des caractéristiques de réponse uniques.

Appliquer des autorisations au moment de la requête

Les sources de connaissances Fabric Ontology utilisent un flux de jeton OBO (on-behalf-of). Vous transmettez le jeton d’accès de l’utilisateur final dans l’en-tête x-ms-query-source-authorization de la requête de récupération. Le jeton doit être limité à l’audience Recherche Azure AI (https://search.azure.com/.default). Le moteur de récupération échange ce jeton contre un jeton limité à Microsoft Fabric et l’utilise afin d’interroger l’élément d’ontologie pour le compte de l’utilisateur final.

L’authentification Recherche Azure AI standard est également requise sur la demande de récupération. Le x-ms-query-source-authorization jeton est passé séparément et ne remplace pas l’authentification du service.

Pour obtenir des instructions sur la transmission du jeton, consultez Appliquer les autorisations lors de la requête (préversion).

Champs de réponse spécifiques à Fabric Ontology

Les sources de connaissances Fabric Ontology renvoient des résultats dans l’objet sourceData de chaque entrée references et les diagnostics de requête dans le tableau activity. sourceData Contient:

fabricAnswer: réponse en langage naturel de l’ontologie.
fabricRawData: Les données structurées ayant servi de base à la réponse, renvoyées au format CSV.

L’exemple suivant montre une réponse d’extraction contenant une référence à une source de connaissances de Fabric Ontology et l’enregistrement d’activité correspondant. Pour obtenir des conseils plus larges sur l’interprétation des réponses de récupération, consultez Examiner la réponse.

Conseil / Astuce

Pour recevoir sourceData pour les références, définissez includeReferenceSourceData sur true dans l’entrée de source de connaissances de knowledgeSourceParams de la requête de récupération.

{
  "response": [
      // ... Response omitted for brevity
  ],
  "activity": [
    {
      "type": "fabricOntology",
      "id": 1,
      "knowledgeSourceName": "my-fabric-ontology-ks",
      "queryTime": "2026-05-11T20:29:24Z",
      "count": 1,
      "fabricOntologyArguments": {
        "search": "Which airlines operate domestic routes?"
      }
    },
    {
      // ... Additional activity records omitted for brevity
    }
  ],
  "references": [
    {
      "type": "fabricOntology",
      "id": "0",
      "activitySource": 1,
      "sourceData": {
        "fabricAnswer": "There are 3 airlines with domestic routes: Delta, United, and American.",
        "fabricRawData": "Airline,Routes\nDelta,47\nUnited,38\nAmerican,29"
      },
      "rerankerScore": 0,
      "workspaceId": "00000000-0000-0000-0000-000000000000",
      "ontologyId": "00000000-0000-0000-0000-000000000001"
    },
    {
      // ... Additional references omitted for brevity
    }
  ]
}

Supprimer une source de connaissances

Avant de pouvoir supprimer une source de connaissances, vous devez supprimer toute base de connaissances qui la référence ou mettre à jour la définition de la base de connaissances pour supprimer la référence. Pour les sources de connaissances qui génèrent un pipeline d’index et d’indexeur, tous les objets générés sont également supprimés . Toutefois, si vous avez utilisé un index existant pour créer une source de connaissances, votre index n’est pas supprimé.

Si vous essayez de supprimer une source de connaissances en cours d’utilisation, l’action échoue et retourne une liste de bases de connaissances affectées.

Pour supprimer une source de connaissances :

Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

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

Un exemple de réponse peut ressembler à ce qui suit :

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

Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

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

Un exemple de réponse peut ressembler à ce qui suit :

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

Supprimez la base de connaissances ou, si vous avez plusieurs sources de connaissances, mettez à jour la base de connaissances pour supprimer la source. Cet exemple montre la suppression.

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

Supprimez la source de connaissances.

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

Reference :SearchIndexClient

Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

# 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

Un exemple de réponse peut ressembler à ce qui suit :

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

Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

# 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

Un exemple de réponse peut ressembler à ce qui suit :

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

Supprimez la base de connaissances ou, si vous avez plusieurs sources de connaissances, mettez à jour la base de connaissances pour supprimer la source. Cet exemple montre la suppression.

# 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

Supprimez la source de connaissances.

# 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

Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

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

Référence :Bases de connaissances - Liste

Un exemple de réponse peut ressembler à ce qui suit :

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

Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

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

Référence :Bases de connaissances - Obtenir

Un exemple de réponse peut ressembler à ce qui suit :

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

Supprimez la base de connaissances ou, si vous avez plusieurs sources de connaissances, mettez à jour la base de connaissances pour supprimer la source. Cet exemple montre la suppression.
```
### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}
```
Référence :Bases de connaissances - Supprimer

Supprimez la source de connaissances.

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

Référence :Sources de connaissances - Supprimer

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-09-17

Créer une source de connaissances Fabric Ontology (préversion)

Assistance à l'utilisation

Prerequisites

Gouvernance et conformité des données

Résidence des données

Certifications de conformité

Rechercher les sources de connaissances existantes

Créer une source de connaissances

Attribuer à une base de connaissances

Interroger une base de connaissances

Appliquer des autorisations au moment de la requête

Champs de réponse spécifiques à Fabric Ontology

Supprimer une source de connaissances

Contenu connexe

Commentaires

Ressources supplémentaires