Créer une base de connaissances dans Recherche IA Azure

Dans Recherche IA Azure, une base de connaissances est un objet de niveau supérieur qui orchestre la récupération agentique. Il définit les sources de connaissances à interroger et le comportement par défaut pour les opérations de récupération. Au moment de la requête, la méthode de récupération cible la base de connaissances pour exécuter le pipeline de récupération configuré.

Vous pouvez créer une base de connaissances dans une charge de travail Foundry IQ dans le portail Microsoft Foundry (nouveau). Vous avez également besoin d’une base de connaissances dans toutes les solutions agentiques que vous créez à l’aide des API Recherche d’IA Azure.

Une base de connaissances spécifie :

• Une ou plusieurs sources de connaissances qui pointent vers du contenu pouvant faire l’objet d’une recherche.
• Un LLM facultatif qui fournit des fonctionnalités de raisonnement pour la planification des requêtes et la formulation de réponses.
• Un effort de raisonnement de récupération qui détermine si un LLM est appelé et gère les coûts, la latence et la qualité.
• Propriétés personnalisées qui contrôlent le routage, la sélection source, le format de sortie et le chiffrement d’objet.

Après avoir créé une base de connaissances, vous pouvez mettre à jour ses propriétés à tout moment. Si la base de connaissances est en cours d’utilisation, les mises à jour prennent effet sur la récupération suivante.

Prerequisites

• Recherche Azure AI dans n’importe quelle région qui propose une récupération par agents. Vous devez activer le ranker sémantique. Si vous utilisez une identité managée pour l’accès en fonction du rôle aux modèles déployés, votre service de recherche doit se trouver sur le niveau tarifaire De base ou supérieur.

• Azure OpenAI avec un déploiement de LLM pris en charge.

• Une ou plusieurs sources de connaissances sur votre service de recherche.

• Autorisation de créer et d’utiliser des objets sur Recherche IA Azure. Nous vous recommandons d’accéder en fonction du rôle. Le contributeur de service de recherche peut créer et gérer une base de connaissances. Le lecteur de données d’index de recherche peut exécuter des requêtes. Vous pouvez également utiliser des clés API si une attribution de rôle n’est pas réalisable. Pour plus d’informations, consultez Se connecter à un service de recherche.

• Dernière version préliminaire de la azure-search-documents bibliothèque cliente pour Python.

Modèles pris en charge

Utilisez l'un des modèles de langage LLM suivants depuis Azure OpenAI ou un modèle open source équivalent. Pour obtenir des instructions de déploiement, consultez Déployer des modèles Azure OpenAI avec Microsoft Foundry.

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

Configurer l’accès

Azure AI Search a besoin d’accéder au LLM à partir d’Azure OpenAI. Nous recommandons Microsoft Entra ID pour l’authentification et l’accès en fonction du rôle pour l’autorisation. Pour attribuer des rôles, vous devez être propriétaire ou administrateur de l’accès utilisateur. Si vous ne pouvez pas utiliser de rôles, utilisez plutôt l’authentification basée sur des clés.

Rechercher les bases de connaissances existantes

Connaître les bases de connaissances existantes est utile pour les réutiliser ou nommer de nouveaux objets. Tous les agents de connaissances de la préversion 2025-08-01 sont retournés dans la collection de bases de connaissances.

Exécutez le code suivant pour répertorier les bases de connaissances existantes par nom.

// List knowledge bases by name
  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}");
  }

Vous pouvez également retourner une base 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 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);

Le code JSON suivant est un exemple de base de connaissances.

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

Créer une base de connaissances

Une base de connaissances pilote le pipeline de récupération agentique. Dans le code de l’application, d'autres agents ou chatbots l'appellent.

Une base de connaissances connecte des sources de connaissances (contenu pouvant faire l’objet d’une recherche) à un déploiement LLM à partir d’Azure OpenAI. Les propriétés sur le LLM établissent la connexion, tandis que les propriétés de la source de connaissances établissent des valeurs par défaut qui informent l’exécution de la requête et la réponse.

Exécutez le code suivant pour créer une base de connaissances.

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

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

// Create a knowledge base
var knowledgeBase = new KnowledgeBase(
    name: knowledgeBaseName,
    knowledgeSources: new KnowledgeSourceReference[] { new KnowledgeSourceReference(knowledgeSourceName) }
)
{
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { model }
};
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBaseName}' created or updated successfully.");

# Create a knowledge base
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), new AzureKeyCredential(apiKey));

var aoaiParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var knowledgeBase = new KnowledgeBase(
    name: "my-kb",
    knowledgeSources: new KnowledgeSourceReference[] 
    { 
        new KnowledgeSourceReference("hotels-sample-knowledge-source"),
        new KnowledgeSourceReference("earth-knowledge-source")
    }
)
{
    Description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    RetrievalInstructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    AnswerInstructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: aoaiParams) },
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort()
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBase.Name}' created or updated successfully.");

Propriétés de la base de connaissances

Transmettez les propriétés suivantes pour créer une base de connaissances.

Interroger une base de connaissances

Configurez les instructions et les messages à envoyer au LLM.

string instructions = @"
Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.
";

var messages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "system" },
        { "content", instructions }
    }
};

Appelez l’action retrieve sur la base de connaissances pour vérifier la connexion LLM et retourner les résultats. Pour plus d’informations sur le retrieve schéma de requête et de réponse, consultez Récupérer des données à l’aide d’une base de connaissances dans Recherche IA Azure.

Remplacez « Où l’océan est-il vert ? » par une chaîne de requête valide pour vos sources de connaissances.

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

var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    tokenCredential: new DefaultAzureCredential()
);

messages.Add(new Dictionary<string, string>
{
    { "role", "user" },
    { "content", @"Where does the ocean look green?" }
});

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in messages) {
    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);

messages.Add(new Dictionary<string, string>
{
    { "role", "assistant" },
    { "content", (retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text }
});

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

// Print the response, activity, and references
Console.WriteLine("Response:");
Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text);

Points clés :

• KnowledgeBaseRetrievalRequest est le contrat d’entrée pour la demande de récupération.

• RetrievalReasoningEffort est obligatoire. Définir cette propriété sur minimal exclut les LLM du pipeline de requête et seules les intentions sont utilisées pour l’entrée de requête. La valeur par défaut est low et prend en charge la planification des requêtes basée sur LLM et la synthèse des réponses avec les messages et le contexte.

• knowledgeSourceParams sont utilisés pour remplacer les paramètres par défaut au moment de la requête.

La réponse à l’exemple de requête peut ressembler à l’exemple suivant :

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Supprimer une base de connaissances

Si vous n’avez plus besoin de la base de connaissances ou que vous devez la reconstruire sur votre service de recherche, utilisez cette demande pour supprimer l’objet.

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

Dans Recherche IA Azure, une base de connaissances est un objet de niveau supérieur qui orchestre la récupération agentique. Il définit les sources de connaissances à interroger et le comportement par défaut pour les opérations de récupération. Au moment de la requête, la méthode de récupération cible la base de connaissances pour exécuter le pipeline de récupération configuré.

Vous pouvez créer une base de connaissances dans une charge de travail Foundry IQ dans le portail Microsoft Foundry (nouveau). Vous avez également besoin d’une base de connaissances dans toutes les solutions agentiques que vous créez à l’aide des API Recherche d’IA Azure.

Une base de connaissances spécifie :

• Une ou plusieurs sources de connaissances qui pointent vers du contenu pouvant faire l’objet d’une recherche.
• Un LLM facultatif qui fournit des fonctionnalités de raisonnement pour la planification des requêtes et la formulation de réponses.
• Un effort de raisonnement de récupération qui détermine si un LLM est appelé et gère les coûts, la latence et la qualité.
• Propriétés personnalisées qui contrôlent le routage, la sélection source, le format de sortie et le chiffrement d’objet.

Après avoir créé une base de connaissances, vous pouvez mettre à jour ses propriétés à tout moment. Si la base de connaissances est en cours d’utilisation, les mises à jour prennent effet sur la récupération suivante.

Prerequisites

• Recherche Azure AI dans n’importe quelle région qui propose une récupération par agents. Vous devez activer le ranker sémantique. Si vous utilisez une identité managée pour l’accès en fonction du rôle aux modèles déployés, votre service de recherche doit se trouver sur le niveau tarifaire De base ou supérieur.

• Azure OpenAI avec un déploiement de LLM pris en charge.

• Une ou plusieurs sources de connaissances sur votre service de recherche.

• Autorisation de créer et d’utiliser des objets sur Recherche IA Azure. Nous vous recommandons d’accéder en fonction du rôle. Le contributeur de service de recherche peut créer et gérer une base de connaissances. Le lecteur de données d’index de recherche peut exécuter des requêtes. Vous pouvez également utiliser des clés API si une attribution de rôle n’est pas réalisable. Pour plus d’informations, consultez Se connecter à un service de recherche.

• Dernière version préliminaire de la azure-search-documents bibliothèque cliente pour Python.

Modèles pris en charge

Utilisez l'un des modèles de langage LLM suivants depuis Azure OpenAI ou un modèle open source équivalent. Pour obtenir des instructions de déploiement, consultez Déployer des modèles Azure OpenAI avec Microsoft Foundry.

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

Configurer l’accès

Azure AI Search a besoin d’accéder au LLM à partir d’Azure OpenAI. Nous recommandons Microsoft Entra ID pour l’authentification et l’accès en fonction du rôle pour l’autorisation. Vous devez être propriétaire ou administrateur de l’accès utilisateur pour attribuer des rôles. Si les rôles ne sont pas réalisables, utilisez plutôt l’authentification basée sur des clés.

Rechercher les bases de connaissances existantes

Connaître les bases de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets. Tous les agents de connaissances de la préversion 2025-08-01 sont retournés dans la collection de bases de connaissances.

Exécutez le code suivant pour répertorier les bases de connaissances existantes par nom.

# List knowledge bases by name
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))

Vous pouvez également retourner une base de connaissances unique par nom pour passer en revue sa définition JSON.

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

Le code JSON suivant est un exemple de réponse pour une base de connaissances.

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

Créer une base de connaissances

Une base de connaissances pilote le pipeline de récupération agentique. Dans le code de l’application, d'autres agents ou chatbots l'appellent.

Une base de connaissances connecte des sources de connaissances (contenu pouvant faire l’objet d’une recherche) à un déploiement LLM à partir d’Azure OpenAI. Les propriétés sur le LLM établissent la connexion, tandis que les propriétés de la source de connaissances établissent des valeurs par défaut qui informent l’exécution de la requête et la réponse.

Exécutez le code suivant pour créer une base de connaissances.

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeBaseAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalLowReasoningEffort

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

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url = "aoai_endpoint",
    api_key="aoai_api_key",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    output_mode = KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort,
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

Propriétés de la base de connaissances

Transmettez les propriétés suivantes pour créer une base de connaissances.

Interroger une base de connaissances

Appelez l’action retrieve sur la base de connaissances pour vérifier la connexion LLM et retourner les résultats. Pour plus d’informations sur le retrieve schéma de requête et de réponse, consultez Récupérer des données à l’aide d’une base de connaissances dans Recherche IA Azure.

Remplacez « Où l’océan est-il vert ? » par une chaîne de requête valide pour vos sources de connaissances.

# Send grounding request
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, SearchIndexKnowledgeSourceParams

kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role = "assistant",
            content = [KnowledgeBaseMessageTextContent(text = "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.")]
        ),
        KnowledgeBaseMessage(
            role = "user",
            content = [KnowledgeBaseMessageTextContent(text = "Where does the ocean look green?")]
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name = "earth-at-night-ks",
            include_references = True,
            include_reference_source_data = True,
            always_query_source = False,
        )
    ],
    include_activity = True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Points clés :

• messages est obligatoire, mais vous pouvez exécuter cet exemple en utilisant uniquement le user rôle qui fournit la requête.

• knowledge_source_params spécifie une ou plusieurs cibles de requête. Pour chaque source de connaissances, vous pouvez spécifier la quantité d’informations à inclure dans la sortie.

La réponse à l’exemple de requête peut ressembler à l’exemple suivant :

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Supprimer une base de connaissances

Si vous n’avez plus besoin de la base de connaissances ou que vous devez la reconstruire sur votre service de recherche, utilisez cette demande pour supprimer l’objet.

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

Dans Recherche IA Azure, une base de connaissances est un objet de niveau supérieur qui orchestre la récupération agentique. Il définit les sources de connaissances à interroger et le comportement par défaut pour les opérations de récupération. Au moment de la requête, la méthode de récupération cible la base de connaissances pour exécuter le pipeline de récupération configuré.

Vous pouvez créer une base de connaissances dans une charge de travail Foundry IQ dans le portail Microsoft Foundry (nouveau). Vous avez également besoin d’une base de connaissances dans toutes les solutions agentiques que vous créez à l’aide des API Recherche d’IA Azure.

Une base de connaissances spécifie :

• Une ou plusieurs sources de connaissances qui pointent vers du contenu pouvant faire l’objet d’une recherche.
• Un LLM facultatif qui fournit des fonctionnalités de raisonnement pour la planification des requêtes et la formulation de réponses.
• Un effort de raisonnement de récupération qui détermine si un LLM est appelé et gère les coûts, la latence et la qualité.
• Propriétés personnalisées qui contrôlent le routage, la sélection source, le format de sortie et le chiffrement d’objet.

Après avoir créé une base de connaissances, vous pouvez mettre à jour ses propriétés à tout moment. Si la base de connaissances est en cours d’utilisation, les mises à jour prennent effet sur la récupération suivante.

Prerequisites

• Recherche Azure AI dans n’importe quelle région qui propose une récupération par agents. Vous devez activer le ranker sémantique. Si vous utilisez une identité managée pour l’accès en fonction du rôle aux modèles déployés, votre service de recherche doit se trouver sur le niveau tarifaire De base ou supérieur.

• Azure OpenAI avec un déploiement de LLM pris en charge.

• Une ou plusieurs sources de connaissances sur votre service de recherche.

• Autorisation de créer et d’utiliser des objets sur Recherche IA Azure. Nous vous recommandons d’accéder en fonction du rôle. Le contributeur de service de recherche peut créer et gérer une base de connaissances. Le lecteur de données d’index de recherche peut exécuter des requêtes. Vous pouvez également utiliser des clés API si une attribution de rôle n’est pas réalisable. Pour plus d’informations, consultez Se connecter à un service de recherche.

• Dernière version préliminaire de la Azure.Search.Documents bibliothèque cliente pour le Kit de développement logiciel (SDK) .NET.

Modèles pris en charge

Utilisez l'un des modèles de langage LLM suivants depuis Azure OpenAI ou un modèle open source équivalent. Pour obtenir des instructions de déploiement, consultez Déployer des modèles Azure OpenAI avec Microsoft Foundry.

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

Configurer l’accès

Azure AI Search a besoin d’accéder au LLM à partir d’Azure OpenAI. Nous recommandons Microsoft Entra ID pour l’authentification et l’accès en fonction du rôle pour l’autorisation. Pour attribuer des rôles, vous devez être propriétaire ou administrateur de l’accès utilisateur. Si vous ne pouvez pas utiliser de rôles, utilisez plutôt l’authentification basée sur des clés.

Rechercher les bases de connaissances existantes

Une base de connaissances est un objet réutilisable de niveau supérieur. Connaître les bases de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets. Tous les agents de connaissances de la préversion 2025-08-01 sont retournés dans la collection de bases de connaissances.

Utilisez les bases de connaissances - Liste (API REST) pour répertorier les bases de connaissances par nom et par type.

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version=2025-11-01-preview&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

Vous pouvez également retourner une base de connaissances unique par nom pour passer en revue sa définition JSON.

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

Le code JSON suivant est un exemple de réponse pour une base de connaissances.

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

Créer une base de connaissances

Une base de connaissances pilote le pipeline de récupération agentique. Dans le code de l’application, d'autres agents ou chatbots l'appellent.

Une base de connaissances connecte des sources de connaissances (contenu pouvant faire l’objet d’une recherche) à un déploiement LLM à partir d’Azure OpenAI. Les propriétés sur le LLM établissent la connexion, tandis que les propriétés du jeu de sources de connaissances définissent les valeurs par défaut qui guident l’exécution de la requête et la réponse.

Utilisez les bases de connaissances - Créer ou mettre à jour (API REST) pour formuler la demande.

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4.1-mini",
                "modelName": "gpt-4.1-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

Propriétés de la base de connaissances

Transmettez les propriétés suivantes pour créer une base de connaissances.

Interroger une base de connaissances

Appelez l’action retrieve sur la base de connaissances pour vérifier la connexion LLM et retourner les résultats. Pour plus d’informations sur le retrieve schéma de requête et de réponse, consultez Récupérer des données à l’aide d’une base de connaissances dans Recherche IA Azure.

Utilisez Récupération des connaissances - Retrieve (API REST) pour formuler la requête. Remplacez « Où l’océan est-il vert ? » par une chaîne de requête valide pour vos sources de connaissances.

# Send grounding request
POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "messages" : [
        { "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
                ]
        },
        {
            "role" : "user",
            "content" : [
                {
                    "text" : "Where does the ocean look green?",
                    "type" : "text"
                }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "alwaysQuerySource": false
        }
  ]
}

Points clés :

• messages est obligatoire, mais vous pouvez exécuter cet exemple en utilisant uniquement le user rôle qui fournit la requête.

• knowledgeSourceParams spécifie une ou plusieurs cibles de requête. Pour chaque source de connaissances, vous pouvez spécifier la quantité d’informations à inclure dans la sortie.

La réponse à l’exemple de requête peut ressembler à l’exemple suivant :

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Supprimer une base de connaissances

Si vous n’avez plus besoin de la base de connaissances ou que vous devez la reconstruire sur votre service de recherche, utilisez cette demande pour supprimer l’objet.

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