Azure AI 검색에서 최신 REST API로 업그레이드
이 문서를 사용하여 데이터 평면 호출을 검색 REST API의 새로운 버전으로 마이그레이션합니다.
2023-11-01은 최신 안정 버전입니다. 이 버전에서는 일반적으로 의미 체계 순위 지정과 인덱싱 및 쿼리 벡터에 대한 지원을 사용할 수 있습니다.
2023-10-01-preview는 최신 미리 보기 버전입니다. 미리 보기 기능에는 기본 제공 쿼리 벡터화, 인덱싱 동안 기본 제공 데이터 청크 및 벡터화가 포함됩니다(텍스트 분할 기술 및 Azure OpenAI Embedding 기술 사용). 새 기능에 대한 도움말은 코드 샘플 및 연습을 참조하세요.
2023-07-01-preview는 벡터 지원을 위한 첫 번째 REST API였습니다. 이제 더 이상 사용되지 않으며 2023-11-01 또는 2023-10-01-preview로 즉시 마이그레이션해야 합니다.
참고 항목
이제 API 참조 문서의 버전이 관리됩니다. 올바른 콘텐츠를 얻으려면 참조 페이지를 연 다음 목차 위에 있는 선택기를 사용하여 버전별로 필터링하세요.
업그레이드 방법
Azure AI Search는 최후의 수단으로 이전 버전과의 호환성을 중단합니다. 이 섹션에서는 최신 버전에서 실행되지 않는 기존 코드를 수정하는 데 도움이 되는 지침을 제공합니다. 업그레이드는 다음과 같은 경우에 필요합니다.
코드가 사용 중지되었거나 사용되지 않는 API 버전을 참조하며 하나 이상의 중요한 변경 사항이 적용될 수 있음. 이 범주에 속하는 API 버전에는 벡터용 2023-07-10-preview 및 2019-05-06이 포함됩니다.
인식할 수 없는 속성이 API 응답에 반환되는 경우 코드가 실패합니다. 애플리케이션이 이해하지 못하는 속성을 무시하는 것이 가장 좋습니다.
코드는 API 요청을 보관하고 새 API 버전으로 다시 전송하려 합니다. 예를 들어 애플리케이션이 검색 API에서 반환된 연속 토큰을 보관하는 경우 이런 현상이 발생할 수 있습니다(자세한 내용은 검색 API 참조의
@search.nextPageParameters를 참조).
2023-10-01-preview로 업그레이드
이 버전은 2023-11-01과 동일하지만 공개 미리 보기에는 기본 제공 쿼리 벡터라이저 및 벡터 사전 필터링 모드의 추가 기능이 있습니다. 이러한 기능을 사용하려면 최신 미리 보기 버전으로 업그레이드해야 합니다.
검색 인덱스 내의 벡터 검색 알고리즘 구성은 2023-11-01과 동일합니다. 2023-07-01-preview의 호환성이 손상되는 변경 문제를 해결하려면 다음 섹션의 지침을 따르세요.
2023-11-01로 업그레이드
이 버전에는 의미 체계 순위 지정 및 벡터 검색 지원에 대한 호환성이 손상되는 변경과 동작 차이가 있습니다.
의미 체계 순위 지정은 일반적으로 사용할 수 있으며 더 이상
queryLanguage속성을 사용하지 않습니다. 또한semanticConfiguration정의가 필요합니다.2020-06-30-preview에서 업그레이드하려면
searchFields을(를) 대체할semanticConfiguration을(를) 만듭니다. 단계는 미리 보기 버전에서 마이그레이션을 참조하세요.벡터 검색 지원은 인덱스 만들기 또는 업데이트(2023-07-01-preview)에 도입되었습니다.
2023-07-01-preview에서 업그레이드하려면 인덱스에서 벡터 구성의 이름을 바꾸고 재구성하고 이 섹션의 지침을 사용하여 벡터 쿼리 구문을 다시 작성합니다.
2023-10-01-preview에서 업그레이드하려면 호환성이 손상되는 변경은 없지만 한 가지 동작 차이가 있습니다. 즉, 필터 식에 대해
vectorFilterMode기본값이 postfilter에서 prefilter로 변경되었습니다. 2023-10-01-preview 코드가vectorFilterMode을(를) 명시적으로 설정하지 않은 경우 새 동작을 이해했는지 확인하거나 이전 동작을 유지하도록 모드를 사후 필터로 설정하세요.
팁
Azure Portal은 2023-07-01-preview 인덱스에 대한 원클릭 업그레이드 경로를 지원합니다. 포털은 2023-07-01-preview 인덱스를 검색하고 마이그레이션 단추를 제공합니다. 마이그레이션을 선택하기 전에 먼저 JSON 편집을 선택하여 업데이트된 스키마를 검토합니다. 이 섹션에 설명된 변경 내용을 준수하는 스키마를 찾아야 합니다. 포털 마이그레이션은 하나의 벡터 검색 알고리즘 구성으로 인덱스만 처리하여 알고리즘에 매핑되는 기본 프로필을 만듭니다. 여러 구성이 포함된 인덱스에는 수동 마이그레이션이 필요합니다.
2023-07-01-preview에서 마이그레이션하는 단계는 다음과 같습니다.
기존 정의를 검색하려면 인덱스 가져오기를 호출합니다.
벡터 검색 구성을 수정합니다. 이 API는 벡터 관련 구성을 하나의 이름으로 묶는 *벡터 프로필 개념을 도입합니다. 또한
algorithmConfigurations의 이름을algorithms로 바꿉니다.algorithmConfigurations의 이름을algorithms로 바꿉니다. 이는 배열의 이름만 바꿉니다. 콘텐츠는 이전 버전과 호환됩니다. 이는 기존 HNSW 구성 매개 변수를 사용할 수 있음을 의미합니다.profiles를 추가하여 각각에 대한 이름과 알고리즘 구성을 제공합니다.
마이그레이션 전(2023-07-01-preview):
"vectorSearch": { "algorithmConfigurations": [ { "name": "myHnswConfig", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } } ]}마이그레이션 후(2023-11-01):
"vectorSearch": { "profiles": [ { "name": "myHnswProfile", "algorithm": "myHnswConfig" } ], "algorithms": [ { "name": "myHnswConfig", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } } ] }벡터 필드 정의를 수정하여
vectorSearchConfiguration을vectorSearchProfile로 바꿉니다. 프로필 이름이 알고리즘 구성 이름이 아닌 새 벡터 프로필 정의로 확인되는지 확인합니다. 다른 벡터 필드 속성은 변경되지 않습니다. 예를 들어, 필터링, 정렬 또는 패싯이 가능하지 않으며 분석기, 노멀라이저 또는 동의어 맵을 사용할 수도 없습니다.이전(2023-07-01-preview):
{ "name": "contentVector", "type": "Collection(Edm.Single)", "key": false, "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "", "searchAnalyzer": "", "indexAnalyzer": "", "normalizer": "", "synonymMaps": "", "dimensions": 1536, "vectorSearchConfiguration": "myHnswConfig" }이후(2023-11-01):
{ "name": "contentVector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "", "searchAnalyzer": "", "indexAnalyzer": "", "normalizer": "", "synonymMaps": "", "dimensions": 1536, "vectorSearchProfile": "myHnswProfile" }변경 내용을 게시하려면 인덱스 만들기 또는 업데이트를 호출합니다.
쿼리 구문을 변경하려면 검색 POST를 수정합니다. 이 API 변경으로 다형성 벡터 쿼리 형식을 지원할 수 있습니다.
vectors의 이름을vectorQueries로 바꿉니다.- 각 벡터 쿼리에 대해
kind를 추가하고 이를 "벡터"로 설정합니다. - 각 벡터 쿼리에 대해
value의 이름을vector로 바꿉니다. - 선택적으로 필터 식을 사용하는 경우
vectorFilterMode를 추가합니다. 기본값은 2023년 10월 1일 이후에 만들어진 인덱스의 사전 필터입니다. 해당 날짜 이전에 만들어진 인덱스는 필터 모드 설정 방법에 관계없이 사후 필터만 지원합니다.
이전(2023-07-01-preview):
{ "search": (this parameter is ignored in vector search), "vectors": [ { "value": [ 0.103, 0.0712, 0.0852, 0.1547, 0.1183 ], "fields": "contentVector", "k": 5 } ], "select": "title, content, category" }이후(2023-11-01):
{ "search": "(this parameter is ignored in vector search)", "vectorQueries": [ { "kind": "vector", "vector": [ 0.103, 0.0712, 0.0852, 0.1547, 0.1183 ], "fields": "contentVector", "k": 5 } ], "vectorFilterMode": "preFilter", "select": "title, content, category" }
이러한 단계를 통해 2023-11-01 API 버전으로의 마이그레이션이 완료됩니다.
2020-06-30으로 업그레이드
이 버전에는 한 가지 호환성이 손상되는 변경과 몇 가지 동작 차이가 있습니다. 일반 공급한 기능은 다음과 같습니다.
- 기술 세트를 통해 생성되고, 다운스트림 분석 및 다른 애플리케이션을 통한 처리를 위해 생성된 보강 콘텐츠의 영구 스토리지인 지식 저장소. 지식 저장소는 Azure AI Search REST API를 통해 생성되지만 Azure Storage에 상주합니다.
주요 변경 내용
코드에 다음 기능이 포함된 경우 이전 API 버전에 대해 작성된 코드는 2020-06-30 이상에서 중단됩니다.
- 필터 식에서 Edm.Date 리터럴(
2020-12-12와 같이 연-월-일로 구성된 날짜)은 Edm.DateTimeOffset 형식(2020-12-12T00:00:00Z)을 따라야 합니다. 이 변경은 표준 시간대 차이로 인해 발생하는 잘못되었거나 예기치 않은 쿼리 결과를 처리하는 데 필요했습니다.
동작 변경
BM25 순위 지정 알고리즘은 이전 순위 지정 알고리즘을 최신 기술로 대체합니다. 2019년 이후에 만들어진 서비스는 이 알고리즘을 자동으로 사용합니다. 이전 서비스의 경우 새 알고리즘을 사용하려면 매개 변수를 설정해야 합니다.
이 버전에서는 null 값에 대해 정렬된 결과가 변경되었고, 정렬이
asc이면 null 값이 처음에 표시되고 정렬이desc이면 마지막에 표시됩니다. null 값을 정렬하는 방법을 처리하는 코드를 작성한 경우 이 변경 내용을 알고 있어야 합니다.
2019-05-06으로 업그레이드
이 API 버전에서 일반 공급되는 기능은 다음과 같습니다.
- 자동 완성 - 부분적으로 지정된 용어 입력을 완성하는 미리 입력 기능입니다.
- 복합 형식 - 검색 인덱스의 구조화된 개체 데이터에 대한 네이티브 지원을 제공합니다.
- Azure Blob 인덱싱의 일부인 JsonLines 구문 분석 모드는 JSON 엔터티마다 하나의 검색 문서를 만들고, 이 문서는 새로운 행으로 구분됩니다.
- AI 보강은 Azure AI 서비스의 AI 보강 엔진을 사용하는 인덱싱을 제공합니다.
호환성이 손상되는 변경
이전 API 버전에 대해 작성된 코드는 다음 기능이 포함된 경우 2019-05-06 이상에서 중단됩니다.
Azure Cosmos DB의 Type 속성입니다. Azure Cosmos DB for NoSQL API 데이터 원본을 대상으로 하는 인덱서의 경우
"type": "documentdb"을(를)"type": "cosmosdb"(으)로 변경합니다.인덱서 오류 처리에
status속성에 대한 참조가 포함된 경우 제거해야 합니다. 유용한 정보를 제공하지 않아 오류 응답에서 상태를 제거했습니다.데이터 원본 연결 문자열은 응답에서 더 이상 반환되지 않습니다. API 버전 2019-05-06 및 2019-05-06-Preview부터 데이터 원본 API가 더 이상 REST 작업에 대한 응답에 연결 문자열을 반환하지 않습니다. 이전 API 버전에서는 POST를 사용하여 만든 데이터 원본에 대해 Azure AI 검색이 201을 반환한 다음, OData 응답을 반환했습니다. 여기에는 일반 텍스트 형식의 연결 문자열이 포함되어 있었습니다.
명명된 엔터티 인식 기술이 사용 중지되었습니다. 코드에서 이름 엔터티 인식 기술을 호출하면 호출이 실패합니다. 대체 기능은 엔터티 인식 기술(V3)입니다. 지원되는 기술로 마이그레이션하려면 지원되지 않는 기술의 권장 사항을 따릅니다.
복합 형식 업그레이드
API 버전 2019-05-06에 복합 형식에 대한 공식 지원이 추가되었습니다. 코드에서 2017-11-11-Preview 또는 2016-09-01-Preview와 같은 복합 형식에 대한 이전 권장 사항을 구현한 경우, 2019-05-06 버전부터 도입된 새로운 제한 사항과 변경된 제한 사항에 주의해야 합니다.
하위 필드 수준 및 인덱스당 복합 컬렉션 수에 대한 제한 사항이 감소했습니다. 미리 보기 API 버전을 사용하여 이러한 제한 사항을 초과하는 인덱스를 만든 경우, API 버전 2019-05-06을 사용하여 해당 인덱스를 업데이트하거나 다시 만들려고 하면 실패합니다. 이런 상황에 처한다면 새로운 한도 내에 맞도록 스키마를 다시 디자인한 다음 인덱스를 다시 빌드해야 합니다.
API 버전 2019-05-06부터 문서당 복합 컬렉션의 요소 수에 대한 새로운 제한 사항이 있습니다. 미리 보기 API 버전을 사용하여 이러한 제한 사항을 초과하는 인덱스를 문서에 만든 경우, API 버전 2019-05-06을 사용하여 해당 데이터의 인덱스를 다시 작성하려고 하면 실패합니다. 이 상황에 처한 경우 데이터의 인덱스를 다시 작성하기 전에 문서당 복합 컬렉션 요소 수를 줄여야 합니다.
자세한 내용은 Azure AI 검색 서비스 제한을 참조하세요.
이전 복합 형식 구조를 업그레이드하는 방법
코드가 이전 미리 보기 API 버전 중 하나에서 복합 형식을 사용 하는 경우 다음과 같은 인덱스 정의 형식을 사용할 수 있습니다.
{
"name": "hotels",
"fields": [
{ "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
{ "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
{ "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
{ "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
{ "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
{ "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
{ "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
{ "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address", "type": "Edm.ComplexType" },
{ "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
{ "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
{ "name": "Rooms", "type": "Collection(Edm.ComplexType)" },
{ "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
{ "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
{ "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
{ "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
{ "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
{ "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
{ "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
{ "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
]
}
인덱스 필드를 정의하는 트리와 유사한 최신 형식은 API 버전 2017-11-11-Preview에서 도입되었습니다. 새 형식에서 각 복합 필드에는 하위 필드가 정의된 필드 컬렉션이 있습니다. API 버전 2019-05-06에서 이 새 형식은 배타적으로 사용되며, 이전 형식을 사용하여 인덱스를 만들거나 업데이트하려는 시도가 실패합니다. 이전 형식을 사용하여 생성된 인덱스가 있는 경우 API 버전 2017-11-11-Preview를 사용하여 새 형식으로 업데이트해야 API 버전 2019-05-06을 사용하여 관리할 수 있습니다.
API 버전 2017-11-11-Preview로 다음 단계를 수행하여 "플랫" 인덱스를 새 형식으로 업데이트할 수 있습니다.
GET 요청을 수행하여 인덱스를 검색합니다. 이미 새 형식이면 완료된 것입니다.
인덱스를 "플랫" 형식에서 새 형식으로 변환합니다. 이 문서의 작성 시점을 기준으로 현재 사용할 수 있는 샘플 코드는 없으므로 이 작업에 대한 코드를 작성해야 합니다.
PUT 요청을 수행하여 인덱스를 새 형식으로 업데이트합니다. 기존 인덱스의 물리적 식에 영향을 주는 변경 내용은 인덱스 업데이트 API에서 허용되지 않으므로 필드의 검색 가능성/필터링 가능성과 같은 인덱스의 다른 세부 정보를 변경하지 마세요.
참고 항목
Azure Portal에서 이전 "플랫" 형식을 사용하여 생성된 인덱스는 관리할 수 없습니다. 가급적 빨리 "플랫" 표현에서 "트리" 표현으로 인덱스를 업그레이드하세요.
다음 단계
검색 REST API 참조 설명서를 검토합니다. 문제가 발생하는 경우 Stack Overflow에서 도움을 요청하거나 고객 지원팀에 문의하세요.