Criar um recurso de Fonte de Conhecimento da Web

Nota

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Nota

Esse recurso de recuperação com agente está disponível de forma geral na API REST 2026-04-01 por acesso programático. O portal do Azure e o portal do Microsoft Foundry continuam fornecendo acesso apenas em versão prévia a todos os recursos de recuperação por agentes. Para obter diretrizes de migração, consulte Migrar o código de recuperação agêncico para a versão mais recente.

Se você optar por usar uma API REST de visualização, poderá acessar recursos que ainda não estão disponíveis para esse recurso. Os recursos de pré-visualização são fornecidos sem um contrato de nível de serviço e não são recomendados para trabalhos em ambientes de produção. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Importante

Esses recursos e funcionalidades fazem parte da API REST 2026-05-01-preview. O 2026-05-01-preview é licenciado para você como parte da sua assinatura do Azure e está sujeito aos termos aplicáveis a "Versões Prévias" nos Termos do Produto Microsoft, no Adendo de Proteção de Dados de Produtos e Serviços da Microsoft ("DPA") e nos Termos de Uso Suplementares para Versões Prévias do Microsoft Azure.

A versão prévia 2026-05-01 dá suporte a conexões com outros serviços de serviços Microsoft e de terceiros. O uso desses serviços está sujeito aos respectivos termos e pode resultar em processamento ou armazenamento de dados fora do limite de conformidade Azure, bem como dados que fluem para o limite de conformidade Azure.

É sua responsabilidade gerenciar se os seus dados serão transferidos para fora dos limites geográficos e de conformidade da sua organização, bem como quaisquer implicações relacionadas, e garantir que as permissões, os limites e as aprovações apropriados estejam devidamente estabelecidos.

Você é responsável por examinar e testar cuidadosamente os aplicativos que cria no contexto de seus casos de uso específicos e tomar todas as decisões e personalizações apropriadas. Isso inclui implementar suas próprias mitigações de IA responsáveis, como metaprompts, filtros de conteúdo ou outros sistemas de segurança, e garantir que seus aplicativos atendam aos padrões adequados de qualidade, confiabilidade, segurança e confiabilidade. Para obter mais informações, consulte a Pesquisa de IA do Azure  Nota de Transparência.

Importante

  • A Fonte de Conhecimento de Página da Web, que utiliza o Fundamentação com a Pesquisa do Bing e/ou Fundamentação com a Pesquisa Personalizada do Bing, é um Serviço de Consumo Interno regido pelos Termos de uso de fundamentação com o Bing e pela Declaração de Privacidade da Microsoft.

  • O Adendo de Proteção de Dados da Microsoft não se aplica aos dados enviados à Fonte de Conhecimento Web. Quando o cliente usa a Fonte de Conhecimento da Web, os Dados do Cliente fluem fora da conformidade Azure e do limite geográfico. Isso também significa que o uso da Fonte de Conhecimento da Web renuncia a todos os compromissos elevados de segurança e conformidade da Nuvem Comunitária Governamental, incluindo a soberania de dados e o suporte baseado em triagem e cidadania, conforme aplicável.

  • O uso da Fonte de Conhecimento da Web gera custos; saiba mais sobre preços.

  • Saiba mais sobre como os administradores do Azure podem gerenciar o acesso ao uso da Fonte de Conhecimento Web.

A Fonte de Conhecimento de Página da Web permite a recuperação de dados da web em tempo real do Microsoft Bing por meio de um pipeline de recuperação por meio de agentes. As fontes de conhecimento são criadas de forma independente, referenciadas em uma base de dados de conhecimento e usadas como dados de aterramento quando a base de dados de conhecimento é consultada em runtime.

A Pesquisa Personalizada do Bing é sempre o provedor de buscas para a Fonte de Conhecimento Web. Embora você não possa especificar provedores ou mecanismos de pesquisa alternativos, você pode incluir ou excluir domínios específicos, como https://learn.microsoft.com. Quando nenhum domínio é especificado, a Fonte de Conhecimento da Web tem acesso irrestrito a toda a Internet pública.

A Fonte de Conhecimento da Web funciona melhor junto com outras fontes de conhecimento. Use isso quando seu conteúdo proprietário não fornecer respostas completas e atualizadas ou quando você quiser complementar os resultados com informações de um mecanismo de pesquisa comercial.

Suporte ao uso

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

Pré-requisitos

  • Pacote necessário: Azure.Search.Documents

    • Para recursos de versão prévia de 01/05/2026, o pacote de versão prévia mais recente: dotnet add package Azure.Search.Documents --prerelease

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

  • Pacote necessário: azure-search-documents

    • Para recursos de versão prévia de 01/05/2026, o pacote de versão prévia mais recente: pip install --pre azure-search-documents

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

Limitações e considerações

  • O conteúdo da 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 literal da web.

  • Para a versão da API 2026-04-01, a base de conhecimento deve incluir uma referência de modelo para a criação de um LLM que resuma conteúdos da internet. Recuperação é sempre extrativa (resumos citados). A síntese de resposta 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-05-01-preview, a referência do modelo de base de dados de conhecimento também habilita a síntese de resposta, que produz uma única resposta formulada por LLM em vez de citações extraídas.

Verificar se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. Saber sobre fontes de conhecimento existentes é útil para reutilizar ou nomear novos objetos.

Execute o código a seguir para listar 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}");
}

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
Authorization: Bearer {{token}}

Reference:Knowledge Sources – List

Você também pode retornar uma única fonte de conhecimento por nome para revisar sua definição de 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}}
Authorization: Bearer {{token}}

Reference:Fontes de Conhecimento – Obter

O JSON a seguir é uma resposta de exemplo para um recurso de Fonte de Conhecimento da Web.

{
  "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 a seguir para criar uma fonte de conhecimento da 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=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 } ]
    }
  }
}

Reference:Knowledge Sources – Criar ou atualizar

Atribuir a uma base de dados de conhecimento

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

Consultar uma base de dados de conhecimento

Quando você consulta uma base de dados de conhecimento que inclui a Fonte de Conhecimento da Web, a matriz de resposta activity de recuperação pode conter dois registros relacionados à Web:

  • Um web registro que captura os parâmetros de runtime usados para a solicitação.
  • Um modelWebSummarization registro que captura o uso de token na 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
    }
  ]
}

Excluir uma fonte de conhecimento

Antes de excluir uma fonte de conhecimento, exclua qualquer base de dados de conhecimento que faça referência a ela ou atualize a definição da base de dados 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 excluídos . No entanto, se você usou um índice existente para criar uma fonte de conhecimento, seu índice não será excluído.

Se você tentar excluir uma fonte de conhecimento que está em uso, a ação falhará e retornará uma lista de bases de dados de conhecimento afetadas.

Para excluir uma fonte de conhecimento:

  1. Obtenha uma lista de todas as bases de dados de conhecimento em 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}");
}

    Reference:SearchIndexClient

    Uma resposta de exemplo pode ser semelhante à 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 de base de conhecimento individual 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);

    Reference:SearchIndexClient

    Uma resposta de exemplo pode ser semelhante à 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. Exclua a base de dados de conhecimento ou, se você tiver várias fontes de conhecimento, atualize a base de dados de conhecimento para remover a origem. Este exemplo mostra a exclusã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.");

    Reference:SearchIndexClient

  4. Exclua a fonte de conhecimento.

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

    Reference:SearchIndexClient

  1. Obtenha uma lista de todas as bases de dados de conhecimento em 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}")

    Reference:SearchIndexClient

    Uma resposta de exemplo pode ser semelhante à 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 de base de conhecimento individual 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)

    Reference:SearchIndexClient

    Uma resposta de exemplo pode ser semelhante à seguinte:

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

  3. Exclua a base de dados de conhecimento ou, se você tiver várias fontes de conhecimento, atualize a base de dados de conhecimento para remover a origem. Este exemplo mostra a exclusã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.")

    Reference:SearchIndexClient

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

    Reference:SearchIndexClient

  1. Obtenha uma lista de todas as bases de dados de conhecimento em 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 Dados de Conhecimento – Lista

    Uma resposta de exemplo pode ser semelhante à 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 de base de conhecimento individual 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 semelhante à seguinte:

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

  3. Exclua a base de dados de conhecimento ou, se você tiver várias fontes de conhecimento, atualize a base de dados de conhecimento para remover a origem. Este exemplo mostra a exclusão.

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

    Referência:Bases de Dados de Conhecimento – Excluir

  4. Exclua a fonte de conhecimento.

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

    Reference:Fontes de Conhecimento - Excluir

Conteúdo relacionado

  • Last updated on