Condividi tramite

Creare una fonte di conoscenza di OneLake

Annotazioni

Questa funzionalità è attualmente disponibile in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Usare una fonte di conoscenza di OneLake per indicizzare ed eseguire query sui file di Microsoft OneLake in una pipeline di recupero con agente. Le origini delle informazioni vengono create in modo indipendente, a cui viene fatto riferimento in una knowledge base e usate come dati di base quando un agente o un chatbot chiama un'azione di recupero in fase di query.

Quando si crea un'origine conoscenza OneLake, si specifica un'origine dati esterna, modelli e proprietà per generare automaticamente gli oggetti di Ricerca di intelligenza artificiale di Azure seguenti:

  • L'origine dati che rappresenta un lakehouse.
  • Insieme di strumenti che suddivide e, facoltativamente, vettorizza il contenuto multimodale dal lakehouse.
  • Indice che archivia il contenuto arricchito e soddisfa i criteri per il recupero agentico.
  • Indicizzatore che usa gli oggetti precedenti per guidare la pipeline di indicizzazione e arricchimento.

L'indicizzatore generato è conforme all'indicizzatore OneLake, i cui prerequisiti, le attività supportate, i formati di documento supportati, i collegamenti supportati e le limitazioni si applicano anche alle origini conoscenze di OneLake. Per altre informazioni, vedere la documentazione dell'indicizzatore OneLake.

Prerequisiti

Verificare le fonti di informazioni esistenti

Una fonte di informazioni è un oggetto riutilizzabile di livello superiore. Conoscere le origini conoscenze esistenti è utile per riutilizzare o denominare nuovi oggetti.

Eseguire il codice seguente per elencare le origini delle informazioni in base al nome e al tipo.

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

È anche possibile restituire una singola fonte di informazioni in base al nome per esaminarne la definizione 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));

Il seguente JSON è un esempio di risposta per una fonte di conoscenza OneLake.

{
  "name": "my-onelake-ks",
  "kind": "indexedOneLake",
  "description": "A sample indexed OneLake knowledge source.",
  "encryptionKey": null,
  "indexedOneLakeParameters": {
    "fabricWorkspaceId": "<REDACTED>",
    "lakehouseId": "<REDACTED>",
    "targetPath": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<REDACTED>",
          "modelName": "text-embedding-3-large"
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini"
        }
      },
      "ingestionSchedule": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
    "datasource": "my-onelake-ks-datasource",
    "indexer": "my-onelake-ks-indexer",
    "skillset": "my-onelake-ks-skillset",
    "index": "my-onelake-ks-index"
    }
  }
}

Annotazioni

Le informazioni sensibili sono state omesse. Le risorse generate vengono visualizzate alla fine della risposta.

Creare una fonte di informazioni

Eseguire il codice seguente per creare un'origine di conoscenza di OneLake.

// Create an IndexedOneLake 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), new AzureKeyCredential(apiKey));

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

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    DisableImageVerbalization = false,
    ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var oneLakeParams = new IndexedOneLakeKnowledgeSourceParameters(
    fabricWorkspaceId: fabricWorkspaceId,
    lakehouseId: lakehouseId)
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new IndexedOneLakeKnowledgeSource(
    name: "my-onelake-ks",
    indexedOneLakeParameters: oneLakeParams)
{
    Description = "This knowledge source pulls content from a lakehouse."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Proprietà specifiche dell'origine

È possibile passare le proprietà seguenti per creare una fonte di conoscenza di OneLake.

Nome Description TIPO Modificabili Obbligatorio
Name Nome della fonte di conoscenze, che deve essere univoco all'interno della raccolta delle fonti di conoscenze e seguire le linee guida per la denominazione degli oggetti in Azure AI Search. String Yes Yes
Description Descrizione dell'origine delle informazioni. String Yes NO
EncryptionKey Chiave gestita dal cliente per crittografare le informazioni riservate sia nell'origine delle informazioni che negli oggetti generati. Oggetto Yes NO
IndexedOneLakeKnowledgeSourceParameters Parametri specifici delle origini delle conoscenze di OneLake: fabricWorkspaceId, lakehouseIde targetPath. Oggetto Yes
fabricWorkspaceId GUID dell'area di lavoro che contiene la lakehouse. String NO Yes
lakehouseId Il GUID del lakehouse. String NO Yes
targetPath Una cartella o un collegamento all'interno della lakehouse. Se non specificato, l'intera lakehouse viene indicizzata. String NO NO

Proprietà ingestionParameters

Solo per le fonti di conoscenza indicizzate, è possibile passare le seguenti proprietà ingestionParameters per controllare il modo in cui il contenuto viene acquisito ed elaborato.

Nome Description TIPO Modificabili Obbligatorio
Identity Identità gestita da usare nell'indicizzatore generato. Oggetto Yes NO
DisableImageVerbalization Abilita o disabilita l'uso della verbalizzazione delle immagini. Il valore predefinito è False, che abilita la verbalizzazione delle immagini. Impostare True su disabilitare la verbalizzazione delle immagini. Boolean NO NO
ChatCompletionModel Modello di completamento della chat che verbalizza le immagini o estrae il contenuto. I modelli supportati sono gpt-4o, gpt-4o-mini, gpt-4.1gpt-4.1-mini, gpt-4.1-nano, gpt-5, , gpt-5-minie gpt-5-nano. La competenza Prompt GenAI verrà inclusa nel set di competenze generato. L'impostazione di questo parametro richiede anche che disable_image_verbalization sia impostato su False. Oggetto Solo api_key e deployment_name sono modificabili NO
EmbeddingModel Modello di incorporamento di testo che vettorizza il contenuto di testo e immagine durante l'indicizzazione e in fase di query. I modelli supportati sono text-embedding-ada-002, text-embedding-3-smalle text-embedding-3-large. La competenza di incorporamento OpenAI di Azure verrà inclusa nel set di competenze generato e il vettore OpenAI di Azure verrà incluso nell'indice generato. Oggetto Solo api_key e deployment_name sono modificabili NO
ContentExtractionMode Controlla la modalità di estrazione del contenuto dai file. Il valore predefinito è minimal, che usa l'estrazione di contenuto standard per testo e immagini. Impostare su standard per il cracking e la suddivisone in blocchi dei documenti usando la competenza Comprensione dei contenuti di Azure, che verrà incluso nel set di competenze generato. Solo per standard, i parametri AiServices e AssetStore sono specificabili. String NO NO
AiServices Una risorsa di Microsoft Foundry per accedere a Azure Content Understanding nei Foundry Tools. L'impostazione di questo parametro richiede che ContentExtractionMode sia impostato su standard. Oggetto Solo api_key modificabile Yes
IngestionSchedule Aggiunge informazioni di pianificazione all'indicizzatore generato. È anche possibile aggiungere una pianificazione in un secondo momento per automatizzare l'aggiornamento dei dati. Oggetto Yes NO
IngestionPermissionOptions Autorizzazioni a livello di documento per l'inserimento da origini di conoscenza selezionate: ADLS Gen2 o SharePoint indicizzato. Se si specifica user_ids, group_idso rbac_scope, l'indicizzatore ADLS Gen2 generato o l'indicizzatore di SharePoint includerà le autorizzazioni inserite. Array NO NO

Controllare lo stato dell'inserimento

Eseguire il codice seguente per monitorare l'avanzamento e l'integrità dell'inserimento, incluso lo stato dell'indicizzatore per le fonti di conoscenza che generano una pipeline dell'indicizzatore e popolano un indice di ricerca.

// Get knowledge source ingestion status
using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get the knowledge source status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;

// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Una risposta per una richiesta che include parametri di inserimento e inserisce attivamente contenuto potrebbe essere simile all'esempio seguente.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Esaminare gli oggetti creati

Quando si crea un'origine di conoscenza di OneLake, il servizio di ricerca crea anche un indicizzatore, un indice, un insieme di competenze e un'origine dati. Non è consigliabile modificare questi oggetti, perché l'introduzione di un errore o un'incompatibilità può interrompere la pipeline.

Dopo aver creato un'origine conoscenze, la risposta elenca gli oggetti creati. Questi oggetti vengono creati in base a un modello fisso e i relativi nomi sono basati sul nome dell'origine della conoscenza. Non è possibile modificare i nomi degli oggetti.

È consigliabile usare il portale di Azure per convalidare la creazione dell'output. Il flusso di lavoro è:

  1. Controllare l'indicizzatore per verificare la presenza di messaggi di esito positivo o negativo. Gli errori di connessione o quota vengono visualizzati qui.
  2. Controllare l'indice per i contenuti ricercabili. Utilizza Explorer di ricerca per eseguire query.
  3. Verificare le capacità per sapere come il contenuto viene suddiviso in parti e, facoltativamente, vettorializzato.
  4. Controllare l'origine dati per informazioni dettagliate sulla connessione. L'esempio usa le chiavi API per semplicità, ma è possibile usare Microsoft Entra ID per l'autenticazione e il controllo degli accessi in base al ruolo per l'autorizzazione.

Assegnare a una knowledge base

Se si è soddisfatti della fonte di conoscenza, continuare con il passaggio successivo: specificare la fonte nel knowledge base.

Per qualsiasi Knowledge Base che specifica una fonte delle informazioni OneLake, assicurarsi di impostarla su includeReferenceSourceDatatrue. Questo passaggio è necessario per eseguire il pull dell'URL del documento di origine nella citazione.

Dopo aver configurato la Knowledge Base, usare l'azione di recupero per eseguire query sull'origine della knowledge base.

Eliminare una fonte di informazioni

Prima di poter eliminare una fonte di conoscenza, devi eliminare qualsiasi knowledge base che vi faccia riferimento o aggiornare la definizione della knowledge base per rimuovere il riferimento. Per le fonti di conoscenza che generano una pipeline di generazione dell'indice e dell'indicizzatore, vengono eliminati anche tutti gli oggetti generati. Tuttavia, se è stato usato un indice esistente per creare un'origine conoscenze, l'indice non viene eliminato.

Se si tenta di eliminare una fonte di conoscenza in uso, l'azione fallisce e restituisce un elenco delle basi di conoscenza interessate.

Per eliminare una fonte di conoscenza:

  1. Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

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

    Una risposta di esempio potrebbe essere simile alla seguente:

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

  2. Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

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

    Una risposta di esempio potrebbe essere simile alla seguente:

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

  3. Eliminare la base di conoscenza o aggiornare la base di conoscenza per rimuovere la fonte di conoscenza se sono presenti più fonti. In questo esempio viene mostrata la procedura di eliminazione.

    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. Eliminare la fonte di informazioni.

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

Annotazioni

Questa funzionalità è attualmente disponibile in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Usare una fonte di conoscenza di OneLake per indicizzare ed eseguire query sui file di Microsoft OneLake in una pipeline di recupero con agente. Le origini delle informazioni vengono create in modo indipendente, a cui viene fatto riferimento in una knowledge base e usate come dati di base quando un agente o un chatbot chiama un'azione di recupero in fase di query.

Quando si crea un'origine conoscenza OneLake, si specifica un'origine dati esterna, modelli e proprietà per generare automaticamente gli oggetti di Ricerca di intelligenza artificiale di Azure seguenti:

  • L'origine dati che rappresenta un lakehouse.
  • Insieme di strumenti che suddivide e, facoltativamente, vettorizza il contenuto multimodale dal lakehouse.
  • Indice che archivia il contenuto arricchito e soddisfa i criteri per il recupero agentico.
  • Indicizzatore che usa gli oggetti precedenti per guidare la pipeline di indicizzazione e arricchimento.

L'indicizzatore generato è conforme all'indicizzatore OneLake, i cui prerequisiti, le attività supportate, i formati di documento supportati, i collegamenti supportati e le limitazioni si applicano anche alle origini conoscenze di OneLake. Per altre informazioni, vedere la documentazione dell'indicizzatore OneLake.

Prerequisiti

Verificare le fonti di informazioni esistenti

Una fonte di informazioni è un oggetto riutilizzabile di livello superiore. Conoscere le origini conoscenze esistenti è utile per riutilizzare o denominare nuovi oggetti.

Eseguire il codice seguente per elencare le origini delle informazioni in base al nome e al tipo.

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

È anche possibile restituire una singola fonte di informazioni in base al nome per esaminarne la definizione 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))

Il seguente JSON è un esempio di risposta per una fonte di conoscenza OneLake.

{
  "name": "my-onelake-ks",
  "kind": "indexedOneLake",
  "description": "A sample indexed OneLake knowledge source.",
  "encryptionKey": null,
  "indexedOneLakeParameters": {
    "fabricWorkspaceId": "<REDACTED>",
    "lakehouseId": "<REDACTED>",
    "targetPath": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<REDACTED>",
          "modelName": "text-embedding-3-large"
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini"
        }
      },
      "ingestionSchedule": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
    "datasource": "my-onelake-ks-datasource",
    "indexer": "my-onelake-ks-indexer",
    "skillset": "my-onelake-ks-skillset",
    "index": "my-onelake-ks-index"
    }
  }
}

Annotazioni

Le informazioni sensibili sono state omesse. Le risorse generate vengono visualizzate alla fine della risposta.

Creare una fonte di informazioni

Eseguire il codice seguente per creare un'origine di conoscenza di OneLake.

# Create a OneLake knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedOneLakeKnowledgeSource, IndexedOneLakeKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters

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

knowledge_source = IndexedOneLakeKnowledgeSource(
    name = "my-onelake-ks",
    description= "This knowledge source pulls content from a lakehouse.",
    encryption_key = None,
    indexed_one_lake_parameters = IndexedOneLakeKnowledgeSourceParameters(
        fabric_workspace_id = "fabric_workspace_id",
        lakehouse_id = "lakehouse_id",
        target_path = None,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = None
        )
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Proprietà specifiche dell'origine

È possibile passare le proprietà seguenti per creare una fonte di conoscenza di OneLake.

Nome Description TIPO Modificabili Obbligatorio
name Nome della fonte di conoscenze, che deve essere univoco all'interno della raccolta delle fonti di conoscenze e seguire le linee guida per la denominazione degli oggetti in Azure AI Search. String Yes Yes
description Descrizione dell'origine delle informazioni. String Yes NO
encryption Chiave gestita dal cliente per crittografare le informazioni riservate sia nell'origine delle informazioni che negli oggetti generati. Oggetto Yes NO
indexed_one_lake_parameters Parametri specifici delle origini delle conoscenze di OneLake: fabric_workspace_id, lakehouse_ide target_path. Oggetto Yes
fabric_workspace_id GUID dell'area di lavoro che contiene la lakehouse. String NO Yes
lakehouse_id Il GUID del lakehouse. String NO Yes
target_path Una cartella o un collegamento all'interno della lakehouse. Se non specificato, l'intera lakehouse viene indicizzata. String NO NO

Proprietà ingestionParameters

Solo per le fonti di conoscenza indicizzate, è possibile passare le seguenti proprietà ingestionParameters per controllare il modo in cui il contenuto viene acquisito ed elaborato.

Nome Description TIPO Modificabili Obbligatorio
identity Identità gestita da usare nell'indicizzatore generato. Oggetto Yes NO
disable_image_verbalization Abilita o disabilita l'uso della verbalizzazione delle immagini. Il valore predefinito è False, che abilita la verbalizzazione delle immagini. Impostare True su disabilitare la verbalizzazione delle immagini. Boolean NO NO
chat_completion_model Modello di completamento della chat che verbalizza le immagini o estrae il contenuto. I modelli supportati sono gpt-4o, gpt-4o-mini, gpt-4.1gpt-4.1-mini, gpt-4.1-nano, gpt-5, , gpt-5-minie gpt-5-nano. La competenza Prompt GenAI verrà inclusa nel set di competenze generato. L'impostazione di questo parametro richiede anche che disable_image_verbalization sia impostato su False. Oggetto Solo api_key e deployment_name sono modificabili NO
embedding_model Modello di incorporamento di testo che vettorizza il contenuto di testo e immagine durante l'indicizzazione e in fase di query. I modelli supportati sono text-embedding-ada-002, text-embedding-3-smalle text-embedding-3-large. La competenza di incorporamento OpenAI di Azure verrà inclusa nel set di competenze generato e il vettore OpenAI di Azure verrà incluso nell'indice generato. Oggetto Solo api_key e deployment_name sono modificabili NO
content_extraction_mode Controlla la modalità di estrazione del contenuto dai file. Il valore predefinito è minimal, che usa l'estrazione di contenuto standard per testo e immagini. Impostare su standard per il cracking e la suddivisone in blocchi dei documenti usando la competenza Comprensione dei contenuti di Azure, che verrà incluso nel set di competenze generato. Solo per standard, i parametri ai_services e asset_store sono specificabili. String NO NO
ai_services Una risorsa di Microsoft Foundry per accedere a Azure Content Understanding nei Foundry Tools. L'impostazione di questo parametro richiede che content_extraction_mode sia impostato su standard. Oggetto Solo api_key modificabile Yes
asset_store Contenitore BLOB per archiviare le immagini estratte. L'impostazione di questo parametro richiede che content_extraction_mode sia impostato su standard. Oggetto NO NO
ingestion_schedule Aggiunge informazioni di pianificazione all'indicizzatore generato. È anche possibile aggiungere una pianificazione in un secondo momento per automatizzare l'aggiornamento dei dati. Oggetto Yes NO
ingestion_permission_options Autorizzazioni a livello di documento per l'inserimento da origini di conoscenza selezionate: ADLS Gen2 o SharePoint indicizzato. Se si specifica user_ids, group_idso rbac_scope, l'indicizzatore ADLS Gen2 generato o l'indicizzatore di SharePoint includerà le autorizzazioni inserite. Array NO NO

Controllare lo stato dell'inserimento

Eseguire il codice seguente per monitorare lo stato e l'integrità dell'inserimento, incluso lo stato dell'indicizzatore per le sorgenti di conoscenza che generano una pipeline per l'indicizzatore e popolano un indice di ricerca.

# Check knowledge source ingestion status
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}/status"
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))

Una risposta per una richiesta che include parametri di inserimento e inserisce attivamente contenuto potrebbe essere simile all'esempio seguente.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Esaminare gli oggetti creati

Quando si crea un'origine di conoscenza di OneLake, il servizio di ricerca crea anche un indicizzatore, un indice, un insieme di competenze e un'origine dati. Non è consigliabile modificare questi oggetti, perché l'introduzione di un errore o un'incompatibilità può interrompere la pipeline.

Dopo aver creato un'origine conoscenze, la risposta elenca gli oggetti creati. Questi oggetti vengono creati in base a un modello fisso e i relativi nomi sono basati sul nome dell'origine della conoscenza. Non è possibile modificare i nomi degli oggetti.

È consigliabile usare il portale di Azure per convalidare la creazione dell'output. Il flusso di lavoro è:

  1. Controllare l'indicizzatore per verificare la presenza di messaggi di esito positivo o negativo. Gli errori di connessione o quota vengono visualizzati qui.
  2. Controllare l'indice per i contenuti ricercabili. Utilizza Explorer di ricerca per eseguire query.
  3. Verificare le capacità per sapere come il contenuto viene suddiviso in parti e, facoltativamente, vettorializzato.
  4. Controllare l'origine dati per informazioni dettagliate sulla connessione. L'esempio usa le chiavi API per semplicità, ma è possibile usare Microsoft Entra ID per l'autenticazione e il controllo degli accessi in base al ruolo per l'autorizzazione.

Assegnare a una knowledge base

Se si è soddisfatti della fonte di conoscenza, continuare con il passaggio successivo: specificare la fonte nel knowledge base.

Per qualsiasi Knowledge Base che specifica una fonte delle informazioni OneLake, assicurarsi di impostarla su includeReferenceSourceDatatrue. Questo passaggio è necessario per eseguire il pull dell'URL del documento di origine nella citazione.

Dopo aver configurato la Knowledge Base, usare l'azione di recupero per eseguire query sull'origine della knowledge base.

Eliminare una fonte di informazioni

Prima di poter eliminare una fonte di conoscenza, devi eliminare qualsiasi knowledge base che vi faccia riferimento o aggiornare la definizione della knowledge base per rimuovere il riferimento. Per le fonti di conoscenza che generano una pipeline di generazione dell'indice e dell'indicizzatore, vengono eliminati anche tutti gli oggetti generati. Tuttavia, se è stato usato un indice esistente per creare un'origine conoscenze, l'indice non viene eliminato.

Se si tenta di eliminare una fonte di conoscenza in uso, l'azione fallisce e restituisce un elenco delle basi di conoscenza interessate.

Per eliminare una fonte di conoscenza:

  1. Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

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

    Una risposta di esempio potrebbe essere simile alla seguente:

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

  2. Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

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

    Una risposta di esempio potrebbe essere simile alla seguente:

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

  3. Eliminare la base di conoscenza o aggiornare la base di conoscenza per rimuovere la fonte di conoscenza se sono presenti più fonti. In questo esempio viene mostrata la procedura di eliminazione.

    # 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. Eliminare la fonte di informazioni.

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

Annotazioni

Questa funzionalità è attualmente disponibile in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Usare una fonte di conoscenza di OneLake per indicizzare ed eseguire query sui file di Microsoft OneLake in una pipeline di recupero con agente. Le origini delle informazioni vengono create in modo indipendente, a cui viene fatto riferimento in una knowledge base e usate come dati di base quando un agente o un chatbot chiama un'azione di recupero in fase di query.

Quando si crea un'origine conoscenza OneLake, si specifica un'origine dati esterna, modelli e proprietà per generare automaticamente gli oggetti di Ricerca di intelligenza artificiale di Azure seguenti:

  • L'origine dati che rappresenta un lakehouse.
  • Insieme di strumenti che suddivide e, facoltativamente, vettorizza il contenuto multimodale dal lakehouse.
  • Indice che archivia il contenuto arricchito e soddisfa i criteri per il recupero agentico.
  • Indicizzatore che usa gli oggetti precedenti per guidare la pipeline di indicizzazione e arricchimento.

L'indicizzatore generato è conforme all'indicizzatore OneLake, i cui prerequisiti, le attività supportate, i formati di documento supportati, i collegamenti supportati e le limitazioni si applicano anche alle origini conoscenze di OneLake. Per altre informazioni, vedere la documentazione dell'indicizzatore OneLake.

Prerequisiti

Verificare le fonti di informazioni esistenti

Una fonte di informazioni è un oggetto riutilizzabile di livello superiore. Conoscere le origini conoscenze esistenti è utile per riutilizzare o denominare nuovi oggetti.

Usare Le origini delle informazioni - Ottenere (API REST) per elencare le origini delle informazioni in base al nome e al tipo.

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

È anche possibile restituire una singola fonte di informazioni in base al nome per esaminarne la definizione JSON.

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

Il seguente JSON è un esempio di risposta per una fonte di conoscenza OneLake.

{
  "name": "my-onelake-ks",
  "kind": "indexedOneLake",
  "description": "A sample indexed OneLake knowledge source.",
  "encryptionKey": null,
  "indexedOneLakeParameters": {
    "fabricWorkspaceId": "<REDACTED>",
    "lakehouseId": "<REDACTED>",
    "targetPath": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<REDACTED>",
          "modelName": "text-embedding-3-large"
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini"
        }
      },
      "ingestionSchedule": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
    "datasource": "my-onelake-ks-datasource",
    "indexer": "my-onelake-ks-indexer",
    "skillset": "my-onelake-ks-skillset",
    "index": "my-onelake-ks-index"
    }
  }
}

Annotazioni

Le informazioni sensibili sono state omesse. Le risorse generate vengono visualizzate alla fine della risposta.

Creare una fonte di informazioni

Usare Origini di conoscenza - Creare o aggiornare (API REST) per creare un'origine di conoscenza di OneLake.

PUT {{search-url}}/knowledgesources/my-onelake-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-onelake-ks",
    "kind": "indexedOneLake",
    "description": "This knowledge source pulls content from a lakehouse.",
    "indexedOneLakeParameters": {
      "fabricWorkspaceId": "<YOUR FABRIC WORKSPACE GUID>",
      "lakehouseId": "<YOUR LAKEHOUSE GUID>",
      "targetPath": null,
      "ingestionParameters": {
        "identity": null,
        "disableImageVerbalization": null,
        "chatCompletionModel": { TRIMMED FOR BREVITY },
        "embeddingModel": { TRIMMED FOR BREVITY },
        "contentExtractionMode": "minimal",
        "ingestionSchedule": null,
        "ingestionPermissionOptions": []
    }
  }
}

Proprietà specifiche dell'origine

È possibile passare le proprietà seguenti per creare una fonte di conoscenza di OneLake.

Nome Description TIPO Modificabili Obbligatorio
name Nome della fonte di conoscenze, che deve essere univoco all'interno della raccolta delle fonti di conoscenze e seguire le linee guida per la denominazione degli oggetti in Azure AI Search. String Yes Yes
kind Il tipo di origine delle conoscenze, che in questo caso è indexedOneLake . String NO Yes
description Descrizione dell'origine delle informazioni. String Yes NO
encryptionKey Chiave gestita dal cliente per crittografare le informazioni riservate sia nell'origine delle informazioni che negli oggetti generati. Oggetto Yes NO
indexedOneLakeParameters Parametri specifici delle origini delle conoscenze di OneLake: fabricWorkspaceId, lakehouseIde targetPath. Oggetto Yes
fabricWorkspaceId GUID dell'area di lavoro che contiene la lakehouse. String NO Yes
lakehouseId Il GUID del lakehouse. String NO Yes
targetPath Una cartella o un collegamento all'interno della lakehouse. Se non specificato, l'intera lakehouse viene indicizzata. String NO NO

Proprietà ingestionParameters

Solo per le fonti di conoscenza indicizzate, è possibile passare le seguenti proprietà ingestionParameters per controllare il modo in cui il contenuto viene acquisito ed elaborato.

Nome Description TIPO Modificabili Obbligatorio
identity Identità gestita da usare nell'indicizzatore generato. Oggetto Yes NO
disableImageVerbalization Abilita o disabilita l'uso della verbalizzazione delle immagini. Il valore predefinito è false, che abilita la verbalizzazione delle immagini. Impostare true su disabilitare la verbalizzazione delle immagini. Boolean NO NO
chatCompletionModel Modello di completamento della chat che verbalizza le immagini o estrae il contenuto. I modelli supportati sono gpt-4o, gpt-4o-mini, gpt-4.1gpt-4.1-mini, gpt-4.1-nano, gpt-5, , gpt-5-minie gpt-5-nano. La competenza Prompt GenAI verrà inclusa nel set di competenze generato. L'impostazione di questo parametro richiede anche che disableImageVerbalization sia impostato su false. Oggetto Solo apiKey e deploymentId sono modificabili NO
embeddingModel Modello di incorporamento di testo che vettorizza il contenuto di testo e immagine durante l'indicizzazione e in fase di query. I modelli supportati sono text-embedding-ada-002, text-embedding-3-smalle text-embedding-3-large. La competenza di incorporamento OpenAI di Azure verrà inclusa nel set di competenze generato e il vettore OpenAI di Azure verrà incluso nell'indice generato. Oggetto Solo apiKey e deploymentId sono modificabili NO
contentExtractionMode Controlla la modalità di estrazione del contenuto dai file. Il valore predefinito è minimal, che usa l'estrazione di contenuto standard per testo e immagini. Impostare su standard per il cracking e la suddivisone in blocchi dei documenti usando la competenza Comprensione dei contenuti di Azure, che verrà incluso nel set di competenze generato. Solo per standard, i parametri aiServices e assetStore sono specificabili. String NO NO
aiServices Una risorsa di Microsoft Foundry per accedere a Azure Content Understanding nei Foundry Tools. L'impostazione di questo parametro richiede che contentExtractionMode sia impostato su standard. Oggetto Solo apiKey modificabile Yes
assetStore Contenitore BLOB per archiviare le immagini estratte. L'impostazione di questo parametro richiede che contentExtractionMode sia impostato su standard. Oggetto NO NO
ingestionSchedule Aggiunge informazioni di pianificazione all'indicizzatore generato. È anche possibile aggiungere una pianificazione in un secondo momento per automatizzare l'aggiornamento dei dati. Oggetto Yes NO
ingestionPermissionOptions Autorizzazioni a livello di documento per l'inserimento da origini di conoscenza selezionate: ADLS Gen2 o SharePoint indicizzato. Se si specifica userIds, groupIdso rbacScope, l'indicizzatore ADLS Gen2 generato o l'indicizzatore di SharePoint includerà le autorizzazioni inserite. Array NO NO

Controllare lo stato dell'inserimento

Usare Knowledge Sources - Status (API REST) per monitorare lo stato e l'integrità dell'inserimento, incluso lo stato dell'indicizzatore per le origini delle informazioni che generano una pipeline dell'indicizzatore e popolano un indice di ricerca.

### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

Una risposta per una richiesta che include parametri di inserimento e inserisce attivamente contenuto potrebbe essere simile all'esempio seguente.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Esaminare gli oggetti creati

Quando si crea un'origine di conoscenza di OneLake, il servizio di ricerca crea anche un indicizzatore, un indice, un insieme di competenze e un'origine dati. Non è consigliabile modificare questi oggetti, perché l'introduzione di un errore o un'incompatibilità può interrompere la pipeline.

Dopo aver creato un'origine conoscenze, la risposta elenca gli oggetti creati. Questi oggetti vengono creati in base a un modello fisso e i relativi nomi sono basati sul nome dell'origine della conoscenza. Non è possibile modificare i nomi degli oggetti.

È consigliabile usare il portale di Azure per convalidare la creazione dell'output. Il flusso di lavoro è:

  1. Controllare l'indicizzatore per verificare la presenza di messaggi di esito positivo o negativo. Gli errori di connessione o quota vengono visualizzati qui.
  2. Controllare l'indice per i contenuti ricercabili. Utilizza Explorer di ricerca per eseguire query.
  3. Verificare le capacità per sapere come il contenuto viene suddiviso in parti e, facoltativamente, vettorializzato.
  4. Controllare l'origine dati per informazioni dettagliate sulla connessione. L'esempio usa le chiavi API per semplicità, ma è possibile usare Microsoft Entra ID per l'autenticazione e il controllo degli accessi in base al ruolo per l'autorizzazione.

Assegnare a una knowledge base

Se si è soddisfatti della fonte di conoscenza, continuare con il passaggio successivo: specificare la fonte nel knowledge base.

Per qualsiasi Knowledge Base che specifica una fonte delle informazioni OneLake, assicurarsi di impostarla su includeReferenceSourceDatatrue. Questo passaggio è necessario per eseguire il pull dell'URL del documento di origine nella citazione.

Dopo aver configurato la Knowledge Base, usare l'azione di recupero per eseguire query sull'origine della knowledge base.

Eliminare una fonte di informazioni

Prima di poter eliminare una fonte di conoscenza, devi eliminare qualsiasi knowledge base che vi faccia riferimento o aggiornare la definizione della knowledge base per rimuovere il riferimento. Per le fonti di conoscenza che generano una pipeline di generazione dell'indice e dell'indicizzatore, vengono eliminati anche tutti gli oggetti generati. Tuttavia, se è stato usato un indice esistente per creare un'origine conoscenze, l'indice non viene eliminato.

Se si tenta di eliminare una fonte di conoscenza in uso, l'azione fallisce e restituisce un elenco delle basi di conoscenza interessate.

Per eliminare una fonte di conoscenza:

  1. Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

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

    Una risposta di esempio potrebbe essere simile alla seguente:

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

  2. Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

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

    Una risposta di esempio potrebbe essere simile alla seguente:

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

  3. Eliminare la Knowledge Base o aggiornare la Knowledge Base rimuovendo la fonte di conoscenza se sono presenti più fonti. In questo esempio viene mostrata la procedura di eliminazione.

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

  4. Eliminare la fonte di informazioni.

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

Contenuti correlati

  • Last updated on