Criar uma fonte de conhecimento do Work IQ (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 Work IQ, você pode gerar custos, e os dados podem ser enviados para fora do limite de conformidade do 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 Work IQ (versão prévia) conecta o Work IQ 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 Work IQ revela a inteligência organizacional a partir do seu conteúdo no Microsoft 365, incluindo documentos, e-mails, reuniões e atividades nos aplicativos do Microsoft 365.

Ao contrário das fontes de conhecimento indexadas, as fontes de conhecimento do Work IQ consultam dados dinâmicos diretamente no momento da 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 chamar o Work IQ em nome do chamador.

Warning

Nesta prévia, uma fonte de conhecimento do Work IQ pode usar capacidades do Work IQ que executam ações, não apenas recuperam informações. Use-o com cuidado, limite o acesso a aplicativos e usuários confiáveis e examine as permissões e controles de governança do seu cenário antes de habilitá-lo.

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.

  • Cada usuário final que consulta essa fonte de conhecimento deve ter uma licença Microsoft 365 Copilot.

  • O serviço Pesquisa de IA do Azure , o ambiente Work IQ e os usuários finais devem estar no mesmo locatário do Microsoft Entra. Não há suporte para recuperação entre locatários.

  • Acesso aprovado à recuperação do Work IQ por meio do Pesquisa de IA do Azure . Para obter mais informações, consulte Solicitar acesso à recuperação do Work IQ.

  • 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

Solicitar acesso à recuperação de dados do Work IQ

A recuperação do Work IQ por meio do Pesquisa de IA do Azure  fica desativada por padrão e requer uma solicitação aprovada pela Microsoft antes de poder ser usada.

Para solicitar acesso:

  1. Registre o sinalizador de recurso EnableFoundryIQWithWorkIQ em sua assinatura de Azure.

    az feature register --namespace Microsoft.Search --name EnableFoundryIQWithWorkIQ --subscription "<your-subscription-guid>"

  2. Registre novamente o provedor de recursos Microsoft.Search.

    az provider register -n Microsoft.Search --subscription "<your-subscription-guid>"

  3. Faça com que um administrador de Microsoft Entra para seu locatário envie o formulário de solicitação de acesso Work IQ.

  4. Aguarde Microsoft habilitar o acesso após a revisão e aprovação da solicitação.

    Dica

    Para registrar uma funcionalidade em versão prévia, é necessária a função interna Owner ou Contributor na assinatura, que é diferente da função do administrador do Microsoft Entra que envia o formulário. As duas responsabilidades podem ser mantidas por pessoas diferentes em sua organização. Para obter mais informações sobre o mecanismo de registro, consulte Configurar recursos de visualização na assinatura do Azure.

Governança e conformidade de dados

O Work IQ funciona inteiramente dentro do limite de confiança do Microsoft 365. Os compromissos a seguir se aplicam quando você encaminha as solicitações dos agentes por meio do Work IQ.

Residência de dadosResidência de dados

O Work IQ obtém dados do locatário do Microsoft 365 da sua organização. Os dados não deixam o locatário nem atravessam fronteiras regionais durante a recuperação. A localização dos dados segue sua configuração de residência de dados de locatário Microsoft 365, não sua região de serviço Pesquisa de IA do Azure . Para obter detalhes, consulte Data, Privacidade e Segurança para Microsoft 365 Copilot.

Privacidade e manipulação de dados

Todas as solicitações do Work IQ são regidas pelas diretrizes de Dados, Privacidade e Segurança para o Microsoft 365 Copilot. Principais compromissos:

  • O Work IQ não usa o conteúdo do cliente para treinar nem melhorar os modelos de IA de base.

Controle de acesso e permissões

O Work IQ aplica automaticamente as permissões do Microsoft 365 a cada solicitação. Os agentes só podem acessar dados que o usuário conectado já está autorizado a ver. Nenhuma elevação de privilégio é possível.

  • O controle de acesso baseado em função, os rótulos de confidencialidade e as barreiras de informações definidas em Microsoft 365 são respeitadas.

Certificações de conformidade

O Work IQ herda as certificações de conformidade do Microsoft 365. Para obter detalhes, consulte Data, Privacidade e Segurança para Microsoft 365 Copilot.

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 do Work IQ.

{
  "name": "my-workiq-ks",
  "kind": "workIQ",
  "description": "A sample Work IQ knowledge source.",
  "encryptionKey": null
}

Criar uma fonte de conhecimento

Execute o código a seguir para criar uma fonte de conhecimento do Work IQ.

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 knowledgeSource = new WorkIQKnowledgeSource(name: "my-workiq-ks")
{
    Description = "A sample Work IQ knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Reference:SearchIndexClient

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import WorkIQKnowledgeSource

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

knowledge_source = WorkIQKnowledgeSource(
    name="my-workiq-ks",
    description="A sample Work IQ knowledge source."
)

index_client.create_or_update_knowledge_source(knowledge_source=knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Reference:SearchIndexClient

### Create a Work IQ knowledge source
PUT {{search-url}}/knowledgesources/my-workiq-ks?api-version=2026-05-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "my-workiq-ks",
  "kind": "workIQ",
  "description": "A sample Work IQ knowledge source."
}

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

Depois que a base de conhecimento estiver configurada, chame a ação de recuperação ou o endpoint MCP para consultar o conteúdo do Work IQ. Esta fonte de conhecimento tem características exclusivas de aplicação de permissões em tempo de consulta e de resposta.

Importante

O Work IQ pode levar de 40 a 60 segundos, ou mais, para responder. Para evitar erros de tempo limite, defina maxRuntimeInSeconds na solicitação de recuperação como 120 ou superior.

Aplicar permissões no momento da consulta

As fontes de conhecimento do Work IQ 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 do Work IQ e o usa para consultar o Work IQ 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 Work IQ

As fontes de conhecimento do Work IQ retornam resultados na matriz references, e diagnósticos da consulta na matriz activity. Cada entrada de referência contém:

  • sourceData.extracts[].text: passagens de texto baseadas no Work IQ.
  • attributions[].seeMoreWebUrl: um link para o documento de origem no Microsoft 365.

O exemplo a seguir mostra uma resposta da operação de recuperação que contém uma referência a uma fonte de conhecimento do Work IQ e o registro de atividade correspondente. 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": "workIQ",
      "id": 0,
      "knowledgeSourceName": "my-workiq-ks",
      "queryTime": "2026-05-01T19:25:23.683Z",
      "count": 1,
      "elapsedMs": 1137,
      "workIQArguments": {
        "search": "my query"
      }
    },
    {
       // ... Additional activity records omitted for brevity       
    }
  ],
  "references": [
    {
      "type": "workIQ",
      "id": "83dd7d40",
      "activitySource": 0,
      "rerankerScore": 3.5,
      "attributions": [
        {
          "seeMoreWebUrl": "https://..."
        }
      ],
      "sourceData": {
        "extracts": [
          {
            "text": "Have your VPN username and password ready."
          }
        ]
      }
    },
    {
      // ... 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:

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

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

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

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

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

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

    Reference:Fontes de Conhecimento - Excluir

Conteúdo relacionado

  • Last updated on