Optimizing models for AI

Enhancing your models for using Omni's AI can significantly improve the accuracy and relevance of AI-generated responses. In this guide, you'll learn what AI context is and how to use it to curate your models.

Requirements

To follow this guide, you'll need:

An understanding of Omni modeling concepts
Familiarity with Omni's model IDE
Familiarity with basic AI terminology such as tokens, agents, etc.

AI context in Omni

What is AI context?

Context is information such as:

Descriptions of topics and fields
Possible field values
How a field might be used

In Omni, this is provided to the AI using a context window. A context window is the amount of text an AI can read and consider at one time when answering a question or completing a task.

Why provide context to AI?

Using context windows allows AI models to understand and incorporate relevant information. Specifically, providing context to the LLM makes it more effective, enabling it to interpret your request accurately and generate meaningful responses.

What does Omni AI use for context?

Omni uses the following for context:

Priority	Description
1	Context from Omni
2	Topic's `ai_context` parameter, if provided
3	Topic's `description`, if provided
4	Topic's `name` and `base_view`
5	Prioritized field properties: `fully_qualified_name` (`view_name.field_name`) - For example, `order_items.total_sale_price` `name` - For example, `total_sale_price` `aliases` `ai_context` `all_values` - Used to specify the possible values for the field
6	Pruned field properties. These properties will be pruned in the following order, but note that fields may be truncated entirely if required. `description` `group_label` - The categorization of the field `label` - If defined, the value will be used. If not provided, a title-cased field name with underscores removed will be used. For example, `Total Sale Price` `semantic_type` - The dimension or aggregate type, such as `dimension`, `sum`, `count`, etc. This value is evaluated based on the field definition and can't be directly modified. `data_type` The field's data type, such as `number`, `string`, etc. `sample_values` - Example values for the field `synonyms` - Other terms used to refer to the field

Where does context apply?

Context applies to:

The AI query helper (Blobby) in the workbook
AI summary visualizations

What limitations does context have?

Omni's model can handle ~400K characters of context:

~15-25K is reserved for Omni app context, which is used to ensure queries are generated properly
The remaining ~375K characters are allocated for context from the semantic layer before truncation, starting with field metadata

To prevent field truncation, we recommend limiting the number of fields included in the context window to 1,200. Let's look at example to explain to demonstrate why.

You have a topic that you want to use for AI querying. Including the topic's description, name, base_view, ai_context, and the included fields' prioritized properties (ex: name), let's say the total characters used is around 10,000.

  375,000 characters   // total allocated for semantic layer context
-  10,000 characters   // topic metadata & prioritized field properties
  ------------------
  365,000 characters   // total remaining for additional context

In the topic, the included fields generally look like this:

active_camp_active_campaign_id_c:
  sql: '"ACTIVE_CAMP_ACTIVE_CAMPAIGN_ID_C"'
  label: Active Campaign Active Campaign ID
  group_label: Active Campaign

The total characters used for this field's basic metadata equals 160 characters.

You'll likely want to add field-level context, such as description, sample_values, and ai_context. Let's add 140 characters to account for the AI-specific metadata, which brings the total characters per field to 300 characters:
```
  160 characters      // basic field metadata
+ 140 characters      // field-level context for AI
  --------------
  300 characters      // total field metadata
```

To get the total number of fields, divide the remaining characters available (365,000) by the total metadata characters per field:

  365,000 characters      // total remaining for additional context
/     300 characters      // total field metadata
  -------------------
    1,200(ish) fields     // total fields for inclusion 

This gives you roughly 1,200 fields to include in the context window before Omni begins truncating fields.

How is context to the AI processed?

Context provided to Omni's AI is shared with OpenAI for the AI query helper (Blobby) and AWS Bedrock for the AI summary visualization. Refer to the AI data security guide for more information.

Curating topics for AI

Including fields

Blobby only uses the fields that exist within the context of a topic to output a response. Fields that have a hidden: true parameter are excluded from the context window. If you'd like to specify fields you want included in the context window, you can leverage the ai_fields parameter within a topic. For fields that you want to include, you can provide additional context at the field level.

Keep in mind that Blobby can't - at least currently - create calculations or aggregations. We recommend periodically checking the Analytics > AI usage dashboard to see what questions your users are asking, so you can further refine and evolve your models.

Extending topics

Topics that you're already leveraging in Omni can be extended to further curate them for AI. Using the extends parameter, you can reuse the definition of an existing topic without needing to repeat the code. Consider the following Order Transactions topic, which you want to extend to create a curated version dedicated to AI usage:

Order Transactions topic
label: Order Transactions

default_filters:
  order_items.status:
    not: [ Returned, Cancelled ]

joins:
  users: {}
  user_order_facts: {}
  inventory_items:
    products:
      distribution_centers: {}

In a new topic, use extends: [ order_items ] to extend the Order Transactions topic. You can then specify what to include in the AI-specific topic, such as limiting fields, filtering the data for specific use cases, adding more AI context, and so on:

Orders for AI querying topic, extended from Order Transactions
extends: [ order_items ]

base_view_label: Order Items
label: Orders for AI Querying

# limit fields included in the context window
ai_fields: [ tag:use_for_ai ]

Enhancing context windows

Topics also have an AI-specific ai_context parameter, which is useful for providing behavioral prompts and guidance for handling certain questions. For example:

ai_context for e-commerce orders
ai_context: |-
  This topic is focuses on e-commerce orders. The main concepts are orders
  at the line item level in the order items table, users in our user table,
  inventory in our inventory items table, and products in the products table.

  Only respond with accurate answers based on the data that you're aware of.
  Don't pivot unless there is more than one dimension included in the query.

  Typical questions will be focused on order performance over time, breakdowns across users, and more. 
  - if asked about sales or performance, always use the order_items.total_sale_price field
  - if asked about which users or who, use the users.full_name and users.email fields. Never return an ID unless explicitly asked.
  - if asked about top n without a specific metric or dimension, assume it involves the order_items.total_sale_price and products.name fields

Providing questions & answers as context

Along with providing context about the topic, you could also use ai_context to provide example questions and their correct answers. This approach is useful if you anticipate specific, recurring questions or you find that Blobby struggles with date filters.

To do this, you'll want to:

Create a query in a workbook that contains the correct answer to the question.
Open the Inspector panel using the bug icon near the lower left corner of the page:
Locate the Query structure section and copy the contents. Note: Some parameters aren't useful for AI context and can be removed to stay below the character limit. For example, modelId, version, and join_path_from_topic_name.

In the topic, include the question and paste the contents of the Query structure section:

Question & answer in ai_context
ai_context: |-
  Example question: What month has the highest sales?
  Answer: 
    {
      "limit": 1,
      "sorts": [
        {
          "column_name": "order_items.total_sale_price",
          "sort_descending": true
        }
      ],
      "table": "order_items",
      "fields": [
        "order_items.created_at[month]",
        "order_items.total_sale_price"
      ],
      "pivots": [],
      "dbtMode": false,
      "filters": {
        "order_items.status": {
          "kind": "EQUALS",
          "type": "string",
          "values": [
            "Returned",
            "Cancelled"
          ],
          "is_negative": true
        }
      }
    }

Adding context to fields

Keeping fields organized and labeled can not only help you create a top-notch self-service experience, it can also make Omni's AI more efficient. The following parameters can be used to add metadata to fields for the purposes of AI:

ai_context - Adds context useful for AI responses
all_values - All possible values for the field
sample_values - Example values for the field
synonyms - Other terms used to refer to the field

You can use the workbook or the IDE to add the parameters.

In the workbook

In the field browser, click the options (three dots) menu next to the field.
Click Modeling > Edit to open the Edit field side panel.

In the IDE

In the IDE, navigate to the view containing the field to add the parameters. For example:

products.view
dimensions:
  brand:
    sql: '"BRAND"'
    description: Brand name of product
    sample_values:
      [
        Calvin Klein,
        Carhartt,
        Hanes,
        Volcom,
        Levi's,
        Diesel,
        Lucky Brand,
        Quicksilver,
        Nautica,
        American Apparel,
        Columbia,
        Hurley,
        Dockers,
        Arc'teryx,
        C-IN2,
        DKNY,
        HOBO,
        NOM,
        ANS
      ]
    synonyms: [ logo ]
    ai_context: To filter this field, use contains with the brand name.

Requirements​

AI context in Omni​

Curating topics for AI​

Including fields​

Extending topics​

Enhancing context windows​

Providing questions & answers as context​

Adding context to fields​