|
| 1 | +--- |
| 2 | +hide: |
| 3 | + - footer |
| 4 | +--- |
| 5 | + |
| 6 | +# LLM Features Configuration |
| 7 | + |
| 8 | +Timesketch includes experimental features leveraging Large Language Models (LLMs) to enhance analysis capabilities. These features include event summarization and AI-generated queries (NL2Q - Natural Language to Query). This document outlines the steps required to configure these features for Timesketch administrators. |
| 9 | + |
| 10 | +## LLM Provider Configuration |
| 11 | + |
| 12 | +To utilize the LLM features, the Timesketch **administrator** must configure an LLM provider in the `timesketch.conf` file. It's possible to configure a specific LLM provider and model per LLM powered feature, or to use a default provider. For most features we recommend using a fast model (such as `gemini-2.0-flash-001` ) for optimal performance, especially for the event summarization feature. |
| 13 | + |
| 14 | +Edit your `timesketch.conf` file to include the `LLM_PROVIDER_CONFIGS` dictionary. Below is a sample configuration with explanations for each parameter. |
| 15 | + |
| 16 | +```python |
| 17 | +# LLM provider configs |
| 18 | +LLM_PROVIDER_CONFIGS = { |
| 19 | + # Configure a LLM provider for a specific LLM enabled feature, or the |
| 20 | + # default provider will be used. |
| 21 | + # Supported LLM Providers: |
| 22 | + # - ollama: Self-hosted, open-source. |
| 23 | + # To use the Ollama provider you need to download and run an Ollama server. |
| 24 | + # See instructions at: https://ollama.ai/ |
| 25 | + # - vertexai: Google Cloud Vertex AI. Requires Google Cloud Project. |
| 26 | + # To use the Vertex AI provider you need to: |
| 27 | + # 1. Create and export a Service Account Key from the Google Cloud Console. |
| 28 | + # 2. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the full path |
| 29 | + # to your service account private key file by adding it to the docker-compose.yml |
| 30 | + # under environment: |
| 31 | + # GOOGLE_APPLICATION_CREDENTIALS=/usr/local/src/timesketch/<key_file>.json |
| 32 | + # 3. Verify your instance has the `google-cloud-aiplatform` lib installed. |
| 33 | + # * $ sudo docker exec timesketch-web pip list | grep google-cloud-aiplatform |
| 34 | + # * You can install it manually using: |
| 35 | + # $ sudo docker exec timesketch-web pip install google-cloud-aiplatform==1.70.0 |
| 36 | + # |
| 37 | + # IMPORTANT: Private keys must be kept secret. If you expose your private key it is |
| 38 | + # recommended to revoke it immediately from the Google Cloud Console. |
| 39 | + # - aistudio: Google AI Studio (API key). Get API key from Google AI Studio website. |
| 40 | + # To use Google's AI Studio simply obtain an API key from https://aistudio.google.com/ |
| 41 | + # Verify your instance runs the required library: |
| 42 | + # * $ sudo docker exec timesketch-web pip list | grep google-generativeai |
| 43 | + # * You can install it manually using: |
| 44 | + # $ sudo docker exec timesketch-web pip install google-generativeai==0.8.4 |
| 45 | + 'nl2q': { |
| 46 | + 'vertexai': { |
| 47 | + 'model': 'gemini-2.0-flash-001', |
| 48 | + 'project_id': '', # Required if using vertexai |
| 49 | + }, |
| 50 | + }, |
| 51 | + 'llm_summarization': { |
| 52 | + 'aistudio': { |
| 53 | + 'model': 'gemini-2.0-flash-001', # Recommended model |
| 54 | + 'api_key': '', # Required if using aistudio |
| 55 | + }, |
| 56 | + }, |
| 57 | + 'default': { |
| 58 | + 'ollama': { |
| 59 | + 'server_url': 'http://localhost:11434', |
| 60 | + 'model': 'gemma2-2b-it', |
| 61 | + }, |
| 62 | + } |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +**Note:** While [users can enable/disable these features](../user/llm-features-user.md), the underlying LLM provider and its configuration are managed by the Timesketch administrator. Enabling these features may incur costs depending on the chosen LLM provider. Please review the pricing details of your selected provider before enabling these features. |
| 67 | + |
| 68 | +## Prompt and Data Configuration |
| 69 | + |
| 70 | +Administrators can further customize the behavior of the LLM features by configuring the paths to various prompt and data files within the `timesketch.conf` file. |
| 71 | + |
| 72 | +```python |
| 73 | +# LLM nl2q configuration |
| 74 | +DATA_TYPES_PATH = '/etc/timesketch/nl2q/data_types.csv' |
| 75 | +PROMPT_NL2Q = '/etc/timesketch/nl2q/prompt_nl2q' |
| 76 | +EXAMPLES_NL2Q = '/etc/timesketch/nl2q/examples_nl2q' |
| 77 | + |
| 78 | +# LLM event summarization configuration |
| 79 | +PROMPT_LLM_SUMMARIZATION = '/etc/timesketch/llm_summarize/prompt.txt' |
| 80 | +``` |
| 81 | + |
| 82 | +* `DATA_TYPES_PATH`: Specifies the path to a CSV file defining common Timesketch data types for the NL2Q feature. |
| 83 | +* `PROMPT_NL2Q`: Specifies the path to the prompt file used by the NL2Q feature to translate a natural language into a Timesketch search query. |
| 84 | +* `EXAMPLES_NL2Q`: Specifies the path to the examples file used by the NL2Q feature. This file provides the LLM with examples of natural language queries and their corresponding Timesketch search queries, which help improve the accuracy of the NL2Q feature. |
| 85 | +* `PROMPT_LLM_SUMMARIZATION`: Specifies the path to the prompt file used by the event summarization feature. Administrators can modify this file to customize the summarization output to their specific needs. This template allows for injecting the event data into the prompt using Python-style string formatting using curly braces `{}`. |
| 86 | +Timesketch provides some default configuration files for both features: |
| 87 | +* [NL2Q default configuration](https://github.com/google/timesketch/tree/master/data/nl2q). |
| 88 | +* [LLM Summarization default configuration](https://github.com/google/timesketch/tree/master/data/llm_summarize). |
0 commit comments