Creare una fonte di informazioni dell'indice di ricerca

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 ulteriori informazioni, vedere Condizioni d'uso supplementari per le anteprime di Microsoft Azure.

Unsearch index knowledge source specifica una connessione a un indice Azure AI Search che fornisce contenuto ricercabile in una pipeline di recupero agentica. 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.

Supporto per l'utilizzo

portale Azure	Portale Microsoft Foundry	.NET SDK	Python SDK	Java SDK	JavaScript SDK	API REST
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisiti

Azure AI Search in qualsiasi area che fornisce il recupero agentico. È necessario che sia abilitato il ranker semantico.
Indice di ricerca contenente testo normale o contenuto vettoriale con una configurazione semantica. Esaminare i criteri di indice per il recupero agentico. L'indice deve trovarsi nello stesso servizio di ricerca della Knowledge Base.
Autorizzazione per creare e usare oggetti in Azure AI Search. È consigliabile usare l'accesso in base al ruolo, ma è possibile usare le chiavi API se un'assegnazione di ruolo non è fattibile. Per altre informazioni, vedere Connettersi a un servizio di ricerca.

Pacchetto di anteprima Azure.Search.Documents: dotnet add package Azure.Search.Documents --prerelease

Pacchetto di anteprima azure-search-documents: pip install --pre azure-search-documents

Versione 2025-11-01-preview delle API REST del servizio di ricerca.

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

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

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 dell'indice di ricerca. Si noti che l'origine delle informazioni specifica un singolo nome di indice e i campi dell'indice da includere nella query.

{
  "name": "my-search-index-ks",
  "kind": "searchIndex",
  "description": "A sample search index knowledge source.",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "my-search-index",
    "semanticConfigurationName": null,
    "sourceDataFields": [],
    "searchFields": []
  }
}

Creare una fonte di informazioni

Eseguire il seguente codice per creare una fonte di conoscenza dell'indice di ricerca.

// Create a search index knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure;

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

var indexKnowledgeSource = new SearchIndexKnowledgeSource(
    name: knowledgeSourceName,
    searchIndexParameters: new SearchIndexKnowledgeSourceParameters(searchIndexName: indexName)
    {
        SourceDataFields = { new SearchIndexFieldReference(name: "id"), new SearchIndexFieldReference(name: "page_chunk"), new SearchIndexFieldReference(name: "page_number") }
    }
);

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

Eseguire il seguente codice per creare una fonte di conoscenza dell'indice di ricerca.

# Create a search index knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, SearchIndexFieldReference

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

knowledge_source = SearchIndexKnowledgeSource(
    name = "my-search-index-ks",
    description= "This knowledge source pulls from an existing index designed for agentic retrieval.",
    encryption_key = None,
    search_index_parameters = SearchIndexKnowledgeSourceParameters(
        search_index_name = "search_index_name",
        semantic_configuration_name = "semantic_configuration_name",
        source_data_fields = [
            SearchIndexFieldReference(name="description"),
            SearchIndexFieldReference(name="category"),
        ],
        search_fields = [
            SearchIndexFieldReference(name="id")
        ],
    )
)

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

Usa Fonti di conoscenza - Crea o Aggiorna (API REST) per creare una fonte di conoscenza per l'indice di ricerca.

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

{
    "name": "my-search-index-ks",
    "kind": "searchIndex",
    "description": "This knowledge source pulls from an existing index designed for agentic retrieval.",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "<YOUR INDEX NAME>",
        "semanticConfigurationName": "my-semantic-config",
        "sourceDataFields": [
          { "name": "description" },
          { "name": "category" }
        ]
    }
}

Proprietà specifiche dell'origine

È possibile passare le proprietà seguenti per creare un'origine di conoscenza dell'indice di ricerca.

Nome	Description	TIPO	Modificabili	Obbligatorio
`Name`	Nome della fonte di conoscenza, che deve essere univoco all'interno della raccolta delle fonti di conoscenza e seguire le linee guida per la denominazione degli oggetti in Azure AI Search.	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
`SearchIndexParameters`	Parametri specifici per le origini delle conoscenze dell'indice di ricerca: `SearchIndexName`, `SemanticConfigurationName`, `SourceDataFields`e `SearchFields`.	Oggetto	Yes	Yes
`SearchIndexName`	Nome dell'indice di ricerca esistente.	String	Yes	Yes
`SemanticConfigurationName`	Esegue l'override della configurazione semantica predefinita per l'indice di ricerca.	String	Yes	NO
`SourceDataFields`	I campi di indice restituiti quando si specifica `IncludeReferenceSourceData` nella definizione della Knowledge Base. Questi campi vengono usati per le citazioni e devono essere `retrievable`. Gli esempi includono il nome del documento, il nome del file, i numeri di pagina o i numeri di capitolo.	Array	Yes	NO
`SearchFields`	Campi di indice in base a cui eseguire una ricerca specifica. Se non specificato, vengono cercati tutti i campi.	Array	Yes	NO

Nome	Description	TIPO	Modificabili	Obbligatorio
`name`	Nome della fonte di conoscenza, che deve essere univoco all'interno della raccolta delle fonti di conoscenza e seguire le linee guida per la denominazione degli oggetti in Azure AI Search.	String	NO	Yes
`description`	Descrizione dell'origine delle informazioni.	String	Yes	NO
`encryption_key`	Chiave gestita dal cliente per crittografare le informazioni riservate sia nell'origine delle informazioni che negli oggetti generati.	Oggetto	Yes	NO
`search_index_parameters`	Parametri specifici per le origini delle conoscenze dell'indice di ricerca: `search_index_name`, `semantic_configuration_name`, `source_data_fields`e `search_fields`.	Oggetto	Yes	Yes
`search_index_name`	Nome dell'indice di ricerca esistente.	String	Yes	Yes
`semantic_configuration_name`	Esegue l'override della configurazione semantica predefinita per l'indice di ricerca.	String	Yes	NO
`source_data_fields`	I campi di indice restituiti quando si specifica `include_reference_source_data` nella definizione della Knowledge Base. Questi campi vengono usati per le citazioni e devono essere `retrievable`. Gli esempi includono il nome del documento, il nome del file, i numeri di pagina o i numeri di capitolo.	Array	Yes	NO
`search_fields`	Campi di indice in base a cui eseguire una ricerca specifica. Se non specificato, vengono cercati tutti i campi.	Array	Yes	NO

Nome	Description	TIPO	Modificabili	Obbligatorio
`name`	Nome della fonte di conoscenza, che deve essere univoco all'interno della raccolta delle fonti di conoscenza e seguire le linee guida per la denominazione degli oggetti in Azure AI Search.	String	NO	Yes
`kind`	Il tipo di origine delle conoscenze, che in questo caso è `searchIndex` .	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
`searchIndexParameters`	Parametri specifici per le origini delle conoscenze dell'indice di ricerca: `searchIndexName`, `semanticConfigurationName`, `sourceDataFields`e `searchFields`.	Oggetto	Yes	Yes
`searchIndexName`	Nome dell'indice di ricerca esistente.	String	Yes	Yes
`semanticConfigurationName`	Esegue l'override della configurazione semantica predefinita per l'indice di ricerca.	String	Yes	NO
`sourceDataFields`	I campi di indice restituiti quando si specifica `includeReferenceSourceData` nella definizione della Knowledge Base. Questi campi vengono usati per le citazioni e devono essere `retrievable`. Gli esempi includono il nome del documento, il nome del file, i numeri di pagina o i numeri di capitolo.	Array	Yes	NO
`searchFields`	Campi di indice in base a cui eseguire una ricerca specifica. Se non specificato, vengono cercati tutti i campi.	Array	Yes	NO

Assegnare a una knowledge base

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

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:

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

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
 }

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

Eliminare la fonte di informazioni.

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

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:

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

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

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

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

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:

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

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

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

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-15

Creare una fonte di informazioni dell'indice di ricerca

Supporto per l'utilizzo

Prerequisiti

Verificare le fonti di informazioni esistenti

Creare una fonte di informazioni

Proprietà specifiche dell'origine

Assegnare a una knowledge base

Eliminare una fonte di informazioni

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive