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.

Nota

Esta funcionalidade de recuperação agêntica está geralmente disponível na API REST 2026-04-01 através de acesso programático. Os portais Azure e Microsoft Foundry continuam a fornecer acesso exclusivamente em pré-visualização a todas as funcionalidades de recuperação de dados através de agentes. Para orientações sobre migração, consulte Migrar código de recuperação agential para a versão mais recente.

Se optar por usar uma API REST de pré-visualização, pode aceder a funcionalidades que ainda não estão geralmente disponíveis para esta funcionalidade. As funcionalidades de pré-visualização são fornecidas sem um acordo de nível de serviço, não sendo recomendadas para cargas de trabalho de produção. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.

Importante

Estas funcionalidades fazem parte da API REST preview de 2026-05-01-. A 2026-05-01-preview é-lhe licenciada como parte da sua subscrição do Azure e está sujeita aos termos aplicáveis a "Previews" nos Termos dos Produtos Microsoft, na Adenda sobre a Proteção de Dados dos Produtos e Serviços Microsoft ("DPA") e nos Termos de Utilização Suplementares para as Pré-visualizações do Microsoft Azure.

A pré-visualização 2026-05-01 suporta ligações a outros serviços da Microsoft e serviços de terceiros. A utilização destes serviços está sujeita aos respetivos termos e pode resultar no processamento ou armazenamento de dados fora do limite de conformidade do Azure, bem como no fluxo de dados para o limite de conformidade do Azure.

É sua responsabilidade gerir se os seus dados irão fluir para além dos limites de conformidade e geográficos da sua organização e quaisquer implicações relacionadas, e garantir que as permissões, limites e aprovações apropriadas sejam providenciadas.

És responsável por rever e testar cuidadosamente as aplicações que constróis no contexto dos teus casos de uso específicos e por tomar todas as decisões e personalizações apropriadas. Isto inclui implementar as suas próprias mitigações de IA responsável, como metaprompts, filtros de conteúdo ou outros sistemas de segurança, e assegurar que as suas aplicações cumprem os padrões adequados de qualidade, fiabilidade, segurança e confiabilidade. Para mais informações, consulte a Nota de Transparência Pesquisa de IA do Azure.

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ões para criar fontes de conhecimento. Configure a autenticação sem chave com o papel de Contribuidor de Serviço de Pesquisa atribuído à sua conta de utilizador (recomendado) ou use uma chave API.

  • Pacote obrigatório Azure.Search.Documents:

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

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

  • Pacote obrigatório azure-search-documents:

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

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

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 de pré-visualização da API de 2026-05-01, a referência do modelo da base de conhecimento também permite a síntese de respostas, 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
api-key: {{api-key}}

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}}
api-key: {{api-key}}

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;

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

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

Referência:SearchIndexClient

### Create Web Knowledge Source
PUT {{search-url}}/knowledgesources/my-web-ks?api-version=2026-05-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 } ]
    }
  }
}

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
api-key: {{api-key}}

    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}}
api-key: {{api-key}}

    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}}
api-key: {{api-key}}

    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}}
api-key: {{api-key}}

    Referência:Fontes de Conhecimento - Eliminar

Conteúdo relacionado

  • Last updated on