Snabbstart: Semantisk rankning - Azure AI Search

I den här snabbstarten använder du klientbiblioteket Azure AI-sökning för .NET för att lägga till semantisk rangordning till ett befintligt sökindex och köra frågor mot indexet.

Semantisk rangordning är en frågesidefunktionalitet som använder maskinläsningsförmåga för att återpoängsätta sökresultaten, vilket främjar de mest semantiskt relevanta matchningarna överst i listan. Du kan lägga till en semantisk konfiguration i ett befintligt index utan återskapandekrav. Semantisk rangordning är mest effektiv för informations- eller beskrivande text.

Tips

Vill du komma igång direkt? Ladda ned source-koden på GitHub.

Förutsättningar

Ett Azure konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
En Azure AI-sökning-tjänst.
Ett index med beskrivande textfält som tillskrivs searchable och retrievable. Den här snabbstarten förutsätter indexet hotels-sample.
.NET 9 eller senare.
Git för att klona exempellagringsplatsen.
Azure CLI för nyckellös autentisering med Microsoft Entra ID.

Konfigurera åtkomst

Innan du börjar kontrollerar du att du har behörighet att komma åt innehåll och åtgärder i Azure AI-sökning. Den här snabbstarten använder Microsoft Entra ID för autentisering och rollbaserad åtkomst för auktorisering. Du måste vara ägare eller administratör för användaråtkomst för att tilldela roller. Om roller inte är genomförbara använder du nyckelbaserad autentisering i stället.

Så här konfigurerar du den rekommenderade rollbaserade åtkomsten:

Aktivera rollbaserad åtkomst för söktjänsten.
Tilldela följande roller till ditt användarkonto.
- Söktjänstdeltagare
- Dataläsare för sökindex

Observera

Till skillnad från andra snabbstarter som skapar och läser in ett index förutsätter den här snabbstarten ett befintligt index som redan innehåller data, så du behöver inte rollen Search Index Data Contributor .

Hämta slutpunkt

Varje Azure AI-sökning-tjänst har en endpoint, vilket är en unik URL som identifierar och ger nätverksåtkomst till tjänsten. I ett senare avsnitt anger du den här slutpunkten för att ansluta till söktjänsten programmatiskt.

Så här får du slutpunkten:

Gå till söktjänsten i Azure-portalen.
Välj Översikt i den vänstra rutan.
Anteckna slutpunkten, som bör se ut som https://my-service.search.windows.net.

Börja med ett index

Den här snabbstarten ändrar ett befintligt index så att det innehåller en semantisk konfiguration. Vi rekommenderar indexet hotels-sample som du kan skapa på några minuter med hjälp av en Azure portalguide.

Om du vill använda ett annat index ersätter du indexnamnet, fältnamnen i den semantiska konfigurationen och fältnamnen i frågeinstruktioner select i exempelkoden. Ditt index bör innehålla beskrivande textfält som tillskrivs som searchable och retrievable.

För att granska och använda indexet hotels-sample före semantisk rangordning:

Gå till söktjänsten i Azure-portalen.
I den vänstra rutan väljer du Sökhanteringsindex>.
Välj hotellexempel.
Välj Semantiska konfigurationer för att visa befintliga konfigurationer. Om du har aktiverat semantisk rangordning under guidens skapandeflöde bör det finnas en standardkonfiguration.
Välj Sökutforskaren och välj sedan Visa>.

Klistra in följande JSON i frågeredigeraren.

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

Välj Sök för att köra frågan.

Svaret bör likna följande exempel. Det här är en fulltextfråga rangordnad efter BM25, så resultaten matchar enskilda frågetermer och språkvarianter snarare än frågans övergripande innebörd. Matchar till exempel walkingwalk, och live och music matchar oberoende i stället för som en fras.

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

Tips

Den här frågan visar hur svaret ser ut innan semantisk rangordning tillämpas. När du har konfigurerat en semantisk konfiguration lägger du till "queryType": "semantic" och "semanticConfiguration": "semantic-config" för att se hur samma fråga rangordnas annorlunda efter semantisk rangordning.

Konfigurera miljön

Använd Git för att klona exempellagringsplatsen.

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

Gå till snabbstartsmappen.

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

I BuildIndex/Program.csersätter du platshållarvärdet för endpoint med den URL som du fick i Hämta slutpunkt.
Upprepa föregående steg för QueryIndex/Program.cs.
Logga in på ditt Azure konto för nyckellös autentisering med Microsoft Entra ID. Om du har flera prenumerationer väljer du den som innehåller din Azure AI-sökning tjänst.
```
az login
```

Kör koden

Kör det första projektet för att uppdatera indexet med en semantisk konfiguration.
```
dotnet run --project BuildIndex
```
Kör det andra projektet för att fråga indexet. Tryck på Retur mellan frågor för att se förloppet från enkel fråga till semantisk fråga med bildtexter och svar.
```
dotnet run --project QueryIndex
```

Produktionen

Det första projektet uppdaterar indexet hotels-sample med en semantisk konfiguration. Utdata innehåller bekräftelse av semantisk konfiguration.

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

Det andra projektet kör fyra frågor. Utdata innehåller sökresultat med relevanspoäng, undertexter och svar.

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

Förstå koden

Observera

Kodfragmenten i det här avsnittet kan ha ändrats för läsbarhet. Ett fullständigt arbetsexempel finns i källkoden.

Nu när du har kört koden ska vi gå igenom de viktigaste stegen:

Konfiguration och autentisering
Uppdatera indexet med en semantisk konfiguration
Fråga indexet

Konfiguration och autentisering

Båda projekten har samma konfigurationsmönster. Filerna Program.cs definierar sökslutpunkten och använder DefaultAzureCredential för nyckellös autentisering.

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

Viktiga lärdomar:

DefaultAzureCredential tillhandahåller nyckellös autentisering med hjälp av Microsoft Entra ID. Den kedjar flera typer av autentiseringsuppgifter, inklusive Azure CLI autentiseringsuppgifter från az login.
SearchIndexClient hanterar åtgärder på indexnivå, till exempel uppdatering av indexschemat.
SearchClient hanterar åtgärder på dokumentnivå, till exempel att köra frågor mot indexet.

Uppdatera indexet med en semantisk konfiguration

Följande kod i BuildIndex/Program.cs lägger till en semantisk konfiguration i det befintliga indexet. Den här åtgärden tar inte bort några sökdokument och ditt index förblir i drift när konfigurationen har lagts till.

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

Viktiga lärdomar:

En semantisk konfiguration anger de fält som används för semantisk rangordning.
Semantiska konfigurationer kan läggas till i befintliga index utan att återskapas.
TitleField anger det fält som representerar dokumentrubriken.
ContentFields anger fälten som innehåller huvudinnehållet.
KeywordsFields anger fälten som innehåller nyckelord eller taggar.

Fråga indexet

Projektet QueryIndex kör fyra frågor i följd och går från en enkel nyckelordssökning till semantisk rangordning med bildtexter och svar.

Enkel fråga

Den första frågan är en enkel nyckelordssökning som inte använder semantisk rangordning. Den här frågan fungerar som en baslinje för att jämföra resultat med och utan semantisk reranking.

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

Viktiga lärdomar:

SearchQueryType.Simple använder BM25-standardrankningsalgoritmen.
Resultaten rangordnas endast efter nyckelordsrelevans (@search.score).

Semantisk fråga (inga bildtexter, inga svar)

Nästa fråga lägger till semantisk rangordning utan bildtexter eller svar. Följande kod visar minimikravet för att anropa semantisk rangordning.

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

Viktiga lärdomar:

SearchQueryType.Semantic aktiverar semantisk rangordning i frågan.
SemanticConfigurationName anger vilken semantisk konfiguration som ska användas.
@search.rerankerScore anger semantisk relevans (högre är bättre).
De första resultaten från termfrågan omkorrigeras med hjälp av semantiska rankningsmodeller. För den här datamängden och frågan är effekterna av semantisk rangordning mer uttalade i de lägre rankade resultaten.

Semantisk fråga med bildtexter

Följande kod lägger till undertexter för att extrahera de mest relevanta avsnitten från varje resultat, med träffmarkeringar som tillämpas på viktiga termer och fraser.

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

Viktiga lärdomar:

QueryCaption aktiverar extraheringstexter från innehållsfälten.
Undertexter innehåller de mest relevanta avsnitten och lägger till  taggar runt viktiga termer.

Semantisk fråga med svar

Den sista frågan lägger till semantiska svar. Den här frågan använder en annan söksträng (searchText2) eftersom semantiska svar fungerar bäst när frågan formuleras som en fråga. Svaret är en ordagrann passage som extraherats från ditt index, inte ett sammansatt svar från en modell för chattens slutförande.

Frågan och det indexerade innehållet måste vara nära justerade för att ett svar ska returneras. Om ingen kandidat uppfyller förtroendetröskeln innehåller svaret inget svar. I det här exemplet används en fråga som är känd för att generera ett resultat så att du kan se syntaxen. Om svaren inte är användbara för ditt scenario, utelämna QueryAnswer från din kod. För sammansatta svar bör du överväga ett RAG-mönster eller agentisk hämtning.

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

Viktiga lärdomar:

QueryAnswer aktiverar extraheringssvar för frågeliknande frågor.
Svaren är ordagrant innehåll som extraheras från det specifika indexet, inte genererad text.

I den här snabbstarten använder du klientbiblioteket Azure AI-sökning för Java för att lägga till semantisk rangordning till ett befintligt sökindex och köra frågor mot indexet.

Semantisk rangordning är en frågesidefunktionalitet som använder maskinläsningsförmåga för att återpoängsätta sökresultaten, vilket främjar de mest semantiskt relevanta matchningarna överst i listan. Du kan lägga till en semantisk konfiguration i ett befintligt index utan återskapandekrav. Semantisk rangordning är mest effektiv för informations- eller beskrivande text.

Tips

Vill du komma igång direkt? Ladda ned source-koden på GitHub.

Förutsättningar

Ett Azure konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
En Azure AI-sökning-tjänst.
Ett index med beskrivande textfält som tillskrivs searchable och retrievable. Den här snabbstarten förutsätter indexet hotels-sample.
Java 21 (LTS) och Maven.
Git för att klona exempellagringsplatsen.
Azure CLI för nyckellös autentisering med Microsoft Entra ID.

Konfigurera åtkomst

Innan du börjar kontrollerar du att du har behörighet att komma åt innehåll och åtgärder i Azure AI-sökning. Den här snabbstarten använder Microsoft Entra ID för autentisering och rollbaserad åtkomst för auktorisering. Du måste vara ägare eller administratör för användaråtkomst för att tilldela roller. Om roller inte är genomförbara använder du nyckelbaserad autentisering i stället.

Så här konfigurerar du den rekommenderade rollbaserade åtkomsten:

Aktivera rollbaserad åtkomst för söktjänsten.
Tilldela följande roller till ditt användarkonto.
- Söktjänstdeltagare
- Dataläsare för sökindex

Observera

Till skillnad från andra snabbstarter som skapar och läser in ett index förutsätter den här snabbstarten ett befintligt index som redan innehåller data, så du behöver inte rollen Search Index Data Contributor .

Hämta slutpunkt

Varje Azure AI-sökning-tjänst har en endpoint, vilket är en unik URL som identifierar och ger nätverksåtkomst till tjänsten. I ett senare avsnitt anger du den här slutpunkten för att ansluta till söktjänsten programmatiskt.

Så här får du slutpunkten:

Gå till söktjänsten i Azure-portalen.
Välj Översikt i den vänstra rutan.
Anteckna slutpunkten, som bör se ut som https://my-service.search.windows.net.

Börja med ett index

Den här snabbstarten ändrar ett befintligt index så att det innehåller en semantisk konfiguration. Vi rekommenderar indexet hotels-sample som du kan skapa på några minuter med hjälp av en Azure portalguide.

Om du vill använda ett annat index ersätter du indexnamnet, fältnamnen i den semantiska konfigurationen och fältnamnen i frågeinstruktioner select i exempelkoden. Ditt index bör innehålla beskrivande textfält som tillskrivs som searchable och retrievable.

För att granska och använda indexet hotels-sample före semantisk rangordning:

Gå till söktjänsten i Azure-portalen.
I den vänstra rutan väljer du Sökhanteringsindex>.
Välj hotellexempel.
Välj Semantiska konfigurationer för att visa befintliga konfigurationer. Om du har aktiverat semantisk rangordning under guidens skapandeflöde bör det finnas en standardkonfiguration.
Välj Sökutforskaren och välj sedan Visa>.

Klistra in följande JSON i frågeredigeraren.

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

Välj Sök för att köra frågan.

Svaret bör likna följande exempel. Det här är en fulltextfråga rangordnad efter BM25, så resultaten matchar enskilda frågetermer och språkvarianter snarare än frågans övergripande innebörd. Matchar till exempel walkingwalk, och live och music matchar oberoende i stället för som en fras.

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

Tips

Den här frågan visar hur svaret ser ut innan semantisk rangordning tillämpas. När du har konfigurerat en semantisk konfiguration lägger du till "queryType": "semantic" och "semanticConfiguration": "semantic-config" för att se hur samma fråga rangordnas annorlunda efter semantisk rangordning.

Konfigurera miljön

Använd Git för att klona exempellagringsplatsen.

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

Gå till snabbstartsmappen.

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

I src/main/resources/application.propertiesersätter du platshållarvärdet för azure.search.endpoint med den URL som du fick i Hämta slutpunkt.
Kompilera projektet för att lösa beroenden, inklusive azure-search-documents.
```
mvn compile
```
När bygget är klart kontrollerar du att inga fel visas i utdata.
Logga in på ditt Azure konto för nyckellös autentisering med Microsoft Entra ID. Om du har flera prenumerationer väljer du den som innehåller din Azure AI-sökning tjänst.
```
az login
```

Kör koden

Hämta de befintliga indexinställningarna.

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

Uppdatera indexet med en semantisk konfiguration.

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

Kör en semantisk fråga.

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

Kör en semantisk fråga med bildtexter.

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

Kör en semantisk fråga med svar.

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

Produktionen

Utdata för GetIndexSettings.java är namnet på indexet, dess fält och dess semantiska konfigurationer. Innan du lägger till en ny konfiguration har indexet bara standardkonfigurationen.

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

Utdata av UpdateIndexSettings.java visar alla semantiska konfigurationer i indexet, inklusive den som koden lade till, följt av ett framgångsmeddelande.

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

Utdata från SemanticQuery.java returnerar alla matchande dokument ordnade efter den semantiska rangordningens omriktningspoäng.

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

Utdataelementet SemanticQueryWithCaptions.java lägger till ett rubrikelement med träffmarkering tillsammans med sökfält. Bildtexter är de mest relevanta avsnitten i ett resultat. Om ditt index innehåller större text hjälper undertexter till att extrahera de mest intressanta meningarna.

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

Resultatet av SemanticAnswer.java innehåller ett semantiskt svar som hämtats från ett av de resultat som bäst matchar frågan, följt av sökresultat med bildtexter.

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

Förstå koden

Observera

Kodfragmenten i det här avsnittet kan ha ändrats för läsbarhet. Ett fullständigt arbetsexempel finns i källkoden.

Nu när du har kört koden ska vi gå igenom de viktigaste stegen:

Konfiguration och autentisering
Uppdatera indexet med en semantisk konfiguration
Fråga indexet

Konfiguration och autentisering

Klassen SearchConfig.java läser in egenskaper från application.properties och skapar en DefaultAzureCredential för nyckellös autentisering.

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

Viktiga lärdomar:

DefaultAzureCredential tillhandahåller nyckellös autentisering med hjälp av Microsoft Entra ID. Den kedjar flera typer av autentiseringsuppgifter, inklusive Azure CLI autentiseringsuppgifter från az login.
Egenskaper läses in från filen application.properties i klasstigen.
Statiska fält (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) delas mellan alla klasser i projektet.

Uppdatera indexet med en semantisk konfiguration

Klassen UpdateIndexSettings.java lägger till en semantisk konfiguration i det befintliga hotels-sample indexet. Den här åtgärden tar inte bort några sökdokument och ditt index förblir i drift när konfigurationen har lagts till.

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

Viktiga lärdomar:

SemanticPrioritizedFields definierar vilka fält som den semantiska rankaren utvärderar. setTitleField anger dokumentrubriken, setContentFields anger huvudinnehållet och setKeywordsFields anger nyckelords- eller taggfälten.
SemanticConfiguration parar ett namn med de prioriterade fälten och identifierar vilken semantisk konfiguration som ska användas vid frågetillfället.
createOrUpdateIndex skickar det uppdaterade schemat till söktjänsten utan att återskapa indexet eller ta bort dokument.

Fråga indexet

Följande tre klasser frågar indexet i ordning och fortsätter från en grundläggande semantisk sökning till semantisk rangordning med bildtexter och svar.

Semantisk fråga (inga bildtexter, inga svar)

Den första frågan lägger till semantisk rangordning utan bildtexter eller svar. Klassen SemanticQuery.java visar minimikravet för att anropa semantisk rangordning.

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

Viktiga lärdomar:

QueryType.SEMANTIC aktiverar semantisk rangordning i frågan.
setSemanticConfigurationName anger vilken semantisk konfiguration som ska användas.
SearchPagedIterable ger en iterabel över de omrankade resultaten. Varje SearchResult innehåller en getSemanticSearch() accessor för omrangörarpoängen.

Semantisk fråga med bildtexter

Klassen SemanticQueryWithCaptions.java lägger till undertexter för att extrahera de mest relevanta avsnitten från varje resultat, med träffmarkeringar som tillämpas på viktiga termer och fraser.

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

Viktiga lärdomar:

QueryCaption(QueryCaptionType.EXTRACTIVE) aktiverar extraheringstexter från innehållsfälten.
setHighlightEnabled(true) lägger till  taggar runt viktiga termer i undertexter.
Varje SearchResult tillhandahåller getQueryCaptions() på den semantiska sökåtkomst.

Semantisk fråga med svar

Klassen SemanticAnswer.java lägger till semantiska svar. Den här klassen använder en fråga som söktext eftersom semantiska svar fungerar bäst när frågan formuleras som en fråga. Svaret är en ordagrann passage som extraherats från ditt index, inte ett sammansatt svar från en modell för chattens slutförande.

Frågan och det indexerade innehållet måste vara nära justerade för att ett svar ska returneras. Om ingen kandidat uppfyller förtroendetröskeln innehåller svaret inget svar. I det här exemplet används en fråga som är känd för att generera ett resultat så att du kan se syntaxen. Om svaren inte är användbara för ditt scenario, utelämna setQueryAnswer från din kod. För sammansatta svar bör du överväga ett RAG-mönster eller agentisk hämtning.

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

Viktiga lärdomar:

QueryAnswer(QueryAnswerType.EXTRACTIVE) aktiverar extraheringssvar för frågeliknande frågor.
Svaren är ordagrant innehåll som extraheras från det specifika indexet, inte genererad text.
results.getSemanticResults().getQueryAnswers() hämtar svarsobjekten separat från sökresultaten.

I den här snabbstarten använder du klientbiblioteket Azure AI-sökning för JavaScript för att lägga till semantisk rangordning till ett befintligt sökindex och köra frågor mot indexet.

Semantisk rangordning är en frågesidefunktionalitet som använder maskinläsningsförmåga för att återpoängsätta sökresultaten, vilket främjar de mest semantiskt relevanta matchningarna överst i listan. Du kan lägga till en semantisk konfiguration i ett befintligt index utan återskapandekrav. Semantisk rangordning är mest effektiv för informations- eller beskrivande text.

Tips

Vill du komma igång direkt? Ladda ned source-koden på GitHub.

Förutsättningar

Ett Azure konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
En Azure AI-sökning-tjänst.
Ett index med beskrivande textfält som tillskrivs searchable och retrievable. Den här snabbstarten förutsätter indexet hotels-sample.
Node.js 20 LTS eller senare.
Git för att klona exempellagringsplatsen.
Azure CLI för nyckellös autentisering med Microsoft Entra ID.

Konfigurera åtkomst

Innan du börjar kontrollerar du att du har behörighet att komma åt innehåll och åtgärder i Azure AI-sökning. Den här snabbstarten använder Microsoft Entra ID för autentisering och rollbaserad åtkomst för auktorisering. Du måste vara ägare eller administratör för användaråtkomst för att tilldela roller. Om roller inte är genomförbara använder du nyckelbaserad autentisering i stället.

Så här konfigurerar du den rekommenderade rollbaserade åtkomsten:

Aktivera rollbaserad åtkomst för söktjänsten.
Tilldela följande roller till ditt användarkonto.
- Söktjänstdeltagare
- Dataläsare för sökindex

Observera

Till skillnad från andra snabbstarter som skapar och läser in ett index förutsätter den här snabbstarten ett befintligt index som redan innehåller data, så du behöver inte rollen Search Index Data Contributor .

Hämta slutpunkt

Varje Azure AI-sökning-tjänst har en endpoint, vilket är en unik URL som identifierar och ger nätverksåtkomst till tjänsten. I ett senare avsnitt anger du den här slutpunkten för att ansluta till söktjänsten programmatiskt.

Så här får du slutpunkten:

Gå till söktjänsten i Azure-portalen.
Välj Översikt i den vänstra rutan.
Anteckna slutpunkten, som bör se ut som https://my-service.search.windows.net.

Börja med ett index

Den här snabbstarten ändrar ett befintligt index så att det innehåller en semantisk konfiguration. Vi rekommenderar indexet hotels-sample som du kan skapa på några minuter med hjälp av en Azure portalguide.

Om du vill använda ett annat index ersätter du indexnamnet, fältnamnen i den semantiska konfigurationen och fältnamnen i frågeinstruktioner select i exempelkoden. Ditt index bör innehålla beskrivande textfält som tillskrivs som searchable och retrievable.

För att granska och använda indexet hotels-sample före semantisk rangordning:

Gå till söktjänsten i Azure-portalen.
I den vänstra rutan väljer du Sökhanteringsindex>.
Välj hotellexempel.
Välj Semantiska konfigurationer för att visa befintliga konfigurationer. Om du har aktiverat semantisk rangordning under guidens skapandeflöde bör det finnas en standardkonfiguration.
Välj Sökutforskaren och välj sedan Visa>.

Klistra in följande JSON i frågeredigeraren.

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

Välj Sök för att köra frågan.

Svaret bör likna följande exempel. Det här är en fulltextfråga rangordnad efter BM25, så resultaten matchar enskilda frågetermer och språkvarianter snarare än frågans övergripande innebörd. Matchar till exempel walkingwalk, och live och music matchar oberoende i stället för som en fras.

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

Tips

Den här frågan visar hur svaret ser ut innan semantisk rangordning tillämpas. När du har konfigurerat en semantisk konfiguration lägger du till "queryType": "semantic" och "semanticConfiguration": "semantic-config" för att se hur samma fråga rangordnas annorlunda efter semantisk rangordning.

Konfigurera miljön

Använd Git för att klona exempellagringsplatsen.

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

Gå till snabbstartsmappen.

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

I sample.enversätter du platshållarvärdet för AZURE_SEARCH_ENDPOINT med den URL som du fick i Hämta slutpunkt.
Byt sample.env namn till .env.
```
mv sample.env .env
```
Installera beroendena.
```
npm install
```
När installationen är klar bör du se en node_modules mapp i projektkatalogen.
Logga in på ditt Azure konto för nyckellös autentisering med Microsoft Entra ID. Om du har flera prenumerationer väljer du den som innehåller din Azure AI-sökning tjänst.
```
az login
```

Kör koden

Hämta de befintliga indexinställningarna.

node -r dotenv/config src/getIndexSettings.js

Uppdatera indexet med en semantisk konfiguration.

node -r dotenv/config src/updateIndexSettings.js

Kör en semantisk fråga.

node -r dotenv/config src/semanticQuery.js

Kör en semantisk fråga med bildtexter.

node -r dotenv/config src/semanticQueryReturnCaptions.js

Kör en semantisk fråga med svar.

node -r dotenv/config src/semanticAnswer.js

Produktionen

Skriptet getIndexSettings.js returnerar namnet på indexet, dess fält och eventuella befintliga semantiska konfigurationer.

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

Skriptet updateIndexSettings.js returnerar alla semantiska konfigurationer i indexet, inklusive den som koden lade till, följt av ett meddelande om att det lyckades.

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.

Skriptet semanticQuery.js returnerar alla matchande dokument ordnade efter den semantiska rangordningens omrankningspoäng.

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

Skriptet semanticQueryReturnCaptions.js returnerar ett rubrikelement med träffmarkeringar tillsammans med sökfält. Bildtexter är de mest relevanta avsnitten i ett resultat. Om ditt index innehåller större text hjälper undertexter till att extrahera de mest intressanta meningarna.

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

Skriptet semanticAnswer.js returnerar ett semantiskt svar som hämtats från ett av de resultat som bäst matchar frågan, följt av sökresultat med bildtexter.

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

Förstå koden

Observera

Kodfragmenten i det här avsnittet kan ha ändrats för läsbarhet. Ett fullständigt arbetsexempel finns i källkoden.

Nu när du har kört koden ska vi gå igenom de viktigaste stegen:

Konfiguration och autentisering
Uppdatera indexet med en semantisk konfiguration
Fråga indexet

Konfiguration och autentisering

Filen config.js läser in miljövariabler och skapar en DefaultAzureCredential för autentisering.

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

Viktiga lärdomar:

DefaultAzureCredential tillhandahåller nyckellös autentisering med hjälp av Microsoft Entra ID. Den kedjar flera typer av autentiseringsuppgifter, inklusive Azure CLI autentiseringsuppgifter från az login.
Miljövariabler läses in från .env filen med hjälp av dotenv.

Uppdatera indexet med en semantisk konfiguration

Filen updateIndexSettings.js lägger till en semantisk konfiguration i det befintliga hotels-sample indexet. Den här åtgärden tar inte bort några sökdokument och ditt index förblir i drift när konfigurationen har lagts till.

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

Viktiga lärdomar:

En semantisk konfiguration anger de fält som används för semantisk rangordning. titleField definierar dokumentrubriken, contentFields definierar huvudinnehållet och keywordsFields definierar nyckelords- eller taggfälten.
Du skapar ett konfigurationsobjekt semanticSearch.configurations och push-överför det till det befintliga indexets matris.
createOrUpdateIndex skickar det uppdaterade schemat till söktjänsten utan att återskapa indexet eller ta bort dokument.

Fråga indexet

Frågeskripten kör tre frågor i följd och går från en grundläggande semantisk sökning till semantisk rangordning med bildtexter och svar.

Semantisk fråga (inga bildtexter, inga svar)

Följande kod visar minimikravet för att anropa semantisk rangordning.

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

Viktiga lärdomar:

queryType: "semantic" aktiverar semantisk rangordning i frågan.
semanticSearchOptions.configurationName anger vilken semantisk konfiguration som ska användas.
Resultatet rerankerScore indikerar semantisk relevans (högre är bättre).

Semantisk fråga med bildtexter

Följande kod lägger till undertexter för att extrahera de mest relevanta avsnitten från varje resultat, med träffmarkeringar som tillämpas på viktiga termer och fraser.

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

Viktiga lärdomar:

captions.captionType: "extractive" aktiverar extraheringstexter från innehållsfälten.
Undertexter innehåller de mest relevanta avsnitten och lägger till  taggar runt viktiga termer.

Semantisk fråga med svar

Den sista frågan lägger till semantiska svar. Den här frågan använder en fråga som söktext eftersom semantiska svar fungerar bäst när frågan formuleras som en fråga. Svaret är en ordagrann passage som extraherats från ditt index, inte ett sammansatt svar från en modell för chattens slutförande.

Frågan och det indexerade innehållet måste vara nära justerade för att ett svar ska returneras. Om ingen kandidat uppfyller förtroendetröskeln innehåller svaret inget svar. I det här exemplet används en fråga som är känd för att generera ett resultat så att du kan se syntaxen. Om svaren inte är användbara för ditt scenario, utelämna answers från din kod. För sammansatta svar bör du överväga ett RAG-mönster eller agentisk hämtning.

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

Viktiga lärdomar:

answers.answerType: "extractive" aktiverar extraheringssvar för frågeliknande frågor.
Svaren är ordagrant innehåll som extraheras från det specifika indexet, inte genererad text.
results.answers hämtar svarsobjekten separat från sökresultaten.

I den här snabbstarten använder du klientbiblioteket Azure AI-sökning för Python för att lägga till semantisk rangordning till ett befintligt sökindex och köra frågor mot indexet.

Semantisk rangordning är en frågesidefunktionalitet som använder maskinläsningsförmåga för att återpoängsätta sökresultaten, vilket främjar de mest semantiskt relevanta matchningarna överst i listan. Du kan lägga till en semantisk konfiguration i ett befintligt index utan återskapandekrav. Semantisk rangordning är mest effektiv för informations- eller beskrivande text.

Tips

Vill du komma igång direkt? Ladda ned source-koden på GitHub.

Förutsättningar

Ett Azure konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
En Azure AI-sökning-tjänst.
Ett index med beskrivande textfält som tillskrivs searchable och retrievable. Den här snabbstarten förutsätter indexet hotels-sample.
Python 3.10 eller senare.
Visual Studio Code med tillägget Python.
Git för att klona exempellagringsplatsen.
Azure CLI för nyckellös autentisering med Microsoft Entra ID.

Konfigurera åtkomst

Innan du börjar kontrollerar du att du har behörighet att komma åt innehåll och åtgärder i Azure AI-sökning. Den här snabbstarten använder Microsoft Entra ID för autentisering och rollbaserad åtkomst för auktorisering. Du måste vara ägare eller administratör för användaråtkomst för att tilldela roller. Om roller inte är genomförbara använder du nyckelbaserad autentisering i stället.

Så här konfigurerar du den rekommenderade rollbaserade åtkomsten:

Aktivera rollbaserad åtkomst för söktjänsten.
Tilldela följande roller till ditt användarkonto.
- Söktjänstdeltagare
- Dataläsare för sökindex

Observera

Till skillnad från andra snabbstarter som skapar och läser in ett index förutsätter den här snabbstarten ett befintligt index som redan innehåller data, så du behöver inte rollen Search Index Data Contributor .

Hämta slutpunkt

Varje Azure AI-sökning-tjänst har en endpoint, vilket är en unik URL som identifierar och ger nätverksåtkomst till tjänsten. I ett senare avsnitt anger du den här slutpunkten för att ansluta till söktjänsten programmatiskt.

Så här får du slutpunkten:

Gå till söktjänsten i Azure-portalen.
Välj Översikt i den vänstra rutan.
Anteckna slutpunkten, som bör se ut som https://my-service.search.windows.net.

Börja med ett index

Den här snabbstarten ändrar ett befintligt index så att det innehåller en semantisk konfiguration. Vi rekommenderar indexet hotels-sample som du kan skapa på några minuter med hjälp av en Azure portalguide.

Om du vill använda ett annat index ersätter du indexnamnet, fältnamnen i den semantiska konfigurationen och fältnamnen i frågeinstruktioner select i exempelkoden. Ditt index bör innehålla beskrivande textfält som tillskrivs som searchable och retrievable.

För att granska och använda indexet hotels-sample före semantisk rangordning:

Gå till söktjänsten i Azure-portalen.
I den vänstra rutan väljer du Sökhanteringsindex>.
Välj hotellexempel.
Välj Semantiska konfigurationer för att visa befintliga konfigurationer. Om du har aktiverat semantisk rangordning under guidens skapandeflöde bör det finnas en standardkonfiguration.
Välj Sökutforskaren och välj sedan Visa>.

Klistra in följande JSON i frågeredigeraren.

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

Välj Sök för att köra frågan.

Svaret bör likna följande exempel. Det här är en fulltextfråga rangordnad efter BM25, så resultaten matchar enskilda frågetermer och språkvarianter snarare än frågans övergripande innebörd. Matchar till exempel walkingwalk, och live och music matchar oberoende i stället för som en fras.

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

Tips

Den här frågan visar hur svaret ser ut innan semantisk rangordning tillämpas. När du har konfigurerat en semantisk konfiguration lägger du till "queryType": "semantic" och "semanticConfiguration": "semantic-config" för att se hur samma fråga rangordnas annorlunda efter semantisk rangordning.

Konfigurera miljön

Använd Git för att klona exempellagringsplatsen.

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

Gå till snabbstartsmappen och öppna den i Visual Studio Code.

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

I sample.enversätter du platshållarvärdet för AZURE_SEARCH_ENDPOINT med den URL som du fick i Hämta slutpunkt.
Byt sample.env namn till .env.
```
mv sample.env .env
```
Öppna semantic-ranking-quickstart.ipynb.
Tryck på Ctrl+Skift+P, välj Notebook: Välj Notebook Kernel och följ anvisningarna för att skapa en virtuell miljö. Välj requirements.txt för beroendena.

När du är klar bör du se en .venv mapp i projektkatalogen.
Logga in på ditt Azure konto för nyckellös autentisering med Microsoft Entra ID. Om du har flera prenumerationer väljer du den som innehåller din Azure AI-sökning tjänst.
```
az login
```

Kör koden

Install packages and set variables Kör cellerna för att installera de nödvändiga paketen och ladda de nödvändiga miljövariablerna.
Kör de återstående cellerna sekventiellt för att lägga till en semantisk konfiguration och fråga indexet.

Produktionen

Cellens Get the index definition utdata är namnet på indexet, dess fält och eventuella befintliga semantiska konfigurationer.

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

Cellens Add a semantic configuration to the index utdata visar alla semantiska konfigurationer i indexet, inklusive den som koden lade till, följt av ett meddelande om att det lyckades.

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!

Cellens Run a term query utdata returnerar alla matchande dokument ordnade efter BM25-poäng. Den här baslinjefrågan använder inte semantisk rangordning.

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

Cellens Run a semantic query utdata returnerar alla matchande dokument ordnade efter den semantiska re-rankerpoängen.

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

Cellens Return captions utdata lägger till ett undertextelement med träffmarkering tillsammans med sökfält. Bildtexter är de mest relevanta avsnitten i ett resultat. Om ditt index innehåller större text hjälper undertexter till att extrahera de mest intressanta meningarna.

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

Cellens Return semantic answers utdata innehåller ett semantiskt svar som hämtats från ett av de resultat som bäst matchar frågan, följt av sökresultat med bildtexter.

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

Förstå koden

Observera

Kodfragmenten i det här avsnittet kan ha ändrats för läsbarhet. Ett fullständigt arbetsexempel finns i källkoden.

Nu när du har kört koden ska vi gå igenom de viktigaste stegen:

Konfiguration och autentisering
Uppdatera indexet med en semantisk konfiguration
Fråga indexet

Konfiguration och autentisering

Cellen Install packages and set variables läser in miljövariabler och skapar en DefaultAzureCredential för autentisering.

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

Viktiga lärdomar:

DefaultAzureCredential tillhandahåller nyckellös autentisering med hjälp av Microsoft Entra ID. Den kedjar flera typer av autentiseringsuppgifter, inklusive Azure CLI autentiseringsuppgifter från az login.
Miljövariabler läses in från .env filen med hjälp av python-dotenv.

Uppdatera indexet med en semantisk konfiguration

Cellen Add a semantic configuration to the index lägger till en semantisk konfiguration i det befintliga hotels-sample indexet. Den här åtgärden tar inte bort några sökdokument och ditt index förblir i drift när konfigurationen har lagts till.

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)

Viktiga lärdomar:

En semantisk konfiguration anger de fält som används för semantisk rangordning. title_field anger dokumentrubriken, content_fields anger huvudinnehållet och keywords_fields anger nyckelords- eller taggfälten.
Du skapar konfigurationen med SemanticConfiguration och dess associerade SemanticPrioritizedFields modell och lägger sedan till den i det befintliga indexet.
create_or_update_index skickar det uppdaterade schemat till söktjänsten utan att återskapa indexet eller ta bort dokument.

Fråga indexet

Frågecellerna kör fyra frågor i följd: en nyckelordssökning i baslinjen följt av tre semantiska rankningsvariationer med ökande funktionalitet.

Termfråga (baslinje)

Cellen Run a term query kör en nyckelordssökning med BM25-bedömning. Den här baslinjefrågan använder inte semantisk rangordning och fungerar som en jämförelsepunkt.

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
)

Viktiga lärdomar:

query_type='simple' anger en nyckelordssökning med BM25-poäng.
I resultaten @search.score anger relevanspoängen för BM25.

Semantisk fråga (inga bildtexter, inga svar)

Cellen Run a semantic query visar minimikravet för att anropa semantisk rangordning.

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

Viktiga lärdomar:

query_type='semantic' aktiverar semantisk rangordning i frågan.
semantic_configuration_name anger vilken semantisk konfiguration som ska användas.
Resultatet @search.reranker_score indikerar semantisk relevans (högre är bättre).

Semantisk fråga med bildtexter

Cellen Return captions lägger till bildtexter för att extrahera de mest relevanta avsnitten från varje resultat, med träffmarkering som tillämpas på viktiga termer och fraser.

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

Viktiga lärdomar:

query_caption='extractive' aktiverar extraheringstexter från innehållsfälten.
Undertexter innehåller de mest relevanta avsnitten och lägger till  taggar runt viktiga termer.

Semantisk fråga med svar

Cellen Return semantic answers lägger till semantiska svar. Den här frågan använder en fråga som söktext eftersom semantiska svar fungerar bäst när frågan formuleras som en fråga. Svaret är en ordagrann passage som extraherats från ditt index, inte ett sammansatt svar från en modell för chattens slutförande.

Frågan och det indexerade innehållet måste vara nära justerade för att ett svar ska returneras. Om ingen kandidat uppfyller förtroendetröskeln innehåller svaret inget svar. I det här exemplet används en fråga som är känd för att generera ett resultat så att du kan se syntaxen. Om svaren inte är användbara för ditt scenario, utelämna query_answer från din kod. För sammansatta svar bör du överväga ett RAG-mönster eller agentisk hämtning.

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

Viktiga lärdomar:

query_answer="extractive" aktiverar extraheringssvar för frågeliknande frågor.
Svaren är ordagrant innehåll som extraheras från det specifika indexet, inte genererad text.
results.get_answers() hämtar svarsobjekten separat från sökresultaten.

I den här snabbstarten använder du klientbiblioteket Azure AI-sökning för JavaScript (kompatibel med TypeScript) för att lägga till semantisk rangordning till ett befintligt sökindex och köra frågor mot indexet.

Semantisk rangordning är en frågesidefunktionalitet som använder maskinläsningsförmåga för att återpoängsätta sökresultaten, vilket främjar de mest semantiskt relevanta matchningarna överst i listan. Du kan lägga till en semantisk konfiguration i ett befintligt index utan återskapandekrav. Semantisk rangordning är mest effektiv för informations- eller beskrivande text.

Tips

Vill du komma igång direkt? Ladda ned source-koden på GitHub.

Förutsättningar

Ett Azure konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
En Azure AI-sökning-tjänst.
Ett index med beskrivande textfält som tillskrivs searchable och retrievable. Den här snabbstarten förutsätter indexet hotels-sample.
Node.js 20 LTS eller senare för att köra den kompilerade koden.
TypeScript för att kompilera TypeScript till JavaScript.
Git för att klona exempellagringsplatsen.
Azure CLI för nyckellös autentisering med Microsoft Entra ID.

Konfigurera åtkomst

Innan du börjar kontrollerar du att du har behörighet att komma åt innehåll och åtgärder i Azure AI-sökning. Den här snabbstarten använder Microsoft Entra ID för autentisering och rollbaserad åtkomst för auktorisering. Du måste vara ägare eller administratör för användaråtkomst för att tilldela roller. Om roller inte är genomförbara använder du nyckelbaserad autentisering i stället.

Så här konfigurerar du den rekommenderade rollbaserade åtkomsten:

Aktivera rollbaserad åtkomst för söktjänsten.
Tilldela följande roller till ditt användarkonto.
- Söktjänstdeltagare
- Dataläsare för sökindex

Observera

Till skillnad från andra snabbstarter som skapar och läser in ett index förutsätter den här snabbstarten ett befintligt index som redan innehåller data, så du behöver inte rollen Search Index Data Contributor .

Hämta slutpunkt

Varje Azure AI-sökning-tjänst har en endpoint, vilket är en unik URL som identifierar och ger nätverksåtkomst till tjänsten. I ett senare avsnitt anger du den här slutpunkten för att ansluta till söktjänsten programmatiskt.

Så här får du slutpunkten:

Gå till söktjänsten i Azure-portalen.
Välj Översikt i den vänstra rutan.
Anteckna slutpunkten, som bör se ut som https://my-service.search.windows.net.

Börja med ett index

Den här snabbstarten ändrar ett befintligt index så att det innehåller en semantisk konfiguration. Vi rekommenderar indexet hotels-sample som du kan skapa på några minuter med hjälp av en Azure portalguide.

Om du vill använda ett annat index ersätter du indexnamnet, fältnamnen i den semantiska konfigurationen och fältnamnen i frågeinstruktioner select i exempelkoden. Ditt index bör innehålla beskrivande textfält som tillskrivs som searchable och retrievable.

För att granska och använda indexet hotels-sample före semantisk rangordning:

Gå till söktjänsten i Azure-portalen.
I den vänstra rutan väljer du Sökhanteringsindex>.
Välj hotellexempel.
Välj Semantiska konfigurationer för att visa befintliga konfigurationer. Om du har aktiverat semantisk rangordning under guidens skapandeflöde bör det finnas en standardkonfiguration.
Välj Sökutforskaren och välj sedan Visa>.

Klistra in följande JSON i frågeredigeraren.

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

Välj Sök för att köra frågan.

Svaret bör likna följande exempel. Det här är en fulltextfråga rangordnad efter BM25, så resultaten matchar enskilda frågetermer och språkvarianter snarare än frågans övergripande innebörd. Matchar till exempel walkingwalk, och live och music matchar oberoende i stället för som en fras.

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

Tips

Den här frågan visar hur svaret ser ut innan semantisk rangordning tillämpas. När du har konfigurerat en semantisk konfiguration lägger du till "queryType": "semantic" och "semanticConfiguration": "semantic-config" för att se hur samma fråga rangordnas annorlunda efter semantisk rangordning.

Konfigurera miljön

Använd Git för att klona exempellagringsplatsen.

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

Gå till snabbstartsmappen.

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

I sample.enversätter du platshållarvärdet för AZURE_SEARCH_ENDPOINT med den URL som du fick i Hämta slutpunkt.
Byt sample.env namn till .env.
```
mv sample.env .env
```
Installera beroendena.
```
npm install
```
När installationen är klar bör du se en node_modules mapp i projektkatalogen.
Kompilera TypeScript-filerna till JavaScript.
```
npm run build
```
Logga in på ditt Azure konto för nyckellös autentisering med Microsoft Entra ID. Om du har flera prenumerationer väljer du den som innehåller din Azure AI-sökning tjänst.
```
az login
```

Kör koden

Hämta de befintliga indexinställningarna.

node -r dotenv/config dist/getIndexSettings.js

Uppdatera indexet med en semantisk konfiguration.

node -r dotenv/config dist/updateIndexSettings.js

Kör en semantisk fråga.

node -r dotenv/config dist/semanticQuery.js

Kör en semantisk fråga med bildtexter.

node -r dotenv/config dist/semanticQueryReturnCaptions.js

Kör en semantisk fråga med svar.
```
node -r dotenv/config dist/semanticAnswer.js
```
Observera

Dessa kommandon kör de kompilerade .js filerna från dist mappen. TypeScript-kod måste överföras till JavaScript innan Node.js kan köra den, varför du tidigare körde npm run build.

Produktionen

Skriptet getIndexSettings.js returnerar indexnamn, antal fält, fältinformation med typ och sökbar status samt eventuella befintliga semantiska konfigurationer.

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

Skriptet updateIndexSettings.js returnerar alla semantiska konfigurationer, inklusive den du lade till.

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.

Skriptet semanticQuery.js returnerar resultat ordnade efter rerankerpoängen.

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

Skriptet semanticQueryReturnCaptions.js returnerar extraheringstexter med träffmarkering. Bildtexter är de mest relevanta avsnitten i ett resultat.

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

Skriptet semanticAnswer.js returnerar ett semantiskt svar (ordagrant innehåll) som hämtas från det resultat som bäst matchar frågan.

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

Förstå koden

Observera

Kodfragmenten i det här avsnittet kan ha ändrats för läsbarhet. Ett fullständigt arbetsexempel finns i källkoden.

Nu när du har kört koden ska vi gå igenom de viktigaste stegen:

Konfiguration och autentisering
Uppdatera indexet med en semantisk konfiguration
Fråga indexet

Konfiguration och autentisering

Filen config.ts läser in miljövariabler, skapar en DefaultAzureCredential för autentisering och definierar ett HotelDocument gränssnitt för typsäkerhet.

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

Viktiga lärdomar:

DefaultAzureCredential tillhandahåller nyckellös autentisering med hjälp av Microsoft Entra ID. Den kedjar flera typer av autentiseringsuppgifter, inklusive Azure CLI autentiseringsuppgifter från az login.
Gränssnittet HotelDocument ger kompileringstidstypkontroll för sökresultat, vilket säkerställer typsäker åtkomst till dokumentfält.
Miljövariabler läses in från .env filen med hjälp av dotenv.

Uppdatera indexet med en semantisk konfiguration

Filen updateIndexSettings.ts lägger till en semantisk konfiguration i det befintliga hotels-sample indexet. Den här åtgärden tar inte bort några sökdokument och ditt index förblir i drift när konfigurationen har lagts till. TypeScript-typanteckningar säkerställer att konfigurationen matchar det förväntade schemat.

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

Viktiga lärdomar:

TypeScript-typer som SemanticPrioritizedFields, SemanticConfigurationoch SemanticField tillhandahålla kompileringstidsverifiering för konfigurationsstrukturen.
titleField anger dokumentrubriken, contentFields anger huvudinnehållet och keywordsFields anger nyckelords- eller taggfälten.
createOrUpdateIndex skickar det uppdaterade schemat till söktjänsten utan att återskapa indexet eller ta bort dokument.

Fråga indexet

Frågeskripten kör tre frågor i följd och går från en grundläggande semantisk sökning till semantisk rangordning med bildtexter och svar.

Semantisk fråga (inga bildtexter, inga svar)

Skriptet semanticQuery.ts visar minimikravet för att anropa semantisk rangordning med typsäkra resultat.

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

Viktiga lärdomar:

SearchClient<HotelDocument> ger typsäker åtkomst till dokumentfält i resultat, med automatisk komplettering för fältnamn i select och result.document.
queryType: "semantic" aktiverar semantisk rangordning i frågan.
semanticSearchOptions.configurationName anger vilken semantisk konfiguration som ska användas.

Semantisk fråga med bildtexter

Skriptet semanticQueryReturnCaptions.ts lägger till bildtexter för att extrahera de mest relevanta avsnitten från varje resultat, med träffmarkeringar som tillämpas på viktiga termer och fraser.

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

Viktiga lärdomar:

captions.captionType: "extractive" aktiverar extraheringstexter från innehållsfälten.
Undertexter innehåller de mest relevanta avsnitten och lägger till  taggar runt viktiga termer.

Semantisk fråga med svar

Skriptet semanticAnswer.ts lägger till semantiska svar. Den använder en fråga som söktext eftersom semantiska svar fungerar bäst när frågan formuleras som en fråga. Svaret är en ordagrann passage som extraherats från ditt index, inte ett sammansatt svar från en modell för chattens slutförande.

Frågan och det indexerade innehållet måste vara nära justerade för att ett svar ska returneras. Om ingen kandidat uppfyller förtroendetröskeln innehåller svaret inget svar. I det här exemplet används en fråga som är känd för att generera ett resultat så att du kan se syntaxen. Om svaren inte är användbara för ditt scenario, utelämna answers från din kod. För sammansatta svar bör du överväga ett RAG-mönster eller agentisk hämtning.

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

Viktiga lärdomar:

answers.answerType: "extractive" aktiverar extraheringssvar för frågeliknande frågor.
Svaren är ordagrant innehåll som extraheras från det specifika indexet, inte genererad text.
results.answers hämtar svarsobjekten separat från sökresultaten.

I den här snabbstarten använder du Azure AI-sökning REST APIs för att lägga till semantisk rangordning till ett befintligt sökindex och köra frågor mot indexet.

Semantisk rangordning är en frågesidefunktionalitet som använder maskinläsningsförmåga för att återpoängsätta sökresultaten, vilket främjar de mest semantiskt relevanta matchningarna överst i listan. Du kan lägga till en semantisk konfiguration i ett befintligt index utan återskapandekrav. Semantisk rangordning är mest effektiv för informations- eller beskrivande text.

Tips

Vill du komma igång direkt? Ladda ned source-koden på GitHub.

Förutsättningar

Ett Azure konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
En Azure AI-sökning-tjänst.
Ett index med beskrivande textfält som tillskrivs searchable och retrievable. Den här snabbstarten förutsätter indexet hotels-sample.
Visual Studio Code med klienttillägget REST.
Git för att klona exempellagringsplatsen.
Azure CLI för nyckellös autentisering med Microsoft Entra ID.

Konfigurera åtkomst

Innan du börjar kontrollerar du att du har behörighet att komma åt innehåll och åtgärder i Azure AI-sökning. Den här snabbstarten använder Microsoft Entra ID för autentisering och rollbaserad åtkomst för auktorisering. Du måste vara ägare eller administratör för användaråtkomst för att tilldela roller. Om roller inte är genomförbara använder du nyckelbaserad autentisering i stället.

Så här konfigurerar du den rekommenderade rollbaserade åtkomsten:

Aktivera rollbaserad åtkomst för söktjänsten.
Tilldela följande roller till ditt användarkonto.
- Söktjänstdeltagare
- Dataläsare för sökindex

Observera

Till skillnad från andra snabbstarter som skapar och läser in ett index förutsätter den här snabbstarten ett befintligt index som redan innehåller data, så du behöver inte rollen Search Index Data Contributor .

Hämta slutpunkt

Varje Azure AI-sökning-tjänst har en endpoint, vilket är en unik URL som identifierar och ger nätverksåtkomst till tjänsten. I ett senare avsnitt anger du den här slutpunkten för att ansluta till söktjänsten programmatiskt.

Så här får du slutpunkten:

Gå till söktjänsten i Azure-portalen.
Välj Översikt i den vänstra rutan.
Anteckna slutpunkten, som bör se ut som https://my-service.search.windows.net.

Börja med ett index

Den här snabbstarten ändrar ett befintligt index så att det innehåller en semantisk konfiguration. Vi rekommenderar indexet hotels-sample som du kan skapa på några minuter med hjälp av en Azure portalguide.

Om du vill använda ett annat index ersätter du indexnamnet, fältnamnen i den semantiska konfigurationen och fältnamnen i frågeinstruktioner select i exempelkoden. Ditt index bör innehålla beskrivande textfält som tillskrivs som searchable och retrievable.

För att granska och använda indexet hotels-sample före semantisk rangordning:

Gå till söktjänsten i Azure-portalen.
I den vänstra rutan väljer du Sökhanteringsindex>.
Välj hotellexempel.
Välj Semantiska konfigurationer för att visa befintliga konfigurationer. Om du har aktiverat semantisk rangordning under guidens skapandeflöde bör det finnas en standardkonfiguration.
Välj Sökutforskaren och välj sedan Visa>.

Klistra in följande JSON i frågeredigeraren.

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

Välj Sök för att köra frågan.

Svaret bör likna följande exempel. Det här är en fulltextfråga rangordnad efter BM25, så resultaten matchar enskilda frågetermer och språkvarianter snarare än frågans övergripande innebörd. Matchar till exempel walkingwalk, och live och music matchar oberoende i stället för som en fras.

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

Tips

Den här frågan visar hur svaret ser ut innan semantisk rangordning tillämpas. När du har konfigurerat en semantisk konfiguration lägger du till "queryType": "semantic" och "semanticConfiguration": "semantic-config" för att se hur samma fråga rangordnas annorlunda efter semantisk rangordning.

Konfigurera miljön

Använd Git för att klona exempellagringsplatsen.

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

Gå till snabbstartsmappen och öppna den i Visual Studio Code.

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

I semantic-index-update.restersätter du platshållarvärdet för @searchUrl med den URL som du fick i Hämta slutpunkt.
Upprepa föregående steg för semantic-query.rest.
Logga in på ditt Azure konto för nyckellös autentisering med Microsoft Entra ID. Om du har flera prenumerationer väljer du den som innehåller din Azure AI-sökning tjänst.
```
az login
```

Generera en åtkomsttoken för nyckellös autentisering med Microsoft Entra ID.

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

I båda .rest filerna ersätter du platshållarvärdet för @personalAccessToken med token från föregående steg.

Kör koden

Öppna semantic-index-update.rest.
Välj Skicka begäran på den första GET-begäran för att verifiera anslutningen.

Ett svar bör visas i ett intilliggande fönster. Om du har befintliga index visas de med namn. Om HTTP-koden är 200 OKär du redo att fortsätta.
### Update the hotels-sample index to include a semantic configuration Skicka begäran om att lägga till en semantisk konfiguration i indexet.

Om du får ett 400 Bad Request fel skiljer sig indexschemat från exemplet. Skicka ### Get the schema of the index-begäran, kopiera svarets JSON, lägg till semantic-avsnittet från källkoden till JSON och ersätt PUT-begärandetexten med det sammanslagna schemat.
Växla till semantic-query.rest och skicka begäranden sekventiellt: en enkel fråga för baslinjejämförelse och sedan semantiska frågor med rangordning, bildtexter och svar.

Produktionen

Begäran Send a search query to the hotels-sample index returnerar resultat rangordnade efter BM25-relevans, vilket anges av fältet @search.score .

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

Begäran Send a search query to the hotels-sample index with semantic ranking lägger till @search.rerankerScore. Observera att ordningen ändras från den enkla frågan.

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

Return captions in the query-begäran lägger till @search.captions med extraherad text och markeringar.

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

Begäran Return semantic answers in the query returnerar ett extraheringssvar i @search.answers när frågan formuleras som en fråga.

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

Förstå koden

Observera

Kodfragmenten i det här avsnittet kan ha ändrats för läsbarhet. Ett fullständigt arbetsexempel finns i källkoden.

Nu när du har kört koden ska vi gå igenom de viktigaste stegen:

Konfiguration och autentisering
Uppdatera indexet med en semantisk konfiguration
Fråga indexet

Konfiguration och autentisering

Båda .rest filerna definierar variabler längst upp för återanvändning för alla begäranden.

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

Viktiga lärdomar:

@searchUrl är slutpunkten för söktjänsten.
@personalAccessToken är en Microsoft Entra ID token som hämtas från Azure CLI. Detta ersätter API-nycklar med nyckellös autentisering.
Authorization: Bearer {{personalAccessToken}} ingår i varje begärandehuvud för autentisering.

Uppdatera indexet med en semantisk konfiguration

Begäran ### Update the hotels-sample index to include a semantic configuration i semantic-index-update.rest skickar det fullständiga indexschemat tillsammans med ett nytt semantic avsnitt. REST-API:et kräver det fullständiga schemat för alla uppdateringsåtgärder, så du kan inte bara skicka den semantiska konfigurationen.

Nyckeltillägget är avsnittet semantic :

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

Viktiga lärdomar:

titleField identifierar vilket fält som innehåller dokumentrubriken för semantisk utvärdering.
prioritizedContentFields identifierar huvudinnehållsfälten. Semantisk ranker utvärderar dessa först vid bedömning av relevans.
prioritizedKeywordsFields identifierar nyckelords- eller taggfält för ytterligare kontext.
rankingOrder: BoostedRerankerScore kombinerar BM25-poängen med poängen från den semantiska omrankaren.
REST-API:et kräver det fullständiga schemat för PUT-åtgärder. Endast avsnittet semantic är nytt. Alla andra fält är oförändrade.

Fråga indexet

Begäranden semantic-query.rest utvecklas från en enkel nyckelordssökning till att rangordnas semantiskt med hjälp av bildtexter och svar. Alla frågor är POST-begäranden till Documents - Search Post (REST API).

Enkel fråga

Begäran ### Send a search query to the hotels-sample index är en enkel nyckelordssökning som inte använder semantisk rangordning. Den fungerar som baslinje för att jämföra resultat med och utan semantisk reranking.

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

Viktiga lärdomar:

queryType: "simple" använder BM25-standardrankningsalgoritmen.
Resultaten rangordnas endast efter nyckelordsrelevans (@search.score).

Semantisk fråga (inga bildtexter, inga svar)

Begäran ### Send a search query to the hotels-sample index with semantic ranking lägger till semantisk rangordning. Följande JSON visar minimikravet för att anropa semantisk rangordning.

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

Viktiga lärdomar:

queryType: "semantic" aktiverar semantisk rangordning i frågan.
semanticConfiguration anger vilken semantisk konfiguration som ska användas.

Semantisk fråga med bildtexter

Begäran ### Return captions in the query lägger till bildtexter för att extrahera de mest relevanta avsnitten från varje resultat, med träffmarkeringar som tillämpas på viktiga termer och fraser.

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

Viktiga lärdomar:

captions: "extractive|highlight-true" aktiverar extraheringstexter med  taggar runt viktiga termer.
Undertexter visas i matrisen @search.captions för varje resultat.

Semantisk fråga med svar

Begäran ### Return semantic answers in the query lägger till semantiska svar. Den använder en fråga som söktext eftersom semantiska svar fungerar bäst när frågan formuleras som en fråga. Svaret är en ordagrann passage som extraherats från ditt index, inte ett sammansatt svar från en modell för chattens slutförande.

Frågan och det indexerade innehållet måste vara nära justerade för att ett svar ska returneras. Om ingen kandidat uppfyller förtroendetröskeln innehåller svaret inget svar. I det här exemplet används en fråga som är känd för att generera ett resultat så att du kan se syntaxen. Om svaren inte är användbara för ditt scenario utelämnar du parametern answers från din begäran. För sammansatta svar bör du överväga ett RAG-mönster eller agentisk hämtning.

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

Viktiga lärdomar:

answers: "extractive" aktiverar extraheringssvar för frågeliknande frågor.
Svar visas i matrisen på den översta nivån @search.answers , separat från enskilda resultat.
Svaren är ordagrant innehåll som extraheras från det specifika indexet, inte genererad text.