검색 인덱스 지식 원본 만들기

검색 인덱스 지식 원본은 에이전트 검색 파이프라인에서 검색 가능한 콘텐츠를 제공하는 Azure AI Search 인덱스에 대한 연결을 지정합니다. 지식 원본 은 독립적으로 생성되고, 지식 에이전트에서 참조되며, 에이전트 또는 챗봇이 쿼리 시 검색 작업을 호출할 때 접지 데이터로 사용됩니다.

지식 원본은 2025-08-01-preview 릴리스의 새로운 기능입니다.

필수 조건

의미 체계 구성을 사용하는 일반 텍스트 또는 벡터 콘텐츠를 포함하는 검색 인덱스가 필요합니다. 에이전트 검색에 대한 인덱스 조건을 검토합니다. 인덱스가 기술 자료 에이전트와 동일한 검색 서비스에 있어야 합니다.

이 문서의 예제를 사용하려면 미리 보기 REST API 호출을 Azure AI Search로 보내기 위해 REST 클라이언트 확장이 있는 Visual Studio Code를 사용하는 것이 좋습니다. 현재 포털 지원은 없습니다.

기존 지식 원본 확인

지식 원본은 재사용 가능한 최상위 개체입니다. 모든 지식 원본은 지식 원본 컬렉션 내에서 고유하게 이름을 지정해야 합니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.

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

### List knowledge sources by name and type
GET {{search-url}}/knowledgeSources?api-version=2025-08-01-preview&$select=name,kind
api-key: {{api-key}}
Content-Type: application/json

이름으로 단일 지식 원본을 반환하여 JSON 정의를 검토할 수도 있습니다.

### Get a knowledge source definition
GET {{search-url}}/knowledgeSources/{{knowledge-source-name}}?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

다음 JSON은 지식 원본에 대한 예제 응답입니다 searchIndex . 지식 원본은 단일 인덱스 이름과 쿼리에 포함할 인덱스의 필드를 지정합니다.

{

  "name": "earth-at-night-ks",
  "kind": "searchIndex",
  "description": "Earth at night e-book knowledge source",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "earth_at_night",
    "sourceDataSelect": "page_chunk,page_number"
  },
  "azureBlobParameters": null,
  "webParameters": null
}

지식 원본 만들기

지식 소스를 생성하려면 searchIndex을(를) 만듭니다.

1. 파일 맨 위에 환경 변수를 설정합니다.

   @search-url = <YOUR SEARCH SERVICE URL>
   @api-key = <YOUR ADMIN API KEY>
   @ks-name = <YOUR KNOWLEDGE SOURCE NAME>
   @index-name = <YOUR INDEX NAME>
   

2. 2025-08-01-Preview의 기술 자료 - REST API(만들기 또는 업데이트) 또는 요청을 작성하기 위한 동등한 기능을 제공하는 Azure SDK 미리 보기 패키지를 사용합니다.

   POST {{search-url}}/knowledgeSources?api-version=2025-08-01-preview
   api-key: {{api-key}}
   Content-Type: application/json
   
   {
       "name" : "{{ks-name}}",
       "kind" : "searchIndex",
       "description" : "Earth at night e-book knowledge source",
       "searchIndexParameters" :{
         "searchIndexName" : "{{index-name}}",
         "sourceDataSelect" : "page_chunk,page_number"
       }
   }
   

3. 요청 보내기를 선택합니다.

핵심 사항:

• name 은 기술 자료 컬렉션 내에서 고유해야 하며 Azure AI Search의 개체 에 대한 명명 지침을 따라야 합니다.

• kind는 검색 인덱스 지식 원본에 대한 searchIndex여야 합니다.

• searchIndexName 는 에이전트 검색을 위해 설계해야 하는 인덱스의 이름입니다.

• sourceDataSelect 는 지식 에이전트 정의에서 includeReferenceSourceData 을/를 지정할 때 반환되는 인덱스 필드 목록입니다. 이러한 필드는 인용에 사용되며 retrievable. 예를 들어 문서 이름, 파일 이름, 페이지 번호 또는 장 번호가 있습니다.

지식 에이전트에 할당

인덱스에 만족하는 경우 다음 단계로 계속 진행합니다. 지식 에이전트에서 지식 원본을 지정합니다.

지식 에이전트 내에는 쿼리 작업과 관련된 지식 원본에 설정할 속성이 더 많이 있습니다.

지식 원본 삭제

더 이상 지식 원본이 필요하지 않거나 검색 서비스에서 다시 빌드해야 하는 경우 이 요청을 사용하여 현재 개체를 삭제합니다.

기술 자료를 삭제하려면 먼저 이를 참조하는 지식 에이전트를 삭제하거나 업데이트 작업에서 참조를 원격으로 만들어야 합니다. 관련 인덱스 및 기술 소스에서 만든 인덱서 파이프라인 개체는 독립 실행형 개체이며 기술 원본과 함께 삭제하거나 업데이트할 필요가 없습니다.

사용 중인 지식 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 지식 에이전트 목록이 반환됩니다.

1. 먼저 모든 지식 에이전트 목록을 가져옵니다. 이 요청은 검색 서비스의 모든 지식 에이전트를 반환합니다.

   ### Get the knowledge agent
   GET {{search-endpoint}}/agents?api-version=2025-08-01-preview&$select=name
   api-key: {{api-key}}
   Content-Type: application/json
   

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

    {
        "@odata.context": "https://my-demo-search-service.search.windows.net/$metadata#agents(name)",
        "value": [
        {
            "name": "earth-blob-ka"
        },
        {
            "name": "hotels-sample-ka"
        }
        ]
    }
   

2. 개별 지식 에이전트 정의를 가져와서 기술 자료 참조를 확인합니다.

   GET {{search-endpoint}}/agents/hotels-sample-ka?api-version=2025-08-01-preview
   api-key: {{api-key}}
   Content-Type: application/json
   

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

    {
      "name": "hotels-sample-ka",
      "description": null,
      "retrievalInstructions": null,
      "knowledgeSources": [
        {
          "name": "hotels-sample-ks",
          "alwaysQuerySource": false,
          "includeReferences": true,
          "includeReferenceSourceData": false,
          "maxSubQueries": null,
          "rerankerThreshold": null
        }
      ],
      "models": [ trimmed for brevity ],
      "outputConfiguration": { trimmed for brevity },
      "requestLimits": { trimmed for brevity},
      "encryptionKey": null
    }
   

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

   ### Delete knowledge agent
   DELETE {{search-endpoint}}/agents/hotels-sample-ka?api-version=2025-08-01-preview
   api-key: {{api-key}}
   Content-Type: application/json
   

4. 지식 원본을 삭제합니다.

   ### Delete a knowledge source definition
   GET {{search-endpoint}}/knowledgeSources/hotels-sample-ks?api-version=2025-08-01-preview
   api-key: {{api-key}}
   Content-Type: application/json
   

관련 콘텐츠

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

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

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