Panduan Cepat: Peringkat Semantik

Catatan

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Dalam panduan mulai cepat ini, Anda menambahkan pemeringkatan semantik ke indeks Pencarian Azure AI yang sudah ada dan menjalankan kueri semantik untuk meningkatkan relevansi hasil. Gunakan tab bahasa untuk memilih alur kerja SDK atau REST pilihan Anda.

Dalam panduan memulai cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk .NET untuk menambahkan peringkat semantik ke indeks pencarian yang ada dan melakukan pencarian pada indeks.

Peringkat semantik adalah fungsionalitas sisi kueri yang menggunakan pemahaman pembacaan mesin untuk mengodekan ulang hasil pencarian, mempromosikan kecocokan yang paling relevan secara semantik ke bagian atas daftar. Anda dapat menambahkan konfigurasi semantik ke indeks yang ada tanpa persyaratan pembangunan ulang. Peringkat semantik paling efektif untuk teks informasi atau deskriptif.

Tips

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Pembaca Indeks Data Pencarian

Catatan

Tidak seperti panduan cepat lain yang membuat dan memuat indeks, panduan cepat ini menggunakan indeks yang sudah ada dan sudah berisi data, sehingga Anda tidak memerlukan peran Kontributor Data Indeks Pencarian.

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Mulai dengan indeks

Langkah cepat ini memodifikasi indeks yang ada untuk menyertakan konfigurasi semantik. Kami merekomendasikan indeks contoh hotel, yang dapat Anda buat dalam hitungan menit menggunakan wizard di portal Azure.

Untuk menggunakan indeks yang berbeda, ganti nama indeks, nama bidang dalam konfigurasi semantik, dan nama bidang dalam pernyataan kueri select di seluruh kode sampel. Indeks Anda harus berisi bidang teks deskriptif yang dikaitkan sebagai searchable dan retrievable.

Untuk meninjau dan menjalankan kueri pada indeks sampel hotel sebelum pengurutan semantik:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilihIndeks> pencarian.

  3. Pilih hotel-sampel.

  4. Pilih Konfigurasi semantik untuk melihat konfigurasi yang ada. Jika Anda mengaktifkan peringkat semantik selama alur pembuatan wizard, harus ada konfigurasi default.

    Tangkapan layar pengaturan semantik bawaan di portal Azure.

  5. Pilih Penjelajah pencarian, lalu pilih Tampilkan>tampilan JSON.

  6. Tempelkan JSON berikut ke editor kueri.

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. Pilih Cari untuk menjalankan kueri.

    Responsnya harus mirip dengan contoh berikut. Ini adalah kueri teks lengkap yang diberi peringkat oleh BM25, sehingga hasilnya cocok pada istilah kueri individual dan varian linguistik daripada arti keseluruhan kueri. Misalnya, walking mencocokkan walk, dan live mencocokkan music secara independen daripada sebagai frasa.

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    Tips

    Kueri ini memperlihatkan tampilan respons sebelum peringkat semantik diterapkan. Setelah Anda mengonfigurasi konfigurasi semantik, tambahkan "queryType": "semantic" dan "semanticConfiguration": "semantic-config" untuk melihat bagaimana kueri yang sama diberi peringkat berbeda dengan peringkat semantik.

Siapkan lingkungan

  1. Gunakan Git untuk mengkloning repositori sampel.

    git clone https://github.com/Azure-Samples/azure-search-dotnet-samples

  2. Masuk ke folder panduan mulai cepat.

    cd azure-search-dotnet-samples/quickstart-semantic-ranking

  3. Di BuildIndex/Program.cs, ganti nilai tempat penampung untuk endpoint dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Ulangi langkah sebelumnya untuk QueryIndex/Program.cs.

  5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

    az login

Jalankan kode

  1. Jalankan proyek pertama untuk memperbarui indeks dengan konfigurasi semantik.

    dotnet run --project BuildIndex

  2. Jalankan proyek kedua untuk mengkueri indeks. Tekan Enter di antara kueri untuk melihat perkembangan dari kueri sederhana ke kueri semantik dengan keterangan dan jawaban.

    dotnet run --project QueryIndex

Keluaran

Proyek pertama memperbarui indeks sampel hotel dengan konfigurasi semantik. Output mencakup konfirmasi konfigurasi semantik.

Here's a list of all indexes on the search service. You should see hotels-sample:
hotels-sample

Added new semantic configuration 'semantic-config' to the index definition.
Index updated successfully.
Here is the revised index definition:
{
  "Name": "hotels-sample",
  ... // Trimmed for brevity
  "SemanticSearch": {
    "DefaultConfigurationName": "semantic-config",
    "Configurations": [
      {
        "Name": "hotels-sample-semantic-configuration",
        ... // Trimmed for brevity
      },
      {
        "Name": "semantic-config",
        "PrioritizedFields": {
          "TitleField": {
            "FieldName": "HotelName"
          },
          "ContentFields": [
            {
              "FieldName": "Description"
            }
          ],
          "KeywordsFields": [
            {
              "FieldName": "Tags"
            }
          ]
        },
        "RankingOrder": {}
      }
    ]
  }
}

Proyek kedua menjalankan empat kueri. Output mencakup hasil pencarian dengan skor relevansi, keterangan, dan jawaban.

Query 1: Simple query using the search string 'walking distance to live music'.
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
----------------------------------------
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
Extractive Answers:
  Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
... // Trimmed for brevity

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Konfigurasi dan autentikasi
  2. Memperbarui indeks dengan konfigurasi semantik
  3. Menjalankan kueri pada indeks

Konfigurasi dan autentikasi

Kedua proyek memiliki pola konfigurasi yang sama. File Program.cs menentukan titik akhir pencarian dan menggunakan DefaultAzureCredential untuk autentikasi tanpa kunci.

var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(endpoint, credential);

Poin-poin penting:

  • DefaultAzureCredential menyediakan autentikasi tanpa kunci menggunakan Microsoft Entra ID. Ini menautkan beberapa jenis kredensial, termasuk kredensial Azure CLI dari az login.
  • SearchIndexClient mengelola operasi tingkat indeks, seperti memperbarui skema indeks.
  • SearchClient menangani operasi tingkat dokumen, seperti mengkueri indeks.

Memperbarui indeks dengan konfigurasi semantik

Kode berikut dalam BuildIndex/Program.cs menambahkan konfigurasi semantik ke indeks yang ada. Operasi ini tidak menghapus dokumen pencarian apa pun, dan indeks Anda tetap beroperasi setelah konfigurasi ditambahkan.

static void AddSemanticConfiguration(
    SearchIndex index,
    string semanticConfigName)
{
    if (index.SemanticSearch == null)
    {
        index.SemanticSearch = new SemanticSearch();
    }
    var configs = index.SemanticSearch.Configurations;
    if (!configs.Any(c => c.Name == semanticConfigName))
    {
        var prioritizedFields =
            new SemanticPrioritizedFields
        {
            TitleField = new SemanticField("HotelName"),
            ContentFields =
            {
                new SemanticField("Description")
            },
            KeywordsFields =
            {
                new SemanticField("Tags")
            }
        };

        configs.Add(
            new SemanticConfiguration(
                semanticConfigName,
                prioritizedFields
            )
        );
    }
    index.SemanticSearch.DefaultConfigurationName =
        semanticConfigName;
}

Poin-poin penting:

  • Konfigurasi semantik menentukan bidang yang digunakan untuk peringkat semantik.
  • Konfigurasi semantik dapat ditambahkan ke indeks yang ada tanpa membangun kembali.
  • TitleField mengatur bidang yang mewakili judul dokumen.
  • ContentFields mengatur bidang yang berisi konten utama.
  • KeywordsFields mengatur bidang yang berisi kata kunci atau tag.

Melakukan kueri pada indeks

Proyek ini QueryIndex menjalankan empat kueri secara berurutan, berkembang dari pencarian kata kunci sederhana ke peringkat semantik dengan keterangan dan jawaban.

Kueri sederhana

Kueri pertama adalah pencarian kata kunci sederhana yang tidak menggunakan peringkat semantik. Kueri ini berfungsi sebagai garis besar untuk membandingkan hasil dengan dan tanpa reranking semantik.

await RunQuery(client, searchText, new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Simple,
    IncludeTotalCount = true,
    Select = { "HotelId", "HotelName", "Description" }
});

Poin-poin penting:

  • SearchQueryType.Simple menggunakan algoritma peringkat BM25 default.
  • Hasil diberi peringkat berdasarkan relevansi kata kunci (@search.score) saja.

Kueri semantik (tanpa keterangan, tidak ada jawaban)

Kueri berikutnya menambahkan peringkat semantik tanpa keterangan atau jawaban. Kode berikut menunjukkan persyaratan minimum untuk memanggil peringkat semantik.

var semanticOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config"
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(client, searchText, semanticOptions);

Poin-poin penting:

  • SearchQueryType.Semantic mengaktifkan peringkat semantik pada kueri.
  • SemanticConfigurationName menentukan konfigurasi semantik mana yang akan digunakan.
  • @search.rerankerScore menunjukkan relevansi semantik (lebih tinggi lebih baik).
  • Hasil awal dari kueri istilah diberi skor ulang menggunakan model peringkat semantik. Untuk himpunan data dan kueri ini, efek peringkat semantik lebih jelas dalam hasil berpangkat lebih rendah.

Kueri semantik dengan keterangan

Kode berikut menambahkan keterangan teks untuk menyoroti bagian yang paling relevan dari setiap hasil, dengan penyorotan istilah dan frasa penting.

var captionsOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryCaption =
            new QueryCaption(QueryCaptionType.Extractive)
        {
            HighlightEnabled = true
        }
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
captionsOptions.HighlightFields.Add("Description");
await RunQuery(
    client, searchText, captionsOptions, showCaptions: true
);

Poin-poin penting:

  • QueryCaption mengaktifkan keterangan ekstraktif dari bidang konten.
  • Keterangan menampilkan bagian yang paling relevan dan menambahkan <em> tag di sekitar istilah penting.

Kueri semantik dengan jawaban

Kueri akhir menambahkan jawaban semantik. Kueri ini menggunakan string pencarian yang berbeda (searchText2) karena jawaban semantik berfungsi paling baik saat kueri diungkapkan sebagai pertanyaan. Jawabannya adalah kutipan verbatim yang diekstrak dari indeks Anda, bukan respons yang dibentuk oleh model penyelesaian obrolan.

Kueri dan konten terindeks harus diratakan erat agar jawaban dikembalikan. Jika tidak ada kandidat yang memenuhi ambang keyakinan, respons tidak menyertakan jawaban. Contoh ini menggunakan pertanyaan yang diketahui menghasilkan hasil sehingga Anda dapat melihat sintaksnya. Jika jawaban tidak berguna untuk skenario Anda, hilangkan QueryAnswer dari kode Anda. Untuk jawaban yang terstruktur, pertimbangkan pola RAG atau pengambilan informasi secara agenik.

var answersOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryAnswer =
            new QueryAnswer(QueryAnswerType.Extractive)
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(
    client, searchText2, answersOptions, showAnswers: true
);

Poin-poin penting:

  • QueryAnswer memungkinkan jawaban ekstraktif untuk kueri yang menyerupai pertanyaan.
  • Jawabannya adalah konten verbatim yang diekstrak dari indeks Anda, bukan teks yang dihasilkan.

Dalam panduan cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk Java untuk menerapkan peringkat semantik ke indeks pencarian yang ada dan melakukan kueri pada indeks tersebut.

Peringkat semantik adalah fungsionalitas sisi kueri yang menggunakan pemahaman pembacaan mesin untuk mengodekan ulang hasil pencarian, mempromosikan kecocokan yang paling relevan secara semantik ke bagian atas daftar. Anda dapat menambahkan konfigurasi semantik ke indeks yang ada tanpa persyaratan pembangunan ulang. Peringkat semantik paling efektif untuk teks informasi atau deskriptif.

Tips

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Pembaca Indeks Data Pencarian

Catatan

Tidak seperti panduan cepat lain yang membuat dan memuat indeks, panduan cepat ini menggunakan indeks yang sudah ada dan sudah berisi data, sehingga Anda tidak memerlukan peran Kontributor Data Indeks Pencarian.

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Mulai dengan indeks

Langkah cepat ini memodifikasi indeks yang ada untuk menyertakan konfigurasi semantik. Kami merekomendasikan indeks contoh hotel, yang dapat Anda buat dalam hitungan menit menggunakan wizard di portal Azure.

Untuk menggunakan indeks yang berbeda, ganti nama indeks, nama bidang dalam konfigurasi semantik, dan nama bidang dalam pernyataan kueri select di seluruh kode sampel. Indeks Anda harus berisi bidang teks deskriptif yang dikaitkan sebagai searchable dan retrievable.

Untuk meninjau dan menjalankan kueri pada indeks sampel hotel sebelum pengurutan semantik:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilihIndeks> pencarian.

  3. Pilih hotel-sampel.

  4. Pilih Konfigurasi semantik untuk melihat konfigurasi yang ada. Jika Anda mengaktifkan peringkat semantik selama alur pembuatan wizard, harus ada konfigurasi default.

    Tangkapan layar pengaturan semantik bawaan di portal Azure.

  5. Pilih Penjelajah pencarian, lalu pilih Tampilkan>tampilan JSON.

  6. Tempelkan JSON berikut ke editor kueri.

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. Pilih Cari untuk menjalankan kueri.

    Responsnya harus mirip dengan contoh berikut. Ini adalah kueri teks lengkap yang diberi peringkat oleh BM25, sehingga hasilnya cocok pada istilah kueri individual dan varian linguistik daripada arti keseluruhan kueri. Misalnya, walking mencocokkan walk, dan live mencocokkan music secara independen daripada sebagai frasa.

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    Tips

    Kueri ini memperlihatkan tampilan respons sebelum peringkat semantik diterapkan. Setelah Anda mengonfigurasi konfigurasi semantik, tambahkan "queryType": "semantic" dan "semanticConfiguration": "semantic-config" untuk melihat bagaimana kueri yang sama diberi peringkat berbeda dengan peringkat semantik.

Siapkan lingkungan

  1. Gunakan Git untuk mengkloning repositori sampel.

    git clone https://github.com/Azure-Samples/azure-search-java-samples

  2. Masuk ke folder panduan mulai cepat.

    cd azure-search-java-samples/quickstart-semantic-ranking

  3. Di src/main/resources/application.properties, ganti nilai tempat penampung untuk azure.search.endpoint dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Kompilasi proyek ini untuk menyelesaikan dependensi, termasuk azure-search-documents.

    mvn compile

    Saat build selesai, verifikasi bahwa tidak ada kesalahan yang muncul dalam output.

  5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

    az login

Jalankan kode

  1. Dapatkan pengaturan indeks yang ada.

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.GetIndexSettings"

  2. Perbarui indeks dengan konfigurasi semantik.

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.UpdateIndexSettings"

  3. Jalankan kueri semantik.

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQuery"

  4. Jalankan kueri semantik dengan keterangan.

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQueryWithCaptions"

  5. Jalankan kueri semantik dengan jawaban.

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticAnswer"

Keluaran

Outputnya GetIndexSettings.java adalah nama indeks, bidangnya, dan konfigurasi semantiknya. Sebelum Anda menambahkan konfigurasi baru, indeks hanya memiliki konfigurasi default.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic search configurations: 1
Configuration name: hotels-sample-semantic-configuration

Output mencantumkan UpdateIndexSettings.java semua konfigurasi semantik pada indeks, termasuk yang ditambahkan kode, diikuti dengan pesan keberhasilan.

// Trimmed for brevity
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Output dari SemanticQuery.java mengembalikan semua dokumen yang cocok dan diurutkan berdasarkan skor penyusun ulang peringkat semantik.

Search result #1:
  Re-ranker Score: 2.61
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.27
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.99
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

Output SemanticQueryWithCaptions.java menambahkan elemen teks keterangan dengan sorotan hasil di samping bidang pencarian. Keterangan adalah bagian yang paling relevan dalam hasilnya. Jika indeks Anda menyertakan teks yang lebih besar, keterangan membantu mengekstrak kalimat yang paling menarik.

Search result #1:
  Re-ranker Score: 2.61
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.27
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

Output dari SemanticAnswer.java mencakup jawaban semantik yang ditarik dari salah satu hasil yang paling cocok dengan pertanyaan, diikuti dengan hasil pencarian dengan caption.

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.98

Search Results:

Search result #1:
Re-ranker Score: 2.12
Hotel: Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Search result #2:
Re-ranker Score: 2.07
Hotel: Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
// Trimmed for brevity

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Konfigurasi dan autentikasi
  2. Memperbarui indeks dengan konfigurasi semantik
  3. Menjalankan kueri pada indeks

Konfigurasi dan autentikasi

Kelas SearchConfig.java memuat properti dari application.properties dan membuat satu DefaultAzureCredential untuk autentikasi tanpa kunci.

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class SearchConfig {
    private static final Properties properties =
        new Properties();

    static {
        try (InputStream input = SearchConfig.class
            .getClassLoader()
            .getResourceAsStream(
                "application.properties")) {
            properties.load(input);
        } catch (IOException e) {
            throw new RuntimeException(
                "Failed to load application.properties",
                e);
        }
    }

    public static final String SEARCH_ENDPOINT =
        properties.getProperty(
            "azure.search.endpoint");
    public static final String INDEX_NAME =
        properties.getProperty(
            "azure.search.index.name");
    public static final String SEMANTIC_CONFIG_NAME =
        properties.getProperty(
            "semantic.configuration.name");

    public static final DefaultAzureCredential
        CREDENTIAL = new DefaultAzureCredentialBuilder()
            .build();
}

Poin-poin penting:

  • DefaultAzureCredential menyediakan autentikasi tanpa kunci menggunakan Microsoft Entra ID. Ini menautkan beberapa jenis kredensial, termasuk kredensial Azure CLI dari az login.
  • Properti dimuat dari application.properties file di classpath.
  • Bidang statis (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, ) CREDENTIALdibagikan di semua kelas dalam proyek.

Memperbarui indeks dengan konfigurasi semantik

Kelas UpdateIndexSettings.java menambahkan konfigurasi semantik ke indeks yang hotels-sample ada. Operasi ini tidak menghapus dokumen pencarian apa pun, dan indeks Anda tetap beroperasi setelah konfigurasi ditambahkan.

import com.azure.search.documents.indexes
    .SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models
    .SearchIndex;
import com.azure.search.documents.indexes.models
    .SemanticConfiguration;
import com.azure.search.documents.indexes.models
    .SemanticField;
import com.azure.search.documents.indexes.models
    .SemanticPrioritizedFields;
import com.azure.search.documents.indexes.models
    .SemanticSearch;

import java.util.ArrayList;
import java.util.List;

var indexClient = new SearchIndexClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

SearchIndex existingIndex =
    indexClient.getIndex(SearchConfig.INDEX_NAME);

var prioritizedFields =
    new SemanticPrioritizedFields()
        .setTitleField(
            new SemanticField("HotelName"))
        .setKeywordsFields(
            List.of(new SemanticField("Tags")))
        .setContentFields(
            List.of(
                new SemanticField("Description")));

var newSemanticConfiguration =
    new SemanticConfiguration(
        SearchConfig.SEMANTIC_CONFIG_NAME,
        prioritizedFields);

SemanticSearch semanticSearch =
    existingIndex.getSemanticSearch();
if (semanticSearch == null) {
    semanticSearch = new SemanticSearch();
    existingIndex.setSemanticSearch(semanticSearch);
}

List<SemanticConfiguration> configurations =
    semanticSearch.getConfigurations();
if (configurations == null) {
    configurations = new ArrayList<>();
    semanticSearch.setConfigurations(configurations);
}

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

Poin-poin penting:

  • SemanticPrioritizedFields menentukan bidang mana yang dievaluasi oleh ranker semantik. setTitleField mengatur judul dokumen, setContentFields mengatur konten utama, dan setKeywordsFields mengatur kata kunci atau bidang tag.
  • SemanticConfiguration memasangkan nama dengan bidang yang diprioritaskan, mengidentifikasi konfigurasi semantik mana yang akan digunakan pada waktu kueri.
  • createOrUpdateIndex mendorong skema yang diperbarui ke layanan pencarian tanpa membangun kembali indeks atau menghapus dokumen.

Melakukan kueri pada indeks

Tiga kelas berikut mengkueri indeks secara berurutan, berkembang dari pencarian semantik dasar ke peringkat semantik dengan keterangan dan jawaban.

Kueri semantik (tanpa keterangan, tidak ada jawaban)

Kueri pertama menambahkan peringkat semantik tanpa keterangan atau jawaban. Kelas SemanticQuery.java menunjukkan persyaratan minimum untuk memanggil peringkat semantik.

import com.azure.search.documents
    .SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models
    .SemanticSearchOptions;
import com.azure.search.documents.util
    .SearchPagedIterable;

var searchClient = new SearchClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .indexName(SearchConfig.INDEX_NAME)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME))
    .setSelect("HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    var document = result.getDocument(
        SearchDocument.class);
    double rerankerScore = result
        .getSemanticSearch().getRerankerScore();

    System.out.printf("Re-ranker Score: %.2f%n",
        rerankerScore);
    System.out.printf("HotelName: %s%n",
        document.get("HotelName"));
    System.out.printf("Description: %s%n%n",
        document.get("Description"));
}

Poin-poin penting:

  • QueryType.SEMANTIC mengaktifkan peringkat semantik pada kueri.
  • setSemanticConfigurationName menentukan konfigurasi semantik mana yang akan digunakan.
  • SearchPagedIterable menyediakan iterasi dari hasil yang telah diurutkan ulang. Masing-masing SearchResult berisi getSemanticSearch() aksesor untuk skor reranker.

Kueri semantik dengan keterangan

Kelas SemanticQueryWithCaptions.java menambahkan teks penjelas untuk mengekstrak bagian yang paling relevan dari setiap hasil, dengan penyorotan kata kunci diterapkan pada istilah serta frasa penting.

import com.azure.search.documents.models
    .QueryCaption;
import com.azure.search.documents.models
    .QueryCaptionResult;
import com.azure.search.documents.models
    .QueryCaptionType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE)
                    .setHighlightEnabled(true)))
    .setSelect(
        "HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    List<QueryCaptionResult> captions =
        result.getSemanticSearch()
            .getQueryCaptions();
    if (captions != null && !captions.isEmpty()) {
        QueryCaptionResult caption = captions.get(0);
        if (caption.getHighlights() != null) {
            System.out.printf(
                "Caption: %s%n",
                caption.getHighlights());
        }
    }
}

Poin-poin penting:

  • QueryCaption(QueryCaptionType.EXTRACTIVE) mengaktifkan keterangan ekstraktif dari bidang konten.
  • setHighlightEnabled(true) <em> menambahkan tag di sekitar istilah penting dalam keterangan.
  • Masing-masing SearchResult menyediakan getQueryCaptions() aksesor pencarian semantik.

Kueri semantik dengan jawaban

Kelas SemanticAnswer.java menambahkan jawaban semantik. Kelas ini menggunakan pertanyaan sebagai teks pencarian karena jawaban semantik berfungsi paling baik saat kueri diungkapkan sebagai pertanyaan. Jawabannya adalah kutipan verbatim yang diekstrak dari indeks Anda, bukan respons yang dibentuk oleh model penyelesaian obrolan.

Kueri dan konten terindeks harus diratakan erat agar jawaban dikembalikan. Jika tidak ada kandidat yang memenuhi ambang keyakinan, respons tidak menyertakan jawaban. Contoh ini menggunakan pertanyaan yang diketahui menghasilkan hasil sehingga Anda dapat melihat sintaksnya. Jika jawaban tidak berguna untuk skenario Anda, hilangkan setQueryAnswer dari kode Anda. Untuk jawaban yang terstruktur, pertimbangkan pola RAG atau pengambilan informasi secara agenik.

import com.azure.search.documents.models
    .QueryAnswer;
import com.azure.search.documents.models
    .QueryAnswerResult;
import com.azure.search.documents.models
    .QueryAnswerType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE))
            .setQueryAnswer(
                new QueryAnswer(
                    QueryAnswerType.EXTRACTIVE)))
    .setSelect(
        "HotelName", "Description", "Category");

SearchPagedIterable results = searchClient.search(
    "What's a good hotel for people who like to read",
    searchOptions, null);

List<QueryAnswerResult> semanticAnswers =
    results.getSemanticResults().getQueryAnswers();

for (QueryAnswerResult answer :
    semanticAnswers != null ? semanticAnswers
        : List.<QueryAnswerResult>of()) {
    if (answer.getHighlights() != null) {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getHighlights());
    } else {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getText());
    }
    System.out.printf(
        "Semantic Answer Score: %.2f%n",
        answer.getScore());
}

Poin-poin penting:

  • QueryAnswer(QueryAnswerType.EXTRACTIVE) memungkinkan jawaban ekstraktif untuk kueri yang menyerupai pertanyaan.
  • Jawabannya adalah konten verbatim yang diekstrak dari indeks Anda, bukan teks yang dihasilkan.
  • results.getSemanticResults().getQueryAnswers() mengambil objek jawaban secara terpisah dari hasil pencarian.

Dalam panduan memulai cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk JavaScript untuk menambahkan peringkat semantik ke indeks pencarian yang ada dan melakukan kueri pada indeks tersebut.

Peringkat semantik adalah fungsionalitas sisi kueri yang menggunakan pemahaman pembacaan mesin untuk mengodekan ulang hasil pencarian, mempromosikan kecocokan yang paling relevan secara semantik ke bagian atas daftar. Anda dapat menambahkan konfigurasi semantik ke indeks yang ada tanpa persyaratan pembangunan ulang. Peringkat semantik paling efektif untuk teks informasi atau deskriptif.

Tips

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Pembaca Indeks Data Pencarian

Catatan

Tidak seperti panduan cepat lain yang membuat dan memuat indeks, panduan cepat ini menggunakan indeks yang sudah ada dan sudah berisi data, sehingga Anda tidak memerlukan peran Kontributor Data Indeks Pencarian.

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Mulai dengan indeks

Langkah cepat ini memodifikasi indeks yang ada untuk menyertakan konfigurasi semantik. Kami merekomendasikan indeks contoh hotel, yang dapat Anda buat dalam hitungan menit menggunakan wizard di portal Azure.

Untuk menggunakan indeks yang berbeda, ganti nama indeks, nama bidang dalam konfigurasi semantik, dan nama bidang dalam pernyataan kueri select di seluruh kode sampel. Indeks Anda harus berisi bidang teks deskriptif yang dikaitkan sebagai searchable dan retrievable.

Untuk meninjau dan menjalankan kueri pada indeks sampel hotel sebelum pengurutan semantik:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilihIndeks> pencarian.

  3. Pilih hotel-sampel.

  4. Pilih Konfigurasi semantik untuk melihat konfigurasi yang ada. Jika Anda mengaktifkan peringkat semantik selama alur pembuatan wizard, harus ada konfigurasi default.

    Tangkapan layar pengaturan semantik bawaan di portal Azure.

  5. Pilih Penjelajah pencarian, lalu pilih Tampilkan>tampilan JSON.

  6. Tempelkan JSON berikut ke editor kueri.

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. Pilih Cari untuk menjalankan kueri.

    Responsnya harus mirip dengan contoh berikut. Ini adalah kueri teks lengkap yang diberi peringkat oleh BM25, sehingga hasilnya cocok pada istilah kueri individual dan varian linguistik daripada arti keseluruhan kueri. Misalnya, walking mencocokkan walk, dan live mencocokkan music secara independen daripada sebagai frasa.

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    Tips

    Kueri ini memperlihatkan tampilan respons sebelum peringkat semantik diterapkan. Setelah Anda mengonfigurasi konfigurasi semantik, tambahkan "queryType": "semantic" dan "semanticConfiguration": "semantic-config" untuk melihat bagaimana kueri yang sama diberi peringkat berbeda dengan peringkat semantik.

Siapkan lingkungan

  1. Gunakan Git untuk mengkloning repositori sampel.

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. Masuk ke folder panduan mulai cepat.

    cd azure-search-javascript-samples/quickstart-semantic-ranking-js

  3. Di sample.env, ganti nilai tempat penampung untuk AZURE_SEARCH_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Ganti nama sample.env menjadi .env.

    mv sample.env .env

  5. Pasang dependensi.

    npm install

    Ketika penginstalan selesai, Anda akan melihat node_modules folder di direktori proyek.

  6. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

    az login

Jalankan kode

  1. Dapatkan pengaturan indeks yang ada.

    node -r dotenv/config src/getIndexSettings.js

  2. Perbarui indeks dengan konfigurasi semantik.

    node -r dotenv/config src/updateIndexSettings.js

  3. Jalankan kueri semantik.

    node -r dotenv/config src/semanticQuery.js

  4. Jalankan kueri semantik dengan keterangan.

    node -r dotenv/config src/semanticQueryReturnCaptions.js

  5. Jalankan kueri semantik dengan jawaban.

    node -r dotenv/config src/semanticAnswer.js

Keluaran

getIndexSettings.js Skrip mengembalikan nama indeks, bidangnya, dan konfigurasi semantik yang ada.

Getting semantic ranking index settings...
Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
Field: Description_fr, Type: Edm.String, Searchable: true
Field: Category, Type: Edm.String, Searchable: true
Field: Tags, Type: Collection(Edm.String), Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

updateIndexSettings.js Skrip mengembalikan semua konfigurasi semantik pada indeks, termasuk yang ditambahkan kode, diikuti dengan pesan sukses.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

semanticQuery.js Skrip mengembalikan semua dokumen cocok yang diurutkan berdasarkan skor peringkat ulang peringkat semantik.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.9861756563186646
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

semanticQueryReturnCaptions.js Skrip mengembalikan elemen keterangan dengan penyorotan temuan bersama bidang pencarian. Keterangan adalah bagian yang paling relevan dalam hasilnya. Jika indeks Anda menyertakan teks yang lebih besar, keterangan membantu mengekstrak kalimat yang paling menarik.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

semanticAnswer.js Skrip mengembalikan jawaban semantik yang ditarik dari salah satu hasil yang paling cocok dengan pertanyaan, diikuti dengan hasil pencarian dengan keterangan.

Answers:

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
// Trimmed for brevity

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Konfigurasi dan autentikasi
  2. Memperbarui indeks dengan konfigurasi semantik
  3. Menjalankan kueri pada indeks

Konfigurasi dan autentikasi

File config.js memuat variabel lingkungan dan membuat DefaultAzureCredential untuk autentikasi.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

Poin-poin penting:

  • DefaultAzureCredential menyediakan autentikasi tanpa kunci menggunakan Microsoft Entra ID. Ini menautkan beberapa jenis kredensial, termasuk kredensial Azure CLI dari az login.
  • Variabel lingkungan dimuat dari .env file menggunakan dotenv.

Memperbarui indeks dengan konfigurasi semantik

File updateIndexSettings.js menambahkan konfigurasi semantik ke indeks hotels-sample yang sudah ada. Operasi ini tidak menghapus dokumen pencarian apa pun, dan indeks Anda tetap beroperasi setelah konfigurasi ditambahkan.

import { SearchIndexClient }
    from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields = {
    titleField: { name: "HotelName" },
    keywordsFields: [{ name: "Tags" }],
    contentFields: [{ name: "Description" }]
};

const newSemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Poin-poin penting:

  • Konfigurasi semantik menentukan bidang yang digunakan untuk peringkat semantik. titleField menentukan judul dokumen, contentFields menentukan konten utama, dan keywordsFields menentukan kata kunci atau bidang tag.
  • Anda membuat objek konfigurasi dan mendorongnya ke array indeks semanticSearch.configurations yang ada.
  • createOrUpdateIndex mendorong skema yang diperbarui ke layanan pencarian tanpa membangun kembali indeks atau menghapus dokumen.

Melakukan kueri pada indeks

Skrip kueri menjalankan tiga kueri secara berurutan, berkembang dari pencarian semantik dasar ke peringkat semantik dengan keterangan dan jawaban.

Kueri semantik (tanpa keterangan, tidak ada jawaban)

Kode berikut menunjukkan persyaratan minimum untuk memanggil peringkat semantik.

import { SearchClient }
    from "@azure/search-documents";
import {
    credential, searchEndpoint,
    indexName, semanticConfigurationName
} from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint, indexName, credential
);

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Poin-poin penting:

  • queryType: "semantic" mengaktifkan peringkat semantik pada kueri.
  • semanticSearchOptions.configurationName menentukan konfigurasi semantik mana yang akan digunakan.
  • Hasil rerankerScore menunjukkan relevansi semantik (semakin tinggi semakin baik).

Kueri semantik dengan keterangan

Kode berikut menambahkan keterangan teks untuk menyoroti bagian yang paling relevan dari setiap hasil, dengan penyorotan istilah dan frasa penting.

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Poin-poin penting:

  • captions.captionType: "extractive" mengaktifkan keterangan ekstraktif dari bidang konten.
  • Keterangan menampilkan bagian yang paling relevan dan menambahkan <em> tag di sekitar istilah penting.

Kueri semantik dengan jawaban

Kueri akhir menambahkan jawaban semantik. Kueri ini menggunakan pertanyaan sebagai teks pencarian karena jawaban semantik berfungsi paling baik saat kueri diungkapkan sebagai pertanyaan. Jawabannya adalah kutipan verbatim yang diekstrak dari indeks Anda, bukan respons yang dibentuk oleh model penyelesaian obrolan.

Kueri dan konten terindeks harus diratakan erat agar jawaban dikembalikan. Jika tidak ada kandidat yang memenuhi ambang keyakinan, respons tidak menyertakan jawaban. Contoh ini menggunakan pertanyaan yang diketahui menghasilkan hasil sehingga Anda dapat melihat sintaksnya. Jika jawaban tidak berguna untuk skenario Anda, hilangkan answers dari kode Anda. Untuk jawaban yang terstruktur, pertimbangkan pola RAG atau pengambilan informasi secara agenik.

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Poin-poin penting:

  • answers.answerType: "extractive" memungkinkan jawaban ekstraktif untuk kueri yang menyerupai pertanyaan.
  • Jawabannya adalah konten verbatim yang diekstrak dari indeks Anda, bukan teks yang dihasilkan.
  • results.answers mengambil objek jawaban secara terpisah dari hasil pencarian.

Dalam panduan memulai cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk Python untuk menambahkan peringkat semantik ke indeks pencarian yang ada dan melakukan kueri pada indeks.

Peringkat semantik adalah fungsionalitas sisi kueri yang menggunakan pemahaman pembacaan mesin untuk mengodekan ulang hasil pencarian, mempromosikan kecocokan yang paling relevan secara semantik ke bagian atas daftar. Anda dapat menambahkan konfigurasi semantik ke indeks yang ada tanpa persyaratan pembangunan ulang. Peringkat semantik paling efektif untuk teks informasi atau deskriptif.

Tips

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Pembaca Indeks Data Pencarian

Catatan

Tidak seperti panduan cepat lain yang membuat dan memuat indeks, panduan cepat ini menggunakan indeks yang sudah ada dan sudah berisi data, sehingga Anda tidak memerlukan peran Kontributor Data Indeks Pencarian.

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Mulai dengan indeks

Langkah cepat ini memodifikasi indeks yang ada untuk menyertakan konfigurasi semantik. Kami merekomendasikan indeks contoh hotel, yang dapat Anda buat dalam hitungan menit menggunakan wizard di portal Azure.

Untuk menggunakan indeks yang berbeda, ganti nama indeks, nama bidang dalam konfigurasi semantik, dan nama bidang dalam pernyataan kueri select di seluruh kode sampel. Indeks Anda harus berisi bidang teks deskriptif yang dikaitkan sebagai searchable dan retrievable.

Untuk meninjau dan menjalankan kueri pada indeks sampel hotel sebelum pengurutan semantik:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilihIndeks> pencarian.

  3. Pilih hotel-sampel.

  4. Pilih Konfigurasi semantik untuk melihat konfigurasi yang ada. Jika Anda mengaktifkan peringkat semantik selama alur pembuatan wizard, harus ada konfigurasi default.

    Tangkapan layar pengaturan semantik bawaan di portal Azure.

  5. Pilih Penjelajah pencarian, lalu pilih Tampilkan>tampilan JSON.

  6. Tempelkan JSON berikut ke editor kueri.

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. Pilih Cari untuk menjalankan kueri.

    Responsnya harus mirip dengan contoh berikut. Ini adalah kueri teks lengkap yang diberi peringkat oleh BM25, sehingga hasilnya cocok pada istilah kueri individual dan varian linguistik daripada arti keseluruhan kueri. Misalnya, walking mencocokkan walk, dan live mencocokkan music secara independen daripada sebagai frasa.

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    Tips

    Kueri ini memperlihatkan tampilan respons sebelum peringkat semantik diterapkan. Setelah Anda mengonfigurasi konfigurasi semantik, tambahkan "queryType": "semantic" dan "semanticConfiguration": "semantic-config" untuk melihat bagaimana kueri yang sama diberi peringkat berbeda dengan peringkat semantik.

Siapkan lingkungan

  1. Gunakan Git untuk mengkloning repositori sampel.

    git clone https://github.com/Azure-Samples/azure-search-python-samples

  2. Arahkan ke folder quickstart dan buka di Visual Studio Code.

    cd azure-search-python-samples/Quickstart-Semantic-Ranking
code .

  3. Di sample.env, ganti nilai tempat penampung untuk AZURE_SEARCH_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Ganti nama sample.env menjadi .env.

    mv sample.env .env

  5. Buka semantic-ranking-quickstart.ipynb.

  6. Tekan Ctrl+Shift+P, pilih Notebook: Pilih Notebook Kernel, dan ikuti perintah untuk membuat lingkungan virtual. Pilih requirements.txt untuk dependensi.

    Setelah selesai, Anda akan melihat .venv folder di direktori proyek.

  7. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

    az login

Jalankan kode

  1. Jalankan Install packages and set variables sel untuk menginstal paket yang diperlukan dan memuat variabel lingkungan.

  2. Jalankan sel yang tersisa secara berurutan untuk menambahkan konfigurasi semantik dan mengkueri indeks.

Keluaran

Output dari sel Get the index definition adalah nama indeks, bidang-bidangnya, dan konfigurasi semantik yang mungkin ada.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: True
Field: HotelName, Type: Edm.String, Searchable: True
Field: Description, Type: Edm.String, Searchable: True
Field: Description_fr, Type: Edm.String, Searchable: True
Field: Category, Type: Edm.String, Searchable: True
Field: Tags, Type: Collection(Edm.String), Searchable: True
// Trimmed for brevity
Semantic config: hotels-sample-semantic-configuration
Title field: HotelName

Output dari sel Add a semantic configuration to the index mencantumkan semua konfigurasi semantik pada indeks, termasuk yang ditambahkan oleh kode, diikuti dengan pesan keberhasilan.

Semantic configurations:
----------------------------------------
  Configuration: hotels-sample-semantic-configuration
    Title field: HotelName
    Keywords fields: Category
    Content fields: Description

  Configuration: semantic-config
    Title field: HotelName
    Keywords fields: Tags
    Content fields: Description

✅ Semantic configuration successfully added!

Output dari sel Run a term query mengembalikan semua dokumen yang cocok yang diurutkan berdasarkan skor BM25. Kueri garis besar ini tidak menggunakan peringkat semantik.

5.360838
4
Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the
historic center of Sublime in an extremely vibrant and lively area
within short walking distance to the sites and landmarks of the city
and is surrounded by the extraordinary beauty of churches, buildings,
shops and monuments. Sublime Cliff is part of a lovingly restored
19th century resort, updated for every modern convenience.
4.691083
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

Output dari sel Run a semantic query menghasilkan semua dokumen yang cocok yang diurutkan berdasarkan skor pengurut ulang semantik.

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
2.271434783935547
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

Output dari sel Return captions menambahkan elemen keterangan dengan penyorotan kata kunci bersama bidang pencarian. Keterangan adalah bagian yang paling relevan dalam hasilnya. Jika indeks Anda menyertakan teks yang lebih besar, keterangan membantu mengekstrak kalimat yang paling menarik.

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
Caption: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to<em> theaters, </em>art galleries,
restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and
then head over to<em> Benaroya Hall </em>to catch the evening's
concert performance.
// Trimmed for brevity

Output Return semantic answers sel menyertakan jawaban semantik yang ditarik dari salah satu hasil yang paling cocok dengan pertanyaan, diikuti dengan hasil pencarian dengan keterangan.

Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around a
stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Konfigurasi dan autentikasi
  2. Memperbarui indeks dengan konfigurasi semantik
  3. Menjalankan kueri pada indeks

Konfigurasi dan autentikasi

Sel Install packages and set variables memuat variabel lingkungan dan membuat DefaultAzureCredential untuk autentikasi.

from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.identity import get_bearer_token_provider
import os

load_dotenv(override=True)

search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = os.getenv(
    "AZURE_SEARCH_INDEX", "hotels-sample"
)

Poin-poin penting:

  • DefaultAzureCredential menyediakan autentikasi tanpa kunci menggunakan Microsoft Entra ID. Ini menautkan beberapa jenis kredensial, termasuk kredensial Azure CLI dari az login.
  • Variabel lingkungan dimuat dari .env file menggunakan python-dotenv.

Memperbarui indeks dengan konfigurasi semantik

Sel Add a semantic configuration to the index menambahkan konfigurasi semantik pada indeks hotels-sample yang sudah ada. Operasi ini tidak menghapus dokumen pencarian apa pun, dan indeks Anda tetap beroperasi setelah konfigurasi ditambahkan.

from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

new_semantic_config = SemanticConfiguration(
    name="semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="HotelName"),
        keywords_fields=[
            SemanticField(field_name="Tags")
        ],
        content_fields=[
            SemanticField(field_name="Description")
        ]
    )
)

if existing_index.semantic_search is None:
    existing_index.semantic_search = SemanticSearch(
        configurations=[new_semantic_config]
    )
else:
    existing_index.semantic_search.configurations.append(
        new_semantic_config
    )

result = index_client.create_or_update_index(existing_index)

Poin-poin penting:

  • Konfigurasi semantik menentukan bidang yang digunakan untuk peringkat semantik. title_field mengatur judul dokumen, content_fields mengatur konten utama, dan keywords_fields mengatur kata kunci atau bidang tag.
  • Anda membuat konfigurasi dengan SemanticConfiguration dan model terkait SemanticPrioritizedFields , lalu menambahkannya ke indeks yang ada.
  • create_or_update_index mendorong skema yang diperbarui ke layanan pencarian tanpa membangun kembali indeks atau menghapus dokumen.

Melakukan kueri pada indeks

Sel kueri menjalankan empat kueri secara berurutan: pencarian kata kunci garis besar diikuti oleh tiga variasi peringkat semantik dengan fungsionalitas yang meningkat.

Kueri istilah (dasar acuan)

Sel Run a term query menjalankan pencarian kata kunci menggunakan penilaian BM25. Kueri garis besar ini tidak menggunakan peringkat semantik dan berfungsi sebagai titik perbandingan.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='simple',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    include_total_count=True
)

Poin-poin penting:

  • query_type='simple' menentukan pencarian kata kunci menggunakan penilaian BM25.
  • @search.score dalam hasil menunjukkan skor relevansi BM25.

Kueri semantik (tanpa keterangan, tidak ada jawaban)

Sel Run a semantic query menunjukkan persyaratan minimum untuk memanggil peringkat semantik.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    query_caption='extractive'
)

Poin-poin penting:

  • query_type='semantic' mengaktifkan peringkat semantik pada kueri.
  • semantic_configuration_name menentukan konfigurasi semantik mana yang akan digunakan.
  • Hasil @search.reranker_score menunjukkan relevansi semantik (semakin tinggi semakin baik).

Kueri semantik dengan keterangan

Sel Return captions menambahkan keterangan untuk mengekstrak bagian yang paling relevan dari setiap hasil, dengan penyorotan temuan diterapkan ke istilah dan frasa penting.

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelName,HotelId,Description',
    query_caption='extractive'
)

for result in results:
    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")

Poin-poin penting:

  • query_caption='extractive' mengaktifkan keterangan ekstraktif dari bidang konten.
  • Keterangan menampilkan bagian yang paling relevan dan menambahkan <em> tag di sekitar istilah penting.

Kueri semantik dengan jawaban

Sel Return semantic answers menambahkan jawaban semantik. Kueri ini menggunakan pertanyaan sebagai teks pencarian karena jawaban semantik berfungsi paling baik saat kueri diungkapkan sebagai pertanyaan. Jawabannya adalah kutipan verbatim yang diekstrak dari indeks Anda, bukan respons yang dibentuk oleh model penyelesaian obrolan.

Kueri dan konten terindeks harus diratakan erat agar jawaban dikembalikan. Jika tidak ada kandidat yang memenuhi ambang keyakinan, respons tidak menyertakan jawaban. Contoh ini menggunakan pertanyaan yang diketahui menghasilkan hasil sehingga Anda dapat melihat sintaksnya. Jika jawaban tidak berguna untuk skenario Anda, hilangkan query_answer dari kode Anda. Untuk jawaban yang terstruktur, pertimbangkan pola RAG atau pengambilan informasi secara agenik.

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="what's a good hotel for people who "
                "like to read",
    select='HotelName,Description,Category',
    query_caption='extractive',
    query_answer="extractive",
)

semantic_answers = results.get_answers()
for answer in semantic_answers:
    if answer.highlights:
        print(f"Semantic Answer: {answer.highlights}")
    else:
        print(f"Semantic Answer: {answer.text}")
    print(f"Semantic Answer Score: {answer.score}\n")

Poin-poin penting:

  • query_answer="extractive" memungkinkan jawaban ekstraktif untuk kueri yang menyerupai pertanyaan.
  • Jawabannya adalah konten verbatim yang diekstrak dari indeks Anda, bukan teks yang dihasilkan.
  • results.get_answers() mengambil objek jawaban secara terpisah dari hasil pencarian.

Dalam memulai cepat ini, Anda menggunakan library klien Pencarian Azure AI untuk JavaScript (kompatibel dengan TypeScript) untuk menambahkan peringkat semantik ke indeks pencarian yang ada dan melakukan kueri terhadap indeks.

Peringkat semantik adalah fungsionalitas sisi kueri yang menggunakan pemahaman pembacaan mesin untuk mengodekan ulang hasil pencarian, mempromosikan kecocokan yang paling relevan secara semantik ke bagian atas daftar. Anda dapat menambahkan konfigurasi semantik ke indeks yang ada tanpa persyaratan pembangunan ulang. Peringkat semantik paling efektif untuk teks informasi atau deskriptif.

Tips

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Pembaca Indeks Data Pencarian

Catatan

Tidak seperti panduan cepat lain yang membuat dan memuat indeks, panduan cepat ini menggunakan indeks yang sudah ada dan sudah berisi data, sehingga Anda tidak memerlukan peran Kontributor Data Indeks Pencarian.

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Mulai dengan indeks

Langkah cepat ini memodifikasi indeks yang ada untuk menyertakan konfigurasi semantik. Kami merekomendasikan indeks contoh hotel, yang dapat Anda buat dalam hitungan menit menggunakan wizard di portal Azure.

Untuk menggunakan indeks yang berbeda, ganti nama indeks, nama bidang dalam konfigurasi semantik, dan nama bidang dalam pernyataan kueri select di seluruh kode sampel. Indeks Anda harus berisi bidang teks deskriptif yang dikaitkan sebagai searchable dan retrievable.

Untuk meninjau dan menjalankan kueri pada indeks sampel hotel sebelum pengurutan semantik:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilihIndeks> pencarian.

  3. Pilih hotel-sampel.

  4. Pilih Konfigurasi semantik untuk melihat konfigurasi yang ada. Jika Anda mengaktifkan peringkat semantik selama alur pembuatan wizard, harus ada konfigurasi default.

    Tangkapan layar pengaturan semantik bawaan di portal Azure.

  5. Pilih Penjelajah pencarian, lalu pilih Tampilkan>tampilan JSON.

  6. Tempelkan JSON berikut ke editor kueri.

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. Pilih Cari untuk menjalankan kueri.

    Responsnya harus mirip dengan contoh berikut. Ini adalah kueri teks lengkap yang diberi peringkat oleh BM25, sehingga hasilnya cocok pada istilah kueri individual dan varian linguistik daripada arti keseluruhan kueri. Misalnya, walking mencocokkan walk, dan live mencocokkan music secara independen daripada sebagai frasa.

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    Tips

    Kueri ini memperlihatkan tampilan respons sebelum peringkat semantik diterapkan. Setelah Anda mengonfigurasi konfigurasi semantik, tambahkan "queryType": "semantic" dan "semanticConfiguration": "semantic-config" untuk melihat bagaimana kueri yang sama diberi peringkat berbeda dengan peringkat semantik.

Siapkan lingkungan

  1. Gunakan Git untuk mengkloning repositori sampel.

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. Masuk ke folder panduan mulai cepat.

    cd azure-search-javascript-samples/quickstart-semantic-ranking-ts

  3. Di sample.env, ganti nilai tempat penampung untuk AZURE_SEARCH_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Ganti nama sample.env menjadi .env.

    mv sample.env .env

  5. Pasang dependensi.

    npm install

    Ketika penginstalan selesai, Anda akan melihat node_modules folder di direktori proyek.

  6. Kompilasi file TypeScript ke JavaScript.

    npm run build

  7. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

    az login

Jalankan kode

  1. Dapatkan pengaturan indeks yang ada.

    node -r dotenv/config dist/getIndexSettings.js

  2. Perbarui indeks dengan konfigurasi semantik.

    node -r dotenv/config dist/updateIndexSettings.js

  3. Jalankan kueri semantik.

    node -r dotenv/config dist/semanticQuery.js

  4. Jalankan kueri semantik dengan keterangan.

    node -r dotenv/config dist/semanticQueryReturnCaptions.js

  5. Jalankan kueri semantik dengan jawaban.

    node -r dotenv/config dist/semanticAnswer.js

    Catatan

    Perintah ini menjalankan file yang dikompilasi .js dari dist folder. Kode TypeScript harus ditranspilasi ke JavaScript sebelum Node.js dapat menjalankannya, itulah sebabnya Anda sebelumnya menjalankan npm run build.

Keluaran

getIndexSettings.js Skrip mengembalikan nama indeks, jumlah bidang, detail bidang dengan jenis dan status yang dapat dicari, dan konfigurasi semantik yang ada.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

updateIndexSettings.js Skrip mengembalikan semua konfigurasi semantik, termasuk yang Anda tambahkan.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Skrip semanticQuery.js mengembalikan hasil yang diurutkan berdasarkan nilai reranker.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza...
  // Trimmed for brevity

semanticQueryReturnCaptions.js Skrip menghasilkan keterangan ekstraktif dengan sorotan hit penting. Keterangan adalah bagian yang paling relevan dalam hasilnya.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel
  in downtown, within walking distance to<em> theaters, </em>art
  galleries, restaurants and shops. Visit<em> Seattle Art Museum
  </em>by day, and then head over to<em> Benaroya Hall </em>to catch
  the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  // Trimmed for brevity

semanticAnswer.js Skrip mengembalikan jawaban semantik (konten verbatim) yang ditarik dari hasil yang paling cocok dengan pertanyaan.

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around
a stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the
main commercial artery of the city in the heart of New York...
Caption: This classic hotel is<em> fully-refurbished </em>and
ideally located on the main commercial artery of the city...
// Trimmed for brevity

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Konfigurasi dan autentikasi
  2. Memperbarui indeks dengan konfigurasi semantik
  3. Menjalankan kueri pada indeks

Konfigurasi dan autentikasi

File config.ts memuat variabel lingkungan, membuat DefaultAzureCredential untuk autentikasi, dan menentukan antarmuka HotelDocument untuk keamanan tipe.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

export interface HotelDocument {
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
}

Poin-poin penting:

  • DefaultAzureCredential menyediakan autentikasi tanpa kunci menggunakan Microsoft Entra ID. Ini menautkan beberapa jenis kredensial, termasuk kredensial Azure CLI dari az login.
  • Antarmuka HotelDocument menyediakan pemeriksaan tipe waktu kompilasi untuk hasil pencarian, memastikan akses tipe aman ke bidang dokumen.
  • Variabel lingkungan dimuat dari .env file menggunakan dotenv.

Memperbarui indeks dengan konfigurasi semantik

File updateIndexSettings.ts menambahkan konfigurasi semantik ke indeks hotels-sample yang sudah ada. Operasi ini tidak menghapus dokumen pencarian apa pun, dan indeks Anda tetap beroperasi setelah konfigurasi ditambahkan. Anotasi jenis TypeScript memastikan konfigurasi cocok dengan skema yang diharapkan.

import {
    SearchIndexClient,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField
} from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields: SemanticPrioritizedFields = {
    titleField: { name: "HotelName" },
    keywordsFields: [
        { name: "Tags" }
    ] as SemanticField[],
    contentFields: [
        { name: "Description" }
    ] as SemanticField[]
};

const newSemanticConfiguration:
    SemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Poin-poin penting:

  • Jenis TypeScript seperti SemanticPrioritizedFields, SemanticConfiguration, dan SemanticField menyediakan validasi waktu kompilasi untuk struktur konfigurasi.
  • titleField mengatur judul dokumen, contentFields mengatur konten utama, dan keywordsFields mengatur kata kunci atau bidang tag.
  • createOrUpdateIndex mendorong skema yang diperbarui ke layanan pencarian tanpa membangun kembali indeks atau menghapus dokumen.

Melakukan kueri pada indeks

Skrip kueri menjalankan tiga kueri secara berurutan, berkembang dari pencarian semantik dasar ke peringkat semantik dengan keterangan dan jawaban.

Kueri semantik (tanpa keterangan, tidak ada jawaban)

Skrip semanticQuery.ts menunjukkan persyaratan minimum untuk memanggil pemeringkatan semantik dengan hasil yang aman tipe.

import { SearchClient }
    from "@azure/search-documents";
import {
    HotelDocument, credential,
    searchEndpoint, indexName,
    semanticConfigurationName
} from "./config.js";

const searchClient =
    new SearchClient<HotelDocument>(
        searchEndpoint, indexName, credential
    );

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Poin-poin penting:

  • SearchClient<HotelDocument> menyediakan akses aman tipe ke bidang dokumen pada hasil, dengan pelengkapan otomatis untuk nama bidang di select dan result.document.
  • queryType: "semantic" mengaktifkan peringkat semantik pada kueri.
  • semanticSearchOptions.configurationName menentukan konfigurasi semantik mana yang akan digunakan.

Kueri semantik dengan keterangan

semanticQueryReturnCaptions.ts Skrip menambahkan teks pelengkap untuk mengekstrak bagian paling relevan dari setiap hasil, dengan penyorotan temuan hasil diterapkan pada istilah dan frasa penting.

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Poin-poin penting:

  • captions.captionType: "extractive" mengaktifkan keterangan ekstraktif dari bidang konten.
  • Keterangan menampilkan bagian yang paling relevan dan menambahkan <em> tag di sekitar istilah penting.

Kueri semantik dengan jawaban

semanticAnswer.ts Skrip menambahkan jawaban semantik. Ini menggunakan pertanyaan sebagai teks pencarian karena jawaban semantik berfungsi paling baik ketika kueri diungkapkan sebagai pertanyaan. Jawabannya adalah kutipan verbatim yang diekstrak dari indeks Anda, bukan respons yang dibentuk oleh model penyelesaian obrolan.

Kueri dan konten terindeks harus diratakan erat agar jawaban dikembalikan. Jika tidak ada kandidat yang memenuhi ambang keyakinan, respons tidak menyertakan jawaban. Contoh ini menggunakan pertanyaan yang diketahui menghasilkan hasil sehingga Anda dapat melihat sintaksnya. Jika jawaban tidak berguna untuk skenario Anda, hilangkan answers dari kode Anda. Untuk jawaban yang terstruktur, pertimbangkan pola RAG atau pengambilan informasi secara agenik.

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Poin-poin penting:

  • answers.answerType: "extractive" memungkinkan jawaban ekstraktif untuk kueri yang menyerupai pertanyaan.
  • Jawabannya adalah konten verbatim yang diekstrak dari indeks Anda, bukan teks yang dihasilkan.
  • results.answers mengambil objek jawaban secara terpisah dari hasil pencarian.

Dalam panduan memulai cepat ini, Anda menggunakan REST API Pencarian Azure AI untuk menambahkan peringkat semantik ke indeks pencarian yang ada dan melakukan kueri pada indeks tersebut.

Peringkat semantik adalah fungsionalitas sisi kueri yang menggunakan pemahaman pembacaan mesin untuk mengodekan ulang hasil pencarian, mempromosikan kecocokan yang paling relevan secara semantik ke bagian atas daftar. Anda dapat menambahkan konfigurasi semantik ke indeks yang ada tanpa persyaratan pembangunan ulang. Peringkat semantik paling efektif untuk teks informasi atau deskriptif.

Tips

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Pembaca Indeks Data Pencarian

Catatan

Tidak seperti panduan cepat lain yang membuat dan memuat indeks, panduan cepat ini menggunakan indeks yang sudah ada dan sudah berisi data, sehingga Anda tidak memerlukan peran Kontributor Data Indeks Pencarian.

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Mulai dengan indeks

Langkah cepat ini memodifikasi indeks yang ada untuk menyertakan konfigurasi semantik. Kami merekomendasikan indeks contoh hotel, yang dapat Anda buat dalam hitungan menit menggunakan wizard di portal Azure.

Untuk menggunakan indeks yang berbeda, ganti nama indeks, nama bidang dalam konfigurasi semantik, dan nama bidang dalam pernyataan kueri select di seluruh kode sampel. Indeks Anda harus berisi bidang teks deskriptif yang dikaitkan sebagai searchable dan retrievable.

Untuk meninjau dan menjalankan kueri pada indeks sampel hotel sebelum pengurutan semantik:

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari panel kiri, pilihIndeks> pencarian.

  3. Pilih hotel-sampel.

  4. Pilih Konfigurasi semantik untuk melihat konfigurasi yang ada. Jika Anda mengaktifkan peringkat semantik selama alur pembuatan wizard, harus ada konfigurasi default.

    Tangkapan layar pengaturan semantik bawaan di portal Azure.

  5. Pilih Penjelajah pencarian, lalu pilih Tampilkan>tampilan JSON.

  6. Tempelkan JSON berikut ke editor kueri.

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. Pilih Cari untuk menjalankan kueri.

    Responsnya harus mirip dengan contoh berikut. Ini adalah kueri teks lengkap yang diberi peringkat oleh BM25, sehingga hasilnya cocok pada istilah kueri individual dan varian linguistik daripada arti keseluruhan kueri. Misalnya, walking mencocokkan walk, dan live mencocokkan music secara independen daripada sebagai frasa.

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    Tips

    Kueri ini memperlihatkan tampilan respons sebelum peringkat semantik diterapkan. Setelah Anda mengonfigurasi konfigurasi semantik, tambahkan "queryType": "semantic" dan "semanticConfiguration": "semantic-config" untuk melihat bagaimana kueri yang sama diberi peringkat berbeda dengan peringkat semantik.

Siapkan lingkungan

  1. Gunakan Git untuk mengkloning repositori sampel.

    git clone https://github.com/Azure-Samples/azure-search-rest-samples

  2. Arahkan ke folder quickstart dan buka di Visual Studio Code.

    cd azure-search-rest-samples/Quickstart-semantic-ranking
code .

  3. Di semantic-index-update.rest, ganti nilai tempat penampung untuk @searchUrl dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Ulangi langkah sebelumnya untuk semantic-query.rest.

  5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

    az login

  6. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, buat token akses.

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

  7. Pada kedua file .rest, ganti placeholder untuk @personalAccessToken dengan token dari langkah sebelumnya.

Jalankan kode

  1. Buka semantic-index-update.rest.

  2. Pilih Kirim Permintaan pada permintaan GET pertama untuk memverifikasi koneksi Anda.

    Respons akan muncul di panel yang berdekatan. Jika Anda memiliki indeks yang sudah ada, indeks tersebut dicantumkan menurut nama. Jika kode HTTP adalah 200 OK, Anda siap untuk melanjutkan.

  3. ### Update the hotels-sample index to include a semantic configuration Kirim permintaan untuk menambahkan konfigurasi semantik ke indeks.

    Jika Anda mendapatkan kesalahan 400 Bad Request, skema indeks Anda berbeda dari contoh. ### Get the schema of the index Kirim permintaan, salin respons JSON, tambahkan semantic bagian dari kode sumber ke JSON, dan ganti isi permintaan PUT dengan skema gabungan Anda.

  4. Beralih ke semantic-query.rest dan mengirim permintaan secara berurutan: kueri sederhana untuk perbandingan garis besar, lalu kueri semantik dengan peringkat, keterangan, dan jawaban.

Keluaran

Permintaan Send a search query to the hotels-sample index mengembalikan hasil yang diberi peringkat oleh relevansi BM25, yang ditunjukkan oleh bidang @search.score.

{
  "@odata.count": 30,
  "value": [
    {
      "@search.score": 5.004435,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza..."
    },
    // Trimmed for brevity
  ]
}

Permintaan Send a search query to the hotels-sample index with semantic ranking menambahkan @search.rerankerScore. Perhatikan bahwa urutan berubah dari kueri sederhana.

{
  "@odata.count": 30,
  "@search.answers": [],
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown..."
    },
    // Trimmed for brevity
  ]
}

Permintaan Return captions in the query menambahkan @search.captions dengan teks yang diekstrak dan sorotan.

{
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops...",
          "highlights": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops..."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel"
    },
    // Trimmed for brevity
  ]
}

Permintaan Return semantic answers in the query mengembalikan jawaban ekstraktif dalam @search.answers saat kueri dirumuskan sebagai pertanyaan.

{
  "@odata.count": 46,
  "@search.answers": [
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night...",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Konfigurasi dan autentikasi
  2. Memperbarui indeks dengan konfigurasi semantik
  3. Menjalankan kueri pada indeks

Konfigurasi dan autentikasi

Kedua .rest file menentukan variabel di bagian atas untuk digunakan kembali di semua permintaan.

@searchUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@personalAccessToken = PUT-YOUR-PERSONAL-ACCESS-TOKEN-HERE
@api-version = 2026-04-01

Poin-poin penting:

  • @searchUrl adalah titik akhir layanan pencarian Anda.
  • @personalAccessToken adalah token Microsoft Entra ID yang diperoleh dari Azure CLI. Ini menggantikan kunci API dengan autentikasi tanpa kunci.
  • Authorization: Bearer {{personalAccessToken}} disertakan dalam setiap header permintaan untuk autentikasi.

Memperbarui indeks dengan konfigurasi semantik

### Update the hotels-sample index to include a semantic configuration Permintaan dalam semantic-index-update.rest mengirim skema indeks lengkap bersama dengan bagian barusemantic. REST API memerlukan skema lengkap untuk operasi pembaruan apa pun, sehingga Anda tidak hanya dapat mengirim konfigurasi semantik.

Penambahan kunci adalah bagian semantic :

"semantic": {
    "configurations": [
        {
            "name": "semantic-config",
            "rankingOrder":
                "BoostedRerankerScore",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        }
    ]
}

Poin-poin penting:

  • titleField mengidentifikasi bidang mana yang berisi judul dokumen untuk evaluasi semantik.
  • prioritizedContentFields mengidentifikasi bidang konten utama. Pemeringkat semantik mengevaluasi hal-hal ini terlebih dahulu saat menilai relevansi.
  • prioritizedKeywordsFields mengidentifikasi bidang kata kunci atau tag untuk konteks tambahan.
  • rankingOrder: BoostedRerankerScore menggabungkan skor BM25 dengan skor reranker semantik.
  • REST API memerlukan skema penuh untuk operasi PUT. Hanya bagian semantic yang baru; semua bidang lain tidak berubah.

Melakukan kueri pada indeks

Permintaan semantic-query.rest berprogres dari pencarian kata kunci sederhana hingga peringkat semantik yang dilengkapi dengan keterangan dan jawaban. Semua kueri adalah permintaan POST ke Documents - Search Post (REST API).

Kueri sederhana

Permintaan ### Send a search query to the hotels-sample index ini adalah pencarian kata kunci sederhana yang tidak menggunakan peringkat semantik. Ini berfungsi sebagai garis besar untuk membandingkan hasil dengan dan tanpa reranking semantik.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "simple"
}

Poin-poin penting:

  • queryType: "simple" menggunakan algoritma peringkat BM25 default.
  • Hasil diberi peringkat berdasarkan relevansi kata kunci (@search.score) saja.

Kueri semantik (tanpa keterangan, tidak ada jawaban)

Permintaan menambahkan pemeringkatan semantik ### Send a search query to the hotels-sample index with semantic ranking. JSON berikut menunjukkan persyaratan minimum untuk memanggil peringkat semantik.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config"
}

Poin-poin penting:

  • queryType: "semantic" mengaktifkan peringkat semantik pada kueri.
  • semanticConfiguration menentukan konfigurasi semantik mana yang akan digunakan.

Kueri semantik dengan keterangan

Permintaan ini menambahkan keterangan tambahan untuk mengekstrak bagian yang paling relevan dari setiap hasil, dengan penyorotan yang menandai diterapkan pada istilah dan frasa penting.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true"
}

Poin-poin penting:

  • captions: "extractive|highlight-true" memungkinkan keterangan ekstraktif dengan penandaan <em> di sekitar istilah penting.
  • Keterangan muncul dalam @search.captions array untuk setiap hasil.

Kueri semantik dengan jawaban

Permintaan menambahkan jawaban semantik ### Return semantic answers in the query. Ini menggunakan pertanyaan sebagai teks pencarian karena jawaban semantik berfungsi paling baik ketika kueri diungkapkan sebagai pertanyaan. Jawabannya adalah kutipan verbatim yang diekstrak dari indeks Anda, bukan respons yang dibentuk oleh model penyelesaian obrolan.

Kueri dan konten terindeks harus diratakan erat agar jawaban dikembalikan. Jika tidak ada kandidat yang memenuhi ambang keyakinan, respons tidak menyertakan jawaban. Contoh ini menggunakan pertanyaan yang diketahui menghasilkan hasil sehingga Anda dapat melihat sintaksnya. Jika jawaban tidak berguna untuk skenario Anda, hilangkan answers parameter dari permintaan Anda. Untuk jawaban yang terstruktur, pertimbangkan pola RAG atau pengambilan informasi secara agenik.

{
    "search":
        "what's a good hotel for people who like to read",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive"
}

Poin-poin penting:

  • answers: "extractive" memungkinkan jawaban ekstraktif untuk kueri yang menyerupai pertanyaan.
  • Jawaban muncul di array @search.answers tingkat atas, terpisah dari hasil individual.
  • Jawabannya adalah konten verbatim yang diekstrak dari indeks Anda, bukan teks yang dihasilkan.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menyebabkan biaya tambahan.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Konten terkait

  • Terakhir diperbarui pada