웹 지식 원본 리소스 만들기

참고

Azure AI 검색 Azure 포털, REST API 및 Azure SDK 통해 사용할 수 있습니다. 또한 엔터프라이즈 콘텐츠를 Microsoft Foundry 포털의 에이전트에 대해 재사용 가능한 사용 권한 인식 기술 자료로 변환하는 관리되는 기술 계층인 Foundry IQ를 뒷받침합니다.

참고

이 에이전트 검색 기능은 프로그래밍 방식 액세스를 통해 2026-04-01 REST API에서 일반적으로 사용할 수 있습니다. Azure 포털 및 Microsoft Foundry 포털은 모든 에이전트 검색 기능에 대한 미리 보기 전용 액세스를 계속 제공합니다. 마이그레이션 지침은 에이전트 검색 코드를 최신 버전으로 마이그레이션을 참조하세요.

미리 보기 REST API를 사용하도록 선택하는 경우 이 기능에 대해 아직 일반 공급되지 않는 기능에 액세스할 수 있습니다. 미리 보기 기능은 서비스 수준 계약 없이 제공되며 프로덕션 워크로드에는 권장되지 않습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

중요

이러한 기능과 기능은 2026-05-01-preview REST API의 일부입니다. 2026-05-01-preview는 Azure 구독의 일부로 사용자에게 라이선스가 부여되며, Microsoft Product Terms의 "미리 보기"에 적용되는 약관, Microsoft 제품 및 서비스 데이터 보호 부록("DPA") 및 Microsoft Azure 미리 보기용 추가 사용 약관의 적용을 받습니다.

2026-05-01-preview는 다른 Microsoft 서비스 및 타사 서비스에 대한 연결을 지원합니다. 이러한 서비스의 사용은 해당 약관의 적용을 받으며 Azure 규정 준수 경계 외부의 데이터 처리 또는 스토리지뿐만 아니라 Azure 규정 준수 경계로 데이터가 유입될 수 있습니다.

데이터가 조직의 규정 준수 및 지리적 경계와 관련된 의미를 벗어나는지 여부와 적절한 권한, 경계 및 승인이 프로비전되는지를 관리하는 것은 사용자의 책임입니다.

특정 사용 사례의 컨텍스트에서 빌드한 애플리케이션을 신중하게 검토하고 테스트하고 모든 적절한 결정 및 사용자 지정을 수행할 책임이 있습니다. 여기에는 메타프롬프트, 콘텐츠 필터 또는 기타 안전 시스템과 같은 책임 있는 AI 완화를 구현하고 애플리케이션이 적절한 품질, 안정성, 보안 및 신뢰성 표준을 충족하도록 보장하는 것이 포함됩니다. 자세한 내용은 Azure AI 검색 투명성 정보를 참고하세요.

중요

웹 지식 소스는 Bing 검색 및/또는 Bing 맞춤 검색을 사용하여 근거를 제공하는 1차 소비 서비스로서 Bing 사용 약관 및 Microsoft 개인정보처리방침에 의해 규제됩니다.
Microsoft 데이터 보호 부록 웹 지식 원본으로 전송된 데이터에는 적용되지 않습니다. 고객이 웹 지식 원본을 사용하는 경우 고객 데이터는 Azure 규정 준수 및 지리적 경계 외부로 흐릅니다. 웹 지식 소스를 사용하게 되면, 해당되는 경우, 데이터 주권 및 시민권 검증 기반 지원을 포함한 모든 강화된 정부 커뮤니티 클라우드 보안 및 준수 약속이 면제됩니다.
웹 지식 원본을 사용하면 비용이 발생합니다. 가격 책정에 대해 자세히 알아봅니다.
Azure 관리자가 웹 지식 원본 사용하기 위해 액세스를 관리하는 방법에 대해 자세히 알아봅니다.

Web Knowledge Source를 사용하면 에이전트 검색 파이프라인의 Microsoft Bing 실시간 웹 데이터를 검색할 수 있습니다. 기술 원본은 독립적으로 생성되고, 기술 자료에서 참조되며, 런타임에 기술 자료를 쿼리할 때 접지 데이터로 사용됩니다.

Bing Custom Search는 항상 웹 지식 원본의 검색 공급자입니다. 대체 검색 공급자 또는 엔진을 지정할 수는 없지만 , 같은 특정 https://learn.microsoft.com 포함하거나 제외할 수 있습니다. 도메인이 지정되지 않은 경우 웹 지식 원본은 전체 공용 인터넷에 무제한으로 액세스할 수 있습니다.

웹 지식 원본은 다른 지식 원본과 함께 가장 잘 작동합니다. 독점 콘텐츠가 완전한 up-to-date 답변을 제공하지 않거나 상업용 검색 엔진의 정보로 결과를 보완하려는 경우 사용합니다.

사용량 지원

Azure 포털	Microsoft Foundry 포털	.NET SDK	Python SDK	Java SDK	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

필수 구성 요소

웹 지식 원본에 대한 액세스가 있는 Azure 구독입니다. 기본적으로 액세스는 사용하도록 설정됩니다. 액세스가 비활성화된 경우 관리자에게 문의하세요.
어떤 공개 리전에서도 사용할 수 있으며, 에이전트형 검색을 제공하는 Azure AI 검색 Service를 의미합니다. 웹 지식 원본은 프라이빗 또는 소버린 클라우드에서 지원되지 않습니다.
지식 소스를 생성할 수 있는 권한 사용자 계정에 할당된 Search Service 기여자 역할을 사용하여 키 없는 인증을 구성하거나 API 키를 사용합니다.

필수 Azure.Search.Documents 패키지:
- 2026-05-01-preview 기능의 경우 최신 미리 보기 패키지: dotnet add package Azure.Search.Documents --prerelease
- 2026-04-01 기능의 경우 안정적인 최신 패키지: dotnet add package Azure.Search.Documents

필수 azure-search-documents 패키지:
- 2026-05-01-preview 기능의 경우 최신 미리 보기 패키지: pip install --pre azure-search-documents
- 2026-04-01 기능의 경우 안정적인 최신 패키지: pip install azure-search-documents

필수 REST API 버전:
- 미리 보기 기능: Search Service 2026-05-01-preview
- 일반 출시 기능: Search Service 2026-04-01

제한 사항 및 고려 사항

웹 콘텐츠는 검색 결과에 포함되기 전에 항상 LLM에 의해 요약됩니다. 결과는 원문 그대로의 웹 텍스트가 아니라 요약으로 인용됩니다.
2026-04-01 API 버전의 경우 기술 자료에는 웹 콘텐츠 요약을 위한 LLM을 제공하는 모델 참조가 포함되어야 합니다. 검색은 항상 추출됩니다(요약 참조). 답변 합성 및 구성 가능한 추론 작업은 이 버전에서 사용할 수 없습니다.
2026-05-01-preview API 버전의 경우 기술 자료 모델 참조는 추출된 인용 대신 단일 LLM 수식 응답을 생성하는 응답 합성을 가능하게 합니다.

기존 지식 원본 확인

기술 자료는 재사용 가능한 최상위 개체입니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.

다음 코드를 실행하여 이름 및 형식별로 기술 자료를 나열합니다.

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

참조:기술 자료 - 목록

이름으로 단일 기술 원본을 반환하여 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));

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

참조:기술 자료 - 가져오기

다음 JSON은 웹 지식 원본 리소스에 대한 예제 응답입니다.

{
  "name": "my-web-ks",
  "kind": "web",
  "description": "A sample Web Knowledge Source.",
  "encryptionKey": null,
  "webParameters": {
    "domains": null
  }
}

기술 자료 만들기

다음 코드를 실행하여 웹 지식 원본을 만듭니다.

2026-05-01-미리보기
2026-04-01

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

참조:SearchIndexClient, WebKnowledgeSource

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

참조:SearchIndexClient, WebKnowledgeSource

2026-05-01-미리보기
2026-04-01

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

참조:SearchIndexClient

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

참조:SearchIndexClient

2026-05-01-미리보기
2026-04-01

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

참조:기술 자료 - 만들기 또는 업데이트

### Create Web Knowledge Source
PUT {{search-url}}/knowledgesources/my-web-ks?api-version=2026-04-01
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 } ]
    }
  }
}

참조:기술 자료 - 만들기 또는 업데이트

기술 자료에 할당

기술 자료에 만족하는 경우 기술 자료에 추가합니다.

지식 베이스 질의

웹 지식 원본을 포함하는 기술 자료를 쿼리할 때 검색 응답 activity 배열에는 다음 두 개의 웹 관련 레코드가 포함될 수 있습니다.

web 요청에 사용되는 런타임 매개 변수를 캡처하는 레코드입니다.
modelWebSummarization 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
    }
  ]
}

지식 원본 삭제

기술 자료를 삭제하려면 먼저 이를 참조하는 기술 자료를 삭제하거나 기술 자료 정의를 업데이트하여 참조를 제거해야 합니다. 인덱스 및 인덱서 파이프라인을 생성하는 기술 원본의 경우 생성된 모든 개체 도 삭제됩니다. 그러나 기존 인덱스로 기술 원본을 만든 경우 인덱스가 삭제되지 않습니다.

사용 중인 기술 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 기술 자료 목록이 반환됩니다.

기술 자료를 삭제하려면 다음을 수행합니다.

검색 서비스의 모든 기술 자료 목록을 가져옵니다.

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

개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

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
 }

기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

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

기술 자료를 삭제합니다.

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

참조:SearchIndexClient

검색 서비스의 모든 기술 자료 목록을 가져옵니다.

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

개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

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

기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

# 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

기술 자료를 삭제합니다.

# 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

검색 서비스의 모든 기술 자료 목록을 가져옵니다.

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

참조:기술 자료 - 목록

예제 응답은 다음과 같을 수 있습니다.

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

개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

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

참조:기술 자료 - 가져오기

예제 응답은 다음과 같을 수 있습니다.

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

기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.
```
### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}
```
참조:기술 자료 - 삭제

기술 자료를 삭제합니다.

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

참조:기술 자료 - 삭제

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-06-29

웹 지식 원본 리소스 만들기

사용량 지원

필수 구성 요소

제한 사항 및 고려 사항

기존 지식 원본 확인

기술 자료 만들기

기술 자료에 할당

지식 베이스 질의

지식 원본 삭제

관련 콘텐츠

피드백

추가 리소스