Hızlı Başlangıç: Anlam derecelendirmesi

Not

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Bu hızlı başlangıçta, var olan bir Azure Yapay Zeka Arama dizinine anlamsal derecelendirme ekleyecek ve sonuç ilgi düzeyini artırmak için anlamsal sorgular çalıştıracaksınız. Tercih ettiğiniz SDK'yı veya REST iş akışını seçmek için dil sekmelerini kullanın.

Bu hızlı başlangıçta, .NET için Azure Yapay Zeka Arama istemci kitaplığını kullanarak var olan bir arama dizinine semantic ranking ekleyecek ve dizini sorgulaacaksınız.

Anlamsal derecelendirme, arama sonuçlarını yeniden puanlama amacıyla makine okuma kavramasını kullanan sorgu tarafı işlevselliğidir ve en ilgili eşleşmeleri listenin en üstüne yükseltmeyi sağlar. Yeniden derleme gereksinimi olmadan var olan bir dizine anlamsal yapılandırma ekleyebilirsiniz. Anlamsal derecelendirme en çok bilgilendirici veya açıklayıcı metinler için etkilidir.

Ipucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Okuyucusu

Not

Diğer dizin oluşturma ve yükleme hızlı başlatmalarından farklı olarak, bu hızlı başlatmamızda halihazırda veri içeren mevcut bir dizin olduğu kabul edilir, bu nedenle Arama Dizin Verisi Katkıcısı rolüne ihtiyacınız yoktur.

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Dizinle başlayın

Bu hızlı başlangıç, var olan bir dizini anlamsal yapılandırma içerecek şekilde değiştirir. Bir Azure portalı sihirbazını kullanarak dakikalar içinde oluşturabileceğiniz hotels-sample dizinini öneririz.

Farklı bir dizin kullanmak için dizin adını, anlamsal yapılandırmadaki alan adlarını ve örnek kodun tamamında sorgu select deyimlerindeki alan adlarını değiştirin. Dizininiz, searchable ve retrievable özniteliklendirilen açıklayıcı metin alanları içermelidir.

Anlam sıralamasından önce hotels-sample dizinini gözden geçirmek ve sorgulamak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Arama yönetimi>Dizinleri'ni seçin.

  3. Hotels-sample seçeneğini belirleyin.

  4. Mevcut yapılandırmaları görüntülemek için Anlamsal yapılandırmalar'ı seçin. Sihirbaz oluşturma akışı sırasında anlamsal derecelendirmeyi etkinleştirdiyseniz varsayılan bir yapılandırma olmalıdır.

    Azure portalındaki varsayılan anlamsal yapılandırmanın ekran görüntüsü.

  5. Arama gezgini'ne ve ardındanJSON görünümünü> tıklayın.

  6. Aşağıdaki JSON dosyasını sorgu düzenleyicisine yapıştırın.

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

  7. Sorguyu çalıştırmak için Ara'yı seçin.

    Yanıt aşağıdaki örneğe benzer olmalıdır. Bu, BM25 tarafından derecelendirilen bir tam metin sorgusudur, bu nedenle sonuçlar sorgunun genel anlamı yerine tek tek sorgu terimleriyle ve dilsel değişkenlerle eşleşmektedir. Örneğin, walking ile walk eşleşir ve live ile music bağımsız olarak, tümcecik olarak değil, eşleşir.

    "@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
]

    Ipucu

    Bu sorgu, semantik derecelendirme uygulanmadan önce yanıtın nasıl göründüğünü gösterir. Anlamsal yapılandırmayı yaptıktan sonra, sorguyu semantik derecelendirme ile farklı şekilde nasıl derecelendiğini görmek için "queryType": "semantic" ve "semanticConfiguration": "semantic-config" ekleyin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

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

  2. Hızlı başlangıç klasörüne gidin.

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

  3. BuildIndex/Program.cs içinde, endpoint yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

  4. için QueryIndex/Program.csönceki adımı yineleyin.

  5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştırma

  1. Dizini anlamsal bir yapılandırmayla güncelleştirmek için ilk projeyi çalıştırın.

    dotnet run --project BuildIndex

  2. dizini sorgulamak için ikinci projeyi çalıştırın. Basit sorgudan açıklamalı alt yazılar ve yanıtlarla anlamsal sorguya ilerleme durumunu görmek için sorgular arasında Enter tuşuna basın.

    dotnet run --project QueryIndex

Çıkış

İlk proje, hotels-sample dizinini anlamsal bir yapılandırmayla güncelleştirir. Çıkış, anlamsal yapılandırmanın onayını içerir.

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

İkinci proje dört sorgu çalıştırır. Çıktı, ilgi derecelerini, başlıkları ve yanıtları içeren arama sonuçlarını içerir.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Yapılandırma ve kimlik doğrulaması
  2. Dizini anlamsal yapılandırmayla güncelleştirme
  3. Dizini sorgulama

Yapılandırma ve kimlik doğrulaması

Her iki proje de aynı yapılandırma desenini paylaşır. Program.cs dosyalar arama uç noktasını tanımlar ve anahtarsız kimlik doğrulama için DefaultAzureCredential kullanılır.

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

Önemli çıkarımlar:

  • DefaultAzureCredential, Microsoft Entra ID kullanarak anahtarsız kimlik doğrulaması sağlar. az login'dan Azure CLI kimlik bilgileri dahil olmak üzere birden çok kimlik bilgisi türünü zincirler.
  • SearchIndexClient dizin şemasını güncelleştirme gibi dizin düzeyinde işlemleri yönetir.
  • SearchClient dizini sorgulama gibi belge düzeyindeki işlemleri işler.

Dizini anlamsal yapılandırmayla güncelleştirme

içindeki aşağıdaki kod BuildIndex/Program.cs , var olan dizine anlamsal bir yapılandırma ekler. Bu işlem hiçbir arama belgesini silmez ve yapılandırma eklendikten sonra dizininiz çalışır durumda kalır.

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;
}

Önemli çıkarımlar:

  • Anlamsal yapılandırma, semantik derecelendirme için kullanılan alanları belirtir.
  • Semantik yapılandırmalar yeniden derlenmeden mevcut dizinlere eklenebilir.
  • TitleField , belge başlığını temsil eden alanı ayarlar.
  • ContentFields , ana içeriği içeren alanları ayarlar.
  • KeywordsFields anahtar sözcük veya etiket içeren alanları ayarlar.

Dizini sorgulama

Proje QueryIndex sırayla dört sorgu çalıştırır ve basit bir anahtar sözcük aramasından açıklamalı alt yazılar ve yanıtlarla anlamsal derecelendirmeye doğru ilerler.

Basit sorgu

İlk sorgu, anlamsal derecelendirme kullanmayan basit bir anahtar sözcük aramasıdır. Bu sorgu, semantik yeniden sıralama ile ve olmadan sonuçları karşılaştırmak için bir temel görevi görür.

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

Önemli çıkarımlar:

  • SearchQueryType.Simple varsayılan BM25 derecelendirme algoritmasını kullanır.
  • Sonuçlar yalnızca anahtar sözcük ilgi düzeyine (@search.score) göre derecelenir.

Anlamsal sorgu (açıklamalı alt yazı yok, yanıt yok)

Sonraki sorgu, açıklamalı alt yazı veya yanıt içermeyen anlamsal derecelendirme ekler. Aşağıdaki kod semantik derecelendirmeyi çağırmak için en düşük gereksinimi gösterir.

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);

Önemli çıkarımlar:

  • SearchQueryType.Semantic sorguda anlamsal derecelendirmeyi etkinleştirir.
  • SemanticConfigurationName kullanılacak semantik yapılandırmayı belirtir.
  • @search.rerankerScore anlamsal ilgiyi gösterir (daha yüksek daha iyidir).
  • Terim sorgusunun ilk sonuçları anlamsal derecelendirme modelleri kullanılarak yeniden puanlanır. Bu veri kümesi ve sorgu için, daha düşük dereceli sonuçlarda semantik derecelendirmenin etkileri daha belirgindir.

Açıklamalı alt yazılar içeren anlamsal sorgu

Aşağıdaki kod, önemli terimlerin ve ifadelerin vurgulandığı her sonuçtan en uygun bölümleri çıkarmak için başlıklar ekler.

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
);

Önemli çıkarımlar:

  • QueryCaption içerik alanlarından çıkarsamalı altyazıları etkinleştirir.
  • Açıklamalı alt yazılar en uygun bölümleri ortaya çıkararak önemli terimlerin çevresine etiketler ekler <em> .

Yanıtlarla anlamsal sorgu

Son sorgu semantik yanıtlar ekler. Bu sorgu farklı bir arama dizesi (searchText2) kullanır çünkü sorgu soru olarak ifade edildiğinde anlamsal yanıtlar en iyi sonucu verir. Yanıt, bir sohbet tamamlama modelinden oluşturulmuş bir yanıt değil, dizininizden ayıklanan ayrıntılı bir metindir.

Yanıtın döndürülebilmesi için sorgunun ve dizine alınan içeriğin yakından hizalanması gerekir. Hiçbir aday güvenilirlik eşiğini karşılamıyorsa yanıt bir yanıt içermez. Bu örnekte, söz dizimini görebilmeniz için sonuç ürettiği bilinen bir soru kullanılır. Yanıtlar senaryonuz için yararlı değilse, kodunuzdan QueryAnswer öğesini çıkarın. Oluşturulan yanıtlar için RAG desenini veya etkin alma yöntemini göz önünde bulundurun.

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
);

Önemli çıkarımlar:

  • QueryAnswer soru benzeri sorgular için ayıklayıcı yanıtlar sağlar.
  • Yanıtlar, dizininizden ayıklanan ayrıntılı içeriklerdir, oluşturulan metin değildir.

Bu hızlı başlangıçta, Java için Azure Yapay Zeka Arama istemci kitaplığını kullanarak var olan bir arama dizinine semantic ranking ekler ve dizini sorgularsınız.

Anlamsal derecelendirme, arama sonuçlarını yeniden puanlama amacıyla makine okuma kavramasını kullanan sorgu tarafı işlevselliğidir ve en ilgili eşleşmeleri listenin en üstüne yükseltmeyi sağlar. Yeniden derleme gereksinimi olmadan var olan bir dizine anlamsal yapılandırma ekleyebilirsiniz. Anlamsal derecelendirme en çok bilgilendirici veya açıklayıcı metinler için etkilidir.

Ipucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Okuyucusu

Not

Diğer dizin oluşturma ve yükleme hızlı başlatmalarından farklı olarak, bu hızlı başlatmamızda halihazırda veri içeren mevcut bir dizin olduğu kabul edilir, bu nedenle Arama Dizin Verisi Katkıcısı rolüne ihtiyacınız yoktur.

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Dizinle başlayın

Bu hızlı başlangıç, var olan bir dizini anlamsal yapılandırma içerecek şekilde değiştirir. Bir Azure portalı sihirbazını kullanarak dakikalar içinde oluşturabileceğiniz hotels-sample dizinini öneririz.

Farklı bir dizin kullanmak için dizin adını, anlamsal yapılandırmadaki alan adlarını ve örnek kodun tamamında sorgu select deyimlerindeki alan adlarını değiştirin. Dizininiz, searchable ve retrievable özniteliklendirilen açıklayıcı metin alanları içermelidir.

Anlam sıralamasından önce hotels-sample dizinini gözden geçirmek ve sorgulamak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Arama yönetimi>Dizinleri'ni seçin.

  3. Hotels-sample seçeneğini belirleyin.

  4. Mevcut yapılandırmaları görüntülemek için Anlamsal yapılandırmalar'ı seçin. Sihirbaz oluşturma akışı sırasında anlamsal derecelendirmeyi etkinleştirdiyseniz varsayılan bir yapılandırma olmalıdır.

    Azure portalındaki varsayılan anlamsal yapılandırmanın ekran görüntüsü.

  5. Arama gezgini'ne ve ardındanJSON görünümünü> tıklayın.

  6. Aşağıdaki JSON dosyasını sorgu düzenleyicisine yapıştırın.

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

  7. Sorguyu çalıştırmak için Ara'yı seçin.

    Yanıt aşağıdaki örneğe benzer olmalıdır. Bu, BM25 tarafından derecelendirilen bir tam metin sorgusudur, bu nedenle sonuçlar sorgunun genel anlamı yerine tek tek sorgu terimleriyle ve dilsel değişkenlerle eşleşmektedir. Örneğin, walking ile walk eşleşir ve live ile music bağımsız olarak, tümcecik olarak değil, eşleşir.

    "@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
]

    Ipucu

    Bu sorgu, semantik derecelendirme uygulanmadan önce yanıtın nasıl göründüğünü gösterir. Anlamsal yapılandırmayı yaptıktan sonra, sorguyu semantik derecelendirme ile farklı şekilde nasıl derecelendiğini görmek için "queryType": "semantic" ve "semanticConfiguration": "semantic-config" ekleyin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

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

  2. Hızlı başlangıç klasörüne gidin.

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

  3. src/main/resources/application.properties içinde, azure.search.endpoint yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

  4. Azure-search-documents dahil olmak üzere bağımlılıkları çözmek için projeyi derleyin.

    mvn compile

    Derleme tamamlandığında, çıkışta hata görünmediğini doğrulayın.

  5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştırma

  1. Mevcut dizin ayarlarını alın.

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

  2. Dizini anlamsal bir yapılandırmayla güncelleştirin.

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

  3. Anlamsal bir sorgu çalıştırın.

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

  4. Açıklamalı alt yazılarla anlamsal bir sorgu çalıştırın.

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

  5. Yanıtlar içeren bir anlamsal sorgu çalıştırın.

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

Çıkış

GetIndexSettings.java çıktısı, dizinin adı, alanları ve anlamsal yapılandırmalarıdır. Yeni bir yapılandırma eklemeden önce dizinde yalnızca varsayılan yapılandırma bulunur.

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

Çıktısı, kod tarafından eklenen yapılandırma da dahil olmak üzere dizindeki tüm anlamsal yapılandırmaları listeler ve ardından bir başarı iletisi gösterir.

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

SemanticQuery.java çıktısı, semantik derecelendirme yeniden sıralayıcı puanına göre sıralanmış tüm eşleşen belgeleri döndürür.

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

çıktısı, arama alanlarının SemanticQueryWithCaptions.java yanına isabet vurgulama içeren bir resim yazısı öğesi ekler. Açıklamalı alt yazılar, sonuçtaki en ilgili bölümlerdir. Dizininiz daha büyük metin içeriyorsa resim yazıları en ilginç cümlelerin ayıklanmasında yardımcı olur.

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

çıktısı SemanticAnswer.java , soruyla en iyi eşleşen sonuçlardan birinden alınan anlamsal bir yanıt ve ardından açıklamalı alt yazılar içeren arama sonuçlarını içerir.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Yapılandırma ve kimlik doğrulaması
  2. Dizini anlamsal yapılandırmayla güncelleştirme
  3. Dizini sorgulama

Yapılandırma ve kimlik doğrulaması

SearchConfig.java sınıfı, öğesinden application.properties özellikleri yükler ve anahtarsız kimlik doğrulaması için bir DefaultAzureCredential oluşturur.

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();
}

Önemli çıkarımlar:

  • DefaultAzureCredential, Microsoft Entra ID kullanarak anahtarsız kimlik doğrulaması sağlar. az login'dan Azure CLI kimlik bilgileri dahil olmak üzere birden çok kimlik bilgisi türünü zincirler.
  • Özellikler, sınıf yolu içindeki dosyadan application.properties yüklenir.
  • Statik alanlar (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) projedeki tüm sınıflar arasında paylaşılır.

Dizini anlamsal yapılandırmayla güncelleştirme

sınıfı, UpdateIndexSettings.java var olan hotels-sample dizine semantik bir yapılandırma ekler. Bu işlem hiçbir arama belgesini silmez ve yapılandırma eklendikten sonra dizininiz çalışır durumda kalır.

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);

Önemli çıkarımlar:

  • SemanticPrioritizedFields semantik dereceleyicinin hangi alanları değerlendirdiği tanımlar. setTitleField belge başlığını ayarlar, setContentFields ana içeriği ayarlar ve setKeywordsFields anahtar sözcük veya etiket alanlarını ayarlar.
  • SemanticConfiguration bir adı önceliklendirilmiş alanlarla eşleştirerek sorgu zamanında hangi semantik yapılandırmanın kullanılacağını belirler.
  • createOrUpdateIndex dizini yeniden oluşturmadan veya belgeleri silmeden güncelleştirilmiş şemayı arama hizmetine yönlendirir.

Dizini sorgulama

Aşağıdaki üç sınıf dizini sırasıyla sorgular ve temel bir anlamsal aramadan açıklamalı alt yazılar ve yanıtlarla anlam derecelendirmesine ilerler.

Anlamsal sorgu (açıklamalı alt yazı yok, yanıt yok)

İlk sorgu, açıklamalı alt yazı veya yanıt içermeyen anlamsal derecelendirme ekler. sınıfı, SemanticQuery.java semantik derecelendirmeyi çağırmak için en düşük gereksinimi gösterir.

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"));
}

Önemli çıkarımlar:

  • QueryType.SEMANTIC sorguda anlamsal derecelendirmeyi etkinleştirir.
  • setSemanticConfigurationName kullanılacak semantik yapılandırmayı belirtir.
  • SearchPagedIterable yeniden sıralanan sonuçlar üzerinde bir yineleyici sağlar. Her bir SearchResult, reranker skoru için bir getSemanticSearch() erişimci içerir.

Açıklamalı alt yazılar içeren anlamsal sorgu

Sınıf, SemanticQueryWithCaptions.java her sonuçtan en uygun bölümleri ayıklamak için başlıklar ekler ve önemli terimlere ve ifadelere vurgulama uygulanır.

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());
        }
    }
}

Önemli çıkarımlar:

  • QueryCaption(QueryCaptionType.EXTRACTIVE) içerik alanlarından çıkarsamalı altyazıları etkinleştirir.
  • setHighlightEnabled(true) açıklamalı alt yazılarda önemli terimlerin çevresine etiketler ekler <em> .
  • Her SearchResult bir getQueryCaptions() anlam arama erişimcisini sağlar.

Yanıtlarla anlamsal sorgu

SemanticAnswer.java sınıfı anlamsal yanıtlar ekler. Bu sınıf arama metni olarak bir soru kullanır çünkü sorgu bir soru olarak ifade edildiğinde anlamsal yanıtlar en iyi sonucu verir. Yanıt, bir sohbet tamamlama modelinden oluşturulmuş bir yanıt değil, dizininizden ayıklanan ayrıntılı bir metindir.

Yanıtın döndürülebilmesi için sorgunun ve dizine alınan içeriğin yakından hizalanması gerekir. Hiçbir aday güvenilirlik eşiğini karşılamıyorsa yanıt bir yanıt içermez. Bu örnekte, söz dizimini görebilmeniz için sonuç ürettiği bilinen bir soru kullanılır. Yanıtlar senaryonuz için yararlı değilse, kodunuzdan setQueryAnswer öğesini çıkarın. Oluşturulan yanıtlar için RAG desenini veya etkin alma yöntemini göz önünde bulundurun.

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());
}

Önemli çıkarımlar:

  • QueryAnswer(QueryAnswerType.EXTRACTIVE) soru benzeri sorgular için ayıklayıcı yanıtlar sağlar.
  • Yanıtlar, dizininizden ayıklanan ayrıntılı içeriklerdir, oluşturulan metin değildir.
  • results.getSemanticResults().getQueryAnswers() yanıt nesnelerini arama sonuçlarından ayrı olarak alır.

Bu hızlı başlangıçta, mevcut bir arama dizinine anlamsal sıralama eklemek ve dizini sorgulamak için JavaScript için Azure Yapay Zeka Arama istemci kitaplığını kullanacaksınız.

Anlamsal derecelendirme, arama sonuçlarını yeniden puanlama amacıyla makine okuma kavramasını kullanan sorgu tarafı işlevselliğidir ve en ilgili eşleşmeleri listenin en üstüne yükseltmeyi sağlar. Yeniden derleme gereksinimi olmadan var olan bir dizine anlamsal yapılandırma ekleyebilirsiniz. Anlamsal derecelendirme en çok bilgilendirici veya açıklayıcı metinler için etkilidir.

Ipucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Okuyucusu

Not

Diğer dizin oluşturma ve yükleme hızlı başlatmalarından farklı olarak, bu hızlı başlatmamızda halihazırda veri içeren mevcut bir dizin olduğu kabul edilir, bu nedenle Arama Dizin Verisi Katkıcısı rolüne ihtiyacınız yoktur.

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Dizinle başlayın

Bu hızlı başlangıç, var olan bir dizini anlamsal yapılandırma içerecek şekilde değiştirir. Bir Azure portalı sihirbazını kullanarak dakikalar içinde oluşturabileceğiniz hotels-sample dizinini öneririz.

Farklı bir dizin kullanmak için dizin adını, anlamsal yapılandırmadaki alan adlarını ve örnek kodun tamamında sorgu select deyimlerindeki alan adlarını değiştirin. Dizininiz, searchable ve retrievable özniteliklendirilen açıklayıcı metin alanları içermelidir.

Anlam sıralamasından önce hotels-sample dizinini gözden geçirmek ve sorgulamak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Arama yönetimi>Dizinleri'ni seçin.

  3. Hotels-sample seçeneğini belirleyin.

  4. Mevcut yapılandırmaları görüntülemek için Anlamsal yapılandırmalar'ı seçin. Sihirbaz oluşturma akışı sırasında anlamsal derecelendirmeyi etkinleştirdiyseniz varsayılan bir yapılandırma olmalıdır.

    Azure portalındaki varsayılan anlamsal yapılandırmanın ekran görüntüsü.

  5. Arama gezgini'ne ve ardındanJSON görünümünü> tıklayın.

  6. Aşağıdaki JSON dosyasını sorgu düzenleyicisine yapıştırın.

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

  7. Sorguyu çalıştırmak için Ara'yı seçin.

    Yanıt aşağıdaki örneğe benzer olmalıdır. Bu, BM25 tarafından derecelendirilen bir tam metin sorgusudur, bu nedenle sonuçlar sorgunun genel anlamı yerine tek tek sorgu terimleriyle ve dilsel değişkenlerle eşleşmektedir. Örneğin, walking ile walk eşleşir ve live ile music bağımsız olarak, tümcecik olarak değil, eşleşir.

    "@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
]

    Ipucu

    Bu sorgu, semantik derecelendirme uygulanmadan önce yanıtın nasıl göründüğünü gösterir. Anlamsal yapılandırmayı yaptıktan sonra, sorguyu semantik derecelendirme ile farklı şekilde nasıl derecelendiğini görmek için "queryType": "semantic" ve "semanticConfiguration": "semantic-config" ekleyin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

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

  2. Hızlı başlangıç klasörüne gidin.

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

  3. sample.env içinde, AZURE_SEARCH_ENDPOINT yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

  4. olarak sample.envyeniden adlandırın.env.

    mv sample.env .env

  5. Bağımlılıkları yükleyin.

    npm install

    Yükleme tamamlandığında proje dizininde bir node_modules klasör görmeniz gerekir.

  6. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştırma

  1. Mevcut dizin ayarlarını alın.

    node -r dotenv/config src/getIndexSettings.js

  2. Dizini anlamsal bir yapılandırmayla güncelleştirin.

    node -r dotenv/config src/updateIndexSettings.js

  3. Anlamsal bir sorgu çalıştırın.

    node -r dotenv/config src/semanticQuery.js

  4. Açıklamalı alt yazılarla anlamsal bir sorgu çalıştırın.

    node -r dotenv/config src/semanticQueryReturnCaptions.js

  5. Yanıtlar içeren bir anlamsal sorgu çalıştırın.

    node -r dotenv/config src/semanticAnswer.js

Çıkış

Betik getIndexSettings.js dizinin adını, alanlarını ve var olan tüm anlamsal yapılandırmaları döndürür.

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 betiği, kodun eklediği konfigürasyon da dahil olmak üzere dizindeki tüm anlamsal yapılandırmaları döndürür ve ardından bir başarı mesajı verir.

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.

Script, tüm eşleşen belgeleri semantik sıralama yeniden sıralayıcı puanına göre sıralanmış olarak döndürür.

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

Betik, semanticQueryReturnCaptions.js arama alanlarının yanında isabet vurgulama içeren bir resim yazısı öğesi döndürür. Açıklamalı alt yazılar, sonuçtaki en ilgili bölümlerdir. Dizininiz daha büyük metin içeriyorsa resim yazıları en ilginç cümlelerin ayıklanmasında yardımcı olur.

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

Betik, semanticAnswer.js soruyla en iyi eşleşen sonuçlardan birinden alınan anlamsal bir yanıt döndürür ve ardından açıklamalı alt yazılar içeren arama sonuçları döndürür.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Yapılandırma ve kimlik doğrulaması
  2. Dizini anlamsal yapılandırmayla güncelleştirme
  3. Dizini sorgulama

Yapılandırma ve kimlik doğrulaması

Dosya ortam config.js değişkenlerini yükler ve kimlik doğrulaması için bir DefaultAzureCredential oluşturur.

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();

Önemli çıkarımlar:

  • DefaultAzureCredential, Microsoft Entra ID kullanarak anahtarsız kimlik doğrulaması sağlar. az login'dan Azure CLI kimlik bilgileri dahil olmak üzere birden çok kimlik bilgisi türünü zincirler.
  • Ortam değişkenleri .env kullanılarak dotenv dosyasından yüklenir.

Dizini anlamsal yapılandırmayla güncelleştirme

Dosya, updateIndexSettings.js var olan hotels-sample dizine anlamsal bir yapılandırma ekler. Bu işlem hiçbir arama belgesini silmez ve yapılandırma eklendikten sonra dizininiz çalışır durumda kalır.

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);

Önemli çıkarımlar:

  • Anlamsal yapılandırma, semantik derecelendirme için kullanılan alanları belirtir. titleField belge başlığını tanımlar, contentFields ana içeriği tanımlar ve keywordsFields anahtar sözcük veya etiket alanlarını tanımlar.
  • Bir yapılandırma nesnesi oluşturup varolan dizinin semanticSearch.configurations dizisine gönderebilirsiniz.
  • createOrUpdateIndex dizini yeniden oluşturmadan veya belgeleri silmeden güncelleştirilmiş şemayı arama hizmetine yönlendirir.

Dizini sorgulama

Sorgu betikleri sırayla üç sorgu çalıştırır ve temel bir anlamsal aramadan açıklamalı alt yazılar ve yanıtlarla anlam sıralamasına ilerler.

Anlamsal sorgu (açıklamalı alt yazı yok, yanıt yok)

Aşağıdaki kod semantik derecelendirmeyi çağırmak için en düşük gereksinimi gösterir.

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"
        ]
    }
);

Önemli çıkarımlar:

  • queryType: "semantic" sorguda anlamsal derecelendirmeyi etkinleştirir.
  • semanticSearchOptions.configurationName kullanılacak semantik yapılandırmayı belirtir.
  • in rerankerScore sonuçları anlamsal ilgiyi gösterir (daha yüksek daha iyidir).

Açıklamalı alt yazılar içeren anlamsal sorgu

Aşağıdaki kod, önemli terimlerin ve ifadelerin vurgulandığı her sonuçtan en uygun bölümleri çıkarmak için başlıklar ekler.

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}`
            );
        }
    }
}

Önemli çıkarımlar:

  • captions.captionType: "extractive" içerik alanlarından çıkarsamalı altyazıları etkinleştirir.
  • Açıklamalı alt yazılar en uygun bölümleri ortaya çıkararak önemli terimlerin çevresine etiketler ekler <em> .

Yanıtlarla anlamsal sorgu

Son sorgu semantik yanıtlar ekler. Bu sorguda arama metni olarak bir soru kullanılır çünkü sorgu soru olarak ifade edildiğinde anlamsal yanıtlar en iyi sonucu verir. Yanıt, bir sohbet tamamlama modelinden oluşturulmuş bir yanıt değil, dizininizden ayıklanan ayrıntılı bir metindir.

Yanıtın döndürülebilmesi için sorgunun ve dizine alınan içeriğin yakından hizalanması gerekir. Hiçbir aday güvenilirlik eşiğini karşılamıyorsa yanıt bir yanıt içermez. Bu örnekte, söz dizimini görebilmeniz için sonuç ürettiği bilinen bir soru kullanılır. Yanıtlar senaryonuz için yararlı değilse, kodunuzdan answers öğesini çıkarın. Oluşturulan yanıtlar için RAG desenini veya etkin alma yöntemini göz önünde bulundurun.

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}`
    );
}

Önemli çıkarımlar:

  • answers.answerType: "extractive" soru benzeri sorgular için ayıklayıcı yanıtlar sağlar.
  • Yanıtlar, dizininizden ayıklanan ayrıntılı içeriklerdir, oluşturulan metin değildir.
  • results.answers yanıt nesnelerini arama sonuçlarından ayrı olarak alır.

Bu hızlı başlangıçta, Python için Azure Yapay Zeka Arama istemci kitaplığını kullanarak var olan bir arama dizinine semantic ranking ekler ve dizini sorgularsınız.

Anlamsal derecelendirme, arama sonuçlarını yeniden puanlama amacıyla makine okuma kavramasını kullanan sorgu tarafı işlevselliğidir ve en ilgili eşleşmeleri listenin en üstüne yükseltmeyi sağlar. Yeniden derleme gereksinimi olmadan var olan bir dizine anlamsal yapılandırma ekleyebilirsiniz. Anlamsal derecelendirme en çok bilgilendirici veya açıklayıcı metinler için etkilidir.

Ipucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Okuyucusu

Not

Diğer dizin oluşturma ve yükleme hızlı başlatmalarından farklı olarak, bu hızlı başlatmamızda halihazırda veri içeren mevcut bir dizin olduğu kabul edilir, bu nedenle Arama Dizin Verisi Katkıcısı rolüne ihtiyacınız yoktur.

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Dizinle başlayın

Bu hızlı başlangıç, var olan bir dizini anlamsal yapılandırma içerecek şekilde değiştirir. Bir Azure portalı sihirbazını kullanarak dakikalar içinde oluşturabileceğiniz hotels-sample dizinini öneririz.

Farklı bir dizin kullanmak için dizin adını, anlamsal yapılandırmadaki alan adlarını ve örnek kodun tamamında sorgu select deyimlerindeki alan adlarını değiştirin. Dizininiz, searchable ve retrievable özniteliklendirilen açıklayıcı metin alanları içermelidir.

Anlam sıralamasından önce hotels-sample dizinini gözden geçirmek ve sorgulamak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Arama yönetimi>Dizinleri'ni seçin.

  3. Hotels-sample seçeneğini belirleyin.

  4. Mevcut yapılandırmaları görüntülemek için Anlamsal yapılandırmalar'ı seçin. Sihirbaz oluşturma akışı sırasında anlamsal derecelendirmeyi etkinleştirdiyseniz varsayılan bir yapılandırma olmalıdır.

    Azure portalındaki varsayılan anlamsal yapılandırmanın ekran görüntüsü.

  5. Arama gezgini'ne ve ardındanJSON görünümünü> tıklayın.

  6. Aşağıdaki JSON dosyasını sorgu düzenleyicisine yapıştırın.

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

  7. Sorguyu çalıştırmak için Ara'yı seçin.

    Yanıt aşağıdaki örneğe benzer olmalıdır. Bu, BM25 tarafından derecelendirilen bir tam metin sorgusudur, bu nedenle sonuçlar sorgunun genel anlamı yerine tek tek sorgu terimleriyle ve dilsel değişkenlerle eşleşmektedir. Örneğin, walking ile walk eşleşir ve live ile music bağımsız olarak, tümcecik olarak değil, eşleşir.

    "@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
]

    Ipucu

    Bu sorgu, semantik derecelendirme uygulanmadan önce yanıtın nasıl göründüğünü gösterir. Anlamsal yapılandırmayı yaptıktan sonra, sorguyu semantik derecelendirme ile farklı şekilde nasıl derecelendiğini görmek için "queryType": "semantic" ve "semanticConfiguration": "semantic-config" ekleyin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

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

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

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

  3. sample.env içinde, AZURE_SEARCH_ENDPOINT yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

  4. olarak sample.envyeniden adlandırın.env.

    mv sample.env .env

  5. Aç semantic-ranking-quickstart.ipynb.

  6. Ctrl+Shift+P tuşlarına basın, Not Defteri: Not Defteri Çekirdeği'ni seçin ve bir sanal ortam oluşturmak için istemleri izleyin. Bağımlılıklar için requirements.txt seçin.

    Tamamlandığında, proje dizininde bir .venv klasör görmeniz gerekir.

  7. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştırma

  1. Install packages and set variables Gerekli paketleri yüklemek ve ortam değişkenlerini yüklemek için hücreleri çalıştırın.

  2. Semantik yapılandırma eklemek ve dizini sorgulamak için kalan hücreleri sıralı olarak çalıştırın.

Çıkış

Get the index definition hücresinin çıktısı dizinin adı, alanları ve mevcut herhangi bir anlamsal yapılandırmadır.

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

Hücrenin Add a semantic configuration to the index çıktısı, eklenen kod dahil olmak üzere dizindeki tüm anlamsal yapılandırmaları ve ardından bir başarı iletisini listeler.

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!

Hücrenin Run a term query çıkışı, BM25 puanına göre sıralanmış tüm eşleşen belgeleri döndürür. Bu temel sorgu semantik derecelendirme kullanmaz.

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

Hücrenin Run a semantic query çıkışı, semantik yeniden sıralama puanına göre sıralanmış tüm eşleşen belgeleri döndürür.

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

Hücrenin çıktısı, arama alanlarına isabet vurgulama özelliğiyle birlikte bir başlık öğesi ekler. Açıklamalı alt yazılar, sonuçtaki en ilgili bölümlerdir. Dizininiz daha büyük metin içeriyorsa resim yazıları en ilginç cümlelerin ayıklanmasında yardımcı olur.

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

Hücrenin çıktısı Return semantic answers , soruyla en iyi eşleşen sonuçlardan birinden alınan bir anlamsal yanıt ve ardından açıklamalı alt yazılar içeren arama sonuçları içerir.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Yapılandırma ve kimlik doğrulaması
  2. Dizini anlamsal yapılandırmayla güncelleştirme
  3. Dizini sorgulama

Yapılandırma ve kimlik doğrulaması

Hücre ortam Install packages and set variables değişkenlerini yükler ve kimlik doğrulaması için bir DefaultAzureCredential oluşturur.

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"
)

Önemli çıkarımlar:

  • DefaultAzureCredential, Microsoft Entra ID kullanarak anahtarsız kimlik doğrulaması sağlar. az login'dan Azure CLI kimlik bilgileri dahil olmak üzere birden çok kimlik bilgisi türünü zincirler.
  • Ortam değişkenleri .env kullanılarak python-dotenv dosyasından yüklenir.

Dizini anlamsal yapılandırmayla güncelleştirme

Hücre, Add a semantic configuration to the index var olan hotels-sample dizine semantik bir yapılandırma ekler. Bu işlem hiçbir arama belgesini silmez ve yapılandırma eklendikten sonra dizininiz çalışır durumda kalır.

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)

Önemli çıkarımlar:

  • Anlamsal yapılandırma, semantik derecelendirme için kullanılan alanları belirtir. title_field belge başlığını ayarlar, content_fields ana içeriği ayarlar ve keywords_fields anahtar sözcük veya etiket alanlarını ayarlar.
  • Yapılandırmayı ilgili SemanticConfiguration modeliyle SemanticPrioritizedFields oluşturursunuz ve ardından bunu var olan dizine eklersiniz.
  • create_or_update_index dizini yeniden oluşturmadan veya belgeleri silmeden güncelleştirilmiş şemayı arama hizmetine yönlendirir.

Dizini sorgulama

Sorgu hücreleri sırayla dört sorgu çalıştırır: temel anahtar sözcük araması ve ardından işlevselliği artan üç anlamsal sıralama varyasyonu.

Terim sorgusu (temel)

Hücre, Run a term query BM25 puanlama kullanarak bir anahtar kelime araması gerçekleştirir. Bu temel sorgu semantik derecelendirme kullanmaz ve bir karşılaştırma noktası görevi görür.

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
)

Önemli çıkarımlar:

  • query_type='simple' BM25 puanlama kullanarak bir anahtar sözcük araması belirtir.
  • @search.score sonuçlarında BM25 alaka düzeyi puanı belirtilmiştir.

Anlamsal sorgu (açıklamalı alt yazı yok, yanıt yok)

Run a semantic query Hücresi, semantik derecelendirmeyi başlatmak için en az gerekliliği gösterir.

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'
)

Önemli çıkarımlar:

  • query_type='semantic' sorguda anlamsal derecelendirmeyi etkinleştirir.
  • semantic_configuration_name kullanılacak semantik yapılandırmayı belirtir.
  • in @search.reranker_score sonuçları anlamsal ilgiyi gösterir (daha yüksek daha iyidir).

Açıklamalı alt yazılar içeren anlamsal sorgu

Hücre, Return captions her sonuçtan en uygun bölümleri ayıklamak için resim yazıları ekler ve önemli terimlere ve tümceciklere isabet vurgulama uygulanır.

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")

Önemli çıkarımlar:

  • query_caption='extractive' içerik alanlarından çıkarsamalı altyazıları etkinleştirir.
  • Açıklamalı alt yazılar en uygun bölümleri ortaya çıkararak önemli terimlerin çevresine etiketler ekler <em> .

Yanıtlarla anlamsal sorgu

Hücre Return semantic answers semantik yanıtlar ekler. Bu sorguda arama metni olarak bir soru kullanılır çünkü sorgu soru olarak ifade edildiğinde anlamsal yanıtlar en iyi sonucu verir. Yanıt, bir sohbet tamamlama modelinden oluşturulmuş bir yanıt değil, dizininizden ayıklanan ayrıntılı bir metindir.

Yanıtın döndürülebilmesi için sorgunun ve dizine alınan içeriğin yakından hizalanması gerekir. Hiçbir aday güvenilirlik eşiğini karşılamıyorsa yanıt bir yanıt içermez. Bu örnekte, söz dizimini görebilmeniz için sonuç ürettiği bilinen bir soru kullanılır. Yanıtlar senaryonuz için yararlı değilse, kodunuzdan query_answer öğesini çıkarın. Oluşturulan yanıtlar için RAG desenini veya etkin alma yöntemini göz önünde bulundurun.

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")

Önemli çıkarımlar:

  • query_answer="extractive" soru benzeri sorgular için ayıklayıcı yanıtlar sağlar.
  • Yanıtlar, dizininizden ayıklanan ayrıntılı içeriklerdir, oluşturulan metin değildir.
  • results.get_answers() yanıt nesnelerini arama sonuçlarından ayrı olarak alır.

Bu hızlı başlangıçta, JavaScript için Azure Yapay Zeka Arama istemci kitaplığını (TypeScript ile uyumlu) kullanarak mevcut bir arama dizinine anlamsal sıralama ekleyecek ve dizini sorgulayacaksınız.

Anlamsal derecelendirme, arama sonuçlarını yeniden puanlama amacıyla makine okuma kavramasını kullanan sorgu tarafı işlevselliğidir ve en ilgili eşleşmeleri listenin en üstüne yükseltmeyi sağlar. Yeniden derleme gereksinimi olmadan var olan bir dizine anlamsal yapılandırma ekleyebilirsiniz. Anlamsal derecelendirme en çok bilgilendirici veya açıklayıcı metinler için etkilidir.

Ipucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Okuyucusu

Not

Diğer dizin oluşturma ve yükleme hızlı başlatmalarından farklı olarak, bu hızlı başlatmamızda halihazırda veri içeren mevcut bir dizin olduğu kabul edilir, bu nedenle Arama Dizin Verisi Katkıcısı rolüne ihtiyacınız yoktur.

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Dizinle başlayın

Bu hızlı başlangıç, var olan bir dizini anlamsal yapılandırma içerecek şekilde değiştirir. Bir Azure portalı sihirbazını kullanarak dakikalar içinde oluşturabileceğiniz hotels-sample dizinini öneririz.

Farklı bir dizin kullanmak için dizin adını, anlamsal yapılandırmadaki alan adlarını ve örnek kodun tamamında sorgu select deyimlerindeki alan adlarını değiştirin. Dizininiz, searchable ve retrievable özniteliklendirilen açıklayıcı metin alanları içermelidir.

Anlam sıralamasından önce hotels-sample dizinini gözden geçirmek ve sorgulamak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Arama yönetimi>Dizinleri'ni seçin.

  3. Hotels-sample seçeneğini belirleyin.

  4. Mevcut yapılandırmaları görüntülemek için Anlamsal yapılandırmalar'ı seçin. Sihirbaz oluşturma akışı sırasında anlamsal derecelendirmeyi etkinleştirdiyseniz varsayılan bir yapılandırma olmalıdır.

    Azure portalındaki varsayılan anlamsal yapılandırmanın ekran görüntüsü.

  5. Arama gezgini'ne ve ardındanJSON görünümünü> tıklayın.

  6. Aşağıdaki JSON dosyasını sorgu düzenleyicisine yapıştırın.

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

  7. Sorguyu çalıştırmak için Ara'yı seçin.

    Yanıt aşağıdaki örneğe benzer olmalıdır. Bu, BM25 tarafından derecelendirilen bir tam metin sorgusudur, bu nedenle sonuçlar sorgunun genel anlamı yerine tek tek sorgu terimleriyle ve dilsel değişkenlerle eşleşmektedir. Örneğin, walking ile walk eşleşir ve live ile music bağımsız olarak, tümcecik olarak değil, eşleşir.

    "@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
]

    Ipucu

    Bu sorgu, semantik derecelendirme uygulanmadan önce yanıtın nasıl göründüğünü gösterir. Anlamsal yapılandırmayı yaptıktan sonra, sorguyu semantik derecelendirme ile farklı şekilde nasıl derecelendiğini görmek için "queryType": "semantic" ve "semanticConfiguration": "semantic-config" ekleyin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

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

  2. Hızlı başlangıç klasörüne gidin.

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

  3. sample.env içinde, AZURE_SEARCH_ENDPOINT yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

  4. olarak sample.envyeniden adlandırın.env.

    mv sample.env .env

  5. Bağımlılıkları yükleyin.

    npm install

    Yükleme tamamlandığında proje dizininde bir node_modules klasör görmeniz gerekir.

  6. TypeScript dosyalarını JavaScript'e derleyin.

    npm run build

  7. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştırma

  1. Mevcut dizin ayarlarını alın.

    node -r dotenv/config dist/getIndexSettings.js

  2. Dizini anlamsal bir yapılandırmayla güncelleştirin.

    node -r dotenv/config dist/updateIndexSettings.js

  3. Anlamsal bir sorgu çalıştırın.

    node -r dotenv/config dist/semanticQuery.js

  4. Açıklamalı alt yazılarla anlamsal bir sorgu çalıştırın.

    node -r dotenv/config dist/semanticQueryReturnCaptions.js

  5. Yanıtlar içeren bir anlamsal sorgu çalıştırın.

    node -r dotenv/config dist/semanticAnswer.js

    Not

    Bu komutlar klasörden derlenmiş .js dosyaları dist çalıştırır. Node.js yürütmeden önce TypeScript kodunun JavaScript'e çevrilmiş olması gerekir. Bu nedenle daha önce çalıştırmıştınız npm run build.

Çıkış

Betik getIndexSettings.js , dizin adını, alan sayısını, tür ve aranabilir durumu olan alan ayrıntılarını ve var olan tüm anlamsal yapılandırmaları döndürür.

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

Betik updateIndexSettings.js , eklediğiniz yapılandırma da dahil olmak üzere tüm anlamsal yapılandırmaları döndürür.

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.

Betik semanticQuery.js reranker puanına göre sıralanmış sonuçları döndürür.

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

Betik, semanticQueryReturnCaptions.js isabet vurgulamalı ayıklayıcı açıklamalı alt yazılar döndürür. Açıklamalı alt yazılar, sonuçtaki en ilgili bölümlerdir.

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

Betik, semanticAnswer.js sonuçtan alınan ve soruya en uygun olan semantik yanıtı (birebir içerik) döndürür.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Yapılandırma ve kimlik doğrulaması
  2. Dizini anlamsal yapılandırmayla güncelleştirme
  3. Dizini sorgulama

Yapılandırma ve kimlik doğrulaması

Dosya ortam config.ts değişkenlerini yükler, kimlik doğrulaması için bir DefaultAzureCredential oluşturur ve tür güvenliği için bir HotelDocument arabirim tanımlar.

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[];
}

Önemli çıkarımlar:

  • DefaultAzureCredential, Microsoft Entra ID kullanarak anahtarsız kimlik doğrulaması sağlar. az login'dan Azure CLI kimlik bilgileri dahil olmak üzere birden çok kimlik bilgisi türünü zincirler.
  • HotelDocument arabirimi, arama sonuçları için derleme zamanı tür denetimi sağlayarak belge alanlarına tür açısından güvenli erişim sağlar.
  • Ortam değişkenleri .env kullanılarak dotenv dosyasından yüklenir.

Dizini anlamsal yapılandırmayla güncelleştirme

Dosya, updateIndexSettings.ts var olan hotels-sample dizine anlamsal bir yapılandırma ekler. Bu işlem hiçbir arama belgesini silmez ve yapılandırma eklendikten sonra dizininiz çalışır durumda kalır. TypeScript türü ek açıklamaları, yapılandırmanın beklenen şemayla eşleştiğinden emin olur.

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);

Önemli çıkarımlar:

  • Türleri SemanticPrioritizedFields, SemanticConfiguration ve SemanticField olan TypeScript türleri, yapılandırma yapısının derleme zamanı doğrulamasını sağlar.
  • titleField belge başlığını ayarlar, contentFields ana içeriği ayarlar ve keywordsFields anahtar sözcük veya etiket alanlarını ayarlar.
  • createOrUpdateIndex dizini yeniden oluşturmadan veya belgeleri silmeden güncelleştirilmiş şemayı arama hizmetine yönlendirir.

Dizini sorgulama

Sorgu betikleri sırayla üç sorgu çalıştırır ve temel bir anlamsal aramadan açıklamalı alt yazılar ve yanıtlarla anlam sıralamasına ilerler.

Anlamsal sorgu (açıklamalı alt yazı yok, yanıt yok)

semanticQuery.ts betiği, tür açısından güvenli sonuçlarla semantik sıralama yapabilmek için gerekli en düşük koşulları gösterir.

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"
        ]
    }
);

Önemli çıkarımlar:

  • SearchClient<HotelDocument>, select ve result.document ile alan adlarına otomatik tamamlama sağlayarak sonuçlardaki belge alanlarına tür açısından güvenli erişim sunar.
  • queryType: "semantic" sorguda anlamsal derecelendirmeyi etkinleştirir.
  • semanticSearchOptions.configurationName kullanılacak semantik yapılandırmayı belirtir.

Açıklamalı alt yazılar içeren anlamsal sorgu

Betik, semanticQueryReturnCaptions.ts her sonuçtan en uygun bölümleri ayıklar ve bunlardan oluşturulan altyazıları ekler. Önemli terimler ve tümcecikler vurgulanır.

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}`
            );
        }
    }
}

Önemli çıkarımlar:

  • captions.captionType: "extractive" içerik alanlarından çıkarsamalı altyazıları etkinleştirir.
  • Açıklamalı alt yazılar en uygun bölümleri ortaya çıkararak önemli terimlerin çevresine etiketler ekler <em> .

Yanıtlarla anlamsal sorgu

Betik semanticAnswer.ts anlamsal yanıtlar ekler. Sorgu bir soru olarak ifade edildiğinde anlamsal yanıtlar en iyi şekilde çalıştığından, arama metni olarak bir soru kullanır. Yanıt, bir sohbet tamamlama modelinden oluşturulmuş bir yanıt değil, dizininizden ayıklanan ayrıntılı bir metindir.

Yanıtın döndürülebilmesi için sorgunun ve dizine alınan içeriğin yakından hizalanması gerekir. Hiçbir aday güvenilirlik eşiğini karşılamıyorsa yanıt bir yanıt içermez. Bu örnekte, söz dizimini görebilmeniz için sonuç ürettiği bilinen bir soru kullanılır. Yanıtlar senaryonuz için yararlı değilse, kodunuzdan answers öğesini çıkarın. Oluşturulan yanıtlar için RAG desenini veya etkin alma yöntemini göz önünde bulundurun.

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}`
    );
}

Önemli çıkarımlar:

  • answers.answerType: "extractive" soru benzeri sorgular için ayıklayıcı yanıtlar sağlar.
  • Yanıtlar, dizininizden ayıklanan ayrıntılı içeriklerdir, oluşturulan metin değildir.
  • results.answers yanıt nesnelerini arama sonuçlarından ayrı olarak alır.

Bu hızlı başlangıçta Azure Yapay Zeka Arama REST API'lerini kullanarak var olan bir arama dizinine semantic ranking ekleyip dizini sorgulaacaksınız.

Anlamsal derecelendirme, arama sonuçlarını yeniden puanlama amacıyla makine okuma kavramasını kullanan sorgu tarafı işlevselliğidir ve en ilgili eşleşmeleri listenin en üstüne yükseltmeyi sağlar. Yeniden derleme gereksinimi olmadan var olan bir dizine anlamsal yapılandırma ekleyebilirsiniz. Anlamsal derecelendirme en çok bilgilendirici veya açıklayıcı metinler için etkilidir.

Ipucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Okuyucusu

Not

Diğer dizin oluşturma ve yükleme hızlı başlatmalarından farklı olarak, bu hızlı başlatmamızda halihazırda veri içeren mevcut bir dizin olduğu kabul edilir, bu nedenle Arama Dizin Verisi Katkıcısı rolüne ihtiyacınız yoktur.

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Dizinle başlayın

Bu hızlı başlangıç, var olan bir dizini anlamsal yapılandırma içerecek şekilde değiştirir. Bir Azure portalı sihirbazını kullanarak dakikalar içinde oluşturabileceğiniz hotels-sample dizinini öneririz.

Farklı bir dizin kullanmak için dizin adını, anlamsal yapılandırmadaki alan adlarını ve örnek kodun tamamında sorgu select deyimlerindeki alan adlarını değiştirin. Dizininiz, searchable ve retrievable özniteliklendirilen açıklayıcı metin alanları içermelidir.

Anlam sıralamasından önce hotels-sample dizinini gözden geçirmek ve sorgulamak için:

  1. Azure portalında arama hizmetinize gidin.

  2. Sol bölmeden Arama yönetimi>Dizinleri'ni seçin.

  3. Hotels-sample seçeneğini belirleyin.

  4. Mevcut yapılandırmaları görüntülemek için Anlamsal yapılandırmalar'ı seçin. Sihirbaz oluşturma akışı sırasında anlamsal derecelendirmeyi etkinleştirdiyseniz varsayılan bir yapılandırma olmalıdır.

    Azure portalındaki varsayılan anlamsal yapılandırmanın ekran görüntüsü.

  5. Arama gezgini'ne ve ardındanJSON görünümünü> tıklayın.

  6. Aşağıdaki JSON dosyasını sorgu düzenleyicisine yapıştırın.

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

  7. Sorguyu çalıştırmak için Ara'yı seçin.

    Yanıt aşağıdaki örneğe benzer olmalıdır. Bu, BM25 tarafından derecelendirilen bir tam metin sorgusudur, bu nedenle sonuçlar sorgunun genel anlamı yerine tek tek sorgu terimleriyle ve dilsel değişkenlerle eşleşmektedir. Örneğin, walking ile walk eşleşir ve live ile music bağımsız olarak, tümcecik olarak değil, eşleşir.

    "@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
]

    Ipucu

    Bu sorgu, semantik derecelendirme uygulanmadan önce yanıtın nasıl göründüğünü gösterir. Anlamsal yapılandırmayı yaptıktan sonra, sorguyu semantik derecelendirme ile farklı şekilde nasıl derecelendiğini görmek için "queryType": "semantic" ve "semanticConfiguration": "semantic-config" ekleyin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

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

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

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

  3. semantic-index-update.rest içinde, @searchUrl yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

  4. için semantic-query.restönceki adımı yineleyin.

  5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

    az login

  6. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için bir erişim belirteci oluşturun.

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

  7. Her iki dosyada da .rest için @personalAccessToken yer tutucu değerini önceki adımdaki belirteçle değiştirin.

Kodu çalıştırma

  1. Aç semantic-index-update.rest.

  2. Bağlantınızı doğrulamak için ilk GET isteğinde İstek Gönder'i seçin.

    Bir yanıt bitişik bir bölmede görünmelidir. Mevcut dizinleriniz varsa, adlarına göre listelenirler. HTTP kodu ise 200 OKdevam etmeye hazırsınız demektir.

  3. Dizine ### Update the hotels-sample index to include a semantic configuration anlamsal yapılandırma ekleme isteğini gönderin.

    Hata 400 Bad Request alırsanız dizin şemanız örnekten farklıdır. ### Get the schema of the index İsteği gönderin, yanıt JSON'unu kopyalayın, kaynak koddaki bölümü JSON'a ekleyin semantic ve PUT isteği gövdesini birleştirilmiş şemanızla değiştirin.

  4. semantic-query.rest'e geçiş yapın ve istekleri sırayla gönderin: temel karşılaştırma için basit bir sorgu, ardından sıralama, altyazılar ve yanıtlar içeren anlamsal sorgular.

Çıkış

İstek, Send a search query to the hotels-sample index BM25 ilgisine göre derecelendirilen ve alanı @search.score olan sonuçları döndürür.

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

İstek ile Send a search query to the hotels-sample index with semantic ranking, @search.rerankerScore eklenir. Sıranın basit sorgudan değiştiğine dikkat edin.

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

İstek, ayıklanan metin ve vurgularla birlikte Return captions in the query unsurunu @search.captions ekler.

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

Sorgu bir soru olarak ifade edildiğinde, Return semantic answers in the query isteği @search.answers içinde ayıklayıcı bir yanıt döndürür.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Yapılandırma ve kimlik doğrulaması
  2. Dizini anlamsal yapılandırmayla güncelleştirme
  3. Dizini sorgulama

Yapılandırma ve kimlik doğrulaması

Her iki dosya da .rest tüm isteklerde yeniden kullanmak üzere en üstte değişkenleri tanımlar.

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

Önemli çıkarımlar:

  • @searchUrl arama hizmetinizin uç noktasıdır.
  • @personalAccessToken, Azure CLI'den elde edilen bir Microsoft Entra ID belirtecidir. Bu, API anahtarlarını anahtarsız kimlik doğrulamasıyla değiştirir.
  • Authorization: Bearer {{personalAccessToken}} kimlik doğrulaması için her istek üst bilgisinde bulunur.

Dizini anlamsal yapılandırmayla güncelleştirme

### Update the hotels-sample index to include a semantic configuration içindeki semantic-index-update.rest isteği, yeni bir semantic bölümüyle birlikte tam dizin şemasını gönderir. REST API herhangi bir güncelleştirme işlemi için tam şema gerektirir, bu nedenle yalnızca anlamsal yapılandırmayı gönderemezsiniz.

Temel ekleme şu bölümdür semantic :

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

Önemli çıkarımlar:

  • titleField semantik değerlendirme için belge başlığını içeren alanı tanımlar.
  • prioritizedContentFields ana içerik alanlarını tanımlar. Anlam dereceleyici, ilgiyi puanlarken bunları ilk olarak değerlendirir.
  • prioritizedKeywordsFields ek bağlam için anahtar sözcük veya etiket alanlarını tanımlar.
  • rankingOrder: BoostedRerankerScore BM25 puanını anlamsal reranker puanıyla birleştirir.
  • REST API, PUT işlemleri için tam şema gerektirir. semantic Yalnızca bölüm yenidir; diğer tüm alanlar değiştirilmez.

Dizini sorgulama

Sorgular, basit bir anahtar kelime aramasından altyazılar ve yanıtlar içeren anlamsal sıralamaya doğru ilerler semantic-query.rest. Tüm sorgular Belgeler - Arama Gönderisi'ne (REST API) yönelik POST istekleridir.

Basit sorgu

İstek ### Send a search query to the hotels-sample index , anlamsal derecelendirme kullanmayan basit bir anahtar sözcük aramasıdır. Sonuçları semantik yeniden sıralama ile ve olmadan karşılaştırmak için bir referans noktası olarak hizmet eder.

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

Önemli çıkarımlar:

  • queryType: "simple" varsayılan BM25 derecelendirme algoritmasını kullanır.
  • Sonuçlar yalnızca anahtar sözcük ilgi düzeyine (@search.score) göre derecelenir.

Anlamsal sorgu (açıklamalı alt yazı yok, yanıt yok)

İstek ### Send a search query to the hotels-sample index with semantic ranking semantik derecelendirme ekler. Aşağıdaki JSON, semantik derecelendirmeyi çağırmak için en düşük gereksinimi gösterir.

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

Önemli çıkarımlar:

  • queryType: "semantic" sorguda anlamsal derecelendirmeyi etkinleştirir.
  • semanticConfiguration kullanılacak semantik yapılandırmayı belirtir.

Açıklamalı alt yazılar içeren anlamsal sorgu

İstek, ### Return captions in the query her sonuçtan en ilgili bölümleri ayıklamak için başlıklar ekler ve önemli terimlere ve tümceciklere vurgulama uygulanır.

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

Önemli çıkarımlar:

  • captions: "extractive|highlight-true", önemli terimler etrafında etiketlerle çıkarımsal altyazıları etkinleştirir.
  • Her sonuç için @search.captions dizisinde altyazılar görüntülenir.

Yanıtlarla anlamsal sorgu

İstek ### Return semantic answers in the query semantik yanıtlar ekler. Sorgu bir soru olarak ifade edildiğinde anlamsal yanıtlar en iyi şekilde çalıştığından, arama metni olarak bir soru kullanır. Yanıt, bir sohbet tamamlama modelinden oluşturulmuş bir yanıt değil, dizininizden ayıklanan ayrıntılı bir metindir.

Yanıtın döndürülebilmesi için sorgunun ve dizine alınan içeriğin yakından hizalanması gerekir. Hiçbir aday güvenilirlik eşiğini karşılamıyorsa yanıt bir yanıt içermez. Bu örnekte, söz dizimini görebilmeniz için sonuç ürettiği bilinen bir soru kullanılır. Yanıtlar sizin senaryonuz için yararlı değilse, isteğinizden answers parametresini atlayın. Oluşturulan yanıtlar için RAG desenini veya etkin alma yöntemini göz önünde bulundurun.

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

Önemli çıkarımlar:

  • answers: "extractive" soru benzeri sorgular için ayıklayıcı yanıtlar sağlar.
  • Yanıtlar, tek tek sonuçlardan ayrı olarak en üst düzey @search.answers dizide görünür.
  • Yanıtlar, dizininizden ayıklanan ayrıntılı içeriklerdir, oluşturulan metin değildir.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

İlgili içerik

  • Son güncelleştirme: