refactor: upgrade AI search SDK and add doc for low cost deployment (#223)

* refactor: upgrade to latest AI Search SDK

* feat: allow disabling semantic search

* chore: clean up removed api

* docs: add doc for low cost deployment (closes #215)

* chore: increase timeout for windows

* chore: lint

* chore: remove extra timeout option for testing

* ci: try disabling autocrlf

Author: sinedied

.github/workflows/build-test.yaml

@@ -19,7 +19,7 @@ jobs:
     name: ${{ matrix.platform }} / Node.js v${{ matrix.node-version }}
     runs-on: ${{ matrix.platform }}
     steps:
-      - run: git config --global core.autocrlf false # Preserve line endings
+      # - run: git config --global core.autocrlf false # Preserve line endings
       - uses: actions/checkout@v4
       - name: Setup Node.js v${{ matrix.node-version }}
         uses: actions/setup-node@v4

README.md

@@ -27,6 +27,7 @@
   - [Resources](#resources)
   - [FAQ](#faq)
   - [Troubleshooting](#troubleshooting)
+  - [Reduce deployment costs](#reduce-deployment-costs)
 - [Note](#note)
 
 [![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&label=GitHub+Codespaces&message=Open&color=brightgreen&logo=github)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=684521881&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=WestUs2)
@@ -426,6 +427,10 @@ Here are the most common failure scenarios and solutions:
 
 1. You're getting an error `401 Principal does not have access to API/Operation` while running the project locally or trying to deploy. That's likely because your environment variables include `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` and `AZURE_CLIENT_SECRET`. You should either grant permissions to the related _Service Principal_ or remove these variables from your environment to ensure normal access. For more details, please refer to [Azure identity SDK](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#defaultazurecredential).
 
+### Reduce deployment costs
+
+See [this doc for reducing costs](./docs/low-cost.md).
+
 ### Note
 
 > Note: The documents used in this demo contain information generated using a language model (Azure OpenAI Service). The information contained in these documents is only for demonstration purposes and does not reflect the opinions or beliefs of Microsoft. Microsoft makes no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability or availability with respect to the information contained in this document. All rights reserved to Microsoft.

docs/low-cost.md

@@ -0,0 +1,31 @@
+# Reduce deployment costs
+
+This AI RAG chat application is designed to be easily deployed using the Azure Developer CLI, which provisions the infrastructure according to the Bicep files in the `infra` folder. Those files describe each of the Azure resources needed, and configures their SKU (pricing tier) and other parameters. Many Azure services offer a free tier, but the infrastructure files in this project do *not* default to the free tier as there are often limitations in that tier.
+
+However, if your goal is to minimize costs while prototyping your application, follow the steps below *before* running `azd up`. Once you've gone through these steps, return to the [deployment steps](../README.md#azure-deployment).
+
+1. Log in to your Azure account using the Azure Developer CLI:
+
+    ```shell
+    azd auth login
+    ```
+
+1. Create a new azd environment for the free resource group:
+
+    ```shell
+    azd env new
+    ```
+
+    Enter a name that will be used for the resource group.
+    This will create a new folder in the `.azure` folder, and set it as the active environment for any calls to `azd` going forward.
+
+1. Use the free tier of Azure AI Search:
+
+    ```shell
+    azd env set AZURE_SEARCH_SERVICE_SKU free
+    ```
+
+    Limitations:
+    1. You are only allowed one free search service across all regions.
+    2. The free tier does not support semantic ranker. Note that will generally result in [decreased search relevance](https://techcommunity.microsoft.com/blog/azure-ai-services-blog/azure-ai-search-outperforming-vector-search-with-hybrid-retrieval-and-ranking-ca/3929167).
+

infra/main.bicep

@@ -358,7 +358,7 @@ module searchService 'core/search/search-services.bicep' = {
     sku: {
       name: searchServiceSkuName
     }
-    semanticSearch: 'free'
+    semanticSearch: searchServiceSkuName == 'standard' ? 'free' : 'disabled'
   }
 }
 
@@ -526,6 +526,7 @@ output AZURE_OPENAI_EMBEDDING_MODEL string = embeddingModelName
 output AZURE_SEARCH_INDEX string = searchIndexName
 output AZURE_SEARCH_SERVICE string = searchService.outputs.name
 output AZURE_SEARCH_SERVICE_RESOURCE_GROUP string = searchServiceResourceGroup.name
+output AZURE_SEARCH_SEMANTIC_RANKER string = searchServiceSkuName == 'standard' ? 'enabled' : 'disabled'
 
 output AZURE_STORAGE_ACCOUNT string = storage.outputs.name
 output AZURE_STORAGE_CONTAINER string = storageContainerName

package-lock.json

@@ -26,7 +26,7 @@
     "@azure/core-http": "^3.0.5",
     "@azure/identity": "^4.0.1",
     "@azure/monitor-opentelemetry": "^1.0.0-beta.2",
-    "@azure/search-documents": "12.0.0-beta.3",
+    "@azure/search-documents": "^12.1.0",
     "@azure/storage-blob": "^12.15.0",
     "@dqbd/tiktoken": "^1.0.7",
     "@fastify/autoload": "^6.1.0",

packages/indexer/package.json

@@ -37,7 +37,7 @@ export class Indexer {
     this.blobStorage = new BlobStorage(logger, azure);
   }
 
-  async createSearchIndex(indexName: string) {
+  async createSearchIndex(indexName: string, useSemanticRanker = false) {
     this.logger.debug(`Ensuring search index "${indexName}" exists`);
 
     const searchIndexClient = this.azure.searchIndex;
@@ -52,6 +52,45 @@ export class Indexer {
     } else {
       const index: SearchIndex = {
         name: indexName,
+        vectorSearch: {
+          algorithms: [
+            {
+              name: 'vector-search-algorithm',
+              kind: 'hnsw',
+              parameters: {
+                m: 4,
+                efSearch: 500,
+                metric: 'cosine',
+                efConstruction: 400,
+              },
+            },
+          ],
+          profiles: [
+            {
+              name: 'vector-search-profile',
+              algorithmConfigurationName: 'vector-search-algorithm',
+            },
+          ],
+        },
+        ...(useSemanticRanker
+          ? {
+              semanticSearch: {
+                defaultConfigurationName: 'semantic-search-config',
+                configurations: [
+                  {
+                    name: 'semantic-search-config',
+                    prioritizedFields: {
+                      contentFields: [
+                        {
+                          name: 'content',
+                        },
+                      ],
+                    },
+                  },
+                ],
+              },
+            }
+          : {}),
         fields: [
           {
             name: 'id',
@@ -73,7 +112,7 @@ export class Indexer {
             sortable: false,
             facetable: false,
             vectorSearchDimensions: 1536,
-            vectorSearchConfiguration: 'default',
+            vectorSearchProfileName: 'vector-search-profile',
           },
           {
             name: 'category',
@@ -94,27 +133,6 @@ export class Indexer {
             facetable: true,
           },
         ],
-        semanticSettings: {
-          configurations: [
-            {
-              name: 'default',
-              prioritizedFields: {
-                prioritizedContentFields: [{ name: 'content' }],
-              },
-            },
-          ],
-        },
-        vectorSearch: {
-          algorithmConfigurations: [
-            {
-              name: 'default',
-              kind: 'hnsw',
-              parameters: {
-                metric: 'cosine',
-              },
-            },
-          ],
-        },
       };
       this.logger.debug(`Creating "${indexName}" search index...`);
       await searchIndexClient.createIndex(index);

packages/indexer/src/lib/indexer.ts

@@ -8,6 +8,7 @@ export interface AppConfig {
   azureStorageContainer: string;
   azureSearchService: string;
   azureSearchIndex: string;
+  azureSearchSemanticRanker: string;
   azureOpenAiService: string;
   azureOpenAiEmbeddingDeployment: string;
   azureOpenAiEmbeddingModel: string;
@@ -28,6 +29,7 @@ export default fp(
       azureStorageAccount: process.env.AZURE_STORAGE_ACCOUNT || '',
       azureStorageContainer: process.env.AZURE_STORAGE_CONTAINER || '',
       azureSearchService: process.env.AZURE_SEARCH_SERVICE || '',
+      azureSearchSemanticRanker: process.env.AZURE_SEARCH_SEMANTIC_RANKER || 'disabled',
       azureSearchIndex: process.env.AZURE_SEARCH_INDEX || '',
       azureOpenAiService: process.env.AZURE_OPENAI_SERVICE || '',
       azureOpenAiEmbeddingDeployment: process.env.AZURE_OPENAI_EMBEDDING_DEPLOYMENT || '',

packages/indexer/src/plugins/config.ts

@@ -33,7 +33,7 @@ const root: FastifyPluginAsyncJsonSchemaToTs = async (fastify, _options): Promis
     handler: async function (request, reply) {
       const { name } = request.body;
       try {
-        await fastify.indexer.createSearchIndex(name);
+        await fastify.indexer.createSearchIndex(name, fastify.config.azureSearchSemanticRanker !== 'enabled');
         reply.code(204);
       } catch (_error: unknown) {
         const error = _error as Error;

packages/indexer/src/routes/indexes/index.ts

@@ -24,6 +24,7 @@ async function config() {
   process.env.AZURE_SEARCH_SERVICE = 'https://example.com';
   process.env.AZURE_STORAGE_ACCOUNT = 'dummystorage';
   process.env.AZURE_STORAGE_CONTAINER = 'testfiles';
+
   return {};
 }