[ESS] [Serverless] Updates BYO LLM page (#6326)

* updates BYO LLM page * fix link error * fixes broken serverless link * troubleshoot * fixes another broken serverless link * updates images and video * Update docs/AI-for-security/connect-to-byo.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/serverless/AI-for-security/connect-to-byo-llm.asciidoc * Update docs/AI-for-security/connect-to-byo.asciidoc --------- Co-authored-by: Nastasha Solomon <[email protected]> (cherry picked from commit 900040b) # Conflicts: # docs/serverless/AI-for-security/connect-to-byo-llm.asciidoc # docs/serverless/AI-for-security/images/lms-cli-welcome.png # docs/serverless/AI-for-security/images/lms-model-select.png # docs/serverless/AI-for-security/images/lms-ps-command.png # docs/serverless/AI-for-security/images/lms-studio-model-loaded-msg.png # docs/serverless/AI-for-security/llm-connector-guides.asciidoc
elastic · Dec 17, 2024 · d0b4dd9 · d0b4dd9
1 parent f1d07a5
commit d0b4dd9
Show file tree

Hide file tree

Showing 11 changed files with 232 additions and 16 deletions.
diff --git a/docs/AI-for-security/connect-to-byo.asciidoc b/docs/AI-for-security/connect-to-byo.asciidoc
@@ -10,7 +10,7 @@ This page provides instructions for setting up a connector to a large language m
 
 This example uses a single server hosted in GCP to run the following components:
 
-* LM Studio with the https://mistral.ai/technology/#models[Mixtral-8x7b] model
+* LM Studio with the https://huggingface.co/mistralai/Mistral-Nemo-Instruct-2407[Mistral-Nemo-Instruct-2407] model
 * A reverse proxy using Nginx to authenticate to Elastic Cloud
 
 image::images/lms-studio-arch-diagram.png[Architecture diagram for this guide]
@@ -20,7 +20,7 @@ NOTE: For testing, you can use alternatives to Nginx such as https://learn.micro
 [discrete]
 == Configure your reverse proxy
 
-NOTE: If your Elastic instance is on the same host as LM Studio, you can skip this step.
+NOTE: If your Elastic instance is on the same host as LM Studio, you can skip this step. Also, check out our https://www.elastic.co/blog/herding-llama-3-1-with-elastic-and-lm-studio[blog post] that walks through the whole process of setting up a single-host implementation.
 
 You need to set up a reverse proxy to enable communication between LM Studio and Elastic. For more complete instructions, refer to a guide such as https://www.digitalocean.com/community/tutorials/how-to-configure-nginx-as-a-reverse-proxy-on-ubuntu-22-04[this one].
 
@@ -74,7 +74,14 @@ server {
 }
 --------------------------------------------------
 
-IMPORTANT: If using the example configuration file above, you must replace several values: Replace `<secret token>` with your actual token, and keep it safe since you'll need it to set up the {elastic-sec} connector. Replace `<yourdomainname.com>` with your actual domain name. Update the `proxy_pass` value at the bottom of the configuration if you decide to change the port number in LM Studio to something other than 1234.
+[IMPORTANT]
+====
+If using the example configuration file above, you must replace several values:
+
+* Replace `<secret token>` with your actual token, and keep it safe since you'll need it to set up the {elastic-sec} connector.
+* Replace `<yourdomainname.com>` with your actual domain name.
+* Update the `proxy_pass` value at the bottom of the configuration if you decide to change the port number in LM Studio to something other than 1234.
+====
 
 [discrete]
 === (Optional) Set up performance monitoring for your reverse proxy
@@ -85,23 +92,20 @@ You can use Elastic's {integrations-docs}/nginx[Nginx integration] to monitor pe
 
 First, install https://lmstudio.ai/[LM Studio]. LM Studio supports the OpenAI SDK, which makes it compatible with Elastic's OpenAI connector, allowing you to connect to any model available in the LM Studio marketplace.
 
-One current limitation of LM Studio is that when it is installed on a server, you must launch the application using its GUI before doing so using the CLI. For example, by using Chrome RDP with an https://cloud.google.com/architecture/chrome-desktop-remote-on-compute-engine[X Window System]. After you've opened the application the first time using the GUI, you can start it by using `sudo lms server start` in the CLI. 
+You must launch the application using its GUI before doing so using the CLI. For example, use Chrome RDP with an https://cloud.google.com/architecture/chrome-desktop-remote-on-compute-engine[X Window System]. After you've opened the application the first time using the GUI, you can start it by using `sudo lms server start` in the CLI. 
 
 Once you've launched LM Studio: 
 
 1. Go to LM Studio's Search window.
-2. Search for an LLM (for example, `Mixtral-8x7B-instruct`). Your chosen model must include `instruct` in its name in order to work with Elastic.
-3. Filter your search for "Compatibility Guess" to optimize results for your hardware. Results will be color coded:
-    * Green means "Full GPU offload possible", which yields the best results.
-    * Blue means "Partial GPU offload possible", which may work.
-    * Red for "Likely too large for this machine", which typically will not work.
+2. Search for an LLM (for example, `Mistral-Nemo-Instruct-2407`). Your chosen model must include `instruct` in its name in order to work with Elastic.
+3. After you find a model, view download options and select a recommended version (green). For best performance, select one with the thumbs-up icon that indicates good performance on your hardware. 
 4. Download one or more models.
 
 IMPORTANT: For security reasons, before downloading a model, verify that it is from a trusted source. It can be helpful to review community feedback on the model (for example using a site like Hugging Face).  
 
 image::images/lms-model-select.png[The LM Studio model selection interface]
 
-In this example we used https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF[`TheBloke/Mixtral-8x7B-Instruct-v0.1.Q3_K_M.gguf`]. It has 46.7B total parameters, a 32,000 token context window, and uses GGUF https://huggingface.co/docs/transformers/main/en/quantization/overview[quanitization]. For more information about model names and format information, refer to the following table.
+In this example we used https://huggingface.co/mistralai/Mistral-Nemo-Instruct-2407[`mistralai/Mistral-Nemo-Instruct-2407`]. It has 12B total parameters, a 128,000 token context window, and uses GGUF https://huggingface.co/docs/transformers/main/en/quantization/overview[quanitization]. For more information about model names and format information, refer to the following table.
 
 [cols="1,1,1,1", options="header"]
 |===
@@ -124,18 +128,18 @@ After downloading a model, load it in LM Studio using the GUI or LM Studio's htt
 [discrete]
 === Option 1: load a model using the CLI (Recommended)
 
-It is a best practice to download models from the marketplace using the GUI, and then load or unload them using the CLI. The GUI allows you to search for models, whereas the CLI only allows you to import specific paths, but the CLI provides a good interface for loading and unloading.
+It is a best practice to download models from the marketplace using the GUI, and then load or unload them using the CLI. The GUI allows you to search for models, whereas the CLI allows you to use `lms get` to search for models. The CLI provides a good interface for loading and unloading.
 
-Use the following commands in your CLI:
+Once you've downloaded a model, use the following commands in your CLI:
 
 1. Verify LM Studio is installed: `lms`
 2. Check LM Studio's status: `lms status`
 3. List all downloaded models: `lms ls`
-4. Load a model: `lms load`
+4. Load a model: `lms load`. 
 
 image::images/lms-cli-welcome.png[The CLI interface during execution of initial LM Studio commands]
 
-After the model loads, you should see a `Model loaded successfully` message in the CLI.
+After the model loads, you should see a `Model loaded successfully` message in the CLI. 
 
 image::images/lms-studio-model-loaded-msg.png[The CLI message that appears after a model loads]
 
@@ -156,8 +160,8 @@ Refer to the following video to see how to load a model using LM Studio's GUI. Y
 <img
   style="width: 100%; margin: auto; display: block;"
   class="vidyard-player-embed"
-  src="https://play.vidyard.com/FMx2wxGQhquWPVhGQgjkyM.jpg"
-  data-uuid="FMx2wxGQhquWPVhGQgjkyM"
+  src="https://play.vidyard.com/c4AxH8d9tWMnwNp5J6bcfX.jpg"
+  data-uuid="c4AxH8d9tWMnwNp5J6bcfX"
   data-v="4"
   data-type="inline"
 />

diff --git a/docs/AI-for-security/images/lms-cli-welcome.png b/docs/AI-for-security/images/lms-cli-welcome.png
diff --git a/docs/AI-for-security/images/lms-model-select.png b/docs/AI-for-security/images/lms-model-select.png
diff --git a/docs/AI-for-security/images/lms-ps-command.png b/docs/AI-for-security/images/lms-ps-command.png
diff --git a/docs/AI-for-security/images/lms-studio-model-loaded-msg.png b/docs/AI-for-security/images/lms-studio-model-loaded-msg.png
diff --git a/docs/serverless/AI-for-security/connect-to-byo-llm.asciidoc b/docs/serverless/AI-for-security/connect-to-byo-llm.asciidoc
@@ -0,0 +1,197 @@
+[[connect-to-byo-llm]]
+= Connect to your own local LLM
+
+:frontmatter-description: Set up a connector to LM Studio so you can use a local model with AI Assistant.
+:frontmatter-tags-products: [security]
+:frontmatter-tags-content-type: [guide]
+:frontmatter-tags-user-goals: [get-started]
+
+This page provides instructions for setting up a connector to a large language model (LLM) of your choice using LM Studio. This allows you to use your chosen model within {elastic-sec}. You'll first need to set up a reverse proxy to communicate with {elastic-sec}, then set up LM Studio on a server, and finally configure the connector in your Elastic deployment. https://www.elastic.co/blog/ai-assistant-locally-hosted-models[Learn more about the benefits of using a local LLM].
+
+This example uses a single server hosted in GCP to run the following components:
+
+* LM Studio with the https://huggingface.co/mistralai/Mistral-Nemo-Instruct-2407[Mistral-Nemo-Instruct-2407] model
+* A reverse proxy using Nginx to authenticate to Elastic Cloud
+
+image::images/lms-studio-arch-diagram.png[Architecture diagram for this guide]
+
+NOTE: For testing, you can use alternatives to Nginx such as https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/overview[Azure Dev Tunnels] or https://ngrok.com/[Ngrok], but using Nginx makes it easy to collect additional telemetry and monitor its status by using Elastic's native Nginx integration. While this example uses cloud infrastructure, it could also be replicated locally without an internet connection.
+
+[discrete]
+== Configure your reverse proxy
+
+NOTE: If your Elastic instance is on the same host as LM Studio, you can skip this step. Also, check out our https://www.elastic.co/blog/herding-llama-3-1-with-elastic-and-lm-studio[blog post] that walks through the whole process of setting up a single-host implementation.
+
+You need to set up a reverse proxy to enable communication between LM Studio and Elastic. For more complete instructions, refer to a guide such as https://www.digitalocean.com/community/tutorials/how-to-configure-nginx-as-a-reverse-proxy-on-ubuntu-22-04[this one].
+
+The following is an example Nginx configuration file:
+
+[source,txt]
+--------------------------------------------------
+server {
+    listen                          80;
+    listen                          [::]:80;
+    server_name                     <yourdomainname.com>;
+    server_tokens off;
+    add_header x-xss-protection "1; mode=block" always;
+    add_header x-frame-options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    return 301                      https://$server_name$request_uri;
+}
+
+server {
+
+    listen                          443 ssl http2;
+    listen                          [::]:443 ssl http2;
+    server_name                     <yourdomainname.com>;
+    server_tokens off;
+    ssl_certificate                 /etc/letsencrypt/live/<yourdomainname.com>/fullchain.pem;
+    ssl_certificate_key             /etc/letsencrypt/live/<yourdomainname.com>/privkey.pem;
+    ssl_session_timeout 1d;
+    ssl_session_cache shared:SSL:50m;
+    ssl_session_tickets on;
+    ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
+    ssl_protocols TLSv1.3 TLSv1.2;
+    ssl_prefer_server_ciphers on;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
+    add_header x-xss-protection "1; mode=block" always;
+    add_header x-frame-options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    ssl_stapling on;
+    ssl_stapling_verify on;
+    ssl_trusted_certificate /etc/letsencrypt/live/<yourdomainname.com>/fullchain.pem;
+    resolver 1.1.1.1;
+    location / {
+          
+    if ($http_authorization != "Bearer <secret token>") {
+    return 401;
+}                            
+
+    proxy_pass http://localhost:1234/;
+   }
+
+}
+--------------------------------------------------
+
+[IMPORTANT]
+====
+If using the example configuration file above, you must replace several values:
+
+* Replace `<secret token>` with your actual token, and keep it safe since you'll need it to set up the {elastic-sec} connector.
+* Replace `<yourdomainname.com>` with your actual domain name.
+* Update the `proxy_pass` value at the bottom of the configuration if you decide to change the port number in LM Studio to something other than 1234.
+====
+
+[discrete]
+=== (Optional) Set up performance monitoring for your reverse proxy
+You can use Elastic's {integrations-docs}/nginx[Nginx integration] to monitor performance and populate monitoring dashboards in the {security-app}.
+
+[discrete]
+== Configure LM Studio and download a model
+
+First, install https://lmstudio.ai/[LM Studio]. LM Studio supports the OpenAI SDK, which makes it compatible with Elastic's OpenAI connector, allowing you to connect to any model available in the LM Studio marketplace.
+
+You must launch the application using its GUI before doing so using the CLI. For example, use Chrome RDP with an https://cloud.google.com/architecture/chrome-desktop-remote-on-compute-engine[X Window System]. After you've opened the application the first time using the GUI, you can start it by using `sudo lms server start` in the CLI. 
+
+Once you've launched LM Studio: 
+
+1. Go to LM Studio's Search window.
+2. Search for an LLM (for example, `Mistral-Nemo-Instruct-2407`). Your chosen model must include `instruct` in its name in order to work with Elastic.
+3. After you find a model, view download options and select a recommended version (green). For best performance, select one with the thumbs-up icon that indicates good performance on your hardware. 
+4. Download one or more models.
+
+IMPORTANT: For security reasons, before downloading a model, verify that it is from a trusted source. It can be helpful to review community feedback on the model (for example using a site like Hugging Face).  
+
+image::images/lms-model-select.png[The LM Studio model selection interface]
+
+In this example we used https://huggingface.co/mistralai/Mistral-Nemo-Instruct-2407[`mistralai/Mistral-Nemo-Instruct-2407`]. It has 12B total parameters, a 128,000 token context window, and uses GGUF https://huggingface.co/docs/transformers/main/en/quantization/overview[quanitization]. For more information about model names and format information, refer to the following table.
+
+[cols="1,1,1,1", options="header"]
+|===
+| Model Name | Parameter Size | Tokens/Context Window | Quantization Format
+| Name of model, sometimes with a version number.
+| LLMs are often compared by their number of parameters — higher numbers mean more powerful models.
+| Tokens are small chunks of input information. Tokens do not necessarily correspond to characters. You can use https://platform.openai.com/tokenizer[Tokenizer] to see how many tokens a given prompt might contain.
+| Quantization reduces overall parameters and helps the model to run faster, but reduces accuracy.
+| Examples: Llama, Mistral, Phi-3, Falcon.
+| The number of parameters is a measure of the size and the complexity of the model. The more parameters a model has, the more data it can process, learn from, generate, and predict.
+| The context window defines how much information the model can process at once. If the number of input tokens exceeds this limit, input gets truncated.
+| Specific formats for quantization vary, most models now support GPU rather than CPU offloading.
+|===
+
+[discrete]
+== Load a model in LM Studio 
+
+After downloading a model, load it in LM Studio using the GUI or LM Studio's https://lmstudio.ai/blog/lms[CLI tool].
+
+[discrete]
+=== Option 1: load a model using the CLI (Recommended)
+
+It is a best practice to download models from the marketplace using the GUI, and then load or unload them using the CLI. The GUI allows you to search for models, whereas the CLI allows you to use `lms get` to search for models. The CLI provides a good interface for loading and unloading.
+
+Once you've downloaded a model, use the following commands in your CLI:
+
+1. Verify LM Studio is installed: `lms`
+2. Check LM Studio's status: `lms status`
+3. List all downloaded models: `lms ls`
+4. Load a model: `lms load`. 
+
+image::images/lms-cli-welcome.png[The CLI interface during execution of initial LM Studio commands]
+
+After the model loads, you should see a `Model loaded successfully` message in the CLI. 
+
+image::images/lms-studio-model-loaded-msg.png[The CLI message that appears after a model loads]
+
+To verify which model is loaded, use the `lms ps` command.
+
+image::images/lms-ps-command.png[The CLI message that appears after running lms ps]
+
+If your model uses NVIDIA drivers, you can check the GPU performance with the `sudo nvidia-smi` command.
+
+[discrete]
+=== Option 2: load a model using the GUI
+
+Refer to the following video to see how to load a model using LM Studio's GUI. You can change the **port** setting, which is referenced in the Nginx configuration file. Note that the **GPU offload** was set to **Max**.
+
+=======
+++++
+<script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>
+<img
+  style="width: 100%; margin: auto; display: block;"
+  class="vidyard-player-embed"
+  src="https://play.vidyard.com/c4AxH8d9tWMnwNp5J6bcfX.jpg"
+  data-uuid="c4AxH8d9tWMnwNp5J6bcfX"
+  data-v="4"
+  data-type="inline"
+/>
+</br>
+++++
+=======
+
+[discrete]
+== (Optional) Collect logs using Elastic's Custom Logs integration
+
+You can monitor the performance of the host running LM Studio using Elastic's {integrations-docs}/log[Custom Logs integration]. This can also help with troubleshooting. Note that the default path for LM Studio logs is `/tmp/lmstudio-server-log.txt`, as in the following screenshot:
+
+image::images/lms-custom-logs-config.png[The configuration window for the custom logs integration]
+
+[discrete]
+== Configure the connector in your Elastic deployment
+
+Finally, configure the connector:
+
+1. Log in to your Elastic deployment.
+2. Find the **Connectors** page in the navigation menu or use the {kibana-ref}/introduction.html#kibana-navigation-search[global search field]. Then click **Create Connector**, and select **OpenAI**. The OpenAI connector enables this use case because LM Studio uses the OpenAI SDK.
+3. Name your connector to help keep track of the model version you are using.
+4. Under **Select an OpenAI provider**, select **Other (OpenAI Compatible Service)**.
+5. Under **URL**, enter the domain name specified in your Nginx configuration file, followed by `/v1/chat/completions`.
+6. Under **Default model**, enter `local-model`.
+7. Under **API key**, enter the secret token specified in your Nginx configuration file.
+8. Click **Save**.
+
+image::images/lms-edit-connector.png[The Edit connector page in the {security-app}, with appropriate values populated]
+
+Setup is now complete. You can use the model you've loaded in LM Studio to power Elastic's generative AI features. You can test a variety of models as you interact with AI Assistant to see what works best without having to update your connector. 
+
+NOTE: While local models work well for <<security-ai-assistant, AI Assistant>>, we recommend you use one of <<security-llm-performance-matrix, these models>> for interacting with <<attack-discovery, Attack discovery>>. As local models become more performant over time, this is likely to change. 
diff --git a/docs/serverless/AI-for-security/images/lms-cli-welcome.png b/docs/serverless/AI-for-security/images/lms-cli-welcome.png
diff --git a/docs/serverless/AI-for-security/images/lms-model-select.png b/docs/serverless/AI-for-security/images/lms-model-select.png
diff --git a/docs/serverless/AI-for-security/images/lms-ps-command.png b/docs/serverless/AI-for-security/images/lms-ps-command.png
diff --git a/docs/serverless/AI-for-security/images/lms-studio-model-loaded-msg.png b/docs/serverless/AI-for-security/images/lms-studio-model-loaded-msg.png
diff --git a/docs/serverless/AI-for-security/llm-connector-guides.asciidoc b/docs/serverless/AI-for-security/llm-connector-guides.asciidoc
@@ -0,0 +1,15 @@
+[[security-llm-connector-guides]]
+= LLM connector guides
+
+// :description: Set up LLM connectors to enable AI features in {elastic-sec}
+// :keywords: security, overview, get-started
+
+This section contains instructions for setting up connectors for LLMs so you can use <<security-ai-assistant,Elastic AI Assistant>> and <<attack-discovery,Attack discovery>>.
+
+Setup guides are available for the following LLM providers:
+
+* <<security-connect-to-azure-openai,Azure OpenAI>>
+* <<security-connect-to-bedrock,Amazon Bedrock>>
+* <<security-connect-to-openai,OpenAI>>
+* <<security-connect-to-google-vertex,Google Vertex>>
+* <<connect-to-byo-llm,LM Studio (custom local LLM)>>