검색 추론 작업 설정

참고

Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.

Important

이 문서에서 (미리 보기)로 표시된 기능 또는 성능은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

Foundry IQ(Azure AI 검색)와 관련된 미리 보기 용어는 미리 보기 기능을 참조하세요.

에이전트 검색에서 검색 추론 작업을 사용하여 기술 자료가 콘텐츠를 검색하기 전에 발생하는 쿼리 계획의 양을 제어합니다. GA 2026-10-01 REST API는 지원 및 .minimallowmedium auto 는 지원되는 미리 보기 API 버전이 필요한 미리 보기 기능입니다. 2026-11-01-preview REST API에서 추론 작업은 Microsoft Retriever 1 쿼리 계획에도 적용될 수 있습니다. 자세한 내용은 Microsoft 리트리버 1 사용을 참조하세요.

기술 자료 또는 검색 요청에서 이 속성을 설정합니다. 요청 설정은 기술 자료 설정을 재정의합니다. 사용 가능한 기능에 따라 달라질 수 있는 서비스 기본값에 의존하지 않고 명시적으로 설정합니다. 계획에 드는 노력과 답변 합성은 별도의 선택 사항입니다.

사용량 지원

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

필수 구성 요소

  • 하나 이상의 기술 자료가 있는 기존 기술 자료 입니다. 모델은 , mediumauto (미리 보기), 응답 합성 또는 웹 요약에 필요하지만 모델 없는 최소 추출에는 필요하지 low않습니다.

  • 기술 자료를 업데이트하고 쿼리할 수 있는 권한입니다. 사용자 계정에 할당된 Search Service 기여자 및 검색 인덱스 데이터 판독기 역할을 사용하여 키 없는 인증을 구성하거나 관리자 API 키를 사용합니다.

  • 최신 Azure.Search.Documents 미리 보기 패키지: dotnet add package Azure.Search.Documents --prerelease

  • 키 없는 인증의 경우 패키지:Azure.Identitydotnet add package Azure.Identity

  • 2026-10-01 GA 작업 수준에 대한 검색 REST API입니다. auto의 경우, REST 예제에서는 2026-11-01-preview를 사용하고 SDK 예제는 기존 미리 보기 패키지 계약을 유지합니다.

  • 키 없는 인증의 경우 각 HTTP 요청의 헤더에 Microsoft Entra ID 토큰을 Authorization 포함합니다.

추론 유형 선택

대기 시간, 비용 및 검색 깊이 간에 원하는 절충을 기반으로 추론 작업을 선택합니다.

추론 작업 수준

2026-11-01-preview REST API에서 기술 자료에 Microsoft Retriever 1({"kind":"microsoftRetriever1"})을 추가하면 Minimal 및 Auto 계획의 쿼리 방식이 변경됩니다. 설정 단계는 Microsoft 리트리버 1 사용을 참조하세요.

  • 최소: Microsoft 리트리버 1만 있는 기술 자료는 최소이지만 자동, 낮음 또는 보통은 지원하지 않습니다.

    • 전체 질문을 포함하는 의미 체계 의도가 정확히 하나인 경우 Minimal은 쿼리 계획에 Microsoft Retriever 1을 사용할 수 있습니다.
    • 여러 의미적 의도를 사용하는 Minimal은 Microsoft Retriever 1 계획을 건너뛰고, 각 의도에 대해 일반 Minimal 검색을 실행하고, 결과를 병합합니다.
  • 자동(미리 보기): 정확히 하나의 Microsoft 리트리버 1 모델과 정확히 하나의 외부 azureOpenAI 또는 openAICompatible 계획 모델이라는 두 개의 모델 쌍이 필요합니다. Microsoft Retriever 1은 검색 계획만 처리하므로 응답 합성에는 외부 모델이 필요합니다.

    • 하나의 의미 체계 의도가 있는 적격 요청의 경우 자동은 초기 신뢰도 패스로 시작하고 즉시 결과를 반환할 수 있습니다. 그렇지 않은 경우 Auto는 Microsoft 리트리버 1을 사용하여 더 심층 검색한 다음 중간에서 외부 모델로 에스컬레이션할 수 있습니다.
    • 여러 의미 체계 의도를 사용하여 자동은 초기 패스와 Microsoft 리트리버 1을 건너뛰고 중간에서 외부 모델로 시작합니다.
수준 설명 추천 제한
minimal 일반 최소는 모델 기반 계획을 우회하고 모든 후보 기술 자료를 검색합니다. alwaysQuerySource: false 는 원본을 제외하지 않습니다. 직접 계획을 관리할 때는 시맨틱 인텐트와 함께 minimal를 사용합니다.
low LLM 기반 계획 및 소스 선택의 단일 패스를 실행한 다음 결과를 병합합니다. 응답 합성은 선택 사항입니다. 더 심층적인 반복 패스 없이 모델 기반 계획에 low를 사용합니다. 모델이 필요합니다. 출력 예산은 정해진 합성 응답 길이가 아닌 구성 및 사용 기능에 따라 달라집니다.
medium 더 심층 검색을 추가하고 후속 반복이 필요한지 여부를 평가합니다. 더 심층적인 모델 지원 검색에 사용합니다 medium . 모델이 필요합니다. 선택한 지역에서 사용할 수 있습니다.
auto (미리 보기) 간단한 검색 패스로 시작하고 모델 기반 계획으로 에스컬레이션할 수 있습니다. 서비스에서 요청에 대한 작업을 선택할 수 있도록 하는 데 사용합니다 auto . 모델 및 지원 미리 보기 API(예: 2026-08-01-preview 또는 2026-11-01-preview.)가 필요합니다. 2026-10-01에서는 지원되지 않습니다.

명시적 작업이 포함된 GA REST 예제는 2026-10-01 REST를 사용하여 검색을 참조하세요. 별도의 2026-11-01-preview 예제는 REST와 응답 합성 사용을 참조하세요.

중간 단위 검색에 대한 반복 검색

중간 검색 추론 작업은 초기 결과가 충분히 관련이 없는 경우 반복 검색을 제공합니다. 추가 의미 체계 분류자 모델이 호출되어 두 번째 반복이 필요한지 확인합니다.

시맨틱 분류기:

  • 질문에 대답하기에 충분한 컨텍스트가 있는 경우를 인식합니다.

  • 컨텍스트에 대한 기존 정보를 사용하여 부족한 결과를 다시 시도합니다. 새 쿼리는 더 집중된 세부 정보를 드릴다운하거나 검색 범위를 넓힐 수 있습니다. 응답의 활동 로그는 보다 포괄적인 답변에 사용되는 생성된 쿼리를 보여 줍니다.

  • L3 분류를 사용하여 다시 점수 지정합니다. 이 범위는 L2 순위와 동일하며, 절대 범위는 0부터 4.0까지입니다.

재시도는 하나뿐입니다. 각 반복은 대기 시간과 비용을 추가하므로 시스템은 한 패스로 재시도를 제한합니다. 두 번째 반복은 쿼리 파이프라인에 입력 토큰을 추가하여 전체 청구 가능한 입력 토큰 수에 추가합니다.

반복은 기존 기술 자료를 다시 사용하거나 다른 원본을 선택할 수 있습니다. 두 번째 패스는 누락된 정보를 제공하기 위해 가장 유망한 기술 원본을 선택합니다.

중간 검색에 대한 지역 지원

Foundry IQ 서비스가 다음 지역 중 하나에 있는 경우 중간 검색 추론 작업을 설정할 수 있습니다.

  • 미국 동부 2
  • 미국 동부
  • 미국 중남부
  • 미국 서부 3
  • 미국 서부 2
  • 미국 서부
  • 독일 중서부
  • 북유럽
  • 스위스 북부
  • 스웨덴 중부
  • 스페인 중부
  • 영국 남부
  • 한국 중부
  • 일본 동부
  • 동남 아시아

지식 베이스에서 추론 노력 설정

지식 베이스 정의에서 retrievalReasoningEffort를 설정하여 해당 쿼리의 기본값을 설정합니다. 추론 작업에는 auto 모델 구성이 필요합니다. 다음 예제에서는 기존 knowledgeSources 구성과 models 구성을 유지하고, 추론 노력을 auto설정하고, 기술 자료를 업데이트합니다.

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

var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";

var indexClient = new SearchIndexClient(endpoint, credential);
var knowledgeBase = (
    await indexClient.GetKnowledgeBaseAsync(knowledgeBaseName)).Value;
knowledgeBase.RetrievalReasoningEffort =
    new KnowledgeRetrievalAutoReasoningEffort();
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);

참조:KnowledgeBase

다른 수준을 사용하려면 KnowledgeRetrievalAutoReasoningEffort을 KnowledgeRetrievalLowReasoningEffort, KnowledgeRetrievalMediumReasoningEffort 또는 KnowledgeRetrievalMinimalReasoningEffort으로 바꾸세요.

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeRetrievalAutoReasoningEffort,
)

endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"

index_client = SearchIndexClient(endpoint, credential)
knowledge_base = index_client.get_knowledge_base(knowledge_base_name)
knowledge_base.retrieval_reasoning_effort = (
    KnowledgeRetrievalAutoReasoningEffort()
)
index_client.create_or_update_knowledge_base(knowledge_base)

참조:KnowledgeBase

다른 수준을 사용하려면 KnowledgeRetrievalAutoReasoningEffort을 KnowledgeRetrievalLowReasoningEffort, KnowledgeRetrievalMediumReasoningEffort 또는 KnowledgeRetrievalMinimalReasoningEffort으로 바꾸세요.

@api-version = 2026-11-01-preview
@knowledge-base-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}

PUT {{knowledge-base-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "{{knowledge-base-name}}",
  "knowledgeSources": [
    {
      "name": "{{knowledge-source-name}}"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "{{aoai-endpoint}}",
        "authIdentity": null,
        "deploymentId": "{{model-deployment-name}}",
        "modelName": "{{model-name}}"
      }
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "auto"
  }
}

참조:지식 베이스 - 생성 또는 업데이트

다른 수준을 사용하려면 low을(를) medium, minimal 또는 retrievalReasoningEffort.kind(으)로 설정합니다.

검색 요청에서 추론 작업 설정

해당 요청에 대해 기술 자료 기본값을 재정의하려면 조회 요청에서 retrievalReasoningEffort를 설정합니다. 다음 예제에서는 메시지를 보내고, auto를 사용하여 이전 섹션의 low 기본값을 재정의하며, 답변 합성(미리 보기)을 활성화합니다.

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

var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";

var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint, knowledgeBaseName, credential);
var request = new KnowledgeBaseRetrievalRequest
{
    RetrievalReasoningEffort =
        new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis
};

request.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What is the return policy?")
        }
    ) { Role = "user" }
);

var result = await kbClient.RetrieveAsync(request);

참조:KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalLowReasoningEffort,
)

endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"

kb_client = KnowledgeBaseRetrievalClient(
    endpoint,
    credential,
    knowledge_base_name=knowledge_base_name,
)
request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="What is the return policy?"
                )
            ],
        )
    ],
    retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
    output_mode=KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
)

result = kb_client.retrieve(request)

참조:KnowledgeBaseRetrievalRequest

@api-version = 2026-11-01-preview
@retrieve-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve

POST {{retrieve-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the return policy?"
        }
      ]
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "answerSynthesis"
}

참조:지식 검색 - 가져오기

검색 요청은 기술 자료에 구성된 지식 소스를 기반으로 한 근거 기반 답변을 반환합니다.