Criar uma fonte de conhecimento do Fabric Data Agent (pré-visualização)

Note

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

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.

Quando se liga ao Fabric IQ, pode ter custos e os dados podem ser enviados para fora do limite de conformidade com o Azure e processados de acordo com os termos de serviço e políticas de gestão de dados aplicáveis. É 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.

Uma fonte de conhecimento Fabric Data Agent (pré-visualização) liga o seu Agente de Dados Microsoft Fabric a um pipeline de recuperação agentical em Pesquisa de IA do Azure. 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 agente de dados atua como analista virtual, gerando e executando consultas com os seus dados Microsoft Fabric para devolver respostas, tabelas e gráficos em linguagem natural. Isto torna úteis as fontes de conhecimento do Fabric Data Agent para dados com elevada taxa de renovação e consultas analíticas.

Ao contrário das fontes de conhecimento indexadas, as fontes de conhecimento do Fabric Data Agent consultam dados em tempo real diretamente no momento da recuperação. Não é necessário um pipeline de ingestão. As consultas requerem um token de acesso do utilizador final, que o motor de recuperação utiliza para consultar o Fabric Data Agent em nome do utilizador final.

Suporte de utilização

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

Pré-requisitos

  • Um serviço Pesquisa de IA do Azure em qualquer região que forneça recuperação proativa.

  • Um espaço de trabalho Microsoft Fabric com um agente data.

  • O seu serviço de pesquisa e espaço de trabalho devem estar no mesmo tenant do Microsoft Entra ID.

  • 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.

  • O pacote de pré-visualização mais recente Azure.Search.Documents: dotnet add package Azure.Search.Documents --prerelease
  • O pacote de pré-visualização mais recente azure-search-documents: pip install --pre azure-search-documents

Governação e conformidade de dados

O Fabric IQ processa pedidos dentro do limite de conformidade Microsoft Fabric para a região do seu espaço de trabalho. Os seguintes compromissos aplicam-se quando encaminha consultas de agentes através do Fabric IQ.

Residência dos dados

O Fabric IQ recupera e processa dados dentro da região onde se encontra o seu espaço de trabalho Microsoft Fabric. Os dados não atravessam fronteiras regionais durante a execução da consulta. A região aplicável e o seu âmbito de conformidade são determinados pela localização do seu espaço de trabalho. Para a lista de regiões suportadas e os quadros de conformidade que cada região satisfaz, veja Microsoft Fabric disponibilidade de região.

Note

Se o seu serviço Pesquisa de IA do Azure estiver numa região Azure diferente do seu espaço de trabalho Fabric, os resultados das consultas são devolvidos entre regiões. Consulte a disponibilidade regional do Microsoft Fabric e os requisitos de residência de dados da sua organização antes de estabelecer ligação a uma área de trabalho do Fabric noutra região.

Certificações de conformidade

A Fabric IQ herda as certificações de conformidade da Microsoft Fabric para a região do espaço de trabalho. Para documentação de conformidade, relatórios de auditoria e os quadros aplicáveis a cada região, consulte Microsoft Fabric disponibilidade regional.

Verifique se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. 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

Você também pode retornar uma única fonte de conhecimento pelo nome para revisar sua definição 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 uma fonte de conhecimento do Fabric Data Agent.

{
  "name": "my-fabric-data-agent-ks",
  "kind": "fabricDataAgent",
  "description": "A Fabric Data Agent knowledge source.",
  "encryptionKey": null,
  "fabricDataAgentParameters": {
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "dataAgentId": "00000000-0000-0000-0000-000000000001"
  }
}

Criar uma fonte de conhecimento

Execute o código seguinte para criar uma fonte de conhecimento do Fabric Data Agent.

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

Uri searchEndpoint = new Uri("<search-service-url>");
AzureKeyCredential credential = new AzureKeyCredential("<api-key>");
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var fabricDataAgent = new FabricDataAgentKnowledgeSource(
    "<knowledge-source-name>",
    new FabricDataAgentKnowledgeSourceParameters("<fabric-workspace-id>", "<fabric-data-agent-id>"))
{
    Description = "A Fabric Data Agent knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(fabricDataAgent);

Referência:SearchIndexClient

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    FabricDataAgentKnowledgeSource,
    FabricDataAgentKnowledgeSourceParameters,
)

index_client = SearchIndexClient(
    endpoint="<search-service-url>",
    credential=AzureKeyCredential("<api-key>")
)

knowledge_source = FabricDataAgentKnowledgeSource(
    name="<knowledge-source-name>",
    description="A Fabric Data Agent knowledge source.",
    fabric_data_agent_parameters=FabricDataAgentKnowledgeSourceParameters(
        workspace_id="<fabric-workspace-id>",
        data_agent_id="<fabric-data-agent-id>"
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)

Referência:SearchIndexClient

### Create a Fabric Data Agent knowledge source
PUT {{search-url}}/knowledgesources/my-fabric-data-agent-ks?api-version=2026-05-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "my-fabric-data-agent-ks",
  "kind": "fabricDataAgent",
  "description": "A Fabric Data Agent knowledge source.",
  "fabricDataAgentParameters": {
    "workspaceId": "{fabric-workspace-id}",
    "dataAgentId": "{fabric-data-agent-id}"
  }
}

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.

Importante

As fontes de conhecimento do Data Agent do Fabric não suportam o esforço de raciocínio de minimalrecuperação. Use low ou medium em vez disso.

Consultar uma base de conhecimento

Depois de configurada a base de conhecimento, chama a ação de recuperação ou o endpoint MCP para consultar o conteúdo do Fabric Data Agent. Esta fonte de conhecimento possui características únicas de aplicação de permissões em tempo de consulta e de resposta.

Aplicar permissões no momento da consulta

As fontes de conhecimento do Fabric Data Agent recorrem a um fluxo de token em nome de (OBO). Passa o token de acesso do utilizador final no x-ms-query-source-authorization cabeçalho do pedido de recuperação. O token tem de ter como âmbito a audiência do Pesquisa de IA do Azure (https://search.azure.com/.default). O motor de recuperação troca este token por um token com âmbito Microsoft Fabric e usa-o para consultar o Fabric Data Agent em nome do utilizador final.

A autenticação padrão do Pesquisa de IA do Azure também é exigida no pedido de recuperação. O x-ms-query-source-authorization token é passado separadamente e não substitui a autenticação do serviço.

Para instruções sobre como passar o token, consulte Impor permissões no momento da consulta (pré-visualização).

Campos de resposta específicos do Fabric Data Agent

As fontes de conhecimento do Data Agent no Fabric devolvem resultados no objeto sourceData de cada entrada references e os diagnósticos da consulta na matriz activity. sourceData contém:

  • fabricAnswer: A resposta em linguagem natural do agente de dados.
  • fabricEmbeddedResources: Quaisquer recursos incorporados, como tabelas e gráficos, quando a consulta produz uma saída estruturada.

O exemplo seguinte mostra uma resposta de recuperação contendo uma referência de fonte de conhecimento do Fabric Data Agent e o respetivo registo de atividade. Para orientações mais amplas sobre a interpretação das respostas de recuperação, consulte Rever a resposta.

Dica

Para receber referências de sourceData, defina includeReferenceSourceData como true na entrada da fonte de conhecimento em knowledgeSourceParams no pedido de recuperação.

{
  "response": [
      // ... Response omitted for brevity
  ],
  "activity": [
    {
      "type": "fabricDataAgent",
      "id": 1,
      "knowledgeSourceName": "my-fabric-data-agent-ks",
      "queryTime": "2026-05-11T19:37:11.600Z",
      "count": 1,
      "fabricDataAgentArguments": {
        "search": "my query"
      }
    },
    {
      // ... Additional activity records omitted for brevity 
    }
  ],
  "references": [
    {
      "type": "fabricDataAgent",
      "id": "0",
      "activitySource": 1,
      "rerankerScore": 2.57,
      "workspaceId": "00000000-0000-0000-0000-000000000000",
      "dataAgentId": "00000000-0000-0000-0000-000000000001",
      "sourceData": {
        "fabricAnswer": "There were 47 airline delays in Q1 2026. The majority occurred on transcontinental routes.",
        "fabricEmbeddedResources": [
          {
            "title": "Q1 2026 Airline Operations Report",
            "mimeType": "text/csv",
            "content": "Route | Delays | Avg. Delay (min)\n--- | --- | ---\nJFK–LAX | 18 | 42\nORD–MIA | 12 | 31"
          }
        ]
      }
    },
    {
      // ... Additional references omitted for brevity 
    }
  ]
}

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

    Um exemplo de resposta pode ter a seguinte aparência:

     {
     "@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

    Um exemplo de resposta pode ter a seguinte aparência:

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

    Referência:SearchIndexClient

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

    Um exemplo de resposta pode ter a seguinte aparência:

     {
     "@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

    Um exemplo de resposta pode ter a seguinte aparência:

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

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

    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

    Um exemplo de resposta pode ter a seguinte aparência:

     {
     "@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

    Um exemplo de resposta pode ter a seguinte aparência:

     {
   "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 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 Conhecimento - Eliminar

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

  • Last updated on