Omni AI Optimizer

Optimisez votre modèle sémantique Omni pour que Blobby (l'agent Omni) retourne des réponses précises et contextuelles.

Conseil : Utilisez omni-model-explorer pour inspecter le contexte AI actuel avant d'apporter des modifications.

Prérequis

# Vérifiez que l'Omni CLI est installée — sinon, demandez à l'utilisateur de l'installer
# Voir : https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Affichez les profils disponibles et sélectionnez le bon
omni config show
# S'il existe plusieurs profils, demandez à l'utilisateur lequel utiliser, puis basculez :
omni config use <profile-name>

Nécessite les permissions Modeler ou Connection Admin.

Découvrir les commandes

omni models --help                    # Lister toutes les opérations de modèle
omni models yaml-create --help        # Afficher les drapeaux pour écrire du YAML

Conseil : Utilisez -o json pour forcer une sortie structurée à des fins de parsing programmatique, ou -o human pour des tableaux lisibles. La valeur par défaut est auto (human dans un TTY, JSON quand dirigé).

Fonctionnement de Blobby

Blobby génère des requêtes en examinant :

Structure des sujets — quelles vues et quels champs sont joints
Labels et descriptions de champs — comment les champs sont nommés
synonyms — noms alternatifs pour les champs
ai_context — instructions explicites que vous écrivez
ai_fields — quels champs sont visibles pour l'IA
sample_queries — exemples de questions avec requêtes correctes
Champs cachés — les champs hidden: true sont exclus
ai_chat_topics — quels sujets sont inclus/exclus du chat IA (au niveau du modèle)

Ordre d'impact : ai_context > ai_fields > sample_queries > synonyms > descriptions de champs.

Écrire ai_context

Ajoutez via l'API YAML :

omni models yaml-create <modelId> --body '{
  "fileName": "order_transactions.topic",
  "yaml": "base_view: order_items\nlabel: Order Transactions\nai_context: |\n  Map \"revenue\" → total_revenue. Map \"orders\" → count.\n  Map \"customers\" → unique_users.\n  Status values: complete, pending, cancelled, returned.\n  Only complete orders for revenue unless specified otherwise.",
  "mode": "extension",
  "commitMessage": "Add AI context to order transactions topic"
}'

Ce qui rend ai_context efficace

Terminologie mappée — mappez le langage métier aux noms de champs :

ai_context: |
  "revenue" or "sales" → order_items.total_revenue
  "orders" → order_items.count
  "customers" → users.count or order_items.unique_users
  "AOV" → order_items.average_order_value

Nuances des données — expliquez ce qui n'est pas évident à partir des noms de champs :

ai_context: |
  Each row is a line item, not an order. One order has multiple line items.
  total_revenue already excludes returns and cancellations.
  Dates are in UTC.

Guidage comportemental — dirigez les motifs courants :

ai_context: |
  For trends, default to weekly granularity, sort ascending.
  For "top N", sort descending and limit to 10.

Persona prompting — définissez la perspective analytique :

ai_context: |
  You are the head of finance analyzing customer payment data.
  Default to monetary values in USD with 2 decimal places.

Garder le contexte concis

Chaque token dans ai_context, description et label est envoyé à l'IA à chaque requête. Des valeurs verbeux gaspillent la fenêtre de contexte et éliminent d'autres champs.

Visez 1-2 phrases par entrée ai_context. Concentrez-vous sur la désambiguïsation et les pièges, pas sur une explication générale.
Gardez les labels courts et lisibles — évitez la qualification redondante (p. ex., « Order Total Revenue Amount » → « Total Revenue »).
Réécrivez les longues valeurs description pour être directs. Si une description répète le nom du champ, supprimez-la.

Curating Fields avec ai_fields

La fenêtre de contexte IA contient ~550 champs avant troncature. Si un sujet s'approche de cette limite, utilisez ai_fields pour curer les champs inclus.

Réduisez le bruit pour les grands modèles :

ai_fields:
  - all_views.*
  - -tag:internal
  - -distribution_centers.*

# Ou liste explicite
ai_fields:
  - order_items.created_at
  - order_items.total_revenue
  - order_items.count
  - users.name
  - users.state
  - products.category

Mêmes opérateurs que le sujet fields : wildcard (*), négation (-), tags (tag:).

Contrôler la visibilité des sujets avec ai_chat_topics

ai_chat_topics est une propriété au niveau du modèle qui contrôle quels sujets Blobby peut voir :

Pas de propriété ai_chat_topics (par défaut) — Blobby peut interroger tous les sujets.
ai_chat_topics: [] (liste vide) — Blobby ne peut interroger aucun sujet. Cela désactive effectivement le chat IA pour le modèle.
Liste explicite — seuls les sujets listés (ou correspondances de tags) sont disponibles. Supporte all_topics, sélecteurs de tags (tag:customer_facing) et négation (-tag:internal, -staging_events).

Vérifiez d'abord — si un sujet n'est pas dans ai_chat_topics, aucune quantité de ai_context ou ai_fields dessus n'aura d'importance. Utilisez omni-model-builder pour modifier cette propriété.

Ajouter sample_queries

Enseignez à Blobby par l'exemple. Construisez la requête correcte dans un workbook, récupérez sa structure, puis ajoutez-la au YAML du sujet :

sample_queries:
  revenue_by_month:
    prompt: "What month has the highest revenue?"
    ai_context: "Use total_revenue grouped by month, sorted descending, limit 1"
    query:
      base_view: order_items
      fields:
        - order_items.created_at[month]
        - order_items.total_revenue
      topic: order_transactions
      limit: 1
      sorts:
        - field: order_items.total_revenue
          desc: true

Note : Lors de l'export de requêtes depuis le workbook d'Omni, vous obtiendrez du JSON avec table, join_paths_from_topic_name et sorts utilisant column_name/sort_descending. Mappez ceux-ci au YAML comme suit :

table → base_view

join_paths_from_topic_name → topic

column_name → field, sort_descending → desc

Le JSON du workbook inclut filters, pivots, limit, column_limit que vous pouvez inclure en YAML (bien que la syntaxe de filtrage nécessite de consulter directement la documentation de l'API Model YAML)

Concentrez-vous sur les questions que les utilisateurs posent réellement — consultez Analytics > AI usage dans Omni.

Extensions de sujets spécifiques à l'IA

Créez une variante de sujet curée pour Blobby en utilisant extends :

# ai_order_transactions.topic
extends: [order_items]
label: AI - Order Transactions

fields:
  - order_items.created_at
  - order_items.status
  - order_items.total_revenue
  - order_items.count
  - users.name
  - users.state
  - products.category

ai_context: |
  Curated view of order data for AI analysis.
  [detailed context here]

sample_queries:
  top_categories_last_month:
    prompt: "Top selling categories last month?"
    query:
      base_view: order_items
      fields:
        - products.category
        - order_items.total_revenue
      topic: ai_order_transactions
      limit: 10
      sorts:
        - field: order_items.total_revenue
          desc: true

Améliorer les descriptions de champs

dimensions:
  status:
    label: Order Status
    description: >
      Current fulfillment status. Values: complete, pending, cancelled, returned.
      Use 'complete' for revenue calculations.

Les bonnes descriptions aident à la fois Blobby et les analystes humains.

Énumérer les valeurs pour les champs catégoriels

Pour les énumérations fermées, utilisez all_values pour que Blobby connaisse chaque valeur de filtre valide :

dimensions:
  status:
    all_values: [complete, pending, cancelled, returned]
  payment_method:
    all_values: [credit_card, debit_card, bank_transfer, paypal, gift_card]

Pour les catégoriques ouvertes où une liste complète n'est pas pratique, utilisez sample_values pour donner des exemples représentatifs :

dimensions:
  product_category:
    sample_values: [Electronics, Clothing, Home & Garden, Sports, Books]
  city:
    sample_values: [New York, Los Angeles, Chicago, Houston, Phoenix]

Ajouter des synonyms

Mappez les noms alternatifs, abréviations et terminologies spécifiques au domaine pour que Blobby mette en correspondance les requêtes des utilisateurs au champ correct. Fonctionne sur les dimensions et les mesures.

dimensions:
  customer_name:
    synonyms: [client, account, buyer, purchaser]
  order_date:
    synonyms: [purchase date, transaction date, order timestamp]

measures:
  total_revenue:
    synonyms: [sales, income, earnings, gross revenue, top line]
  average_order_value:
    synonyms: [AOV, avg order, basket size]

Synonyms vs ai_context : Utilisez synonyms pour le mapping des noms au niveau du champ. Utilisez ai_context pour le guidage comportemental au niveau du sujet, les nuances des données et les relations multi-champs.

Caveat pruning : Quand le modèle est grand et le contexte serré, les synonyms sont taillés avant les descriptions. Réservez les synonyms aux champs de haute valeur où les utilisateurs utilisent couramment des noms alternatifs.

Évitez la redondance : N'ajoutez pas de synonyms qui dupliquent le label ou le nom du champ — ils n'ajoutent aucun signal et gaspillent des tokens.

Éviter la duplication

ai_context et description servent des audiences différentes. description est face à l'humain (montré dans le sélecteur de champs et la documentation). ai_context est un indice réservé à l'IA. Ne mettez pas le même texte dans les deux — ai_context doit ajouter un guidage que la description ne couvre pas (désambiguïsation, pièges, quand utiliser un champ plutôt qu'un autre).

Consolidez le contexte partagé au niveau de la vue. Si plusieurs champs dans une vue partagent le même ai_context (p. ex., « toutes les valeurs monétaires sont en USD »), déplacez-le au ai_context au niveau de la vue plutôt que de le répéter sur chaque champ. Le ai_context au niveau du champ doit être spécifique à ce champ.

Exemple — avant :

dimensions:
  gross_revenue:
    ai_context: "Monetary value in USD. This is revenue before refunds."
    description: "Monetary value in USD. This is revenue before refunds."
  net_revenue:
    ai_context: "Monetary value in USD. This is revenue after refunds."
    description: "Monetary value in USD. This is revenue after refunds."

Après :

ai_context: "All monetary values in this view are in USD."

dimensions:
  gross_revenue:
    ai_context: "Revenue before refunds."
    description: "Total revenue before refunds and cancellations are applied."
  net_revenue:
    ai_context: "Revenue after refunds. Use this for profitability analysis."
    description: "Total revenue after refunds and cancellations."

Checklist d'optimisation

Priorisez les changements à haut impact. Améliorez la formulation sans changer la sémantique.

Inspectez l'état actuel avec omni-model-explorer
Vérifiez le ai_chat_topics au niveau du modèle — assurez-vous que les bons sujets sont visibles pour l'IA
Vérifiez le tableau de bord d'utilisation de l'IA pour les questions réelles des utilisateurs
Comptez les champs — curez avec ai_fields si vous approchez 550
Écrivez ai_context mappant les termes métier aux champs (gardez à 1-2 phrases)
Ajoutez synonyms aux dimensions et mesures clés (skip si elles dupliquent le label)
Améliorez les valeurs description et label des champs
Ajoutez all_values/sample_values pour les champs catégoriels
Ajoutez sample_queries pour les 3-5 meilleures questions
Supprimez la duplication entre ai_context et description ; consolidez le contexte partagé au niveau de la vue
Envisagez extends pour les variantes de sujets spécifiques à l'IA
Testez de manière itérative — interrogez Blobby et affinez

Référence de documentation

Optimizing Models for AI · Synonyms · Topic Parameters · Model YAML API · Omni AI Overview

Skills associées

omni-model-explorer — inspecter le contexte IA existant
omni-model-builder — modifier les vues et les sujets
omni-query — tester les requêtes pour vérifier la sortie de Blobby

omni-ai-optimizer