openai-embeddings: matches style and flow with chatbot-rag-app (#373)

Signed-off-by: Adrian Cole <[email protected]>

Author: codefromthecrypt

example-apps/openai-embeddings/.npmrc

@@ -0,0 +1 @@
+package-lock=false

example-apps/openai-embeddings/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:22-alpine
+
+ENV NODE_ENV production
+WORKDIR /usr/src/app
+COPY . .
+RUN --mount=type=cache,target=/root/.npm \
+    npm install --omit=dev
+USER node
+EXPOSE 3000
+
+ENTRYPOINT ["npm", "run"]
+CMD ["app"]

example-apps/openai-embeddings/README.md

@@ -1,130 +1,130 @@
 # OpenAI embeddings example application
 
-## Overview
+This is a small example Node.js/Express application that demonstrates how to
+integrate Elastic and OpenAI.
 
-Small example Node.js/Express.js application to demonstrate how to integrate Elastic and OpenAI.
+The application has two components:
+* [generate](generate_embeddings.js)
+  * Generates embeddings for [sample_data](sample_data/medicare.json) into
+    Elasticsearch.
+* [app](search_app.js)
+  * Runs the web service which hosts the [web frontend](views) and the
+    search API.
+* Both scripts use the [Elasticsearch](https://github.com/elastic/elasticsearch-js) and [OpenAI](https://github.com/openai/openai-node) JavaScript clients.
 
-This folder includes two files:
+![Screenshot of the sample app](./app-demo.png)
 
-- `generate_embeddings.js`: Processes a JSON file, generates text embeddings for each document in the file using OpenAI's API, and then stores the documents and their corresponding embeddings in an Elasticsearch index.
-- `search_app.js`: A tiny Express.js web app that renders a search bar, generates embeddings for search queries, and performs semantic search using Elasticsearch's [kNN search](https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html). It retrieves the search results and returns a list of hits, ranked by relevance.
+## Download the Project
 
-Both scripts use the [Elasticsearch](https://github.com/elastic/elasticsearch-js) and [OpenAI](https://github.com/openai/openai-node) JavaScript clients.
+Download the project from Github and extract the `openai-embeddings` folder.
+
+```bash
+curl https://codeload.github.com/elastic/elasticsearch-labs/tar.gz/main | \
+tar -xz --strip=2 elasticsearch-labs-main/example-apps/openai-embeddings
+```
 
-## Requirements
+## Make your .env file
 
-- Node.js 16+
+Copy [env.example](env.example) to `.env` and fill in values noted inside.
 
-## Setup
+## Installing and connecting to Elasticsearch
 
-This section will walk you through the steps for setting up and using the application from scratch.
-(Skip the first steps if you already have an Elastic deployment and OpenAI account/API key.)
+There are a number of ways to install Elasticsearch. Cloud is best for most
+use-cases. Visit the [Install Elasticsearch](https://www.elastic.co/search-labs/tutorials/install-elasticsearch) for more information.
 
-### 1. Download the Project
+Once you decided your approach, edit your `.env` file accordingly.
 
-Download the project from Github and extract the `openai-embeddings` folder.
+### Running your own Elastic Stack with Docker
+
+If you'd like to start Elastic locally, you can use the provided
+[docker-compose-elastic.yml](docker-compose-elastic.yml) file. This starts
+Elasticsearch, Kibana, and APM Server and only requires Docker installed.
+
+Use docker compose to run Elastic stack in the background:
 
 ```bash
-curl https://codeload.github.com/elastic/elasticsearch-labs/tar.gz/main | \
-tar -xz --strip=2 elasticsearch-labs-main/example-apps/openai-embeddings
+docker compose -f docker-compose-elastic.yml up --force-recreate -d
 ```
 
-### 2. Create OpenAI account and API key
+Then, you can view Kibana at http://localhost:5601/app/home#/
 
-- Go to https://platform.openai.com/ and sign up
-- Generate an API key and make note of it
+If asked for a username and password, use username: elastic and password: elastic.
 
-![OpenAI API key](images/openai_api_key.png)
+Clean up when finished, like this:
 
-### 3. Create Elastic Cloud account and credentials
+```bash
+docker compose -f docker-compose-elastic.yml down
+```
 
-- [Sign up](https://cloud.elastic.co/registration?onboarding_token=vectorsearch&utm_source=github&utm_content=elasticsearch-labs-samples) for a Elastic cloud account
-- Make note of the master username/password shown to you during creation of the deployment
-- Make note of the Elastic Cloud ID after the deployment
+## Running the App
 
-![Elastic Cloud credentials](images/elastic_credentials.png)
+There are two ways to run the app: via Docker or locally. Docker is advised for
+ease while locally is advised if you are making changes to the application.
 
-![Elastic Cloud ID](images/elastic_cloud_id.png)
+### Run with docker
 
-### 4. Install Node dependencies
+Docker compose is the easiest way, as you get one-step to:
+* generate embeddings and store them into Elasticsearch
+* run the app, which listens on http://localhost:3000
 
-```sh
-npm install
+**Double-check you have a `.env` file with all your variables set first!**
+
+```bash
+docker compose up --build --force-recreate
 ```
 
-### 5. Set environment variables
+Clean up when finished, like this:
 
-```sh
-export ELASTIC_CLOUD_ID=<your Elastic cloud ID>
-export ELASTIC_USERNAME=<your Elastic username>
-export ELASTIC_PASSWORD=<your Elastic password>
-export OPENAI_API_KEY=<your OpenAI API key>
+```bash
+docker compose down
 ```
 
-### 6. Generate embeddings and index documents
+### Run locally
 
-```sh
-npm run generate
+First, set up a Node.js environment for the example like this:
 
-Connecting to Elastic Cloud: my-openai-integration-test:dXMt(...)
-(node:95956) ExperimentalWarning: stream/web is an experimental feature. This feature could change at any time
-(Use `node --trace-warnings ...` to show where the warning was created)
-Reading from file sample_data/medicare.json
-Processing 12 documents...
-Processing batch of 10 documents...
-Calling OpenAI API for 10 embeddings with model text-embedding-ada-002
-Indexing 10 documents to index openai-integration...
-Processing batch of 2 documents...
-Calling OpenAI API for 2 embeddings with model text-embedding-ada-002
-Indexing 2 documents to index openai-integration...
-Processing complete
+```bash
+nvm use --lts  # or similar to setup Node.js v20 or later
+npm install
 ```
 
-_**Note**: the example application uses the `text-embedding-ada-002` OpenAI model for generating the embeddings, which provides a 1536-dimensional vector output. See [this section](#using-a-different-openai-model) if you want to use a different model._
-
-### 7. Launch web app
+**Double-check you have a `.env` file with all your variables set first!**
 
-```sh
-npm run app
+#### Run the generate command
 
-Connecting to Elastic Cloud: my-openai-integration-test:dXMt(...)
-(node:96017) ExperimentalWarning: stream/web is an experimental feature. This feature could change at any time
-(Use `node --trace-warnings ...` to show where the warning was created)
-Express app listening on port 3000
+First, ingest the data into elasticsearch:
+```bash
+npm run generate
 ```
 
-### 8. Run semantic search in the web app
-
-- Open http://localhost:3000 in your browser
-- Enter a search query and press Search
+#### Run the app
 
-![Search example](images/search.png)
+Now, run the app, which listens on http://localhost:3000
+```bash
+npm run app
+```
 
-## Customize configuration
+## Advanced
 
-Here are some tips for modifying the code for your use case. For example, you might want to use your own sample data.
+Here are some tips for modifying the code for your use case. For example, you
+might want to use your own sample data.
 
 ### Using a different source file or document mapping
 
 - Ensure your file contains the documents in JSON format
-- Modify the document mappings and fields in the `.js` files and in `views/search.hbs`
-- Modify the initialization of `FILE` in `utils.js`
+- Modify the document mappings and fields in the `.js` files and in [views/search.hbs](views/search.hbs)
+- Modify the initialization of `FILE` in [utils.js](utils.js)
 
 ### Using a different OpenAI model
 
-- Modify the initialization of `MODEL` in `utils.js`
-- Ensure that `embedding.dims` in your index mapping is the same number as the dimensions of the model's output
+- Modify `EMBEDDINGS_MODEL` in `.env`
+- Ensure that `embedding.dims` in your index mapping is the same number as the dimensions of the model's output.
 
 ### Using a different Elastic index
 
-- Modify the initialization of `INDEX` in `utils.js`
-
-### Using a different method for authenticating with Elastic
-
-- Modify the initialization of `elasticsearchClient` in `utils.js`
-- Refer to [this document](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-connecting.html#authentication) about authentication schemes
+- Modify the initialization of `INDEX` in [utils.js](utils.js)
 
-### Running on self-managed Elastic cluster
+### Using a different method to connect to Elastic
 
-- Modify the initialization of `elasticsearchClient` in `utils.js`
-- Refer to [this document](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-connecting.html#connect-self-managed-new) about connecting to a self-managed cluster
+- Modify the initialization of `elasticsearchClient` in [utils.js](utils.js)
+- Refer to [this document](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-connecting.html)

example-apps/openai-embeddings/images/search.png renamed to example-apps/openai-embeddings/app-demo.png

@@ -0,0 +1,91 @@
+name: elastic-stack
+
+services:
+  elasticsearch:
+    image: docker.elastic.co/elasticsearch/elasticsearch:8.17.0
+    container_name: elasticsearch
+    ports:
+      - 9200:9200
+    environment:
+      - node.name=elasticsearch
+      - cluster.name=docker-cluster
+      - discovery.type=single-node
+      - ELASTIC_PASSWORD=elastic
+      - bootstrap.memory_lock=true
+      - xpack.security.enabled=true
+      - xpack.security.http.ssl.enabled=false
+      - xpack.security.transport.ssl.enabled=false
+      - xpack.license.self_generated.type=trial
+      - ES_JAVA_OPTS=-Xmx8g
+    ulimits:
+      memlock:
+        soft: -1
+        hard: -1
+    healthcheck:
+      test: ["CMD-SHELL", "curl -s http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=500ms"]
+      retries: 300
+      interval: 1s
+
+  elasticsearch_settings:
+    depends_on:
+      elasticsearch:
+        condition: service_healthy
+    image: docker.elastic.co/elasticsearch/elasticsearch:8.17.0
+    container_name: elasticsearch_settings
+    restart: 'no'
+    command: >
+      bash -c '        
+        # gen-ai assistants in kibana save state in a way that requires security to be enabled, so we need to create
+        # a kibana system user before starting it.
+        echo "Setup the kibana_system password";
+        until curl -s -u "elastic:elastic" -X POST http://elasticsearch:9200/_security/user/kibana_system/_password -d "{\"password\":\"elastic\"}" -H "Content-Type: application/json" | grep -q "^{}"; do sleep 5; done;
+      '
+
+  kibana:
+    image: docker.elastic.co/kibana/kibana:8.17.0
+    container_name: kibana
+    depends_on:
+      elasticsearch_settings:
+        condition: service_completed_successfully
+    ports:
+      - 5601:5601
+    environment:
+      - SERVERNAME=kibana
+      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
+      - ELASTICSEARCH_USERNAME=kibana_system
+      - ELASTICSEARCH_PASSWORD=elastic
+      # Non-default settings from here:
+      # https://github.com/elastic/apm-server/blob/main/testing/docker/kibana/kibana.yml
+      - MONITORING_UI_CONTAINER_ELASTICSEARCH_ENABLED=true
+      - XPACK_SECURITY_ENCRYPTIONKEY=fhjskloppd678ehkdfdlliverpoolfcr
+      - XPACK_ENCRYPTEDSAVEDOBJECTS_ENCRYPTIONKEY=fhjskloppd678ehkdfdlliverpoolfcr
+      - SERVER_PUBLICBASEURL=http://127.0.0.1:5601
+    healthcheck:
+      test: ["CMD-SHELL", "curl -s http://localhost:5601/api/status | grep -q 'All services are available'"]
+      retries: 300
+      interval: 1s
+
+  apm-server:
+    image: docker.elastic.co/apm/apm-server:8.17.0
+    container_name: apm-server
+    depends_on:
+      elasticsearch:
+        condition: service_healthy
+    command: >
+      apm-server
+        -E apm-server.kibana.enabled=true
+        -E apm-server.kibana.host=http://kibana:5601
+        -E apm-server.kibana.username=elastic
+        -E apm-server.kibana.password=elastic
+        -E output.elasticsearch.hosts=["http://elasticsearch:9200"]
+        -E output.elasticsearch.username=elastic
+        -E output.elasticsearch.password=elastic
+    cap_add: ["CHOWN", "DAC_OVERRIDE", "SETGID", "SETUID"]
+    cap_drop: ["ALL"]
+    ports:
+      - 8200:8200
+    healthcheck:
+      test: ["CMD-SHELL", "bash -c 'echo -n > /dev/tcp/127.0.0.1/8200'"]
+      retries: 300
+      interval: 1s
+

example-apps/openai-embeddings/docker-compose-elastic.yml

@@ -0,0 +1,33 @@
+name: chatbot-rag-app
+
+services:
+  generate:
+    build:
+      context: .
+    container_name: generate
+    restart: 'no'
+    environment:
+      # host.docker.internal means connect to the host machine, e.g. your laptop
+      ELASTICSEARCH_URL: "http://host.docker.internal:9200"
+    env_file:
+      - .env
+    command: generate
+    extra_hosts:
+        - "host.docker.internal:host-gateway"
+
+  app:
+    depends_on:
+      generate:
+        condition: service_completed_successfully
+    container_name: api-frontend
+    build:
+      context: .
+    environment:
+      # host.docker.internal means connect to the host machine, e.g. your laptop
+      ELASTICSEARCH_URL: "http://host.docker.internal:9200"
+    env_file:
+      - .env
+    ports:
+      - "3000:3000"
+    extra_hosts:
+        - "host.docker.internal:host-gateway"

example-apps/openai-embeddings/docker-compose.yml

@@ -0,0 +1,16 @@
+# Make a copy of this file with the name .env and assign values to variables
+
+# How you connect to Elasticsearch: change details to your instance
+ELASTICSEARCH_URL=http://localhost:9200
+ELASTICSEARCH_USER=elastic
+ELASTICSEARCH_PASSWORD=elastic
+# ELASTICSEARCH_API_KEY=
+
+# Update this with your real OpenAI API key
+OPENAI_API_KEY=
+# EMBEDDINGS_MODEL=text-embedding-ada-002
+
+# Uncomment to use Ollama instead of OpenAI
+# OPENAI_BASE_URL=http://localhost:11434/v1
+# OPENAI_API_KEY=unused
+# EMBEDDINGS_MODEL=all-minilm:33m