建立一個 Work IQ 知識來源（預覽）

• 最新的 Azure.Search.Documents 預覽套件：dotnet add package Azure.Search.Documents --prerelease

• 對於無鑰匙認證，套件如下 Azure.Identity ： dotnet add package Azure.Identity

• 最新的 azure-search-documents 預覽套件：pip install --pre azure-search-documents

• 對於無鑰匙認證，套件如下 azure-identity ： pip install azure-identity

• 搜尋服務 REST API 的 2026-08-01 預覽 版。

• 對於無金鑰認證，請在Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。

// 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}");
}

參考資料：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})")

參考資料：SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

參考資料：知識來源列表

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

參考資料：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))

參考資料：SearchIndexClient

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

參考資料：知識來源 - 取得

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

Uri searchEndpoint =
    new("https://<search-service-name>.search.windows.net");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var entraAuthentication = new EntraAppAuthentication(
    Guid.Parse("<application-client-id>"),
    Guid.Parse("<federated-credential-id>"));
var knowledgeSource = new WorkIQKnowledgeSource(
    "my-workiq-ks",
    new WorkIQKnowledgeSourceParameters(entraAuthentication))
{
    Description = "A sample Work IQ knowledge source."
};

KnowledgeSource createdSource =
    await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Created knowledge source '{createdSource.Name}'.");

參考資料：SearchIndexClient，WorkIQKnowledgeSource

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    EntraAppAuthentication,
    WorkIQKnowledgeSource,
    WorkIQKnowledgeSourceParameters,
)

endpoint = "https://<search-service-name>.search.windows.net"
credential = DefaultAzureCredential()

knowledge_source = WorkIQKnowledgeSource(
    name="my-workiq-ks",
    description="A sample Work IQ knowledge source.",
    work_iq_parameters=WorkIQKnowledgeSourceParameters(
        entra_app_authentication=EntraAppAuthentication(
            application_id="<application-client-id>",
            federated_credential_id="<federated-credential-id>",
        )
    ),
)

with SearchIndexClient(endpoint, credential) as index_client:
    created_source = index_client.create_or_update_knowledge_source(
        knowledge_source
    )
print(f"Created knowledge source '{created_source.name}'.")

參考資料：SearchIndexClient，WorkIQKnowledgeSource

@search-endpoint = <search-endpoint> // Example: https://my-service.search.windows.net
@search-access-token = <search-access-token> // Run: az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv

### Create a Work IQ knowledge source
PUT {{search-endpoint}}/knowledgesources/my-workiq-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation

{
  "name": "my-workiq-ks",
  "kind": "workIQ",
  "description": "A sample Work IQ knowledge source.",
  "workIQParameters": {
    "entraAppAuthentication": {
      "applicationId": "<application-client-id>",
      "federatedCredentialId": "<federated-credential-id>"
    }
  }
}

參考資料：知識來源 - 建立或更新

using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

Uri searchEndpoint =
    new("https://<search-service-name>.search.windows.net");
string userAssertion = "<user-assertion>";
var credential = new DefaultAzureCredential();
var options = new SearchClientOptions();
options.Retry.NetworkTimeout = TimeSpan.FromSeconds(130);
var retrievalClient = new KnowledgeBaseRetrievalClient(
    searchEndpoint,
    "my-kb",
    credential,
    options);

var request = new KnowledgeBaseRetrievalRequest
{
    IncludeActivity = true,
    MaxRuntimeInSeconds = 120
};
request.Intents.Add(
    new KnowledgeRetrievalSemanticIntent("Find my project status."));
request.KnowledgeSourceParams.Add(
    new WorkIQKnowledgeSourceParams("my-workiq-ks")
    {
        IncludeReferences = true,
        IncludeReferenceSourceData = true
    });

var response = await retrievalClient.RetrieveAsync(
    request,
    querySourceAuthorization: null,
    queryWorkIQSourceAuthorization: userAssertion);
Console.WriteLine(response.Value);

參考資料：KnowledgeBaseRetrievalClient， KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalSemanticIntent,
    WorkIQKnowledgeSourceParams,
)

endpoint = "https://<search-service-name>.search.windows.net"
user_assertion = "<user-assertion>"
credential = DefaultAzureCredential()

request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search="Find my project status."
        )
    ],
    knowledge_source_params=[
        WorkIQKnowledgeSourceParams(
            knowledge_source_name="my-workiq-ks",
            include_references=True,
            include_reference_source_data=True,
        )
    ],
    include_activity=True,
    max_runtime_in_seconds=120,
)

with KnowledgeBaseRetrievalClient(
    endpoint,
    credential,
    knowledge_base_name="my-kb",
) as retrieval_client:
    response = retrieval_client.retrieve(
        request,
        query_work_iq_source_authorization=user_assertion,
        timeout=130,
    )

print(response)

參考資料：KnowledgeBaseRetrievalClient， KnowledgeBaseRetrievalRequest

@search-endpoint = <search-endpoint>
@search-access-token = <search-access-token>
@user-assertion = <user-assertion>

### Query a knowledge base with a Work IQ knowledge source
POST {{search-endpoint}}/knowledgebases/my-kb/retrieve?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
x-ms-query-work-iq-source-authorization: {{user-assertion}}
Content-Type: application/json

{
  "messages": [{
    "role": "user",
    "content": [{
      "type": "text",
      "text": "Find my project status."
    }]
  }],
  "knowledgeSourceParams": [{
    "knowledgeSourceName": "my-workiq-ks",
    "kind": "workIQ",
    "includeReferences": true,
    "includeReferenceSourceData": true
  }],
  "includeActivity": true,
  "maxRuntimeInSeconds": 120
}

參考資料：知識檢索 - 檢索

1. 取得你搜尋服務中所有知識庫的清單。

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

   參考資料：SearchIndexClient

   範例回應可能如下所示：

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. 取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

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

   參考資料：SearchIndexClient

   範例回應可能如下所示：

    {
      "Name": "earth-knowledge-base",
      "KnowledgeSources": [
        {
          "Name": "earth-knowledge-source"
        }
      ],
      "Models": [
        {}
      ],
      "RetrievalReasoningEffort": {},
      "OutputMode": {},
      "ETag": "\u00220x8DE278629D782B3\u0022",
      "EncryptionKey": null,
      "Description": null,
      "RetrievalInstructions": null,
      "AnswerInstructions": null
    }
   

3. 要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。 這個例子顯示刪除。

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

   參考資料：SearchIndexClient

4. 刪除知識來源。

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

   參考資料：SearchIndexClient

1. 取得你搜尋服務中所有知識庫的清單。

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

   參考資料：SearchIndexClient

   範例回應可能如下所示：

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. 取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

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

   參考資料：SearchIndexClient

   範例回應可能如下所示：

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

3. 要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。 這個例子顯示刪除。

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

   參考資料：SearchIndexClient

4. 刪除知識來源。

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

   參考資料：SearchIndexClient

1. 取得你搜尋服務中所有知識庫的清單。

   ### Get knowledge bases
   GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
   Authorization: Bearer {{token}}
   

   參考資料：知識庫列表

   範例回應可能如下所示：

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. 取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

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

   參考資料：知識庫 - 取得

   範例回應可能如下所示：

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

3. 要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。 這個例子顯示刪除。

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

   參考資料：知識庫 - 刪除

4. 刪除知識來源。

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

   參考資料：知識來源 - 刪除