Azure AI Search에서 지식 에이전트를 사용하여 데이터 검색

Azure AI Search에서 에이전트 검색 은 쿼리 계획에 LLM(대규모 언어 모델)을 사용하는 새로운 병렬 쿼리 아키텍처입니다. 검색 가능하고 관련성이 있는 것의 범위를 넓히는 하위 쿼리를 생성합니다. 컨텍스트에 대한 채팅 기록을 통합합니다. LLM은 질의를 연구하고 하위 질의 구성을 위해 다른 구와 용어를 사용하여 보다 구체적인 질의로 세분화합니다.

이 문서에서는 지식 에이전트 및 병렬 쿼리 처리를 호출하는 검색 작업을 사용하는 방법을 설명합니다. 2025-05-01-preview의 호환성이 손상되는 변경이 도입된 새로운 2025-08-01-preview용으로 업데이트되었습니다. 호환성이 손상되는 변경에 대한 도움말은 에이전트 검색 코드 마이그레이션을 참조하세요.

이 문서에서는 검색 응답의 세 가지 구성 요소도 설명합니다.

• LLM에 대한 추출된 응답
• 참조된 결과
• 쿼리 작업

검색 요청에는 지식 에이전트에 설정된 기본값을 재정의하는 쿼리 처리에 대한 지침이 포함될 수 있습니다.

필수 조건

• 검색 가능한 인덱스를 래핑하는 기술 자료 입니다. 검색 인덱스 지식 원본 또는 Blob 지식 원본입니다.

• 채팅 완료 모델 및 하나 이상의 기술 자료를 나타내는 지식 에이전트 입니다.

• Azure AI Search는 기본 가격 책정 계층 이상에서 의미 체계 순위 매기기를 제공하는 모든 지역에서 제공됩니다. 검색 서비스에는 채팅 완성 모델에 대한 역할 기반 액세스를 위한 관리 ID 가 있어야 합니다.

• Azure AI Search에 대한 권한. 검색 인덱스 데이터 판독기는 Azure AI Search에서 쿼리를 실행할 수 있지만 검색 서비스 관리 ID에는 Azure OpenAI 리소스에 대한 Cognitive Services 사용자 권한이 있어야 합니다. 로컬 테스트 및 액세스 토큰 가져오기에 대한 자세한 내용은 빠른 시작: 키 없이 연결합니다.

• API 요구 사항. 지식 에이전트를 만들거나 사용하려면 2025-08-01-preview 데이터 평면 REST API를 사용합니다. 또는 Python용 Azure SDK, .NET용 Azure SDK, Java용 Azure SDK 등 지식 에이전트 API를 제공하는 Azure SDK의 시험판 패키지를 사용합니다.

이 가이드의 단계를 수행하려면 REST 클라이언트를 사용하여 Azure AI Search에 REST API 호출을 보내는 Visual Studio Code를 사용하는 것이 좋습니다. 현재 포털 지원은 없습니다.

검색 작업 호출

기술 에이전트 개체에 대한 검색 작업을 호출하여 검색을 호출하고 응답을 반환합니다. 이 작업에 해당하는 기능을 제공하는 2025-08-01-preview 데이터 평면 REST API 또는 Azure SDK 시험판 패키지를 사용합니다.

검색 인덱스 내의 모든 searchable 필드는 쿼리 실행에 대한 범위 내입니다. 인덱스에 벡터 필드가 포함된 경우 쿼리 입력을 벡터화할 수 있도록 인덱스에 유효한 벡터라이저 정의 가 있어야 합니다. 그렇지 않으면 벡터 필드가 무시됩니다. 암시적 쿼리 유형은 semantic검색 모드 또는 검색 필드 선택 항목이 없습니다.

검색 경로 입력은 자연어로 된 채팅 대화 기록이며, 배열 messages 에 대화가 포함되어 있습니다.

@search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# Send grounding request
POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}

{
    "messages" : [
            {
                "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "You can answer questions about the Earth at night.
                    Sources have a JSON format with a ref_id that must be cited in the answer.
                    If you do not have the answer, respond with 'I do not know'." }
                ]
            },
            {
                "role" : "user",
                "content" : [
                  { "type" : "text", "text" : "Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?" }
                ]
            }
        ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": null,
      "knowledgeSourceName": "earth-at-night-blob-ks",
      "kind": "searchIndex"
    }
  ]
}

핵심 사항:

• 검색 작업은 지식 에이전트를 대상으로 합니다. 지식 에이전트는 하나 이상의 기술 자료 및 기술 원본 구성을 지정합니다. 출력 및 의미 체계 순위 구성에 대한 지식 에이전트 정의를 검토합니다.

• messages 는 모델에 전송된 메시지를 표시합니다. 메시지 형식은 Azure OpenAI API와 유사합니다.

  • 는 메시지의 원본 위치를 정의합니다(예: <a0/>). 사용하는 모델은 유효한 역할을 결정합니다.

  • content 는 LLM에 전송된 메시지 또는 프롬프트입니다. 이 미리 보기에서는 반드시 텍스트여야 합니다.

• knowledgeSourceParams는 선택 사항입니다. 에이전트에 둘 이상의 지식 원본이 있고 검색 작업을 하나의 기술 원본에만 집중하려는 경우 기술 자료를 지정합니다. 지식 에이전트에 원하는 구성이 포함된 기술 원본이 하나만 있는 경우 이 섹션을 생략할 수 있습니다.

  검색 작업에 대한 기술 자료 사양은 검색 서비스의 대상 검색 인덱스를 설명합니다. 따라서 지식 원본 "kind"가 Azure Blob인 경우에도 여기서 유효한 값은 다음과 같습니다 searchIndex. 이 첫 번째 공개 미리 보기 릴리스에서는 knowledgeSourceParams.kind 항상 searchIndex.입니다.

추출된 응답 검토

추출된 응답은 일반적으로 응답을 작성하는 데 사용하여 접지 데이터로 사용하는 LLM에 전달되는 단일 통합 문자열입니다. LLM에 대한 API 호출에는 모델에 대한 통합 문자열과 지침이 포함되며, 기초 데이터를 단독으로 사용할지 또는 보완재로 사용할지 여부 등의 지침이 포함됩니다.

응답 본문도 채팅 메시지 스타일 형식으로 구성됩니다. 현재 이 미리 보기 릴리스에서는 콘텐츠가 JSON으로 직렬화됩니다.

"response": [
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "[{\"ref_id\":0,\"title\":\"Urban Structure\",\"terms\":\"Location of Phoenix, Grid of City Blocks, Phoenix Metropolitan Area at Night\",\"content\":\"<content chunk redacted>\"}]"
            }
        ]
    }
]

핵심 사항:

• content.text 는 JSON 배열입니다. 쿼리 및 채팅 기록 입력을 고려할 때 검색 인덱스에 있는 가장 관련성이 큰 문서(또는 청크)로 구성된 단일 문자열입니다. 이 배열은 대화 완성 모델이 사용자의 질문에 대한 응답을 생성하는 데 사용하는 기본 데이터입니다.

  응답의 이 부분은 200개 이하의 청크로 구성되며, 2.5 재랜커 점수의 최소 임계값을 충족하지 못하는 결과를 제외합니다.

  문자열은 청크의 참조 ID(인용 용도로 사용됨) 및 대상 인덱스의 의미 체계 구성에 지정된 모든 필드로 시작합니다. 이 예제에서는 대상 인덱스의 의미 체계 구성에 "제목" 필드, "용어" 필드 및 "콘텐츠" 필드가 있다고 가정해야 합니다.

• content.type 에는 이 미리 보기 text에서 유효한 값이 하나 있습니다.

활동 배열을 검토하다

활동 배열은 쿼리 계획을 출력하고 요청을 실행할 때 수행되는 작업을 추적하는 데 도움이 됩니다. 청구 의미 및 리소스 호출 빈도를 이해할 수 있도록 작업의 투명성을 제공합니다.

출력에는 다음이 포함됩니다.

• 입력에 사용되는 토큰
• 출력에 대한 토큰 수
• 검색 파이프라인으로 전송된 하위 쿼리
• 하위 쿼리당 결과 수
• 하위 쿼리에 대한 필터(해당하는 경우)
• 순위 및 추출에 사용되는 토큰 수

다음은 활동 배열의 예입니다.

"activity": [
    {
      "type": "ModelQueryPlanning",
      "id": 0,
      "inputTokens": 1261,
      "outputTokens": 270
    },
    {
      "type": "AzureSearchQuery",
      "id": 1,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "suburban belts December brightening urban cores comparison",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:25.944Z",
      "count": 0,
      "elapsedMs": 600
    },
    {
      "type": "AzureSearchQuery",
      "id": 2,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "Phoenix nighttime street grid visibility from space",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:26.128Z",
      "count": 2,
      "elapsedMs": 161
    },
    {
      "type": "AzureSearchQuery",
      "id": 3,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "interstate visibility from space midwestern cities",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:26.277Z",
      "count": 0,
      "elapsedMs": 147
    },
    {
      "type": "AzureSearchSemanticRanker",
      "id": 4,
      "inputTokens": 2622
    }
  ],

참조 배열 검토

배열은 references 기본 접지 데이터의 직접 참조이며 응답을 생성하는 데 사용되는 데이터를 포함합니다 sourceData . 검색 엔진에서 검색되고 의미상 순위가 지정된 모든 단일 문서로 구성됩니다. 필드 sourceData에는 id와 의미 체계 필드: title, terms, content가 포함됩니다.

특정 id 응답 내의 항목에 대한 참조 ID입니다. 검색 인덱스의 문서 키가 아닙니다. 인용을 제공하는 데 사용됩니다.

이 배열의 목적은 쉽게 통합할 수 있도록 채팅 메시지 스타일 구조를 제공하는 것입니다. 예를 들어 결과를 다른 구조로 직렬화하거나 사용자에게 반환하기 전에 데이터를 프로그래밍 방식으로 조작해야 하는 경우입니다.

참조 배열의 원본 데이터 개체에서 구조화된 데이터를 가져와서 조작할 수도 있습니다.

다음은 참조 배열의 예입니다.

  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "0",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_104_verbalized",
      "sourceData": null
    },
    {
      "type": "AzureSearchDoc",
      "id": "1",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_105_verbalized",
      "sourceData": null
    }
  ]

관련 콘텐츠

• Azure AI Search의 에이전트적 검색

• 에이전트 RAG: Azure AI Search를 사용하여 추론 검색 엔진 빌드(YouTube 비디오)

• 에이전트 검색을 특징으로 하는 Azure OpenAI 데모