Criar uma fonte de conhecimento do Agente de Dados Fabric (versão prévia)

Note

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.

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.

Ao se conectar ao Fabric IQ, você pode incorrer em custos e os dados podem ser enviados fora do limite de conformidade Azure e processados de acordo com os termos de serviço aplicáveis e as políticas de tratamento de dados. É 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.

Uma fonte de conhecimento do Agente de Dados do Fabric (versão prévia) conecta seu Agente de Dados do Microsoft Fabric a um pipeline de recuperação por meio de agentes na Pesquisa de IA do Azure. 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.

O agente de dados atua como um analista virtual, gerando e executando consultas em seus dados Microsoft Fabric para retornar respostas, tabelas e gráficos de linguagem natural. Isso torna as fontes de conhecimento do Agente de Dados do Fabric úteis para dados com alta taxa de alteração e consultas analíticas.

Ao contrário das fontes de conhecimento indexadas, as fontes de conhecimento do Agente de Dados do Fabric consultam dados em tempo real diretamente durante a recuperação. Não é necessário nenhum pipeline de ingestão. As consultas exigem um token de acesso do usuário final, que o mecanismo de recuperação usa para consultar o agente de dados Fabric em nome do usuário final.

Suporte de uso

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

Pré-requisitos

Um serviço de Pesquisa de IA do Azure em qualquer região que forneça recuperação agêntica.
Um workspace do Microsoft Fabric com um agente de dados.
Seu serviço de pesquisa e espaço de trabalho devem estar no mesmo locatário do Microsoft Entra ID.
Permissões para criar fontes de conhecimento. Configure a autenticação sem chave com a função Colaborador do Serviço de Pesquisa atribuída à sua conta de usuário (recomendado) ou use uma chave de API.

O pacote de versão prévia Azure.Search.Documents mais recente: dotnet add package Azure.Search.Documents --prerelease

O pacote de versão prévia azure-search-documents mais recente: pip install --pre azure-search-documents

A versão 2026-05-01-preview das APIs REST do Serviço de Pesquisa.

Governança e conformidade de dados

O Fabric IQ processa solicitações dentro do limite de conformidade do Microsoft Fabric na região do seu workspace. Os compromissos a seguir se aplicam quando você roteia consultas de agentes por meio do Fabric IQ.

Residência de dadosResidência de dados

Fabric IQ recupera e processa dados na região em que reside o workspace Microsoft Fabric. Os dados não ultrapassam os limites regionais durante a execução da consulta. A região aplicável e seu escopo de conformidade são determinados pelo local do workspace. Para obter a lista de regiões com suporte e as estruturas de conformidade que cada região satisfaz, consulte Microsoft Fabric disponibilidade da região.

Note

Se o serviço Pesquisa de IA do Azure estiver em uma região de Azure diferente do workspace Fabric, os resultados da consulta serão retornados entre regiões. Verifique a disponibilidade de região do Microsoft Fabric e os requisitos de residência de dados da sua organização antes de conectar um workspace do Fabric em outra região.

Certificações de conformidade

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

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

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

Reference:Fontes de Conhecimento – Obter

O JSON a seguir é uma resposta de exemplo para uma fonte de conhecimento 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 a seguir para criar uma fonte de conhecimento do agente de dados Fabric.

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

Reference: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)

Reference: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}"
  }
}

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.

Importante

As fontes de conhecimento do Agente de Dados do Fabric não oferecem suporte ao esforço de raciocínio de minimalrecuperação. Em vez disso, use low ou medium.

Consultar uma base de dados de conhecimento

Depois que a base de conhecimento estiver configurada, chame a ação de recuperação ou o ponto de extremidade MCP para consultar o conteúdo do Agente de Dados do Fabric. Esta fonte de conhecimento tem características exclusivas 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 Agente de Dados no Fabric usam um fluxo de token OBO (em nome de). Você passa o token de acesso do usuário final no x-ms-query-source-authorization cabeçalho na solicitação de recuperação. O token deve ter como escopo o público do Pesquisa de IA do Azure (https://search.azure.com/.default). O mecanismo de recuperação troca esse token por um token com escopo de Microsoft Fabric e o usa para consultar o agente de dados Fabric em nome do usuário final.

A autenticação de Pesquisa de IA do Azure padrão também é necessária na solicitação de recuperação. O x-ms-query-source-authorization token é passado separadamente e não substitui a autenticação de serviço.

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

Campos de resposta específicos do Agente de Dados do Fabric

As fontes de conhecimento do Agente de Dados do Fabric retornam resultados no objeto sourceData de cada entrada references e os diagnósticos de consulta na matriz activity. sourceData Contém:

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

O exemplo a seguir mostra uma resposta de recuperação de dados que contém uma referência a uma fonte de conhecimento do Fabric Data Agent e o respectivo registro de atividade. Para obter orientações mais amplas sobre como interpretar respostas de recuperação, consulte Examinar a resposta.

Dica

Para receber sourceData para referências, defina includeReferenceSourceData como true na entrada da fonte de conhecimento em knowledgeSourceParams na solicitação 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 
    }
  ]
}

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:

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

Obtenha uma definição individual de 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);

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
 }

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

Exclua a fonte de conhecimento.

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

Reference:SearchIndexClient

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

Obtenha uma definição individual de 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)

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

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

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

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

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

Obtenha uma definição individual de 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 semelhante à seguinte:

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

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}}
api-key: {{api-key}}
```
Referência:Bases de Dados de Conhecimento – Excluir

Exclua a fonte de conhecimento.

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

Reference:Fontes de Conhecimento - Excluir

Comentários

Esta página foi útil?

Last updated on 2026-06-29

Criar uma fonte de conhecimento do Agente de Dados Fabric (versão prévia)

Suporte de uso

Pré-requisitos

Governança e conformidade de dados

Residência de dadosResidência de dados

Certificações de conformidade

Verificar se há fontes de conhecimento existentes

Criar uma fonte de conhecimento

Atribuir a uma base de dados de conhecimento

Consultar uma base de dados de conhecimento

Aplicar permissões no momento da consulta

Campos de resposta específicos do Agente de Dados do Fabric

Excluir uma fonte de conhecimento

Conteúdo relacionado

Comentários

Recursos adicionais