Meningkatkan ke REST API terbaru di Azure AI Search

Artikel
04/19/2024

Gunakan artikel ini untuk memigrasikan panggilan data plane ke versi Search REST API yang lebih baru.

2023-11-01 adalah versi stabil terbaru. Peringkat dan dukungan semantik untuk vektor pengindeksan dan kueri umumnya tersedia dalam versi ini.
Pratinjau 10-10-2023 adalah versi pratinjau terbaru. Fitur pratinjau termasuk vektorisasi kueri bawaan, pemotongan dan vektorisasi data bawaan selama pengindeksan (menggunakan keterampilan Pemisahan Teks dan keterampilan Penyematan Azure OpenAI). Lihat sampel kode dan panduan untuk bantuan terkait fitur baru.
Pratinjau 2023-07-01 adalah REST API pertama untuk dukungan vektor. Sekarang tidak digunakan lagi dan Anda harus segera bermigrasi ke pratinjau 2023-11-01 atau 2023-10-01.

Catatan

Dokumen referensi API sekarang diberi versi. Untuk mendapatkan konten yang tepat, buka halaman referensi lalu filter menurut versi, menggunakan pemilih yang terletak di atas daftar isi.

Cara meningkatkan

Azure AI Search memutuskan kompatibilitas mundur sebagai upaya terakhir. Bagian ini menyediakan instruksi untuk membantu Anda mengubah kode yang sudah ada yang tidak akan berjalan dalam versi yang lebih baru. Peningkatan diperlukan ketika:

Kode Anda mereferensikan versi API yang dihentikan atau tidak digunakan lagi dan tunduk pada satu atau beberapa perubahan yang melanggar. Versi API yang termasuk dalam kategori ini termasuk pratinjau 2023-07-10 untuk vektor dan 2019-05-06.
Kode Anda gagal saat properti yang tidak dikenal dikembalikan dalam respons API. Sebagai praktik terbaik, aplikasi Anda harus mengabaikan properti yang tidak dipahaminya.
Kode Anda mempertahankan permintaan API dan mencoba mengirim ulang permintaan tersebut ke versi API baru. Misalnya, ini mungkin terjadi jika aplikasi Anda mempertahankan token kelanjutan yang dikembalikan dari Search API (untuk informasi selengkapnya, cari @search.nextPageParameters di Referensi Search API).

Tingkatkan ke pratinjau 2023-10-01

Versi ini identik dengan 2023-11-01 tetapi memiliki fitur tambahan dalam pratinjau publik: vektorizer kueri bawaan dan mode prafilter vektor. Jika Anda ingin menggunakan fitur tersebut, Anda harus meningkatkan ke versi pratinjau terbaru.

Konfigurasi algoritma pencarian vektor di dalam indeks pencarian identik dengan 2023-11-01. Untuk memperbaiki perubahan yang melanggar dari pratinjau 2023-07-01, ikuti instruksi di bagian berikutnya.

Tingkatkan ke 2023-11-01

Versi ini memiliki perubahan yang melanggar dan perbedaan perilaku untuk peringkat semantik dan dukungan pencarian vektor.

Peringkat semantik umumnya tersedia dan tidak lagi menggunakan queryLanguage properti . Ini juga memerlukan semanticConfiguration definisi.

Untuk meningkatkan dari 2020-06-30-preview, buat semanticConfiguration untuk mengganti .searchFields Lihat Melakukan migrasi dari versi pratinjau untuk langkah-langkahnya.
Dukungan pencarian vektor diperkenalkan dalam Buat atau Perbarui Indeks (pratinjau 2023-07-01).

Untuk meningkatkan dari pratinjau 2023-07-01, ganti nama dan restrukturisasi konfigurasi vektor dalam indeks, dan tulis ulang sintaks kueri vektor Anda menggunakan instruksi di bagian ini.

Untuk meningkatkan dari pratinjau 2023-10-01, tidak ada perubahan yang melanggar, tetapi ada satu perbedaan perilaku: vectorFilterMode default berubah dari postfilter menjadi prafilter untuk ekspresi filter. Jika kode pratinjau 2023-10-01 Anda tidak diatur vectorFilterMode secara eksplisit, pastikan Anda memahami perilaku baru, atau mengatur mode ke postfilter untuk mempertahankan perilaku lama.

Tip

portal Azure mendukung jalur peningkatan satu klik untuk indeks pratinjau 2023-07-01. Portal mendeteksi indeks pratinjau 2023-07-01 dan menyediakan tombol Migrasi . Sebelum memilih Migrasi, pilih Edit JSON untuk meninjau skema yang diperbarui terlebih dahulu. Anda harus menemukan skema yang sesuai dengan perubahan yang dijelaskan di bagian ini. Migrasi portal hanya menangani indeks dengan satu konfigurasi algoritma pencarian vektor, membuat profil default yang memetakan ke algoritma. Indeks dengan beberapa konfigurasi memerlukan migrasi manual.

Berikut adalah langkah-langkah untuk bermigrasi dari pratinjau 2023-07-01:

Panggil Dapatkan Indeks untuk mengambil definisi yang ada.

Ubah konfigurasi pencarian vektor. API ini memperkenalkan konsep *profil vektor yang menggabungkan konfigurasi terkait vektor dengan satu nama. Ini juga mengganti nama algorithmConfigurations menjadi algorithms.

Ganti nama algorithmConfigurations menjadi algorithms. Ini hanya penggantian nama array. Konten kompatibel mundur. Ini berarti parameter konfigurasi HNSW Anda yang ada dapat digunakan.
Tambahkan profiles, berikan nama dan konfigurasi algoritma untuk masing-masing konfigurasi.

Sebelum migrasi (pratinjau 2023-07-01):

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

Setelah migrasi (2023-11-01):

  "vectorSearch": {
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ],
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ]
  }

Ubah definisi bidang vektor, ganti vectorSearchConfiguration dengan vectorSearchProfile. Pastikan nama profil diselesaikan ke definisi profil vektor baru, dan bukan nama konfigurasi algoritma. Properti bidang vektor lainnya tetap tidak berubah. Misalnya, mereka tidak dapat difilter, dapat diurutkan, atau dapat difaset, atau menggunakan penganalisis atau normalizer atau peta sinonim.

Sebelum (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"
  }

Setelah (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"
  }

Panggil Buat atau Perbarui Indeks untuk memposting perubahan.

Ubah Search POST untuk mengubah sintaks kueri. Perubahan API ini memungkinkan dukungan untuk jenis kueri vektor polimorfik.

Ganti nama vectors menjadi vectorQueries.
Untuk setiap kueri vektor, tambahkan kind, atur ke "vektor".
Untuk setiap kueri vektor, ganti nama value menjadi vector.
Secara opsional, tambahkan vectorFilterMode jika Anda menggunakan ekspresi filter. Defaultnya adalah prafilter untuk indeks yang dibuat setelah 2023-10-01. Indeks yang dibuat sebelum tanggal tersebut hanya mendukung postfilter, terlepas dari cara Anda mengatur mode filter.

Sebelum (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"
}

Setelah (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"
}

Langkah-langkah ini menyelesaikan migrasi ke versi API 2023-11-01.

Meningkatkan ke 2020-06-30

Dalam versi ini, ada satu perubahan yang melanggar dan beberapa perbedaan perilaku. Fitur yang tersedia secara umum meliputi:

Penyimpanan pengetahuan, yang merupakan penyimpanan yang terus menerus untuk konten diperkaya yang dibuat melalui keterampilan, didesain untuk analisis downstream dan pemrosesan melalui aplikasi lainnya. Penyimpanan pengetahuan dibuat melalui REST API Azure AI Search tetapi berada di Azure Storage.

Breaking change

Kode yang ditulis terhadap versi API sebelumnya berhenti pada 2020-06-30 dan yang lebih baru jika kode berisi fungsionalitas berikut:

Setiap literal Edm.Date (tanggal yang terdiri dari tahun-bulan-hari, seperti 2020-12-12) dalam ekspresi filter harus mengikuti format Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Perubahan ini diperlukan untuk menangani hasil kueri yang salah atau tidak terduga karena perbedaan zona waktu.

Perubahan perilaku

Algoritma peringkat BM25 menggantikan algoritma peringkat sebelumnya dengan teknologi yang lebih baru. Layanan yang dibuat setelah 2019 menggunakan algoritma ini secara otomatis. Untuk layanan lama, Anda harus mengatur parameter untuk menggunakan algoritma baru.
Hasil yang diurutkan untuk nilai null telah berubah dalam versi ini, dengan nilai null muncul terlebih dahulu jika pengurutannya adalah asc dan terakhir jika pengurutannya adalah desc. Jika Anda menulis kode untuk menangani pengurutan nilai null, perhatikan perubahan ini.

Meningkatkan ke 2019-05-06

Beberapa fitur sekarang tersedia secara umum dalam versi API ini, yang meliputi:

Autocomplete adalah fitur typeahead yang melengkapi sebagian input istilah tertentu.
Jenis kompleks menyediakan dukungan asli untuk data objek terstruktur dalam indeks pencarian.
Mode penguraian JsonLines, bagian dari pengindeksan Azure Blob, membuat satu dokumen pencarian per entitas JSON yang dipisahkan oleh baris baru.
Pengayaan AI menyediakan pengindeksan yang menggunakan mesin pengayaan AI layanan Azure AI.

Perubahan mencolok

Kode yang ditulis terhadap jeda versi API sebelumnya pada 2019-05-06 dan yang lebih baru jika berisi fungsionalitas berikut:

Ketik properti untuk Azure Cosmos DB. Untuk pengindeks yang menargetkan Azure Cosmos DB untuk sumber data NOSQL API , ubah "type": "documentdb" ke "type": "cosmosdb".
Jika penanganan kesalahan pengindeks Anda menyertakan referensi ke status properti , Anda harus menghapusnya. Kami menghapus status dari respons kesalahan karena tidak memberikan informasi yang berguna.
String koneksi sumber data tidak lagi dikembalikan dalam respons. Dari versi API 2019-05-06 dan 2019-05-06-Preview dan seterusnya, API sumber data tidak lagi mengembalikan string koneksi dalam respons operasi REST apa pun. Di versi API sebelumnya, untuk sumber data yang dibuat menggunakan POST, Azure AI Search mengembalikan 201 diikuti oleh respons OData, yang berisi string koneksi dalam teks biasa.
Keterampilan kognitif Pengenalan Entitas Bernama dihentikan. Jika Anda memanggil keterampilan Pengenalan Entitas Nama dalam kode Anda, panggilan gagal. Fungsionalitas penggantinya adalah Kemampuan Pengenalan Entitas (V3). Ikuti rekomendasi dalam Keterampilan yang tidak digunakan lagi untuk bermigrasi ke keterampilan yang didukung.

Meningkatkan jenis kompleks

API versi 2019-05-06 menambahkan dukungan formal untuk jenis kompleks. Jika kode Anda menerapkan rekomendasi sebelumnya untuk kesetaraan jenis kompleks di 2017-11-11-Preview atau 2016-09-01-Preview, ada beberapa batas yang baru dan diubah mulai versi 2019-05-06 yang perlu Anda ketahui:

Batasan kedalaman subbidang dan jumlah koleksi kompleks per indeks telah diturunkan. Jika Anda membuat indeks yang melebihi batas ini menggunakan versi API pratinjau, upaya apa pun untuk memperbarui atau membuatnya kembali menggunakan versi API 2019-05-06 akan gagal. Jika Anda menemukan diri Anda dalam situasi ini, Anda perlu mendesain ulang skema Anda agar sesuai dalam batas baru lalu membangun kembali indeks Anda.
Ada batas baru mulai versi api 2019-05-06 pada jumlah elemen koleksi kompleks per dokumen. Jika Anda membuat indeks dengan dokumen yang melebihi batas ini menggunakan versi API pratinjau, upaya apa pun untuk mengindeks kembali data tersebut menggunakan versi API 2019-05-06 akan gagal. Jika Anda menemukan diri Anda dalam situasi ini, Anda perlu mengurangi jumlah elemen pengumpulan kompleks per dokumen sebelum mengindeks ulang data Anda.

Untuk informasi selengkapnya, lihat Batas layanan untuk Pencarian Azure AI.

Cara meningkatkan struktur jenis kompleks lama

Jika kode Anda menggunakan jenis kompleks dengan salah satu versi API pratinjau yang lebih lama, Anda mungkin menggunakan format definisi indeks yang terlihat seperti ini:

{
  "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" }
  ]
}

Format seperti pohon yang lebih baru untuk mendefinisikan bidang indeks diperkenalkan dalam API versi 2017-11-11-Preview. Dalam format baru, setiap bidang kompleks memiliki kumpulan bidang tempat sub-bidangnya ditentukan. Dalam API versi 2019-05-06, format baru ini digunakan secara eksklusif dan upaya membuat atau memperbarui indeks menggunakan format lama akan gagal. Jika Anda memiliki indeks yang dibuat menggunakan format lama, Anda harus menggunakan API versi 2017-11-11-Preview untuk memperbaruinya ke format baru sebelum dapat dikelola menggunakan API versi 2019-05-06.

Anda dapat memperbarui indeks "flat" ke format baru dengan langkah-langkah berikut menggunakan API versi 2017-11-11-Preview:

Lakukan permintaan GET untuk mengambil indeks Anda. Jika permintaan sudah dalam format baru, Anda sudah selesai.
Terjemahkan indeks dari format "flat" ke format baru. Anda harus menulis kode untuk tugas ini karena tidak ada kode sampel yang tersedia pada saat penulisan ini.
Lakukan permintaan PUT untuk memperbarui indeks ke format baru. Hindari mengubah detail indeks lainnya, seperti kemampuan pencarian/filterabilitas bidang, karena perubahan yang memengaruhi ekspresi fisik indeks yang ada tidak diizinkan oleh API Indeks Pembaruan.