Creare una risorsa di fonte di conoscenza Web

Importante

  • Fonte di conoscenza del Web, che usa il Grounding con Ricerca Bing e/o con Ricerca Personalizzata Bing, è un servizio di First Party Consumption Service disciplinato dalle condizioni di utilizzo di Grounding con Bing e dall’Informativa sulla privacy di Microsoft.

  • Il Microsoft Data Protection Addendum non si applica ai dati inviati al Web Knowledge Source. Quando il cliente usa l'origine delle informazioni Web, i dati dei clienti passano all'esterno del limite geografico e di conformità Azure. Questo significa anche che l'uso della fonte di conoscenza Web determina la rinuncia a tutti gli elevati impegni di sicurezza e conformità previsti per il Cloud Community del Governo, inclusa la sovranità dei dati e il supporto basato su controlli e cittadinanza, quando applicabile.

  • L'uso dell'origine delle informazioni Web comporta costi; Altre informazioni sui prezzi.

  • Altre informazioni su come gli amministratori di Azure possono gestire l'accesso all'uso della fonte di conoscenza web.

Nota

Questa funzionalità di recupero agente è generalmente disponibile nella versione dell'API REST 2026-04-01 tramite accesso programmatico. Il portale di Azure e il portale Foundry di Microsoft continueranno a fornire l'accesso in anteprima a tutte le funzionalità di recupero agentico. Per indicazioni sulla migrazione, vedere Eseguire la migrazione del codice di recupero agenti alla versione più recente.

Se si sceglie di usare una versione di anteprima dell'API REST, è possibile accedere alle funzionalità non ancora disponibili a livello generale per questa funzionalità. Le funzionalità di anteprima vengono fornite senza un contratto di servizio e non sono consigliate per i carichi di lavoro di produzione. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

Web Knowledge Source consente il recupero di dati Web in tempo reale da Microsoft Bing in una pipeline di recupero agentico. 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.

Bing Ricerca Personalizzata è sempre il provider di ricerca per la Fonte di Conoscenza Web. Anche se non è possibile specificare provider o motori di ricerca alternativi, è possibile includere o escludere domini specifici, ad esempio https://learn.microsoft.com. Quando non viene specificato alcun dominio, l'origine delle informazioni Web ha accesso senza restrizioni all'intera rete Internet pubblica.

L'origine delle informazioni Web funziona meglio insieme ad altre fonti di conoscenza. Usa Web Knowledge Source quando il contenuto proprietario non fornisce risposte complete, up-to-date o quando vuoi integrare i risultati con le informazioni di un motore di ricerca commerciale.

Supporto per l'utilizzo

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

Prerequisiti

  • Pacchetto Azure.Search.Documents obbligatorio:

    • Per le funzionalità di anteprima del 2025-11-01, il pacchetto di anteprima più recente: dotnet add package Azure.Search.Documents --prerelease

    • Per le funzionalità 2026-04-01, il pacchetto stabile più recente: dotnet add package Azure.Search.Documents

  • Pacchetto azure-search-documents obbligatorio:

    • Per le funzionalità di anteprima del 2025-11-01, il pacchetto di anteprima più recente: pip install azure-search-documents --pre

    • Per le funzionalità 2026-04-01, il pacchetto stabile più recente: pip install azure-search-documents

Limitazioni e considerazioni

  • Il contenuto Web viene sempre riepilogato da un LLM prima che venga incluso nei risultati del recupero. I risultati sono riepiloghi citati, non testo web letterale.

  • Per la versione dell'API 2026-04-01, la base di conoscenza deve includere un riferimento al modello per utilizzare l'LLM nel riepilogo dei contenuti web. Il recupero è sempre di tipo estrattivo con sommari citati. La sintesi delle risposte e il componente di ragionamento configurabile non sono disponibili in questa versione.

  • Per la versione dell'API 2025-11-01-preview, il riferimento al modello di knowledge base abilita anche la sintesi delle risposte, che produce una singola risposta formulata dall'LLM anziché le citazioni estratte.

Verificare la presenza di fonti di conoscenza esistenti

Un'origine delle conoscenze è un oggetto riutilizzabile di primo livello. 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}");
}

Reference:SearchIndexClient

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

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

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

Reference:SearchIndexClient

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

Reference:Knowledge Sources - List

Puoi anche restituire una singola fonte di conoscenza per 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));

Reference:SearchIndexClient

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

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

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

Reference:SearchIndexClient

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

Reference:Fonti di Conoscenza - Ottieni

Il codice JSON seguente è una risposta di esempio per una risorsa origine informazioni Web.

{
  "name": "my-web-ks",
  "kind": "web",
  "description": "A sample Web Knowledge Source.",
  "encryptionKey": null,
  "webParameters": {
    "domains": null
  }
}

Creare una fonte di conoscenza

Eseguire il codice seguente per creare un'origine delle informazioni Web.

// Create Web 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 knowledgeSource = new WebKnowledgeSource(name: "my-web-ks")
{
    Description = "A sample Web Knowledge Source.",
    WebParameters = new WebKnowledgeSourceParameters
    {
        Domains = new WebKnowledgeSourceDomains
        {
            AllowedDomains = 
            {
                new WebKnowledgeSourceDomain(address: "learn.microsoft.com") { IncludeSubpages = true }
            },
            BlockedDomains = 
            {
                new WebKnowledgeSourceDomain(address: "bing.com") { IncludeSubpages = false }
            }
        }
    }
};

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

Reference:SearchIndexClient, WebKnowledgeSource

# Create Web Knowledge Source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import WebKnowledgeSource, WebKnowledgeSourceParameters, WebKnowledgeSourceDomains, WebKnowledgeSourceDomain

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

knowledge_source = WebKnowledgeSource(
    name = "my-web-ks",
    description = "A sample Web Knowledge Source.",
    encryption_key = None,
    web_parameters = WebKnowledgeSourceParameters(
        domains = WebKnowledgeSourceDomains(
            allowed_domains = [ WebKnowledgeSourceDomain(address="learn.microsoft.com", include_subpages=True) ],
            blocked_domains = [ WebKnowledgeSourceDomain(address="bing.com", include_subpages=False) ]
        )
    )
)

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

Reference:SearchIndexClient

### Create Web Knowledge Source
PUT {{search-url}}/knowledgesources/my-web-ks?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{api-key}}

{
  "name": "my-web-ks",
  "kind": "web",
  "description": "This knowledge source pulls content from the web.",
  "encryptionKey": null,
  "webParameters": {
    "domains": {
      "allowedDomains": [ { "address": "learn.microsoft.com", "includeSubpages": true } ],
      "blockedDomains": [ { "address": "bing.com", "includeSubpages": false } ]
    }
  }
}

Riferimento:Fonti di conoscenza - Creare o Aggiornare

Proprietà specifiche dell'origine

Per entrambe le versioni dell'API 2025-11-01-preview e 2026-04-01, è possibile passare le proprietà seguenti per creare una fonte di conoscenza web.

Nome Descrizione Digitare Modificabile Obbligatorio
Name Nome dell'origine di conoscenza, che deve essere univoco all'interno della raccolta delle origini di conoscenza e seguire le linee guida di denominazione per gli oggetti in Azure AI Search. Stringa No Sì
Description Descrizione dell'origine delle informazioni. Se non specificato, Azure AI Search applica una descrizione predefinita. Stringa Sì No
EncryptionKey Chiave gestita dal cliente per crittografare le informazioni riservate nell'origine delle informazioni. Oggetto Sì No
WebParameters Parametri specifici della fonte di conoscenza Web. Attualmente, si tratta solo di Domains. Oggetto Sì No
Domains Domini per consentire o bloccare nello spazio di ricerca. Per impostazione predefinita, l'origine delle informazioni usa Grounding con Ricerca Bing per eseguire ricerche nell'intera rete Internet pubblica. Quando si specificano domini, l'origine della knowledge base usa Grounding con Ricerca personalizzata Bing per limitare i risultati ai domini specificati. In entrambi i casi, Ricerca personalizzata Bing è il provider di ricerca. Oggetto Sì No
AllowedDomains Domini da includere nello spazio di ricerca. Per ogni dominio, è necessario specificarne il formato address nel website.com. È anche possibile specificare se includere le pagine secondarie del dominio impostando IncludeSubpages su true o false. Array Sì No
BlockedDomains Domini da escludere dallo spazio di ricerca. Per ogni dominio, è necessario specificarne il formato address nel website.com. È anche possibile specificare se includere le pagine secondarie del dominio impostando IncludeSubpages su true o false. Array Sì No
Nome Descrizione Digitare Modificabile Obbligatorio
name Nome dell'origine di conoscenza, che deve essere univoco all'interno della raccolta delle origini di conoscenza e seguire le linee guida di denominazione per gli oggetti in Azure AI Search. Stringa No Sì
description Descrizione dell'origine delle informazioni. Se non specificato, Azure AI Search applica una descrizione predefinita. Stringa Sì No
encryption_key Chiave gestita dal cliente per crittografare le informazioni riservate nell'origine delle informazioni. Oggetto Sì No
web_parameters Parametri specifici della fonte di conoscenza Web. Attualmente, si tratta solo di domains. Oggetto Sì No
domains Domini per consentire o bloccare nello spazio di ricerca. Per impostazione predefinita, l'origine delle informazioni usa Grounding con Ricerca Bing per eseguire ricerche nell'intera rete Internet pubblica. Quando si specificano domini, l'origine della knowledge base usa Grounding con Ricerca personalizzata Bing per limitare i risultati ai domini specificati. In entrambi i casi, Ricerca personalizzata Bing è il provider di ricerca. Oggetto Sì No
allowed_domains Domini da includere nello spazio di ricerca. Per ogni dominio, è necessario specificarne il formato address nel website.com. È anche possibile specificare se includere le pagine secondarie del dominio impostando include_subpages su true o false. Array Sì No
blocked_domains Domini da escludere dallo spazio di ricerca. Per ogni dominio, è necessario specificarne il formato address nel website.com. È anche possibile specificare se includere le pagine secondarie del dominio impostando include_subpages su true o false. Array Sì No
Nome Descrizione Digitare Modificabile Obbligatorio
name Nome dell'origine di conoscenza, che deve essere univoco all'interno della raccolta delle origini di conoscenza e seguire le linee guida di denominazione per gli oggetti in Azure AI Search. Stringa No Sì
kind Il tipo di origine delle conoscenze, che in questo caso è web . Stringa No Sì
description Descrizione dell'origine delle informazioni. Se non specificato, Azure AI Search applica una descrizione predefinita. Stringa Sì No
encryptionKey Chiave gestita dal cliente per crittografare le informazioni riservate nell'origine delle informazioni. Oggetto Sì No
webParameters Parametri specifici della fonte di conoscenza Web. Attualmente, si tratta solo di domains. Oggetto Sì No
domains Domini per consentire o bloccare nello spazio di ricerca. Per impostazione predefinita, l'origine delle informazioni usa Grounding con Ricerca Bing per eseguire ricerche nell'intera rete Internet pubblica. Quando si specificano domini, l'origine della knowledge base usa Grounding con Ricerca personalizzata Bing per limitare i risultati ai domini specificati. In entrambi i casi, Ricerca personalizzata Bing è il provider di ricerca. Oggetto Sì No
allowedDomains Domini da includere nello spazio di ricerca. Per ogni dominio, è necessario specificarne il formato address nel website.com. È anche possibile specificare se includere le pagine secondarie del dominio impostando includeSubpages su true o false. Array Sì No
blockedDomains Domini da escludere dallo spazio di ricerca. Per ogni dominio, è necessario specificarne il formato address nel website.com. È anche possibile specificare se includere le pagine secondarie del dominio impostando includeSubpages su true o false. Array Sì No

Assegnare a una base di conoscenza

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

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

"Revisione dell'output dei dati recuperati"

Quando si esegue una query su una Knowledge Base che include la Fonte di conoscenza Web, la risposta di recupero della matrice activity può contenere due record correlati al web.

  • Record web che acquisisce i parametri di runtime usati per la richiesta.
  • Registro modelWebSummarization che acquisisce l'utilizzo dei token nel processo di sintesi LLM.
{
  "activity": [
    {
      "id": 1,
      "type": "web",
      "knowledgeSourceName": "my-web-ks",
      "elapsedMs": 212,
      "webArguments": {
        "search": "What is the latest news about AI in education?",
        "language": "en",
        "market": "en-US",
        "count": 10,
        "freshness": "2026-03-01..2026-03-31"
      }
    },
    {
      "id": 2,
      "type": "modelWebSummarization",
      "elapsedMs": 87,
      "inputTokens": 1234,
      "outputTokens": 256
    }
  ]
}

Eliminare una fonte di conoscenza

Prima di poter eliminare una fonte di conoscenza, è necessario eliminare qualsiasi base di conoscenza che vi faccia riferimento o aggiornare la definizione della base di conoscenza per rimuovere il riferimento. Per le fonti di conoscenza che generano una pipeline 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 attualmente 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}");
}

    Reference:SearchIndexClient

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

    Reference:SearchIndexClient

    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 Knowledge Base o, se si dispone di più origini informazioni, aggiornare la Knowledge Base per rimuovere l'origine. Questo esempio mostra l'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.");

    Reference:SearchIndexClient

  4. Eliminare l'origine delle informazioni.

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

    Reference:SearchIndexClient

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

    # Get knowledge bases
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

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

print("Knowledge Bases:")
for kb in index_client.list_knowledge_bases():
    print(f"  - {kb.name}")

    Reference:SearchIndexClient

    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
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
kb = index_client.get_knowledge_base("knowledge_base_name")
print(kb)

    Reference:SearchIndexClient

    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, se si dispone di più origini informazioni, aggiornare la Knowledge Base per rimuovere l'origine. Questo esempio mostra l'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.")

    Reference:SearchIndexClient

  4. Eliminare l'origine delle 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.")

    Reference:SearchIndexClient

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

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

    Reference:Knowledge Bases - List

    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-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}

    Reference:Knowledge Bases - Get

    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, se si dispone di più origini informazioni, aggiornare la Knowledge Base per rimuovere l'origine. Questo esempio mostra l'eliminazione.

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

    Reference:Basi di conoscenza - Elimina

  4. Eliminare l'origine delle informazioni.

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

    Riferimento:Fonti di Conoscenza - Elimina

Contenuto correlato

  • Last updated on