[lightspeed-docs-1.0] LCORE-38: document BYOK

configure/ols-configuring-openshift-lightspeed.adoc

@@ -25,4 +25,6 @@ include::modules/ols-granting-access-to-individual-users.adoc[leveloffset=+2]
 include::modules/ols-granting-access-to-user-group.adoc[leveloffset=+2]
 include::modules/ols-filtering-and-redacting-information.adoc[leveloffset=+1]
 include::modules/ols-cluster-interaction-overview.adoc[leveloffset=+1]
-include::modules/ols-enabling-cluster-interaction.adoc[leveloffset=+2]
+include::modules/ols-enabling-cluster-interaction.adoc[leveloffset=+2]
+include::modules/ols-about-the-byo-knowledge-tool.adoc[leveloffset=+1]
+include::modules/ols-providing-custom-knowledge-to-the-llm.adoc[leveloffset=+2]

modules/ols-about-the-byo-knowledge-tool.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+// * lightspeed-docs-main/configure/ols-configuring-openshift-lightspeed.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="about-the-byo-knowledge-tool_{context}"]
+= About the BYO Knowledge tool
+
+The {ols-long} service uses a large language model (LLM) to generate responses to questions. You can enhance the knowledge that is available to the LLM by using the BYO Knowledge tool to create a retrieval-augmented generation (RAG) database. 
+
+When you create a RAG database, you customize the {ols-long} service for your environment. For example, a network administrator can develop a standard operating procedure (SOP) that is used to provision an {ocp-product-title} cluster. Then, the network administrator can use the BYO Knowledge tool to enhance the knowledge available to the LLM by including information from the SOP.
+
+To bring your own knowledge to an LLM, you complete the following steps:
+
+* Create the custom content in Markdown format.
+* Use the BYO Knowledge tool to package the content as a container image.
+* Push the container image to an image registry, such as `quay.io`.
+* Update the `OLSConfig` custom resource file to list the image that you pushed to the image registry.
+* Access the {ols-long} virtual assistant and submit a question that is associated with the custom knowledge that you made available to the LLM.
++
+[NOTE]
+====
+When you use the BYO Knowledge tool, the documents that you make available to the LLM are sent to the LLM provider.
+====

modules/ols-providing-custom-knowledge-to-the-llm.adoc

@@ -0,0 +1,115 @@
+// Module included in the following assemblies:
+// * lightspeed-docs-main/configure/ols-configuring-openshift-lightspeed.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="providing-custom-knowledge-to-the-llm_{context}"]
+= Providing custom knowledge to the LLM
+
+Customize the information available to the large language model (LLM) by providing access to a container image that resides in a remote image registry. The examples in this procedure use `quay.io` as the remote container image registry, and the path for the custom image is `quay.io/<username>/my-byok-image:latest`.
+
+:FeatureName: The BYO Knowledge tool
+include::snippets/technology-preview.adoc[]
+
+.Prerequisites
+
+* You are logged in to the {ocp-product-title} web console as a user account that has permission to create a cluster-scoped custom resource (CR) file, such as a user with the `cluster-admin` role.
+
+* You have installed the {ols-long} Operator.
+
+* You have configured the LLM provider.
+
+* The custom information you want to add resides as a collection of Markdown files. No other file format is supported.
+
+* You have an account for a container image registry, such as `quay.io`.
+
+.Procedure 
+
+. Specify the location of the directory with the Markdown files for the retrieval-augmented generation (RAG) database and the path for the image that the BYO Knowledge tool generates by running the following command: 
++
+[source,terminal]
+----
+$ podman run -it --rm --device=/dev/fuse \
+  -v $XDG_RUNTIME_DIR/containers/auth.json:/run/user/0/containers/auth.json:Z \
+  -v <dir_tree_with_markdown_files>:/markdown:Z \
+  -v <dir_for_image_tar>:/output:Z \
+  registry.redhat.io/openshift-lightspeed-tech-preview/lightspeed-rag-tool-rhel9:latest
+----
++
+[NOTE]
+====
+The container image that the tool generates contains a custom RAG database. The RAG database provides additional information to the LLM. 
+====
+
+. Load the container image that the BYO Knowledge tool generated by running the following command:
++
+[source,terminal]
+----
+$ podman load < <directory_for_image_tar>/<my-byok-image.tar>
+----
+
+. Display the podman images that are on your local computer by running the following command:
++
+[source,terminal]
+----
+$ podman images
+----
++
+.Example output
+[source,terminal]
+----
+REPOSITORY                            TAG                IMAGE ID      CREATED       SIZE
+localhost/my-byok-image               latest             be7d1770bf10  1 minute  ago    2.37 GB
+...
+----
+
+. Tag the local image with a name and destination so that the image can be pushed to the container image registry by running the following command:
++
+[source,terminal]
+----
+$ podman tag localhost/my-byok-image:latest quay.io/<username>/my-byok-image:latest
+----
+
+. Push the local container image to the container image registry by running the following command:
++
+[source,terminal]
+----
+$ podman push quay.io/<username>/my-byok-image:latest
+----
+
+. Modify the `OLSconfig` CR to deploy the newly created RAG database alongside the existing one:
+
+.. In the {ocp-product-title} web console, click *Operators* -> *Installed Operators*. 
+
+.. Select *All Projects* in the  *Project* dropdown at the top of the screen.
+
+.. Click *{ols-long} Operator*.
+
+.. Click *OLSConfig*, then click the `cluster` configuration instance in the list.
+
+.. Click the *YAML* tab.
+
+.. Insert the `spec.ols.rag` yaml code:
++
+.Example `OLSconfig` CR file
+[source,yaml,subs="attributes,verbatim"]
+----
+apiVersion: ols.openshift.io/v1alpha1
+kind: OLSConfig
+metadata:
+  name: cluster
+spec:
+  ols:
+    rag:
+      - image: quay.io/<username>/my-byok-image:latest # <1>
+        indexPath: /rag/vector_db
+        indexID: vector_db_index    
+----
+<1> Where `image` specifies the tag for the image that was pushed to the image registry so that the {ols-long} Operator can access the custom content. The {ols-long} Operator can work with more than one RAG database that you create.
+
+. Click *Save*.
+
+.Verification
+
+* Access the {ols-long} virtual assistant and submit a question associated with the custom content that you provided to the LLM.
++
+The {ols-long} virtual assistant generates a response based on the custom content.