Rövid útmutató: Szemantikai rangsorolás

Ebben a gyorsútmutatóban az Azure AI Keresés .NET ügyfélkódtára-t használja, hogy hozzáadjon szemantikus rangsorolást egy meglévő keresési indexhez, és lekérdezze az indexet.

A szemantikai rangsor egy lekérdezés oldalán található funkció, amely gépi olvasási megértést használ a keresési eredmények újraértékeléséhez, elősegítve a szemantikai szempontból releváns találatokat a lista tetejére. Szemantikai konfigurációt adhat hozzá egy meglévő indexhez újraépítési követelmény nélkül. A szemantikai rangsorolás az információs vagy leíró szövegek esetében a leghatékonyabb.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás.

• Index leíró szövegmezőkkel, amelyhez a searchable és a retrievable attribútumok tartoznak. Ez a rövid útmutató a szállodai mintaindexet feltételezi.

• .NET 9 vagy újabb.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

Első lépés egy index

Ez a rövid útmutató egy meglévő indexet módosít, hogy szemantikai konfigurációt tartalmazzon. Javasoljuk a szállodai mintaindexet, amelyet percek alatt létrehozhat egy Azure portál varázsló használatával.

Másik index használatához cserélje le az index nevét, a szemantikai konfiguráció mezőneveit és a lekérdezési select utasítások mezőneveit a mintakódban. Az indexnek tartalmaznia kell olyan leíró szövegmezőket, amelyek attribútumként vannak megadva: searchable és retrievable.

A szállodák mintaindexének áttekintése és lekérdezése szemantikai rangsorolás előtt:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza a Kereséskezelési>indexek lehetőséget.

3. Válassza ki hotels-sample.

4. A meglévő konfigurációk megtekintéséhez válassza a szemantikai konfigurációkat . Ha engedélyezte a szemantikai rangsorolást a varázslólétrehozási folyamat során, rendelkeznie kell egy alapértelmezett konfigurációval.

   Alapértelmezett szemantikai konfiguráció képernyőképe az Azure portálon.

5. Válassza a Kereséskezelő, majd a JSON-nézet megtekintése> lehetőséget.

6. Illessze be a következő JSON-t a lekérdezésszerkesztőbe.

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

7. A lekérdezés futtatásához válassza a Keresés lehetőséget .

   A válasznak az alábbi példához hasonlónak kell lennie. Ez egy teljes szöveges lekérdezés, amelyet a BM25 rangsorol, így az eredmények a lekérdezés általános jelentése helyett az egyes lekérdezési kifejezéseken és nyelvi változatokon egyeznek. Például a walking egyezik a walk-el, és a live és a music egymástól függetlenül egyeznek meg, nem pedig kifejezésként.

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

   Tipp

   Ez a lekérdezés bemutatja, hogyan néz ki a válasz a szemantikai rangsor alkalmazása előtt. Miután konfigurált egy szemantikai konfigurációt, adja hozzá "queryType": "semantic" és "semanticConfiguration": "semantic-config" elemeket, és tekintse meg, hogyan rangsorolja a szemantikai rangsorolás ugyanazt a lekérdezést.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

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

3. Ebben BuildIndex/Program.csa fájlban cserélje le a helyőrző értékét endpoint a Get végpontban beszerzett URL-címre.

4. Ismételje meg az előző lépést a következőhöz QueryIndex/Program.cs: .

5. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Futtassa az első projektet az index szemantikai beállításokkal történő frissítéséhez.

   dotnet run --project BuildIndex
   

2. Futtassa a második projektet az index lekérdezéséhez. Nyomja le az Enter billentyűt a lekérdezések között az egyszerű lekérdezéstől a szemantikai lekérdezésig a feliratok és válaszok megjelenítéséhez.

   dotnet run --project QueryIndex
   

Kimenet

Az első projekt szemantikai konfigurációval frissíti a szállodai mintaindexet. A kimenet tartalmazza a szemantikai konfiguráció megerősítését.

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

A második projekt négy lekérdezést futtat. A kimenet tartalmazza a találatokat relevanciapontokkal, feliratokkal és válaszokkal.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Konfiguráció és hitelesítés
2. Az index frissítése szemantikai konfigurációval
3. Az index lekérdezése

Konfiguráció és hitelesítés

Mindkét projekt ugyanazzal a konfigurációs mintával rendelkezik. A Program.cs fájlok határozzák meg a keresési végpontot, és kulcs nélküli hitelesítésre használják DefaultAzureCredential .

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

Főbb tanulságok

• DefaultAzureCredential kulcs nélküli hitelesítést biztosít Microsoft Entra ID használatával. Több hitelesítő adattípust is összekapcsol, beleértve a az login > Azure CLI hitelesítő adatait is.
• SearchIndexClient kezeli az indexszintű műveleteket, például az indexséma frissítését.
• SearchClient dokumentumszintű műveleteket kezel, például az index lekérdezését.

Az index frissítése szemantikai konfigurációval

A következő kód szemantikai BuildIndex/Program.cs konfigurációt ad hozzá a meglévő indexhez. Ez a művelet nem töröl keresési dokumentumokat, és az index a konfiguráció hozzáadása után is működőképes marad.

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

Főbb tanulságok

• A szemantikai konfiguráció a szemantikai rangsoroláshoz használt mezőket határozza meg.
• A szemantikai konfigurációk újraépítés nélkül hozzáadhatók a meglévő indexekhez.
• TitleField beállítja a dokumentum címét jelképező mezőt.
• ContentFields beállítja a fő tartalmat tartalmazó mezőket.
• KeywordsFields kulcsszavakat vagy címkéket tartalmazó mezőket állít be.

Az index lekérdezése

A QueryIndex projekt négy lekérdezést futtat egymás után, az egyszerű kulcsszókereséstől a szemantikai rangsorolásig feliratokkal és válaszokkal.

Egyszerű lekérdezés

Az első lekérdezés egy egyszerű kulcsszókeresés, amely nem használ szemantikai rangsorolást. Ez a lekérdezés viszonyítási alapként szolgál az eredmények szemantikai újrarendezéssel és anélkül történő összehasonlításához.

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

Főbb tanulságok

• SearchQueryType.Simple az alapértelmezett BM25 rangsorolási algoritmust használja.
• Az eredmények csak kulcsszó-relevancia (@search.score) alapján vannak rangsorolva.

Szemantikai lekérdezés (nincs felirat, nincs válasz)

A következő lekérdezés felirat és válasz nélkül ad hozzá szemantikai rangsorolást. Az alábbi kód a szemantikai rangsorolás minimális követelményét mutatja be.

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

Főbb tanulságok

• SearchQueryType.Semantic lehetővé teszi a szemantikai rangsorolást a lekérdezésen.
• SemanticConfigurationName a használni kívánt szemantikai konfigurációt határozza meg.
• @search.rerankerScore szemantikai relevanciát jelez (a magasabb jobb).
• A kifejezés lekérdezésének kezdeti eredményei szemantikai rangsorolási modellek használatával lesznek újból megszerkesztve. Ebben az adatkészletben és lekérdezésben a szemantikai rangsorolás hatása hangsúlyosabb az alacsonyabb rangsorolású eredményekben.

Szemantikai lekérdezés feliratokkal

Az alábbi kód feliratokat ad hozzá az egyes eredmények legfontosabb szakaszainak kinyeréséhez, a fontos kifejezésekre és kifejezésekre pedig találatkiemelést alkalmazva.

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

Főbb tanulságok

• QueryCaption lehetővé teszi a feliratok kinyerését a tartalommezőkből.
• A feliratok kiemelik a legrelevánsabb szakaszokat, és címkékkel látják el <em> a fontos kifejezéseket.

Szemantikai lekérdezés válaszokkal

A végső lekérdezés szemantikai válaszokat ad hozzá. Ez a lekérdezés egy másik keresési sztringet () használ,searchText2 mert a szemantikai válaszok akkor működnek a legjobban, ha a lekérdezést kérdésként fogalmazza meg. A válasz egy, az indexből kinyert szó szerinti részlet, nem pedig egy csevegési modell által összerakott válasz.

A lekérdezést és az indexelt tartalmat szorosan össze kell igazítani a válasz visszaadásához. Ha egyetlen jelölt sem éri el a megbízhatósági küszöbértéket, a válasz nem tartalmaz választ. Ez a példa egy olyan kérdést használ, amelyről ismert, hogy eredményt ad, így láthatja a szintaxist. Ha a válaszok nem hasznosak a forgatókönyvedhez, hagyd ki QueryAnswer a kódból. A megkomponált válaszok esetében fontolja meg a RAG-mintát vagy az agent alapú lekérést.

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

Főbb tanulságok

• QueryAnswer lehetővé teszi a kérdésekhez hasonló lekérdezések kinyerési válaszait.
• A válaszok az indexből kinyert szó szerinti tartalom, nem pedig a létrehozott szöveg.

Ebben a rövid útmutatóban a Java számára készült Azure AI Keresés klienskönyvtárát használja, hogy szemantikus rangsorolást adjon hozzá egy meglévő keresési indexhez, és lekérdezze az indexet.

A szemantikai rangsor egy lekérdezés oldalán található funkció, amely gépi olvasási megértést használ a keresési eredmények újraértékeléséhez, elősegítve a szemantikai szempontból releváns találatokat a lista tetejére. Szemantikai konfigurációt adhat hozzá egy meglévő indexhez újraépítési követelmény nélkül. A szemantikai rangsorolás az információs vagy leíró szövegek esetében a leghatékonyabb.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás.

• Index leíró szövegmezőkkel, amelyhez a searchable és a retrievable attribútumok tartoznak. Ez a rövid útmutató a szállodai mintaindexet feltételezi.

• Java 21 (LTS) és Maven.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

Első lépés egy index

Ez a rövid útmutató egy meglévő indexet módosít, hogy szemantikai konfigurációt tartalmazzon. Javasoljuk a szállodai mintaindexet, amelyet percek alatt létrehozhat egy Azure portál varázsló használatával.

Másik index használatához cserélje le az index nevét, a szemantikai konfiguráció mezőneveit és a lekérdezési select utasítások mezőneveit a mintakódban. Az indexnek tartalmaznia kell olyan leíró szövegmezőket, amelyek attribútumként vannak megadva: searchable és retrievable.

A szállodák mintaindexének áttekintése és lekérdezése szemantikai rangsorolás előtt:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza a Kereséskezelési>indexek lehetőséget.

3. Válassza ki hotels-sample.

4. A meglévő konfigurációk megtekintéséhez válassza a szemantikai konfigurációkat . Ha engedélyezte a szemantikai rangsorolást a varázslólétrehozási folyamat során, rendelkeznie kell egy alapértelmezett konfigurációval.

   Alapértelmezett szemantikai konfiguráció képernyőképe az Azure portálon.

5. Válassza a Kereséskezelő, majd a JSON-nézet megtekintése> lehetőséget.

6. Illessze be a következő JSON-t a lekérdezésszerkesztőbe.

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

7. A lekérdezés futtatásához válassza a Keresés lehetőséget .

   A válasznak az alábbi példához hasonlónak kell lennie. Ez egy teljes szöveges lekérdezés, amelyet a BM25 rangsorol, így az eredmények a lekérdezés általános jelentése helyett az egyes lekérdezési kifejezéseken és nyelvi változatokon egyeznek. Például a walking egyezik a walk-el, és a live és a music egymástól függetlenül egyeznek meg, nem pedig kifejezésként.

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

   Tipp

   Ez a lekérdezés bemutatja, hogyan néz ki a válasz a szemantikai rangsor alkalmazása előtt. Miután konfigurált egy szemantikai konfigurációt, adja hozzá "queryType": "semantic" és "semanticConfiguration": "semantic-config" elemeket, és tekintse meg, hogyan rangsorolja a szemantikai rangsorolás ugyanazt a lekérdezést.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

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

3. Ebben src/main/resources/application.propertiesa fájlban cserélje le a helyőrző értékét azure.search.endpoint a Get végpontban beszerzett URL-címre.

4. Állítsa össze a projektet a függőségek, köztük az azure-search-documents feloldása érdekében.

   mvn compile
   

   Ha a build befejeződött, ellenőrizze, hogy nem jelennek-e meg hibák a kimenetben.

5. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Kérje le a meglévő indexbeállításokat.

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

2. Frissítse az indexet szemantikai konfigurációval.

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

3. Szemantikai lekérdezés futtatása.

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

4. Szemantikai lekérdezés futtatása feliratokkal.

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

5. Szemantikai lekérdezés futtatása válaszokkal.

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

Kimenet

A kimenet GetIndexSettings.java az index neve, mezői és szemantikai konfigurációi. Új konfiguráció hozzáadása előtt az index csak az alapértelmezett konfigurációval rendelkezik.

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

A kimenet felsorolja UpdateIndexSettings.java az index összes szemantikai konfigurációját, beleértve a hozzáadott kódot, majd egy sikeres üzenetet.

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

A SemanticQuery.java kimenet minden egyező dokumentumot visszaad, amelyeket a szemantikai újrarangsorolási pontszám szerint rendez.

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

A kimenet SemanticQueryWithCaptions.java egy feliratelemet ad hozzá, amely a keresési mezők mellett a találatok kiemelésével is rendelkezik. Az eredmény szempontjából a feliratok a legrelevánsabb szakaszok. Ha az index nagyobb szöveget tartalmaz, a feliratok segítenek kinyerni a legérdekesebb mondatokat.

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

A kimenet SemanticAnswer.java tartalmaz egy szemantikai választ, amely az egyik találatból származik, amely a legjobban megfelel a kérdésnek, majd a keresési eredmények feliratokkal.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Konfiguráció és hitelesítés
2. Az index frissítése szemantikai konfigurációval
3. Az index lekérdezése

Konfiguráció és hitelesítés

Az SearchConfig.java osztály betölti a tulajdonságokat a application.properties forrásból, és létrehoz egy DefaultAzureCredential-t kulcs nélküli hitelesítéshez.

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

Főbb tanulságok

• DefaultAzureCredential kulcs nélküli hitelesítést biztosít Microsoft Entra ID használatával. Több hitelesítő adattípust is összekapcsol, beleértve a az login > Azure CLI hitelesítő adatait is.
• A tulajdonságok az application.properties osztályúton lévő fájlból töltődnek be.
• A statikus mezők (SEARCH_ENDPOINT, INDEX_NAME, , SEMANTIC_CONFIG_NAMECREDENTIAL) a projekt összes osztályában meg vannak osztva.

Az index frissítése szemantikai konfigurációval

Az UpdateIndexSettings.java osztály szemantikai konfigurációt ad hozzá a meglévő hotels-sample indexhez. Ez a művelet nem töröl keresési dokumentumokat, és az index a konfiguráció hozzáadása után is működőképes marad.

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

Főbb tanulságok

• SemanticPrioritizedFields Meghatározza, hogy a szemantikai rangsoroló mely mezőket értékeli ki. setTitleField beállítja a dokumentum címét, setContentFields beállítja a fő tartalmat, és setKeywordsFields beállítja a kulcsszó- vagy címkemezőket.
• SemanticConfiguration a rangsorban szereplő mezőkkel párosít egy nevet, amely meghatározza, hogy melyik szemantikai konfigurációt használja a lekérdezési időpontban.
• createOrUpdateIndex Leküldi a frissített sémát a keresési szolgáltatásba az index újraépítése vagy a dokumentumok törlése nélkül.

Az index lekérdezése

Az alábbi három osztály egymás után kérdezi le az indexet, és az alapszintű szemantikai kereséstől a szemantikai rangsorolásig halad, feliratokkal és válaszokkal.

Szemantikai lekérdezés (nincs felirat, nincs válasz)

Az első lekérdezés felirat és válasz nélkül ad hozzá szemantikai rangsorolást. Az SemanticQuery.java osztály a szemantikai rangsor meghívásának minimális követelményét mutatja.

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

Főbb tanulságok

• QueryType.SEMANTIC lehetővé teszi a szemantikai rangsorolást a lekérdezésen.
• setSemanticConfigurationName a használni kívánt szemantikai konfigurációt határozza meg.
• SearchPagedIterable iterálható objektumot biztosít a visszarendezett eredményekre. Mindegyik SearchResult tartalmaz egy getSemanticSearch() kiegészítőt a reranker pontszámhoz.

Szemantikai lekérdezés feliratokkal

Az SemanticQueryWithCaptions.java osztály feliratokat ad hozzá az egyes eredmények legrelevánsabb részeihez, és a fontos kifejezésekre pedig találatkiemelést alkalmaz.

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

Főbb tanulságok

• QueryCaption(QueryCaptionType.EXTRACTIVE) lehetővé teszi a feliratok kinyerését a tartalommezőkből.
• setHighlightEnabled(true) címkéket <em> ad hozzá a fontos kifejezésekhez a feliratokban.
• Mindegyik SearchResult tartalmazza getQueryCaptions() a szemantikai keresési kiegészítőt.

Szemantikai lekérdezés válaszokkal

Az SemanticAnswer.java osztály szemantikai válaszokat ad hozzá. Ez az osztály egy kérdést használ keresési szövegként, mert a szemantikai válaszok akkor működnek a legjobban, ha a lekérdezést kérdésként fogalmazták meg. A válasz egy, az indexből kinyert szó szerinti részlet, nem pedig egy csevegési modell által összerakott válasz.

A lekérdezést és az indexelt tartalmat szorosan össze kell igazítani a válasz visszaadásához. Ha egyetlen jelölt sem éri el a megbízhatósági küszöbértéket, a válasz nem tartalmaz választ. Ez a példa egy olyan kérdést használ, amelyről ismert, hogy eredményt ad, így láthatja a szintaxist. Ha a válaszok nem hasznosak a forgatókönyvedhez, hagyd ki setQueryAnswer a kódból. A megkomponált válaszok esetében fontolja meg a RAG-mintát vagy az agent alapú lekérést.

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

Főbb tanulságok

• QueryAnswer(QueryAnswerType.EXTRACTIVE) lehetővé teszi a kérdésekhez hasonló lekérdezések kinyerési válaszait.
• A válaszok az indexből kinyert szó szerinti tartalom, nem pedig a létrehozott szöveg.
• results.getSemanticResults().getQueryAnswers() a válaszobjektumokat a keresési eredményektől elkülönítve kéri le.

Ebben a rövid útmutatóban a JavaScripthez készült Azure AI Keresés ügyfélkódtárat használjasemantikus rangsorolás hozzáadásához egy meglévő keresési indexhez, és lekérdezi az indexet.

A szemantikai rangsor egy lekérdezés oldalán található funkció, amely gépi olvasási megértést használ a keresési eredmények újraértékeléséhez, elősegítve a szemantikai szempontból releváns találatokat a lista tetejére. Szemantikai konfigurációt adhat hozzá egy meglévő indexhez újraépítési követelmény nélkül. A szemantikai rangsorolás az információs vagy leíró szövegek esetében a leghatékonyabb.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás.

• Index leíró szövegmezőkkel, amelyhez a searchable és a retrievable attribútumok tartoznak. Ez a rövid útmutató a szállodai mintaindexet feltételezi.

• Node.js 20 LTS vagy újabb.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

Első lépés egy index

Ez a rövid útmutató egy meglévő indexet módosít, hogy szemantikai konfigurációt tartalmazzon. Javasoljuk a szállodai mintaindexet, amelyet percek alatt létrehozhat egy Azure portál varázsló használatával.

Másik index használatához cserélje le az index nevét, a szemantikai konfiguráció mezőneveit és a lekérdezési select utasítások mezőneveit a mintakódban. Az indexnek tartalmaznia kell olyan leíró szövegmezőket, amelyek attribútumként vannak megadva: searchable és retrievable.

A szállodák mintaindexének áttekintése és lekérdezése szemantikai rangsorolás előtt:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza a Kereséskezelési>indexek lehetőséget.

3. Válassza ki hotels-sample.

4. A meglévő konfigurációk megtekintéséhez válassza a szemantikai konfigurációkat . Ha engedélyezte a szemantikai rangsorolást a varázslólétrehozási folyamat során, rendelkeznie kell egy alapértelmezett konfigurációval.

   Alapértelmezett szemantikai konfiguráció képernyőképe az Azure portálon.

5. Válassza a Kereséskezelő, majd a JSON-nézet megtekintése> lehetőséget.

6. Illessze be a következő JSON-t a lekérdezésszerkesztőbe.

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

7. A lekérdezés futtatásához válassza a Keresés lehetőséget .

   A válasznak az alábbi példához hasonlónak kell lennie. Ez egy teljes szöveges lekérdezés, amelyet a BM25 rangsorol, így az eredmények a lekérdezés általános jelentése helyett az egyes lekérdezési kifejezéseken és nyelvi változatokon egyeznek. Például a walking egyezik a walk-el, és a live és a music egymástól függetlenül egyeznek meg, nem pedig kifejezésként.

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

   Tipp

   Ez a lekérdezés bemutatja, hogyan néz ki a válasz a szemantikai rangsor alkalmazása előtt. Miután konfigurált egy szemantikai konfigurációt, adja hozzá "queryType": "semantic" és "semanticConfiguration": "semantic-config" elemeket, és tekintse meg, hogyan rangsorolja a szemantikai rangsorolás ugyanazt a lekérdezést.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

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

3. Ebben sample.enva fájlban cserélje le a helyőrző értékét AZURE_SEARCH_ENDPOINT a Get végpontban beszerzett URL-címre.

4. Átnevezés sample.env : .env.

   mv sample.env .env
   

5. Telepítse a függőségeket.

   npm install
   

   Amikor a telepítés befejeződött, a projektkönyvtárban meg kell jelennie egy node_modules mappának.

6. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Kérje le a meglévő indexbeállításokat.

   node -r dotenv/config src/getIndexSettings.js
   

2. Frissítse az indexet szemantikai konfigurációval.

   node -r dotenv/config src/updateIndexSettings.js
   

3. Szemantikai lekérdezés futtatása.

   node -r dotenv/config src/semanticQuery.js
   

4. Szemantikai lekérdezés futtatása feliratokkal.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. Szemantikai lekérdezés futtatása válaszokkal.

   node -r dotenv/config src/semanticAnswer.js
   

Kimenet

A getIndexSettings.js szkript visszaadja az index nevét, a mezőit és a meglévő szemantikai konfigurációkat.

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

A updateIndexSettings.js szkript visszaadja az index összes szemantikai konfigurációját, beleértve a hozzáadott kódot, majd egy sikeres üzenetet.

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.

A semanticQuery.js szkript visszaadja az összes egyező dokumentumot, amelyeket a szemantikai újraértékelő pontszám szerint rendez.

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

A semanticQueryReturnCaptions.js szkript egy feliratelemet ad vissza, a keresési mezők mellett a találatok kiemelésével. Az eredmény szempontjából a feliratok a legrelevánsabb szakaszok. Ha az index nagyobb szöveget tartalmaz, a feliratok segítenek kinyerni a legérdekesebb mondatokat.

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

A semanticAnswer.js szkript egy szemantikai választ ad vissza az egyik olyan eredményből, amely a legjobban megfelel a kérdésnek, ezt követik a keresési eredmények leírásokkal.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Konfiguráció és hitelesítés
2. Az index frissítése szemantikai konfigurációval
3. Az index lekérdezése

Konfiguráció és hitelesítés

A config.js fájl betölti a környezeti változókat, és létrehoz egy DefaultAzureCredential hitelesítéshez szükségest.

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

Főbb tanulságok

• DefaultAzureCredential kulcs nélküli hitelesítést biztosít Microsoft Entra ID használatával. Több hitelesítő adattípust is összekapcsol, beleértve a az login > Azure CLI hitelesítő adatait is.
• A környezeti változók a .env fájlból töltődnek be a dotenv használatával.

Az index frissítése szemantikai konfigurációval

A updateIndexSettings.js fájl szemantikai konfigurációt ad hozzá a meglévő hotels-sample indexhez. Ez a művelet nem töröl keresési dokumentumokat, és az index a konfiguráció hozzáadása után is működőképes marad.

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

Főbb tanulságok

• A szemantikai konfiguráció a szemantikai rangsoroláshoz használt mezőket határozza meg. titleField meghatározza a dokumentum címét, contentFields meghatározza a fő tartalmat, és keywordsFields meghatározza a kulcsszó- vagy címkemezőket.
• Létre kell hoznia egy konfigurációs objektumot, és le kell küldenie a meglévő indextömbbe semanticSearch.configurations .
• createOrUpdateIndex Leküldi a frissített sémát a keresési szolgáltatásba az index újraépítése vagy a dokumentumok törlése nélkül.

Az index lekérdezése

A lekérdezési szkriptek három lekérdezést futtatnak egymás után, és az alapszintű szemantikai kereséstől a szemantikai rangsorolásig haladnak feliratokkal és válaszokkal.

Szemantikai lekérdezés (nincs felirat, nincs válasz)

Az alábbi kód a szemantikai rangsorolás minimális követelményét mutatja be.

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

Főbb tanulságok

• queryType: "semantic" lehetővé teszi a szemantikai rangsorolást a lekérdezésen.
• semanticSearchOptions.configurationName a használni kívánt szemantikai konfigurációt határozza meg.
• Az rerankerScore eredmények szemantikai relevanciát jeleznek (a magasabb jobb).

Szemantikai lekérdezés feliratokkal

Az alábbi kód feliratokat ad hozzá az egyes eredmények legfontosabb szakaszainak kinyeréséhez, a fontos kifejezésekre és kifejezésekre pedig találatkiemelést alkalmazva.

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

Főbb tanulságok

• captions.captionType: "extractive" lehetővé teszi a feliratok kinyerését a tartalommezőkből.
• A feliratok kiemelik a legrelevánsabb szakaszokat, és címkékkel látják el <em> a fontos kifejezéseket.

Szemantikai lekérdezés válaszokkal

A végső lekérdezés szemantikai válaszokat ad hozzá. Ez a lekérdezés egy kérdést használ keresési szövegként, mert a szemantikai válaszok akkor működnek a legjobban, ha a lekérdezést kérdésként fogalmazták meg. A válasz egy, az indexből kinyert szó szerinti részlet, nem pedig egy csevegési modell által összerakott válasz.

A lekérdezést és az indexelt tartalmat szorosan össze kell igazítani a válasz visszaadásához. Ha egyetlen jelölt sem éri el a megbízhatósági küszöbértéket, a válasz nem tartalmaz választ. Ez a példa egy olyan kérdést használ, amelyről ismert, hogy eredményt ad, így láthatja a szintaxist. Ha a válaszok nem hasznosak a forgatókönyvedhez, hagyd ki answers a kódból. A megkomponált válaszok esetében fontolja meg a RAG-mintát vagy az agent alapú lekérést.

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

Főbb tanulságok

• answers.answerType: "extractive" lehetővé teszi a kérdésekhez hasonló lekérdezések kinyerési válaszait.
• A válaszok az indexből kinyert szó szerinti tartalom, nem pedig a létrehozott szöveg.
• results.answers a válaszobjektumokat a keresési eredményektől elkülönítve kéri le.

A(z) ebben a gyors útmutatóban az Azure AI Keresés Python-ügyfélkönyvtár segítségével szemantikus rangsorolást adhat hozzá egy meglévő keresési indexhez, és lekérdezheti az indexet.

A szemantikai rangsor egy lekérdezés oldalán található funkció, amely gépi olvasási megértést használ a keresési eredmények újraértékeléséhez, elősegítve a szemantikai szempontból releváns találatokat a lista tetejére. Szemantikai konfigurációt adhat hozzá egy meglévő indexhez újraépítési követelmény nélkül. A szemantikai rangsorolás az információs vagy leíró szövegek esetében a leghatékonyabb.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás.

• Index leíró szövegmezőkkel, amelyhez a searchable és a retrievable attribútumok tartoznak. Ez a rövid útmutató a szállodai mintaindexet feltételezi.

• Python 3.10 vagy újabb.

• Visual Studio Code a Python kiterjesztéssel.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

Első lépés egy index

Ez a rövid útmutató egy meglévő indexet módosít, hogy szemantikai konfigurációt tartalmazzon. Javasoljuk a szállodai mintaindexet, amelyet percek alatt létrehozhat egy Azure portál varázsló használatával.

Másik index használatához cserélje le az index nevét, a szemantikai konfiguráció mezőneveit és a lekérdezési select utasítások mezőneveit a mintakódban. Az indexnek tartalmaznia kell olyan leíró szövegmezőket, amelyek attribútumként vannak megadva: searchable és retrievable.

A szállodák mintaindexének áttekintése és lekérdezése szemantikai rangsorolás előtt:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza a Kereséskezelési>indexek lehetőséget.

3. Válassza ki hotels-sample.

4. A meglévő konfigurációk megtekintéséhez válassza a szemantikai konfigurációkat . Ha engedélyezte a szemantikai rangsorolást a varázslólétrehozási folyamat során, rendelkeznie kell egy alapértelmezett konfigurációval.

   Alapértelmezett szemantikai konfiguráció képernyőképe az Azure portálon.

5. Válassza a Kereséskezelő, majd a JSON-nézet megtekintése> lehetőséget.

6. Illessze be a következő JSON-t a lekérdezésszerkesztőbe.

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

7. A lekérdezés futtatásához válassza a Keresés lehetőséget .

   A válasznak az alábbi példához hasonlónak kell lennie. Ez egy teljes szöveges lekérdezés, amelyet a BM25 rangsorol, így az eredmények a lekérdezés általános jelentése helyett az egyes lekérdezési kifejezéseken és nyelvi változatokon egyeznek. Például a walking egyezik a walk-el, és a live és a music egymástól függetlenül egyeznek meg, nem pedig kifejezésként.

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

   Tipp

   Ez a lekérdezés bemutatja, hogyan néz ki a válasz a szemantikai rangsor alkalmazása előtt. Miután konfigurált egy szemantikai konfigurációt, adja hozzá "queryType": "semantic" és "semanticConfiguration": "semantic-config" elemeket, és tekintse meg, hogyan rangsorolja a szemantikai rangsorolás ugyanazt a lekérdezést.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Nyissa meg a quickstart mappát a Visual Studio Code-ban.

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

3. Ebben sample.enva fájlban cserélje le a helyőrző értékét AZURE_SEARCH_ENDPOINT a Get végpontban beszerzett URL-címre.

4. Átnevezés sample.env : .env.

   mv sample.env .env
   

5. Nyisd meg semantic-ranking-quickstart.ipynb.

6. Nyomja le a Ctrl+Shift+P billentyűkombinációt, válassza a Jegyzetfüzet: Jegyzetfüzet kernel kiválasztása lehetőséget, és kövesse az utasításokat egy virtuális környezet létrehozásához. Válassza a requirements.txt a függőségekhez.

   Ha elkészült, meg kell jelennie egy .venv mappának a projektkönyvtárban.

7. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Futtassa a Install packages and set variables cellákat a szükséges csomagok telepítéséhez és a környezeti változók betöltéséhez.

2. Futtassa a fennmaradó cellákat egymás után a szemantikai konfiguráció hozzáadásához és az index lekérdezéséhez.

Kimenet

A Get the index definition cella kimenete az index neve, annak mezői, és a meglévő szemantikai konfigurációk.

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

A cella kimenete felsorolja az Add a semantic configuration to the index index összes szemantikai konfigurációját, beleértve a hozzáadott kódot, majd egy sikeres üzenetet.

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!

A Run a term query kimenete az összes egyező dokumentumot visszaadja, amelyeket a BM25 pontszám alapján rendeztek. Ez az alapkonfigurációs lekérdezés nem használ szemantikai rangsorolást.

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

A cella kimenete a Run a semantic query szemantikai rangsoroló pontszáma szerint rendezett összes egyező dokumentumot visszaadja.

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

A Return captions cella kimenete egy feliratkomponenst ad hozzá, amely kiemeli a találatokat, és a keresési mezők mellett helyezkedik el. Az eredmény szempontjából a feliratok a legrelevánsabb szakaszok. Ha az index nagyobb szöveget tartalmaz, a feliratok segítenek kinyerni a legérdekesebb mondatokat.

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

A Return semantic answers cella kimenete tartalmaz egy szöveges választ, amely a kérdésnek legmegfelelőbb találatok egyikéből származik, majd a keresési találatok feliratokkal következnek.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Konfiguráció és hitelesítés
2. Az index frissítése szemantikai konfigurációval
3. Az index lekérdezése

Konfiguráció és hitelesítés

A Install packages and set variables cella betölti a környezeti változókat, és létrehoz egy DefaultAzureCredential hitelesítést.

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

Főbb tanulságok

• DefaultAzureCredential kulcs nélküli hitelesítést biztosít Microsoft Entra ID használatával. Több hitelesítő adattípust is összekapcsol, beleértve a az login > Azure CLI hitelesítő adatait is.
• A környezeti változók a .env fájlból töltődnek be a python-dotenv használatával.

Az index frissítése szemantikai konfigurációval

A Add a semantic configuration to the index cella szemantikai konfigurációt ad hozzá a meglévő hotels-sample indexhez. Ez a művelet nem töröl keresési dokumentumokat, és az index a konfiguráció hozzáadása után is működőképes marad.

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)

Főbb tanulságok

• A szemantikai konfiguráció a szemantikai rangsoroláshoz használt mezőket határozza meg. title_field beállítja a dokumentum címét, content_fields beállítja a fő tartalmat, és keywords_fields beállítja a kulcsszó- vagy címkemezőket.
• Hozza létre a konfigurációt SemanticConfiguration és annak társított modelljét SemanticPrioritizedFields , majd fűzze hozzá a meglévő indexhez.
• create_or_update_index Leküldi a frissített sémát a keresési szolgáltatásba az index újraépítése vagy a dokumentumok törlése nélkül.

Az index lekérdezése

A lekérdezéscellák négy lekérdezést futtatnak egymás után: egy alapszintű kulcsszókeresést, majd három szemantikai rangsorolási változatot, amelyek egyre nagyobb funkcionalitással működnek.

Kifejezés lekérdezése (alapterv)

A Run a term query cella BM25-pontozással futtat egy kulcsszókeresést. Ez az alapkonfigurációs lekérdezés nem használ szemantikai rangsorolást, és összehasonlítási pontként szolgál.

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
)

Főbb tanulságok

• query_type='simple' kulcsszókeresést határoz meg a BM25 pontozás alkalmazásával.
• A @search.score az eredményeknél a BM25 relevancia-pontszámát jelzi.

Szemantikai lekérdezés (nincs felirat, nincs válasz)

A Run a semantic query cella a szemantikai rangsor meghívásának minimális követelményét jeleníti meg.

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

Főbb tanulságok

• query_type='semantic' lehetővé teszi a szemantikai rangsorolást a lekérdezésen.
• semantic_configuration_name a használni kívánt szemantikai konfigurációt határozza meg.
• Az @search.reranker_score eredmények szemantikai relevanciát jeleznek (a magasabb jobb).

Szemantikai lekérdezés feliratokkal

A Return captions cella feliratokat ad hozzá az egyes eredmények legrelevánsabb részeinek kiemelésére, a fontos szavak és kifejezések találatkiemelésével.

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

Főbb tanulságok

• query_caption='extractive' lehetővé teszi a feliratok kinyerését a tartalommezőkből.
• A feliratok kiemelik a legrelevánsabb szakaszokat, és címkékkel látják el <em> a fontos kifejezéseket.

Szemantikai lekérdezés válaszokkal

A Return semantic answers cella szemantikai válaszokat ad hozzá. Ez a lekérdezés egy kérdést használ keresési szövegként, mert a szemantikai válaszok akkor működnek a legjobban, ha a lekérdezést kérdésként fogalmazták meg. A válasz egy, az indexből kinyert szó szerinti részlet, nem pedig egy csevegési modell által összerakott válasz.

A lekérdezést és az indexelt tartalmat szorosan össze kell igazítani a válasz visszaadásához. Ha egyetlen jelölt sem éri el a megbízhatósági küszöbértéket, a válasz nem tartalmaz választ. Ez a példa egy olyan kérdést használ, amelyről ismert, hogy eredményt ad, így láthatja a szintaxist. Ha a válaszok nem hasznosak a forgatókönyvedhez, hagyd ki query_answer a kódból. A megkomponált válaszok esetében fontolja meg a RAG-mintát vagy az agent alapú lekérést.

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

Főbb tanulságok

• query_answer="extractive" lehetővé teszi a kérdésekhez hasonló lekérdezések kinyerési válaszait.
• A válaszok az indexből kinyert szó szerinti tartalom, nem pedig a létrehozott szöveg.
• results.get_answers() a válaszobjektumokat a keresési eredményektől elkülönítve kéri le.

Ebben a rövid útmutatóban a JavaScript-hez készült Azure AI Keresés ügyfélkódtárat (a TypeScripttel kompatibilis) használja szemantikus rangsorolás hozzáadása egy meglévő keresési indexhez, és annak lekérdezése céljából.

A szemantikai rangsor egy lekérdezés oldalán található funkció, amely gépi olvasási megértést használ a keresési eredmények újraértékeléséhez, elősegítve a szemantikai szempontból releváns találatokat a lista tetejére. Szemantikai konfigurációt adhat hozzá egy meglévő indexhez újraépítési követelmény nélkül. A szemantikai rangsorolás az információs vagy leíró szövegek esetében a leghatékonyabb.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás.

• Index leíró szövegmezőkkel, amelyhez a searchable és a retrievable attribútumok tartoznak. Ez a rövid útmutató a szállodai mintaindexet feltételezi.

• Node.js 20 LTS-t vagy újabb verziót a lefordított kód futtatásához.

• TypeScript a TypeScript JavaScriptre való fordításához.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

Első lépés egy index

Ez a rövid útmutató egy meglévő indexet módosít, hogy szemantikai konfigurációt tartalmazzon. Javasoljuk a szállodai mintaindexet, amelyet percek alatt létrehozhat egy Azure portál varázsló használatával.

Másik index használatához cserélje le az index nevét, a szemantikai konfiguráció mezőneveit és a lekérdezési select utasítások mezőneveit a mintakódban. Az indexnek tartalmaznia kell olyan leíró szövegmezőket, amelyek attribútumként vannak megadva: searchable és retrievable.

A szállodák mintaindexének áttekintése és lekérdezése szemantikai rangsorolás előtt:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza a Kereséskezelési>indexek lehetőséget.

3. Válassza ki hotels-sample.

4. A meglévő konfigurációk megtekintéséhez válassza a szemantikai konfigurációkat . Ha engedélyezte a szemantikai rangsorolást a varázslólétrehozási folyamat során, rendelkeznie kell egy alapértelmezett konfigurációval.

   Alapértelmezett szemantikai konfiguráció képernyőképe az Azure portálon.

5. Válassza a Kereséskezelő, majd a JSON-nézet megtekintése> lehetőséget.

6. Illessze be a következő JSON-t a lekérdezésszerkesztőbe.

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

7. A lekérdezés futtatásához válassza a Keresés lehetőséget .

   A válasznak az alábbi példához hasonlónak kell lennie. Ez egy teljes szöveges lekérdezés, amelyet a BM25 rangsorol, így az eredmények a lekérdezés általános jelentése helyett az egyes lekérdezési kifejezéseken és nyelvi változatokon egyeznek. Például a walking egyezik a walk-el, és a live és a music egymástól függetlenül egyeznek meg, nem pedig kifejezésként.

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

   Tipp

   Ez a lekérdezés bemutatja, hogyan néz ki a válasz a szemantikai rangsor alkalmazása előtt. Miután konfigurált egy szemantikai konfigurációt, adja hozzá "queryType": "semantic" és "semanticConfiguration": "semantic-config" elemeket, és tekintse meg, hogyan rangsorolja a szemantikai rangsorolás ugyanazt a lekérdezést.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

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

3. Ebben sample.enva fájlban cserélje le a helyőrző értékét AZURE_SEARCH_ENDPOINT a Get végpontban beszerzett URL-címre.

4. Átnevezés sample.env : .env.

   mv sample.env .env
   

5. Telepítse a függőségeket.

   npm install
   

   Amikor a telepítés befejeződött, a projektkönyvtárban meg kell jelennie egy node_modules mappának.

6. A TypeScript-fájlok fordítása JavaScript-fájlba.

   npm run build
   

7. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Kérje le a meglévő indexbeállításokat.

   node -r dotenv/config dist/getIndexSettings.js
   

2. Frissítse az indexet szemantikai konfigurációval.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. Szemantikai lekérdezés futtatása.

   node -r dotenv/config dist/semanticQuery.js
   

4. Szemantikai lekérdezés futtatása feliratokkal.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. Szemantikai lekérdezés futtatása válaszokkal.

   node -r dotenv/config dist/semanticAnswer.js
   

   Megjegyzés

   Ezek a parancsok futtatják a lefordított .js fájlokat a dist mappából. A TypeScript-kódot JavaScriptre kell lefordítani, mielőtt a Node.js végrehajthatja azt, ezért korábban futtatta a npm run build-t.

Kimenet

A getIndexSettings.js szkript visszaadja az index nevét, a mezők számát, a mezők típusát és kereshető állapotát, valamint a meglévő szemantikai konfigurációkat.

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

A updateIndexSettings.js szkript az összes szemantikai konfigurációt visszaadja, beleértve a hozzáadott konfigurációt is.

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.

A semanticQuery.js szkript a reranker-pontszám által rendezett eredményeket adja vissza.

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

A semanticQueryReturnCaptions.js szkript kinyert feliratokat ad vissza a találatok kiemelésével. Az eredmény szempontjából a feliratok a legrelevánsabb szakaszok.

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

A semanticAnswer.js szkript egy szemantikai választ (szó szerinti tartalmat) ad vissza az eredményből, amely a legjobban megfelel a kérdésnek.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Konfiguráció és hitelesítés
2. Az index frissítése szemantikai konfigurációval
3. Az index lekérdezése

Konfiguráció és hitelesítés

A config.ts fájl betölti a környezeti változókat, létrehoz egy DefaultAzureCredential hitelesítést, és meghatározza a HotelDocument típusbiztonság felületét.

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

Főbb tanulságok

• DefaultAzureCredential kulcs nélküli hitelesítést biztosít Microsoft Entra ID használatával. Több hitelesítő adattípust is összekapcsol, beleértve a az login > Azure CLI hitelesítő adatait is.
• A HotelDocument felület fordítási idejű típusellenőrzést biztosít a keresési eredményekhez, biztosítva a dokumentummezők típusbiztos elérését.
• A környezeti változók a .env fájlból töltődnek be a dotenv használatával.

Az index frissítése szemantikai konfigurációval

A updateIndexSettings.ts fájl szemantikai konfigurációt ad hozzá a meglévő hotels-sample indexhez. Ez a művelet nem töröl keresési dokumentumokat, és az index a konfiguráció hozzáadása után is működőképes marad. A TypeScript típusú széljegyzetek biztosítják, hogy a konfiguráció megegyezik a várt sémával.

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

Főbb tanulságok

• TypeScript-típusok, mint például a SemanticPrioritizedFields, SemanticConfiguration, és SemanticField, fordítási időbeli ellenőrzést biztosítanak a konfigurációs struktúra számára.
• titleField beállítja a dokumentum címét, contentFields beállítja a fő tartalmat, és keywordsFields beállítja a kulcsszó- vagy címkemezőket.
• createOrUpdateIndex Leküldi a frissített sémát a keresési szolgáltatásba az index újraépítése vagy a dokumentumok törlése nélkül.

Az index lekérdezése

A lekérdezési szkriptek három lekérdezést futtatnak egymás után, és az alapszintű szemantikai kereséstől a szemantikai rangsorolásig haladnak feliratokkal és válaszokkal.

Szemantikai lekérdezés (nincs felirat, nincs válasz)

A semanticQuery.ts szkript bemutatja a szemantikai rangsor típusbiztos eredményekkel való meghívásának minimális követelményét.

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

Főbb tanulságok

• SearchClient<HotelDocument> típusbiztos hozzáférést nyújt a dokumentummezőkhöz az eredményekben, és automatikus kiegészítést biztosít a mezőnevekhez a select és result.document.
• queryType: "semantic" lehetővé teszi a szemantikai rangsorolást a lekérdezésen.
• semanticSearchOptions.configurationName a használni kívánt szemantikai konfigurációt határozza meg.

Szemantikai lekérdezés feliratokkal

A semanticQueryReturnCaptions.ts szkript feliratokkal kinyeri a legrelevánsabb részeket az egyes eredményekből, a fontos szavak és kifejezések pedig kiemeléssel jelezve jelennek meg.

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

Főbb tanulságok

• captions.captionType: "extractive" lehetővé teszi a feliratok kinyerését a tartalommezőkből.
• A feliratok kiemelik a legrelevánsabb szakaszokat, és címkékkel látják el <em> a fontos kifejezéseket.

Szemantikai lekérdezés válaszokkal

A semanticAnswer.ts szkript szemantikai válaszokat ad hozzá. Egy kérdést használ keresési szövegként, mert a szemantikai válaszok akkor működnek a legjobban, ha a lekérdezést kérdésként fogalmazták meg. A válasz egy, az indexből kinyert szó szerinti részlet, nem pedig egy csevegési modell által összerakott válasz.

A lekérdezést és az indexelt tartalmat szorosan össze kell igazítani a válasz visszaadásához. Ha egyetlen jelölt sem éri el a megbízhatósági küszöbértéket, a válasz nem tartalmaz választ. Ez a példa egy olyan kérdést használ, amelyről ismert, hogy eredményt ad, így láthatja a szintaxist. Ha a válaszok nem hasznosak a forgatókönyvedhez, hagyd ki answers a kódból. A megkomponált válaszok esetében fontolja meg a RAG-mintát vagy az agent alapú lekérést.

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

Főbb tanulságok

• answers.answerType: "extractive" lehetővé teszi a kérdésekhez hasonló lekérdezések kinyerési válaszait.
• A válaszok az indexből kinyert szó szerinti tartalom, nem pedig a létrehozott szöveg.
• results.answers a válaszobjektumokat a keresési eredményektől elkülönítve kéri le.

Ebben a rövid útmutatóban a Azure AI Keresés REST API-k használatával adhat hozzá semantikus rangsorolást egy meglévő keresési indexhez, és lekérdezheti az indexet.

A szemantikai rangsor egy lekérdezés oldalán található funkció, amely gépi olvasási megértést használ a keresési eredmények újraértékeléséhez, elősegítve a szemantikai szempontból releváns találatokat a lista tetejére. Szemantikai konfigurációt adhat hozzá egy meglévő indexhez újraépítési követelmény nélkül. A szemantikai rangsorolás az információs vagy leíró szövegek esetében a leghatékonyabb.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás.

• Index leíró szövegmezőkkel, amelyhez a searchable és a retrievable attribútumok tartoznak. Ez a rövid útmutató a szállodai mintaindexet feltételezi.

• Visual Studio Code a REST ügyfélkiterjesztéssel.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

Első lépés egy index

Ez a rövid útmutató egy meglévő indexet módosít, hogy szemantikai konfigurációt tartalmazzon. Javasoljuk a szállodai mintaindexet, amelyet percek alatt létrehozhat egy Azure portál varázsló használatával.

Másik index használatához cserélje le az index nevét, a szemantikai konfiguráció mezőneveit és a lekérdezési select utasítások mezőneveit a mintakódban. Az indexnek tartalmaznia kell olyan leíró szövegmezőket, amelyek attribútumként vannak megadva: searchable és retrievable.

A szállodák mintaindexének áttekintése és lekérdezése szemantikai rangsorolás előtt:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza a Kereséskezelési>indexek lehetőséget.

3. Válassza ki hotels-sample.

4. A meglévő konfigurációk megtekintéséhez válassza a szemantikai konfigurációkat . Ha engedélyezte a szemantikai rangsorolást a varázslólétrehozási folyamat során, rendelkeznie kell egy alapértelmezett konfigurációval.

   Alapértelmezett szemantikai konfiguráció képernyőképe az Azure portálon.

5. Válassza a Kereséskezelő, majd a JSON-nézet megtekintése> lehetőséget.

6. Illessze be a következő JSON-t a lekérdezésszerkesztőbe.

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

7. A lekérdezés futtatásához válassza a Keresés lehetőséget .

   A válasznak az alábbi példához hasonlónak kell lennie. Ez egy teljes szöveges lekérdezés, amelyet a BM25 rangsorol, így az eredmények a lekérdezés általános jelentése helyett az egyes lekérdezési kifejezéseken és nyelvi változatokon egyeznek. Például a walking egyezik a walk-el, és a live és a music egymástól függetlenül egyeznek meg, nem pedig kifejezésként.

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

   Tipp

   Ez a lekérdezés bemutatja, hogyan néz ki a válasz a szemantikai rangsor alkalmazása előtt. Miután konfigurált egy szemantikai konfigurációt, adja hozzá "queryType": "semantic" és "semanticConfiguration": "semantic-config" elemeket, és tekintse meg, hogyan rangsorolja a szemantikai rangsorolás ugyanazt a lekérdezést.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Nyissa meg a quickstart mappát a Visual Studio Code-ban.

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

3. Ebben semantic-index-update.resta fájlban cserélje le a helyőrző értékét @searchUrl a Get végpontban beszerzett URL-címre.

4. Ismételje meg az előző lépést a következőhöz semantic-query.rest: .

5. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

6. A Microsoft Entra ID kulcs nélküli hitelesítéséhez hozzon létre egy hozzáférési jogkivonatot.

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

7. Mindkét .rest fájlban cserélje le a helyőrző értékét @personalAccessToken a tokennel az előző lépés alapján.

A kód futtatása

1. Nyisd meg semantic-index-update.rest.

2. Válassza a Kérés küldése lehetőséget az első GET kérelemben a kapcsolat ellenőrzéséhez.

   A válasznak egy szomszédos panelen kell megjelennie. Ha rendelkezik meglévő indexel, azok név szerint vannak felsorolva. Ha a HTTP-kód az 200 OK, készen áll a folytatásra.

3. Küldje el azt a ### Update the hotels-sample index to include a semantic configuration kérést, amely szemantikai konfigurációt szeretne hozzáadni az indexhez.

   Ha hibaüzenetet 400 Bad Request kap, az indexséma eltér a mintától. Küldje el a ### Get the schema of the index kérést, másolja ki a válasz JSON-t, adja hozzá a semantic szakaszt a forráskódból a JSON-hoz, és cserélje le a PUT kérés törzsét az egyesített sémára.

4. Váltson semantic-query.rest -re, és küldje el a kérelmeket egymás után: egy egyszerű lekérdezést az alapkonfiguráció összehasonlításához, majd szemantikai lekérdezéseket rangsorolással, feliratokkal és válaszokkal.

Kimenet

A Send a search query to the hotels-sample index kérelem a BM25 relevancia alapján rangsorolt eredményeket adja vissza, amelyet a @search.score mező jelez.

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

A Send a search query to the hotels-sample index with semantic ranking kérés hozzáadja a elemet @search.rerankerScore. Figyelje meg, hogy a rendelés az egyszerű lekérdezésből változik.

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

A Return captions in the query kérelem kibontott szöveggel és kiemelésekkel bővíthető @search.captions .

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

A Return semantic answers in the query kérés kinyerő választ @search.answers ad vissza, amikor a lekérdezés kérdésként van megfogalmazva.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Konfiguráció és hitelesítés
2. Az index frissítése szemantikai konfigurációval
3. Az index lekérdezése

Konfiguráció és hitelesítés

Mindkét .rest fájl a tetején változókat határoz meg az összes kérés újrafelhasználásához.

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

Főbb tanulságok

• @searchUrl a keresési szolgáltatás végpontja.
• @personalAccessToken egy Microsoft Entra ID jogkivonat, amely az Azure CLI-ből származik. Ez az API-kulcsokat kulcs nélküli hitelesítésre cseréli.
• Authorization: Bearer {{personalAccessToken}} minden kérés fejlécébe bekerül a hitelesítéshez.

Az index frissítése szemantikai konfigurációval

A ### Update the hotels-sample index to include a semantic configuration kérés a semantic-index-update.rest-ben a teljes indexsémát küldi el egy új semantic szakaszsal együtt. A REST API-hoz minden frissítési művelet teljes sémája szükséges, így nem küldheti el csak a szemantikai konfigurációt.

Az új semantic szakasz a kulcsfontosságú hozzáadás.

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

Főbb tanulságok

• titleField azonosítja, hogy melyik mező tartalmazza a szemantikai értékelés dokumentumcímét.
• prioritizedContentFields azonosítja a fő tartalommezőket. A szemantikai rangsoroló ezeket értékeli ki először a relevancia értékelésekor.
• prioritizedKeywordsFields a további környezet kulcsszó- vagy címkemezőit azonosítja.
• rankingOrder: BoostedRerankerScore egyesíti a BM25 pontszámot a szemantikai reranker pontszámmal.
• A REST API-hoz a PUT-műveletek teljes sémája szükséges. Csak a semantic szakasz új, az összes többi mező változatlan marad.

Az index lekérdezése

A semantic-query.rest kérések egy egyszerű kulcsszókereséstől a szemantikai rangsorolásig terjednek, magyarázó szövegekkel és válaszokkal. Minden lekérdezés POST-kérés a Dokumentumok – Search Post (REST API) szolgáltatáshoz.

Egyszerű lekérdezés

A ### Send a search query to the hotels-sample index kérés egy egyszerű kulcsszókeresés, amely nem használ szemantikai rangsorolást. Alapkonfigurációként szolgál az eredmények szemantikai újrarankálással és anélkül történő összehasonlításához.

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

Főbb tanulságok

• queryType: "simple" az alapértelmezett BM25 rangsorolási algoritmust használja.
• Az eredmények csak kulcsszó-relevancia (@search.score) alapján vannak rangsorolva.

Szemantikai lekérdezés (nincs felirat, nincs válasz)

A ### Send a search query to the hotels-sample index with semantic ranking kérés szemantikai rangsorolást ad hozzá. Az alábbi JSON a szemantikai rangsor meghívásának minimális követelményét mutatja be.

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

Főbb tanulságok

• queryType: "semantic" lehetővé teszi a szemantikai rangsorolást a lekérdezésen.
• semanticConfiguration a használni kívánt szemantikai konfigurációt határozza meg.

Szemantikai lekérdezés feliratokkal

A ### Return captions in the query kérés feliratokat ad az egyes eredmények legfontosabb részeinek kiemeléséhez, a fontos fogalmakra és kifejezésekre pedig találati kiemelés vonatkozik.

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

Főbb tanulságok

• captions: "extractive|highlight-true" lehetővé teszi a fontos kifejezésekhez kapcsolódó címkékkel rendelkező <em> kinyerési feliratok használatát.
• Az egyes eredményekhez felirat jelenik meg a @search.captions tömbben.

Szemantikai lekérdezés válaszokkal

A ### Return semantic answers in the query kérés szemantikai válaszokat ad hozzá. Egy kérdést használ keresési szövegként, mert a szemantikai válaszok akkor működnek a legjobban, ha a lekérdezést kérdésként fogalmazták meg. A válasz egy, az indexből kinyert szó szerinti részlet, nem pedig egy csevegési modell által összerakott válasz.

A lekérdezést és az indexelt tartalmat szorosan össze kell igazítani a válasz visszaadásához. Ha egyetlen jelölt sem éri el a megbízhatósági küszöbértéket, a válasz nem tartalmaz választ. Ez a példa egy olyan kérdést használ, amelyről ismert, hogy eredményt ad, így láthatja a szintaxist. Ha a válaszok nem hasznosak a forgatókönyvhöz, hagyja ki a paramétert a answers kérésből. A megkomponált válaszok esetében fontolja meg a RAG-mintát vagy az agent alapú lekérést.

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

Főbb tanulságok

• answers: "extractive" lehetővé teszi a kérdésekhez hasonló lekérdezések kinyerési válaszait.
• A válaszok a legfelső szintű @search.answers tömbben jelennek meg, az egyes eredményektől elkülönítve.
• A válaszok az indexből kinyert szó szerinti tartalom, nem pedig a létrehozott szöveg.