Merge pull request #78 from diberry/diberry/0709-semantic-reranker-2

Fixes for semantic ranker

Author: HeidiSteen

quickstart-semantic-ranking-js/README.md

@@ -27,8 +27,9 @@ Semantic ranking uses machine reading comprehension from Microsoft to rescore se
    - Copy `sample.env` to `.env`
    - Update the values with your Azure AI Search service details:
      ```
-     SEARCH_ENDPOINT=https://your-service-name.search.windows.net
+     AZURE_SEARCH_ENDPOINT=https://your-service-name.search.windows.net
      INDEX_NAME=hotels-sample-index
+     AZURE_SEARCH_API_KEY=your-api-key
      ```
 
 4. **Get your search service endpoint and API key**

quickstart-semantic-ranking-js/sample.env

@@ -1,5 +1,5 @@
 # Azure AI Search Service Configuration
-SEARCH_ENDPOINT=PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
-INDEX_NAME=hotels-sample-index
+AZURE_SEARCH_ENDPOINT=PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
+AZURE_SEARCH_INDEX_NAME=hotels-sample-index
 SEMANTIC_CONFIGURATION_NAME=semantic-config
 

quickstart-semantic-ranking-js/src/config.js

@@ -5,8 +5,8 @@ import { DefaultAzureCredential } from "@azure/identity";
 
 // Configuration - use environment variables
 export const searchEndpoint = process.env.AZURE_SEARCH_ENDPOINT || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
-export const searchApiKey = process.env.AZURE_SEARCH_API_KEY || "PUT-YOUR-SEARCH-SERVICE-ADMIN-API-KEY-HERE";
 export const indexName = process.env.AZURE_SEARCH_INDEX_NAME || "hotels-sample-index";
+export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";
 
 // Create credential
 export const credential = new DefaultAzureCredential();

quickstart-semantic-ranking-js/src/getIndexSettings.js

@@ -23,4 +23,6 @@ if(index.semanticSearch && index.semanticSearch.configurations) {
         console.log(`Configuration name: ${config.name}`);
         console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
     }
+} else {
+    console.log("No semantic configuration exists for this index.");
 }

quickstart-semantic-ranking-js/src/semanticAnswer.js

@@ -1,18 +1,16 @@
 import { SearchClient } from "@azure/search-documents";
-import { credential, searchEndpoint, indexName } from "./config.js";
+import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";
 
 const searchClient = new SearchClient(
     searchEndpoint,
     indexName,
     credential
 );
 
-const configurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";
-
 const results = await searchClient.search("walking distance to live music", {
     queryType: "semantic",
     semanticSearchOptions: {
-        configurationName: configurationName,
+        configurationName: semanticConfigurationName,
         captions: {
             captionType: "extractive"
         },

quickstart-semantic-ranking-js/src/semanticQuery.js

@@ -1,18 +1,16 @@
 import { SearchClient } from "@azure/search-documents";
-import { credential, searchEndpoint, indexName } from "./config.js";
+import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";
 
 const searchClient = new SearchClient(
     searchEndpoint,
     indexName,
     credential
 );
 
-const configurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";
-
 const results = await searchClient.search("walking distance to live music", {
     queryType: "semantic",
     semanticSearchOptions: {
-        configurationName: configurationName
+        configurationName: semanticConfigurationName
     },
     select: ["HotelId", "HotelName", "Description"]
 });

quickstart-semantic-ranking-js/src/semanticQueryReturnCaptions.js

@@ -1,22 +1,19 @@
 import { SearchClient } from "@azure/search-documents";
-import { credential, searchEndpoint, indexName } from "./config.js";
+import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";
 
 const searchClient = new SearchClient(
     searchEndpoint,
     indexName,
     credential
 );
 
-const configurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";
-
-// Debug info
-console.log(`Using semantic configuration: ${configurationName}`);
+console.log(`Using semantic configuration: ${semanticConfigurationName}`);
 console.log("Search query: walking distance to live music");
 
 const results = await searchClient.search("walking distance to live music", {
     queryType: "semantic",
     semanticSearchOptions: {
-        configurationName: configurationName,
+        configurationName: semanticConfigurationName,
         captions: {
             captionType: "extractive",
             highlight: true

quickstart-semantic-ranking-js/src/updateIndexSettings.js

@@ -1,10 +1,9 @@
 import {
     SearchIndexClient
 } from "@azure/search-documents";
-import { searchEndpoint, indexName, credential } from "./config.js";
+import { searchEndpoint, indexName, credential, semanticConfigurationName } from "./config.js";
 
 try {
-    const configurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";
 
     const indexClient = new SearchIndexClient(searchEndpoint, credential);
 
@@ -23,7 +22,7 @@ try {
     };
 
     const newSemanticConfiguration = {
-        name: configurationName,
+        name: semanticConfigurationName,
         prioritizedFields: fields
     };
 
@@ -32,7 +31,7 @@ try {
         existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
     } else {
         const configExists = existingIndex.semanticSearch?.configurations?.some(
-            config => config.name === configurationName
+            config => config.name === semanticConfigurationName
         );
         if (!configExists) {
             existingIndex.semanticSearch = {

quickstart-semantic-ranking-ts/README.md

@@ -1,8 +1,8 @@
 # Azure AI Search Semantic Ranking Quickstart - TypeScript
 
-This TypeScript sample demonstrates how to use semantic ranking in Azure AI Search to improve search relevance using machine reading comprehension. This is a TypeScript port of the [quickstart](https://learn.microsoft.com/azure/search/search-get-started-semantic).
+This TypeScript sample demonstrates how to use semantic ranking in Azure AI Search to improve search relevance using machine reading comprehension. This is a TypeScript version of the [quickstart](https://learn.microsoft.com/azure/search/search-get-started-semantic).
 
-The sample has been factored into a modular structure, similar to the vector search quickstart, with separate files for different operations.
+The sample has been factored into a modular structure, with separate files for different operations.
 
 ## What is Semantic Ranking?
 
@@ -30,6 +30,7 @@ Semantic ranking uses machine reading comprehension from Microsoft to rescore se
      ```
      SEARCH_ENDPOINT=https://your-service-name.search.windows.net
      INDEX_NAME=hotels-sample-index
+     AZURE_SEARCH_API_KEY=your-api-key
      ```
 
 4. **Get your search service endpoint and API key**
@@ -40,220 +41,27 @@ Semantic ranking uses machine reading comprehension from Microsoft to rescore se
 
 ## Run the Sample
 
-### Run Complete Quickstart
+### Getting Index Settings
 ```bash
-# Build and run the complete quickstart
-npm run dev
-
-# Or separately:
-npm run build
-npm run start
+npm run get-index-settings
 ```
 
-### Run Individual Operations
-You can also run individual operations separately:
-
+### Updating Index Settings for Semantic Search
 ```bash
-# Create the search index with semantic configuration
-npm run create-index
-
-# Upload sample documents
-npm run upload-docs
-
-# Run BM25 text search
-npm run search-bm25
-
-# Run semantic search with reranking
-npm run search-semantic
-
-# Run semantic search with answers
-npm run search-answers
-
-# Delete the index (useful for testing)
-npm run delete-index
-```
-
-## What This Sample Does
-
-The quickstart demonstrates the key steps for implementing semantic ranking:
-
-1. **Creates a search index** with semantic configuration
-   - Defines fields for hotel data (HotelName, Description, Category, etc.)
-   - Sets up semantic configuration specifying:
-     - **Title field**: HotelName (most important for ranking)
-     - **Content fields**: Description (main content to analyze)  
-     - **Keywords fields**: Category (additional context)
-
-2. **Uploads sample documents** containing hotel information with varied descriptions
-
-3. **Runs different types of queries** to show the difference:
-   - **Empty query**: Verifies the index is operational
-   - **Text query with BM25**: Traditional keyword-based scoring
-   - **Semantic query**: AI-powered reranking with captions
-   - **Semantic answers**: Direct answer extraction from content
-
-## Key Features Demonstrated
-
-### Semantic Configuration
-Shows how to configure semantic search with prioritized fields:
-- **Title field**: The most important field for semantic ranking
-- **Content fields**: Fields containing the main content to be analyzed
-- **Keywords fields**: Fields providing additional context
-
-### Query Comparison
-- **BM25 scoring**: Traditional keyword matching with frequency-based relevance
-- **Semantic reranking**: AI understanding of context and meaning
-- **Reranker scores**: Higher scores indicate better semantic relevance to the query
-
-### Enhanced Results
-- **Semantic Captions**: Automatically extracted relevant snippets with highlighting
-- **Semantic Answers**: Direct responses to question-like queries when confidence is high
-
-## Understanding the Results
-
-When you run the sample, you'll see different results for the same query "restaurant on site":
-
-**BM25 Results**: May prioritize documents that simply contain the words "restaurant" and "site"
-
-**Semantic Results**: Will understand the intent and rank hotels that actually have dining facilities higher, even if they don't use the exact words
-
-## Example Output
-
-```
-=== Running text query (BM25 scoring) ===
-BM25-scored results:
-Score: 1.23
-Hotel: Sublime Palace Hotel
-Description: ...historic center...sites and landmarks...
-
-=== Running semantic query ===
-Semantic-ranked results:
-Reranker Score: 2.45
-Hotel: Gastronomic Landscape Hotel
-Description: The Gastronomic Hotel stands out for its culinary excellence...
-Caption: culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services
+npm run update-index-settings
 ```
 
-## Project Structure
-
-The sample has been refactored into a modular structure for better maintainability and reusability:
-
-```
-quickstart-semantic-ranking-ts/
-├── src/
-│   ├── config.ts                    # Configuration and type definitions
-│   ├── createIndex.ts               # Index creation with semantic configuration
-│   ├── uploadDocuments.ts           # Document upload functionality  
-│   ├── searchBM25.ts               # BM25 text search queries
-│   ├── searchSemantic.ts           # Semantic search with reranking
-│   ├── searchSemanticAnswer.ts     # Semantic search with answers
-│   ├── main.ts                     # Main orchestration script
-│   └── semantic-ranking-quickstart.ts  # Original monolithic version (for reference)
-├── dist/                           # Compiled JavaScript (generated)
-├── package.json                    # Node.js dependencies and scripts  
-├── tsconfig.json                   # TypeScript configuration
-├── sample.env                      # Environment variables template
-└── README.md                      # This file
-```
-
-## Modular Code Overview
-
-### Configuration (`config.ts`)
-- Centralizes environment variables and credentials
-- Exports the `HotelDocument` interface for type safety
-- Provides reusable configuration for all modules
-
-### Index Creation (`createIndex.ts`)
-- Creates the search index with semantic configuration
-- Defines field mappings and analyzers
-- Sets up semantic prioritized fields (title, content, keywords)
-
-### Document Upload (`uploadDocuments.ts`)
-- Uploads sample hotel documents to the index
-- Handles batch upload operations with error handling
-
-### Search Operations
-- **`searchBM25.ts`**: Traditional keyword-based search with BM25 scoring
-- **`searchSemantic.ts`**: Semantic search with AI-powered reranking and captions  
-- **`searchSemanticAnswer.ts`**: Semantic search with direct answer extraction
-
-### Main Orchestrator (`main.ts`)
-- Coordinates all operations in the correct sequence
-- Provides validation and error handling
-- Can be used as the primary entry point
-
-## Benefits of the Modular Structure
-
-This refactored structure provides several advantages:
-
-- **Modularity**: Each file has a single responsibility and can be used independently
-- **Reusability**: Individual operations can be imported and used in other projects
-- **Testability**: Each module can be tested in isolation
-- **Maintainability**: Changes to one operation don't affect others
-- **Educational**: Easier to understand each concept separately
-- **Flexibility**: Run only the operations you need during development
-
-## Semantic Configuration Details
-
-```typescript
-const semanticConfig = {
-    name: "semantic-config", 
-    prioritizedFields: {
-        titleField: { name: "HotelName" },        // Primary ranking field
-        contentFields: [{ name: "Description" }], // Main content for analysis  
-        keywordsFields: [{ name: "Category" }]    // Additional context
-    }
-};
+### Run Semantic Queries
+```bash
+npm run get-semantic-query
 ```
 
-## Learn More
-
-- [Azure AI Search Semantic Ranking Documentation](https://learn.microsoft.com/azure/search/semantic-search-overview)
-- [Original Python Quickstart](https://learn.microsoft.com/azure/search/search-get-started-semantic)
-- [Azure SDK for JavaScript Documentation](https://docs.microsoft.com/javascript/api/@azure/search-documents/)
-- [Semantic Search Best Practices](https://learn.microsoft.com/azure/search/semantic-how-to-query-request)
-
-## Troubleshooting
-
-- **Service Requirements**: Ensure your search service has semantic ranker enabled (Basic tier or higher)
-- **Configuration**: Verify your endpoint URL and API key are correct
-- **Index Conflicts**: Check that the index name doesn't conflict with existing indexes  
-- **SDK Version**: Make sure you have the latest version of the Azure Search Documents SDK
-- **Field Configuration**: Ensure your semantic configuration references existing searchable fields
-
-## Clean Up
-
-The sample creates an index named "hotels-quickstart" by default. You can delete it easily:
-
+### Get Captions with Results
 ```bash
-npm run delete-index
+npm run get-captions
 ```
 
-Or programmatically:
-```typescript
-await indexClient.deleteIndex(indexName);
+### Get Semantic Answers
+```bash
+npm run get-answers
 ```
-
-## Migration from Original Structure
-
-This sample has been refactored from a single-file structure to a modular one:
-
-**Before** (Single File):
-- `semantic-ranking-quickstart.ts` - All functionality in one file
-
-**After** (Modular Structure):
-- `config.ts` - Configuration and types
-- `createIndex.ts` - Index creation  
-- `uploadDocuments.ts` - Document upload
-- `searchBM25.ts` - BM25 search operations
-- `searchSemantic.ts` - Semantic search
-- `searchSemanticAnswer.ts` - Semantic answers
-- `main.ts` - Orchestration script
-- `deleteIndex.ts` - Cleanup utility
-
-The original single-file version is preserved as `semantic-ranking-quickstart.ts` for reference.
-
-## Related Samples
-
-- [Vector Search Quickstart](../quickstart-vector-ts/) - Learn about vector search capabilities
-- [RAG with TypeScript](../quickstart-rag-ts/) - Retrieval Augmented Generation patterns

quickstart-semantic-ranking-ts/sample.env

@@ -1,4 +1,4 @@
 # Azure AI Search Service Configuration
-SEARCH_ENDPOINT=PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
-INDEX_NAME=hotels-sample-index
-SEMANTIC_CONFIGURATION_NAME=semantic-config
+AZURE_SEARCH_ENDPOINT=PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
+AZURE_SEARCH_INDEX_NAME=hotels-sample-index
+SEMANTIC_CONFIGURATION_NAME=semantic-config