Criar um recurso de Fonte de Conhecimento Web

Nota

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Importante

Funcionalidades, capacidades ou propriedades assinaladas (pré-visualização) não são abrangidas por um acordo de nível de serviço, não são recomendadas para cargas de trabalho em produção e podem mudar ou ser limitadas antes de se tornarem geralmente disponíveis. Os termos de pré-visualização do Pesquisa de IA do Azure aplicam-se a todas as funcionalidades de pré-visualização, sejam independentes ou parte de uma funcionalidade geralmente disponível.

Importante

  • Web Knowledge Source, que utiliza Grounding com Bing Search e/ou Grounding com Bing Custom Search, é um Serviço de Consumo First Party regulado pelo Grounding com termos de uso do Bing e pela Declaração de Privacidade Microsoft.

  • O Adendo Microsoft Proteção de Dados não se aplica aos dados enviados para a Web Knowledge Source. Quando o Cliente utiliza o Web Knowledge Source, os Dados do Cliente fluem fora dos limites de conformidade com o Azure e Geo. Isto também significa que a utilização do Web Knowledge Source dispensa todos os compromissos elevados de segurança e conformidade da Comunidade Governamental na Cloud, incluindo soberania de dados e apoio baseado em triagem/cidadania, conforme aplicável.

  • A utilização da Web Knowledge Source implica custos; Saiba mais sobre preços.

  • Saiba mais sobre como os administradores Azure podem gerir acesso ao uso do Web Knowledge Source.

Web Knowledge Source permite a recuperação de dados web em tempo real de Microsoft Bing num pipeline de recuperação agentiva. As fontes de conhecimento são criadas de forma independente, referenciadas numa base de conhecimento e usadas como dados de base quando a base é consultada em tempo de execução.

O Bing Custom Search é sempre o fornecedor de pesquisa para a Web Knowledge Source. Embora não possa especificar fornecedores ou motores de busca alternativos, pode incluir ou excluir domínios específicos, como https://learn.microsoft.com. Quando não são especificados domínios, o Web Knowledge Source tem acesso irrestrito a toda a internet pública.

O Web Knowledge Source funciona melhor em conjunto com outras fontes de conhecimento. Utilize-o quando o seu conteúdo proprietário não fornecer respostas completas e atualizadas ou quando quiser complementar os resultados com informações de um motor de pesquisa comercial.

Suporte de utilização

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

Pré-requisitos

  • Uma subscrição Azure com acesso ao Web Knowledge Source. Por padrão, o acesso está ativado. Contacta o teu administrador se o acesso estiver desativado.

  • Um serviço de pesquisa da Azure AI em qualquer região pública que forneça recuperação agente. O Web Knowledge Source não é suportado em clouds privadas ou soberanas.

  • Permissão para criar fontes de conhecimento. Configure a autenticação sem chave com o papel de Contribuidor do Serviço de Pesquisa atribuído à sua conta de utilizador (recomendado) ou utilize uma chave API de administrador.

  • Pacote obrigatório Azure.Search.Documents:

    • Para obter as funcionalidades de 2026-08-01-preview, o pacote de pré-visualização mais recente: dotnet add package Azure.Search.Documents --prerelease

    • Para as funcionalidades 2026-04-01, o pacote estável mais recente: dotnet add package Azure.Search.Documents

  • Para autenticação sem chave, o Azure.Identity pacote: dotnet add package Azure.Identity

  • Pacote obrigatório azure-search-documents:

    • Para obter as funcionalidades de 2026-08-01-preview, o pacote de pré-visualização mais recente: pip install --pre azure-search-documents

    • Para as funcionalidades 2026-04-01, o pacote estável mais recente: pip install azure-search-documents

  • Para autenticação sem chave, o azure-identity pacote: pip install azure-identity

  • Versão obrigatória da API REST do Serviço de Pesquisa:

  • Para autenticação sem chave, inclua um token Microsoft Entra ID no Authorization cabeçalho de cada pedido HTTP.

Limitações e considerações

  • O conteúdo web é sempre resumido por um LLM antes de ser incluído nos resultados de recuperação. Os resultados são resumos citados, não texto web literal.

  • Para a versão da API de 01-04-2026, a base de conhecimento deve incluir uma referência de modelo para disponibilizar o LLM para a sumarização de conteúdo web. A recuperação é sempre extrativa (resumos citados). A síntese de respostas e o esforço de raciocínio configurável não estão disponíveis nesta versão.

  • Para a versão da API 2026-08-01-preview, a referência de modelo da base de conhecimento também permite síntese de respostas (versão preliminar), que produz uma única resposta formulada pelo LLM em vez de citações extraídas.

Verifique fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto de topo e reutilizável. Conhecer as fontes de conhecimento existentes é útil tanto para reutilizar como para nomear novos objetos.

Execute o seguinte código para listar as fontes de conhecimento por nome e 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}");
}

Referência: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})")

Referência:SearchIndexClient

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

Referência:Fontes de Conhecimento - Lista

Também pode devolver uma única fonte de conhecimento pelo nome para rever a sua definição em 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));

Referência: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))

Referência:SearchIndexClient

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

Referência:Fontes de Conhecimento - Obter

O JSON seguinte é uma resposta de exemplo para um recurso Web Knowledge Source.

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

Criar uma fonte de conhecimento

Execute o código seguinte para criar uma fonte de conhecimento web.

// Create Web Knowledge Source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Identity;

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

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

Referência:SearchIndexClient, WebKnowledgeSource

# Create Web Knowledge Source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import WebKnowledgeSource, WebKnowledgeSourceParameters, WebKnowledgeSourceDomains, WebKnowledgeSourceDomain

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

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

Referência:SearchIndexClient

### Create Web Knowledge Source
PUT {{search-endpoint}}/knowledgesources/my-web-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

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

Referência:Fontes de Conhecimento - Criar ou Atualizar

Atribuir a uma base de conhecimento

Se estiver satisfeito com a fonte de conhecimento, adicione-a a uma base de conhecimento.

Consultar uma base de conhecimento

Quando consulta uma base de conhecimento que inclui a Fonte de Conhecimento da Web, o array de resposta de consulta activity pode conter dois registos relacionados com a web:

  • Um web registro que captura os parâmetros de execução usados para o pedido.
  • Um registo que capta a utilização do modelWebSummarization token para a etapa de sumarização do 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
    }
  ]
}

Eliminar uma fonte de conhecimento

Antes de poder eliminar uma fonte de conhecimento, deve eliminar qualquer base de conhecimento que a faça referência ou atualizar a definição da base de conhecimento para remover a referência. Para fontes de conhecimento que geram um pipeline de índice e indexador, todos os objetos gerados também são eliminados. No entanto, se usou um índice existente para criar uma fonte de conhecimento, o seu índice não é eliminado.

Se tentar eliminar uma fonte de conhecimento que está em uso, a ação falha e devolve uma lista das bases de conhecimento afetadas.

Para eliminar uma fonte de conhecimento:

  1. Obtenha uma lista de todas as bases de conhecimento do seu serviço de pesquisa.

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

    Referência:SearchIndexClient

    Uma resposta de exemplo pode ser a seguinte:

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

  2. Obtenha uma definição individual da base de conhecimento para verificar referências de fontes de conhecimento.

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

    Referência:SearchIndexClient

    Uma resposta de exemplo pode ser a seguinte:

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

  3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. Este exemplo mostra eliminação.

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

    Referência:SearchIndexClient

  4. Apaga a fonte de conhecimento.

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

    Referência:SearchIndexClient

  1. Obtenha uma lista de todas as bases de conhecimento do seu serviço de pesquisa.

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

    Referência:SearchIndexClient

    Uma resposta de exemplo pode ser a seguinte:

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

  2. Obtenha uma definição individual da base de conhecimento para verificar referências de fontes de conhecimento.

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

    Referência:SearchIndexClient

    Uma resposta de exemplo pode ser a seguinte:

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

  3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. Este exemplo mostra eliminação.

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

    Referência:SearchIndexClient

  4. Apaga a fonte de conhecimento.

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

    Referência:SearchIndexClient

  1. Obtenha uma lista de todas as bases de conhecimento do seu serviço de pesquisa.

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

    Referência:Bases de Conhecimento - Lista

    Uma resposta de exemplo pode ser a seguinte:

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

  2. Obtenha uma definição individual da base de conhecimento para verificar referências de fontes de conhecimento.

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

    Referência:Bases de Conhecimento - Obter

    Uma resposta de exemplo pode ser a seguinte:

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

  3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. Este exemplo mostra eliminação.

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

    Referência:Bases de Conhecimento - Eliminar

  4. Apaga a fonte de conhecimento.

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

    Referência:Fontes de Conhecimento - Eliminar

Conteúdo relacionado

  • Última atualização a