REST를 사용하여 Azure AI 검색 통합 벡터화 설정

이 문서에서는 기술 세트를 사용하여 지원되는 데이터 원본의 콘텐츠를 청크 및 벡터화하는 방법을 알아봅니다. 기술 세트는 청크 분할을 위해 텍스트 분할 기술 또는 문서 레이아웃 기술을 호출하고, 청크를 벡터화하기 위해 지원되는 임베딩 모델에 연결된 임베딩 기술을 호출합니다. 청크 및 벡터화된 콘텐츠를 벡터 인덱스로 저장하는 방법도 알아봅니다.

이 문서에서는 REST를 사용하는 통합 벡터화를 위한 엔드투엔드 워크플로에 대해 설명합니다. 포털 기반 지침은 Quickstart: Azure Portal 텍스트 및 이미지 벡터화를 참조하세요.

필수 구성 요소

• 활성 구독이 있는 Azure 계정입니다. 무료로 계정을 만듭니다.

• Azure AI 검색 서비스. 기본 계층 이상을 사용하는 것이 좋습니다.

• 지원되는 데이터 원본입니다.

• 지원되는 임베딩 모델입니다.

• 빠른 시작 완료: 키 없이 연결하고 시스템 할당 관리 ID를 구성합니다. 데이터 평면 작업에 키 기반 인증을 사용할 수 있지만 이 문서에서는 더 안전한 역할 및 관리 ID를 가정합니다.

• REST 클라이언트 확장이 있는 Visual Studio Code입니다.

지원되는 데이터 원본

통합 벡터화는 지원되는 모든 데이터 원본에서 작동합니다. 그러나 이 문서에서는 다음 표에 설명된 가장 일반적으로 사용되는 데이터 원본에 중점을 둡니다.

데이터 원본	설명
Azure Blob Storage	이 데이터 원본은 Blob 및 테이블에서 작동합니다. 표준 성능(범용 v2) 계정을 사용해야 합니다. 액세스 계층은 핫, 쿨 또는 콜드일 수 있습니다.
ADLS(Azure Data Lake Storage) Gen2	계층 구조 네임스페이스를 사용하도록 설정된 Azure Storage 계정입니다. Data Lake Storage 있는지 확인하려면 프로퍼티 탭의 Overview 탭을 확인합니다.
Microsoft OneLake	이 데이터 원본은 OneLake 파일 및 단축아이콘에 연결합니다.

지원되는 임베딩 모델

통합 벡터화를 위해 다음 포함 모델 중 하나를 사용합니다. 배포 지침은 이후 섹션에서 제공됩니다.

¹ Azure OpenAI 리소스의 엔드포인트는 예를 들어https://my-unique-name.openai.azure.com이 있어야 합니다. Azure 포털에서 리소스를 만든 경우 리소스를 설정하는 동안 이 하위 도메인이 자동으로 생성됩니다.

² Azure Microsoft Foundry 포털에서 만든 OpenAI 리소스(포함 모델에 대한 액세스 권한 포함)는 지원되지 않습니다. Azure 포털에서 Azure OpenAI 리소스를 만들어야 합니다.

³ 청구 목적으로, Azure AI 검색 스킬셋에 Microsoft Foundry 리소스를 연결해야 합니다. 키 없는 연결을 사용하여 기술 세트를 만들지 않는 한 두 리소스는 동일한 지역에 있어야 합니다.

⁴ Azure Vision 멀티모달 포함 모델은 선택 지역 사용할 수 있습니다.

역할 기반 액세스

역할 할당 또는 전체 액세스 연결 문자열을 사용하여 키 기반 인증에 Microsoft Entra ID 사용할 수 있습니다. 다른 리소스에 대한 Azure AI 검색 연결의 경우 역할 할당을 권장합니다.

통합 벡터화에 대한 역할 기반 액세스를 구성하려면 다음을 수행합니다.

1. 검색 서비스에서 역할을 사용하도록 설정하고시스템 할당 관리 ID를 구성합니다.

2. 데이터 원본 플랫폼 및 포함 모델 공급자에서 검색 서비스가 데이터 및 모델에 액세스할 수 있도록 하는 역할 할당을 만듭니다. 데이터 준비 및 포함 모델 준비를 참조하세요.

Azure AI 검색 대한 연결 정보 가져오기

이 섹션에서는 Azure AI 검색 서비스에 대한 엔드포인트 및 Microsoft Entra 토큰을 검색합니다. REST 요청에서 연결을 설정하려면 두 값이 모두 필요합니다.

1. Azure 포털 검색 서비스로 이동합니다.

2. 검색 엔드포인트를 가져오려면 개요 페이지에서 URL을 복사합니다. 검색 엔드포인트의 예는 .입니다 https://my-service.search.windows.net.

3. Microsoft Entra 토큰을 가져오려면 로컬 시스템에서 다음 명령을 실행합니다. 이 단계를 수행하려면 빠른 시작을 완료해야 합니다. 키 없이 연결합니다.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

데이터 준비

이 섹션에서는 지원되는 데이터 원본에 파일을 업로드하고 역할을 할당하며 연결 정보를 가져와 통합 벡터화를 위해 데이터를 준비합니다.

임베딩 모델 준비

이 섹션에서는 역할을 할당하고, 엔드포인트를 가져오고, 지원되는 포함 모델 배포하여 통합 벡터화를 위한 Azure AI 리소스를 준비합니다.

변수 설정

이 섹션에서는 Azure AI 검색 서비스, 지원되는 데이터 원본 및 지원되는 포함 모델 연결 정보를 지정합니다.

1. Visual Studio Code에서 다음의 자리 표시자들을 .rest 또는 .http 파일에 붙여넣으십시오.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
   

2. @baseUrl를 검색 엔드포인트로 바꾸고, @token를 Get connection information for Azure AI 검색에서 얻은 Microsoft Entra 토큰으로 바꿉니다.

3. 데이터 원본에 따라 다음 변수를 추가합니다.

   데이터 원본	변수	이 정보를 입력합니다.
   Azure Blob Storage (Azure 블롭 스토리지)	@storageConnectionString 및 @blobContainer	연결 문자열 및 데이터 준비 단계에서 생성한 컨테이너의 이름입니다.
   ADLS Gen2	@storageConnectionString 및 @blobContainer	연결 문자열 및 데이터 준비 단계에서 생성한 컨테이너의 이름입니다.
   OneLake	@workspaceId 및 @lakehouseId	데이터 준비에서 얻은 작업 영역 및 레이크하우스 ID입니다.

4. 포함 모델 공급자에 따라 다음 변수를 추가합니다.

   임베딩 모델 제공업체	변수	이 정보를 입력합니다.
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentName및 @aoaiModelName	임베딩 모델 준비에서 얻은 엔드포인트, 배포 이름, 모델 이름입니다.
   Azure 비전	@AiFoundryEndpoint	포함 모델 준비에서 얻은 엔드포인트입니다.

5. 변수를 확인하려면 다음 요청을 보냅니다.

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   

   인접한 창에 응답이 표시됩니다. 기존 인덱스가 있으면 목록에 나열됩니다. 그렇지 않으면 목록이 비어 있습니다. HTTP 코드가 200 OK이면, 계속 진행할 준비가 된 것입니다.

귀하의 데이터에 연결

이 섹션에서는 인덱서 기반 인덱싱을 위해 지원되는 데이터 원본 에 연결합니다. Azure AI 검색 indexer는 형식과 자격 증명 및 컨테이너가 지정된 데이터 원본이 필요합니다.

1. 데이터 원본 만들기를 사용하여 인덱싱하는 동안 연결 정보를 제공하는 데이터 원본을 정의합니다.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-data-source",
       "type": "azureblob",
       "subtype": null,
       "credentials": {
           "connectionString": "{{storageConnectionString}}"
       },
       "container": {
           "name": "{{blobContainer}}",
           "query": null
       },
       "dataChangeDetectionPolicy": null,
       "dataDeletionDetectionPolicy": null
     }
   

2. 데이터 원본으로 설정 type : azureblob 또는 adlsgen2.

3. 데이터 원본을 만들려면 요청 보내기를 선택합니다.

4. OneLake를 사용하는 경우 credentials.connectionString을 ResourceId={{workspaceId}}로 설정하고, container.name을 {{lakehouseId}}로 설정합니다.

역량 개발

이 섹션에서는 내 콘텐츠를 청크로 나누기 위해 내장 스킬을 호출하고, 그 청크의 벡터 표현을 생성하기 위해 임베딩 스킬을 사용하는 기술 세트 를 생성합니다. 이 기술 세트는 색인 작성 중에 이후 섹션에서 실행됩니다.

기본 제공 기술을 호출하여 콘텐츠를 세분화되게 하다

콘텐츠를 청크로 분할하면 포함 모델의 요구 사항을 충족하고 잘림으로 인한 데이터 손실을 방지할 수 있습니다. 청크 분할에 대한 자세한 내용은 벡터 검색 솔루션에 대한 큰 문서 청크를 참조하세요.

기본 제공 데이터 청크의 경우 Azure AI 검색 텍스트 분할 기술 및 Azure Content Understanding 기술 제공합니다. 텍스트 분할 기술은 텍스트를 특정 길이의 문장이나 페이지로 나누는 반면, Azure Content Understanding 기술은 단락 경계를 존중하는 의미 체계의 레이아웃 인식 청크를 수행합니다.

1. 기술 세트 만들기를 사용하여 기술 세트를 정의합니다.

   ### Create a skillset
   POST {{baseUrl}}/skillsets?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-skillset",
       "skills": []
     }
   

2. skills 배열에서 텍스트 분할 기술 또는 Azure Content Understanding 기술을 호출합니다. 다음 정의 중 하나를 붙여넣을 수 있습니다.

       "skills": [
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "name": "my-text-split-skill",
          "textSplitMode": "pages",
          "maximumPageLength": 2000,
          "pageOverlapLength": 500,
          "maximumPagesToTake": 0,
          "unit": "characters",
          "defaultLanguageCode": "en",
          "inputs": [
           {
             "name": "text",
             "source": "/document/text",
             "inputs": []
           }
          ],
          "outputs": [
           {
             "name": "textItems"
           }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
          "name": "my-content-understanding-skill",
          "context": "/document",
          "chunkingProperties": {
            "method": "semantic",
            "unit": "tokens",
            "maximumLength": 500
          },
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "text_sections",
             "targetName": "text_sections"
           }
          ]
        }
       ]
   

포함 기능을 호출하여 청크를 벡터화합니다

청크로 분할한 콘텐츠를 벡터화하려면, 스킬 세트에 지원되는 임베딩 모델을 참조하는 임베딩 스킬을 포함해야 합니다.

1. skills 배열에서 기본 제공 청킹 기술 다음에 Azure OpenAI 임베딩 기술 또는 Azure Vision 멀티모달 임베딩 기술(미리 보기)을 호출합니다. 다음 정의 중 하나를 붙여넣을 수 있습니다.

        {
          "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
          "resourceUri": "{{aoaiEndpoint}}",
          "deploymentId": "{{aoaiDeploymentName}}",
          "modelName": "{{aoaiModelName}}",
          "dimensions": 1536,
          "inputs": [
            {
              "name": "text",
              "source": "/document/text"
            }
          ],
          "outputs": [
            {
              "name": "embedding"
            }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
          "context": "/document",
          "modelVersion": "2023-04-15",
          "inputs": [
            {
              "name": "url",
              "source": "/document/metadata_storage_path"
            },
            {
              "name": "queryString",
              "source": "/document/metadata_storage_sas_token"
            }
          ],
          "outputs": [
            {
              "name": "vector"
            }
          ]
        }
   

   참고

   Azure Vision 멀티모달 포함 기술은 미리 보기로 제공됩니다. 이 기술을 호출하려면 최신 미리 보기 API 버전을 사용합니다.

2. Azure OpenAI Embedding 기능을 사용하는 경우, 을(를) 포함 모델에서 생성된 임베딩 수로 설정합니다.

3. Azure Vision 멀티모달 임베딩 기술을 사용하는 경우 배열 뒤에 skills를 연결합니다. 이 첨부 파일은 청구를 위한 것입니다.

       "skills": [ ... ],
       "cognitiveServices": {
         "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
         "subdomainUrl": "{{AiFoundryEndpoint}}"
        }
   

4. 기술 세트를 만들려면 요청 보내기를 선택합니다.

벡터 인덱스 만들기

이 섹션에서는 vector index 만들어 Azure AI 검색 서비스에서 물리적 데이터 구조를 설정합니다. 벡터 인덱스의 스키마에는 다음이 필요합니다.

• 이름
• 키 필드(문자열)
• 하나 이상의 벡터 필드
• 벡터 구성

벡터 필드는 청크 분할된 데이터의 숫자 표현을 저장합니다. 검색 가능하고 검색 결과로 가져올 수 있어야 하지만, 필터링이나 패싯팅이나 정렬 기능은 지원하지 않습니다. 또한 분석기, 정규화기 또는 동의어 맵 할당을 가질 수 없습니다.

다음 단계의 샘플 인덱스에는 벡터 필드 외에도 사람이 읽을 수 있는 콘텐츠에 대한 비벡터 필드가 포함되어 있습니다. 벡터화하려는 콘텐츠에 해당하는 일반 텍스트를 포함하는 것이 일반적입니다. 자세한 내용은 벡터 인덱스 만들기를 참조하세요.

1. 인덱스 만들기를 사용하여 벡터 인덱스의 스키마를 정의합니다.

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-vector-index",
       "fields": [],
       "vectorSearch": []
     }
   

2. 섹션에 벡터 검색 구성 을 추가합니다 vectorSearch .

       "vectorSearch": {
         "algorithms": [
           {
             "name": "hnsw-algorithm",
             "kind": "hnsw",
             "hnswParameters": {
               "m": 4,
               "efConstruction": 400,
               "efSearch": 100,
               "metric": "cosine"
             }
           }
         ],
         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
           }
         ]
       }
   

   vectorSearch.algorithms 는 벡터 필드 인덱싱 및 쿼리에 사용되는 알고리즘을 지정하고 vectorSearch.profiles 알고리즘 구성을 벡터 필드에 할당할 수 있는 프로필에 연결합니다.

3. 임베딩 모델에 따라 vectorSearch.algorithms.metric을(를) 업데이트합니다. 거리 메트릭에 유효한 값은cosine, dotproduct및 euclideanhamming.

4. 배열에 fields 필드를 추가합니다. 문서 식별을 위한 키 필드, 사람이 읽을 수 있는 콘텐츠의 비벡터 필드 및 포함을 위한 벡터 필드를 포함합니다.

       "fields": [
         {
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "filterable": true
         },
         {
           "name": "title",
           "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
         },
         {
           "name": "titleVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         },
         {
           "name": "content",
           "type": "Edm.String",
            "searchable": true,
            "retrievable": true
         },
         {
           "name": "contentVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         }
       ]
   

5. 포함 기술에 따라 각 벡터 필드에 대해 다음 값으로 설정합니다 dimensions .

   스킬 임베딩	이 값을 입력합니다.
   Azure OpenAI	임베딩 모델에서 생성된 임베딩 수입니다.
   Azure 비전	1024

인덱스로 벡터라이저 추가

이 섹션에서는 인덱스에서 벡터 라이저를 정의하여 쿼리 시 벡터 화를 사용하도록 설정합니다. 벡터라이저는 데이터를 인덱싱하는 포함 모델을 사용하여 검색 문자열 또는 이미지를 벡터 검색을 위해 벡터로 디코딩합니다.

1. Azure OpenAI 벡터라이저 또는 Azure Vision 벡터라이저(미리 보기)를 추가합니다vectorSearch.profiles. 다음 정의 중 하나를 붙여넣을 수 있습니다.

         "profiles": [ ... ],
         "vectorizers": [
           {
             "name": "my-openai-vectorizer",
             "kind": "azureOpenAI",
             "azureOpenAIParameters": {
               "resourceUri": "{{aoaiEndpoint}}",
               "deploymentId": "{{aoaiDeploymentName}}",
               "modelName": "{{aoaiModelName}}"
             }
           },
           {
             "name": "my-ai-services-vision-vectorizer",
             "kind": "aiServicesVision",
             "aiServicesVisionParameters": {
               "resourceUri": "{{AiFoundryEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   참고

   Azure Vision 벡터라이저는 미리 보기로 제공됩니다. 이 벡터라이저를 호출하려면 최신 미리 보기 API 버전을 사용합니다.

2. vectorSearch.profiles에서 벡터라이저를 지정합니다.

         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
             "vectorizer": "my-openai-vectorizer"
           }
         ]
   

3. 벡터 인덱서를 만들려면 요청 보내기를 선택합니다.

인덱서 만들기

이 섹션에서는 데이터 검색에서 기술 세트 실행, 인덱 싱에 이르기까지 전체 벡터화 파이프라인을 구동하는 인덱서를 만듭니다. 일정 에 따라 인덱서를 실행 하여 제한으로 인해 누락된 변경 내용 또는 문서를 처리하는 것이 좋습니다.

1. 인덱서 만들기를 사용하여 벡터화 파이프라인을 실행하는 인덱서 정의

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-indexer",
       "dataSourceName": "my-data-source",
       "targetIndexName": "my-vector-index",
       "skillsetName": "my-skillset",
       "schedule": {
         "interval": "PT2H"
       },
       "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null
       }
     }
   

2. 인덱서를 만들려면 요청 보내기를 선택합니다.

벡터 쿼리를 실행하여 인덱싱 확인

이 섹션에서는 벡터 쿼리를 만들어 콘텐츠가 성공적으로 인덱싱되었는지 확인합니다. 이전 섹션에서 벡터라이저를 구성했으므로 검색 엔진은 일반 텍스트 또는 이미지를 쿼리 실행을 위해 벡터로 디코딩할 수 있습니다.

1. Documents - Search Post 기능을 사용하여 쿼리 시간에 벡터화된 쿼리를 정의합니다.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "count": true,
       "select": "title, content",
       "vectorQueries": [
           {
             "kind": "text",
             "text": "a sample text string for integrated vectorization",
             "fields": "titleVector, contentVector",
             "k": "3"
           }
       ]
     }
   

   참고

   Azure Vision 벡터라이저는 미리 보기로 제공됩니다. 이 벡터라이저를 호출하려면 최신 미리 보기 API 버전을 사용합니다.

   통합 벡터화를 kind 호출하는 쿼리의 경우 텍스트 문자열을 texttext 지정해야 합니다. 이 문자열은 벡터 필드에 할당된 벡터라이저에 전달됩니다. 자세한 내용은 통합 벡터화를 사용한 쿼리를 참조하세요.

2. 벡터 쿼리를 실행하려면 요청 보내기를 선택합니다.

관련 콘텐츠

• Azure AI 검색의 통합 벡터 임베딩
• Quickstart: Azure Portal에서 벡터 검색
• 통합 벡터화를 위한 Python 샘플