Azure AI Search에서 기술 자료 만들기

Azure AI Search에서 지식 기반은 자율 검색을 오케스트레이션하는 최상위 개체입니다. 쿼리할 기술 자료와 검색 작업에 대한 기본 동작을 정의합니다. 쿼리 시 검색 메서드 는 기술 자료를 대상으로 하여 구성된 검색 파이프라인을 실행합니다.

Microsoft Foundry(신규) 포털의 Foundry IQ 워크로드 에서 기술 자료를 만들 수 있습니다. 또한 Azure AI Search API를 사용하여 만드는 에이전트 솔루션에 기술 자료가 필요합니다.

지식 기반은 다음과 같이 지정합니다.

• 검색 가능한 콘텐츠를 가리키는 하나 이상의 기술 자료입니다.
• 쿼리 계획 및 답변 공식화에 대한 추론 기능을 제공하는 선택적 LLM입니다.
• LLM이 호출되는지 여부를 결정하고 비용, 대기 시간 및 품질을 관리하는 검색 추론 작업입니다.
• 라우팅, 원본 선택, 출력 형식 및 개체 암호화를 제어하는 사용자 지정 속성입니다.

기술 자료를 만든 후 언제든지 해당 속성을 업데이트할 수 있습니다. 기술 자료가 사용 중인 경우 업데이트는 다음 검색에 적용됩니다.

필수 조건

• 에이전트 검색을 제공하는 모든 지역의 Azure AI 검색. 의미 체계 순위가 활성화되어 있어야 합니다. 배포된 모델에 대한 역할 기반 액세스에 관리 ID 를 사용하는 경우 검색 서비스는 기본 가격 책정 계층 이상에 있어야 합니다.

• 지원되는 LLM 배포를 사용하는 Azure OpenAI.

• 검색 서비스에 있는 하나 이상의 지식 소스.

• Azure AI Search에서 개체를 만들고 사용할 수 있는 권한입니다. 역할 기반 액세스를 권장합니다. Search Service 기여자는 기술 자료를 만들고 관리할 수 있습니다. 검색 인덱스 데이터 판독기는 쿼리를 실행할 수 있습니다. 또는 역할 할당이 불가능한 경우 API 키를 사용할 수 있습니다. 자세한 내용은 검색 서비스에 연결을 참조하세요.

• Python용 클라이언트 라이브러리의azure-search-documents 최신 미리 보기 버전입니다.

지원되는 모델

Azure OpenAI 또는 동등한 오픈 소스 모델에서 다음 LLM 중 하나를 사용합니다. 배포 지침은 Microsoft Foundry를 사용하여 Azure OpenAI 모델 배포를 참조하세요.

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

액세스 구성

Azure AI Search는 Azure OpenAI에서 LLM에 액세스해야 합니다. 인증에는 Microsoft Entra ID를, 권한 부여에는 역할 기반 액세스에 사용하는 것이 좋습니다. 역할을 할당하려면 소유자 또는 사용자 액세스 관리자여야 합니다. 역할을 사용할 수 없는 경우 대신 키 기반 인증을 사용합니다.

기존 기술 자료 확인

기존 기술 자료에 대해 아는 것은 다시 사용하거나 새 개체의 이름을 지정하는 데 유용합니다. 모든 2025-08-01-preview 지식 에이전트는 기술 자료 컬렉션에 포함되어 반환됩니다.

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

// List knowledge bases by name
  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}");
  }

이름으로 단일 기술 자료를 반환하여 JSON 정의를 검토할 수도 있습니다.

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

다음 JSON은 기술 자료의 예입니다.

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

기술 자료 만들기

지식 베이스는 에이전트 기반 검색 파이프라인을 구동합니다. 애플리케이션 코드에서 다른 에이전트 또는 챗봇은 이를 호출합니다.

기술 자료는 지식 원본(검색 가능한 콘텐츠)을 Azure OpenAI의 LLM 배포에 연결합니다. LLM의 속성은 연결을 설정하고, 지식 원본의 속성은 쿼리 실행 및 응답을 알리는 기본값을 설정합니다.

다음 코드를 실행하여 기술 자료를 만듭니다.

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

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Create a knowledge base
var knowledgeBase = new KnowledgeBase(
    name: knowledgeBaseName,
    knowledgeSources: new KnowledgeSourceReference[] { new KnowledgeSourceReference(knowledgeSourceName) }
)
{
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { model }
};
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBaseName}' created or updated successfully.");

# Create a knowledge base
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var aoaiParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var knowledgeBase = new KnowledgeBase(
    name: "my-kb",
    knowledgeSources: new KnowledgeSourceReference[] 
    { 
        new KnowledgeSourceReference("hotels-sample-knowledge-source"),
        new KnowledgeSourceReference("earth-knowledge-source")
    }
)
{
    Description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    RetrievalInstructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    AnswerInstructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: aoaiParams) },
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort()
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBase.Name}' created or updated successfully.");

기술 자료 속성

다음 속성을 전달하여 지식 기반을 만듭니다.

기술 자료 쿼리

LLM에 보낼 지침 및 메시지를 설정합니다.

string instructions = @"
Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.
";

var messages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "system" },
        { "content", instructions }
    }
};

retrieve 기술 자료에 대한 작업을 호출하여 LLM 연결을 확인하고 결과를 반환합니다. 요청 및 응답 스키마에 대한 retrieve 자세한 내용은 Azure AI Search의 기술 자료를 사용하여 데이터 검색을 참조하세요.

"바다는 녹색으로 보이는 곳"을 지식 원본에 유효한 쿼리 문자열로 바꿉니다.

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

var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    tokenCredential: new DefaultAzureCredential()
);

messages.Add(new Dictionary<string, string>
{
    { "role", "user" },
    { "content", @"Where does the ocean look green?" }
});

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in messages) {
    if (message["role"] != "system") {
        retrievalRequest.Messages.Add(new KnowledgeBaseMessage(content: new[] { new KnowledgeBaseMessageTextContent(message["content"]) }) { Role = message["role"] });
    }
}
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
var retrievalResult = await baseClient.RetrieveAsync(retrievalRequest);

messages.Add(new Dictionary<string, string>
{
    { "role", "assistant" },
    { "content", (retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text }
});

(retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text 

// Print the response, activity, and references
Console.WriteLine("Response:");
Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text);

핵심 사항:

• KnowledgeBaseRetrievalRequest 는 검색 요청에 대한 입력 계약입니다.

• RetrievalReasoningEffort 가 필요합니다. 쿼리 파이프라인에서 LLM을 제외하도록 minimal 설정하면 쿼리 입력에 의도만 사용됩니다. 기본값은 low LLM 기반 쿼리 계획 및 메시지 및 컨텍스트와의 응답 합성을 지원합니다.

• knowledgeSourceParams 는 쿼리 시 기본 매개 변수를 덮어쓰는 데 사용됩니다.

샘플 쿼리에 대한 응답은 다음 예제와 같을 수 있습니다.

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

기술 자료 삭제

더 이상 기술 자료가 필요하지 않거나 검색 서비스에서 다시 빌드할 필요가 없는 경우 이 요청을 사용하여 개체를 삭제합니다.

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

Azure AI Search에서 지식 기반은 자율 검색을 오케스트레이션하는 최상위 개체입니다. 쿼리할 기술 자료와 검색 작업에 대한 기본 동작을 정의합니다. 쿼리 시 검색 메서드 는 기술 자료를 대상으로 하여 구성된 검색 파이프라인을 실행합니다.

Microsoft Foundry(신규) 포털의 Foundry IQ 워크로드 에서 기술 자료를 만들 수 있습니다. 또한 Azure AI Search API를 사용하여 만드는 에이전트 솔루션에 기술 자료가 필요합니다.

지식 기반은 다음과 같이 지정합니다.

• 검색 가능한 콘텐츠를 가리키는 하나 이상의 기술 자료입니다.
• 쿼리 계획 및 답변 공식화에 대한 추론 기능을 제공하는 선택적 LLM입니다.
• LLM이 호출되는지 여부를 결정하고 비용, 대기 시간 및 품질을 관리하는 검색 추론 작업입니다.
• 라우팅, 원본 선택, 출력 형식 및 개체 암호화를 제어하는 사용자 지정 속성입니다.

기술 자료를 만든 후 언제든지 해당 속성을 업데이트할 수 있습니다. 기술 자료가 사용 중인 경우 업데이트는 다음 검색에 적용됩니다.

필수 조건

• 에이전트 검색을 제공하는 모든 지역의 Azure AI 검색. 의미 체계 순위가 활성화되어 있어야 합니다. 배포된 모델에 대한 역할 기반 액세스에 관리 ID 를 사용하는 경우 검색 서비스는 기본 가격 책정 계층 이상에 있어야 합니다.

• 지원되는 LLM 배포를 사용하는 Azure OpenAI.

• 검색 서비스에 있는 하나 이상의 지식 소스.

• Azure AI Search에서 개체를 만들고 사용할 수 있는 권한입니다. 역할 기반 액세스를 권장합니다. Search Service 기여자는 기술 자료를 만들고 관리할 수 있습니다. 검색 인덱스 데이터 판독기는 쿼리를 실행할 수 있습니다. 또는 역할 할당이 불가능한 경우 API 키를 사용할 수 있습니다. 자세한 내용은 검색 서비스에 연결을 참조하세요.

• Python용 클라이언트 라이브러리의azure-search-documents 최신 미리 보기 버전입니다.

지원되는 모델

Azure OpenAI 또는 동등한 오픈 소스 모델에서 다음 LLM 중 하나를 사용합니다. 배포 지침은 Microsoft Foundry를 사용하여 Azure OpenAI 모델 배포를 참조하세요.

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

액세스 구성

Azure AI Search는 Azure OpenAI에서 LLM에 액세스해야 합니다. 인증에는 Microsoft Entra ID를, 권한 부여에는 역할 기반 액세스에 사용하는 것이 좋습니다. 역할을 할당하려면 소유자 또는 사용자 액세스 관리자 여야 합니다. 역할이 가능하지 않은 경우 대신 키 기반 인증을 사용합니다.

기존 기술 자료 확인

기존 기술 자료에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다. 모든 2025-08-01-preview 지식 에이전트는 기술 자료 컬렉션에 포함되어 반환됩니다.

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

# List knowledge bases by name
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

이름으로 단일 기술 자료를 반환하여 JSON 정의를 검토할 수도 있습니다.

# Get a knowledge base definition
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

다음 JSON은 기술 자료에 대한 예제 응답입니다.

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

기술 자료 만들기

지식 베이스는 에이전트 기반 검색 파이프라인을 구동합니다. 애플리케이션 코드에서 다른 에이전트 또는 챗봇은 이를 호출합니다.

기술 자료는 지식 원본(검색 가능한 콘텐츠)을 Azure OpenAI의 LLM 배포에 연결합니다. LLM의 속성은 연결을 설정하고, 지식 원본의 속성은 쿼리 실행 및 응답을 알리는 기본값을 설정합니다.

다음 코드를 실행하여 기술 자료를 만듭니다.

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeBaseAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalLowReasoningEffort

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url = "aoai_endpoint",
    api_key="aoai_api_key",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    output_mode = KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort,
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

기술 자료 속성

다음 속성을 전달하여 지식 기반을 만듭니다.

기술 자료 쿼리

retrieve 기술 자료에 대한 작업을 호출하여 LLM 연결을 확인하고 결과를 반환합니다. 요청 및 응답 스키마에 대한 retrieve 자세한 내용은 Azure AI Search의 기술 자료를 사용하여 데이터 검색을 참조하세요.

"바다는 녹색으로 보이는 곳"을 지식 원본에 유효한 쿼리 문자열로 바꿉니다.

# Send grounding request
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, SearchIndexKnowledgeSourceParams

kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role = "assistant",
            content = [KnowledgeBaseMessageTextContent(text = "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.")]
        ),
        KnowledgeBaseMessage(
            role = "user",
            content = [KnowledgeBaseMessageTextContent(text = "Where does the ocean look green?")]
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name = "earth-at-night-ks",
            include_references = True,
            include_reference_source_data = True,
            always_query_source = False,
        )
    ],
    include_activity = True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

핵심 사항:

• messages가 필요하지만, 쿼리를 제공하는 user 역할만으로도 이 예제를 실행할 수 있습니다.

• knowledge_source_params 은 하나 이상의 쿼리 대상을 지정합니다. 각 지식 원본에 대해 출력에 포함할 정보의 양을 지정할 수 있습니다.

샘플 쿼리에 대한 응답은 다음 예제와 같을 수 있습니다.

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

기술 자료 삭제

더 이상 기술 자료가 필요하지 않거나 검색 서비스에서 다시 빌드할 필요가 없는 경우 이 요청을 사용하여 개체를 삭제합니다.

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

Azure AI Search에서 지식 기반은 자율 검색을 오케스트레이션하는 최상위 개체입니다. 쿼리할 기술 자료와 검색 작업에 대한 기본 동작을 정의합니다. 쿼리 시 검색 메서드 는 기술 자료를 대상으로 하여 구성된 검색 파이프라인을 실행합니다.

Microsoft Foundry(신규) 포털의 Foundry IQ 워크로드 에서 기술 자료를 만들 수 있습니다. 또한 Azure AI Search API를 사용하여 만드는 에이전트 솔루션에 기술 자료가 필요합니다.

지식 기반은 다음과 같이 지정합니다.

• 검색 가능한 콘텐츠를 가리키는 하나 이상의 기술 자료입니다.
• 쿼리 계획 및 답변 공식화에 대한 추론 기능을 제공하는 선택적 LLM입니다.
• LLM이 호출되는지 여부를 결정하고 비용, 대기 시간 및 품질을 관리하는 검색 추론 작업입니다.
• 라우팅, 원본 선택, 출력 형식 및 개체 암호화를 제어하는 사용자 지정 속성입니다.

기술 자료를 만든 후 언제든지 해당 속성을 업데이트할 수 있습니다. 기술 자료가 사용 중인 경우 업데이트는 다음 검색에 적용됩니다.

필수 조건

• 에이전트 검색을 제공하는 모든 지역의 Azure AI 검색. 의미 체계 순위가 활성화되어 있어야 합니다. 배포된 모델에 대한 역할 기반 액세스에 관리 ID 를 사용하는 경우 검색 서비스는 기본 가격 책정 계층 이상에 있어야 합니다.

• 지원되는 LLM 배포를 사용하는 Azure OpenAI.

• 검색 서비스에 있는 하나 이상의 지식 소스.

• Azure AI Search에서 개체를 만들고 사용할 수 있는 권한입니다. 역할 기반 액세스를 권장합니다. Search Service 기여자는 기술 자료를 만들고 관리할 수 있습니다. 검색 인덱스 데이터 판독기는 쿼리를 실행할 수 있습니다. 또는 역할 할당이 불가능한 경우 API 키를 사용할 수 있습니다. 자세한 내용은 검색 서비스에 연결을 참조하세요.

• .NET SDK용 Azure.Search.Documents 클라이언트 라이브러리 의 최신 미리 보기 버전입니다.

지원되는 모델

Azure OpenAI 또는 동등한 오픈 소스 모델에서 다음 LLM 중 하나를 사용합니다. 배포 지침은 Microsoft Foundry를 사용하여 Azure OpenAI 모델 배포를 참조하세요.

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

액세스 구성

Azure AI Search는 Azure OpenAI에서 LLM에 액세스해야 합니다. 인증에는 Microsoft Entra ID를, 권한 부여에는 역할 기반 액세스에 사용하는 것이 좋습니다. 역할을 할당하려면 소유자 또는 사용자 액세스 관리자여야 합니다. 역할을 사용할 수 없는 경우 대신 키 기반 인증을 사용합니다.

기존 기술 자료 확인

기술 자료는 재사용 가능한 최상위 개체입니다. 기존 기술 자료에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다. 모든 2025-08-01-preview 지식 에이전트는 기술 자료 컬렉션에 포함되어 반환됩니다.

기술 자료 - 목록(REST API)을 사용하여 이름 및 형식별로 기술 자료를 나열합니다.

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version=2025-11-01-preview&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

이름으로 단일 기술 자료를 반환하여 JSON 정의를 검토할 수도 있습니다.

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

다음 JSON은 기술 자료에 대한 예제 응답입니다.

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

기술 자료 만들기

지식 베이스는 에이전트 기반 검색 파이프라인을 구동합니다. 애플리케이션 코드에서 다른 에이전트 또는 챗봇은 이를 호출합니다.

기술 자료는 지식 원본(검색 가능한 콘텐츠)을 Azure OpenAI의 LLM 배포에 연결합니다. LLM의 속성은 연결을 설정하지만, 기술 자료 집합의 속성은 기본적으로 쿼리 실행 및 응답을 안내합니다.

기술 자료 사용 - REST API(만들기 또는 업데이트)를 사용하여 요청을 작성합니다.

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4.1-mini",
                "modelName": "gpt-4.1-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

기술 자료 속성

다음 속성을 전달하여 지식 기반을 만듭니다.

기술 자료 쿼리

retrieve 기술 자료에 대한 작업을 호출하여 LLM 연결을 확인하고 결과를 반환합니다. 요청 및 응답 스키마에 대한 retrieve 자세한 내용은 Azure AI Search의 기술 자료를 사용하여 데이터 검색을 참조하세요.

기술 자료 검색 - 검색(REST API)을 사용하여 요청을 작성합니다. "바다는 녹색으로 보이는 곳"을 지식 원본에 유효한 쿼리 문자열로 바꿉니다.

# Send grounding request
POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "messages" : [
        { "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
                ]
        },
        {
            "role" : "user",
            "content" : [
                {
                    "text" : "Where does the ocean look green?",
                    "type" : "text"
                }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "alwaysQuerySource": false
        }
  ]
}

핵심 사항:

• messages가 필요하지만, 쿼리를 제공하는 user 역할만으로도 이 예제를 실행할 수 있습니다.

• knowledgeSourceParams 은 하나 이상의 쿼리 대상을 지정합니다. 각 지식 원본에 대해 출력에 포함할 정보의 양을 지정할 수 있습니다.

샘플 쿼리에 대한 응답은 다음 예제와 같을 수 있습니다.

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

기술 자료 삭제

더 이상 기술 자료가 필요하지 않거나 검색 서비스에서 다시 빌드할 필요가 없는 경우 이 요청을 사용하여 개체를 삭제합니다.

# Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{search-api-key}}