omni-ai-optimizer

Omni AI 优化器

优化 Omni 语义模型，让 Blobby（Omni Agent）返回准确且符合上下文的答案。

提示：进行更改前，使用 omni-model-explorer 检查当前 AI 上下文。

前提条件

# Verify the Omni CLI is installed — if not, ask the user to install it
# See: https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Show available profiles and select the appropriate one
omni config show
# If multiple profiles exist, ask the user which to use, then switch:
omni config use <profile-name>

# Confirm the active profile is authenticated and inspect your permissions:
omni whoami whoami

身份验证：配置文件通过 API key 或 OAuth 进行身份验证。如果 whoami（或任何调用）返回 401，请交由用户处理——让用户运行 ! omni config login <profile>（OAuth 2.1 浏览器流程；浏览器会阻塞约 2 分钟）。在无头/CI 会话中不要自行运行 config login（没有浏览器 → 超时）；在本地交互式机器上则可以运行。有关配置文件设置（omni config init --auth oauth）以及使用 --schema 探索命令和请求正文格式，请参阅 **omni-api-conventions** 规则。

需要 Modeler 或 Connection Admin 权限。

探索命令

omni models --help                    # List all model operations
omni models yaml-create --help        # Show flags for writing YAML

提示：使用 -o json 强制输出结构化数据，以便进行程序化解析；使用 -o human 输出易读的表格。默认值为 auto（在 TTY 中输出人类可读内容，通过管道传递时输出 JSON）。

安全的模型写入默认做法

• 先创建分支——除非用户明确要求更改生产环境，否则绝不要将 AI 优化 YAML 直接写入共享模型。创建或使用模型分支，然后将分支 ID 传递给 omni models yaml-create。
• 写入前先读取——添加 ai_context、ai_fields、sample_queries、描述或同义词前，先检查当前主题/视图 YAML。如果请求的优化已经存在，应说明它已配置，而不要重复添加。
• 针对主题的请求应在主题层处理——用户要求改进主题时，优先使用主题级 ai_context、ai_fields 或 sample_queries。只有在请求明确涉及某个特定字段的其他名称时，才使用字段级 synonyms。
• 主题映射完整后，不要再添加“辅助”同义词——对于“Blobby 把收入和订单数弄混了”或“正确映射这些术语”之类的请求，如果主题级 ai_context 已将业务术语映射到正确字段，并包含所需的反向约束，就应停止并说明无需重复写入。在这种情况下添加字段级同义词属于冗余，会增加提示词/令牌的负担。
• 使用 --name 创建分支——omni models create-branch <model-id> --name <branch-name> 不接受 JSON 格式的 --body。

Blobby 的工作方式

上下文优先级顺序

Omni 按以下顺序组装上下文窗口：

1. Omni Engineering 预先构建的上下文和调优内容
2. 模型、主题和视图上的 ai_context
3. 主题 description
4. 主题 name 和 base_view
5. 优先保留的字段属性——name（完全限定名，view.field）和字段 ai_context。永不裁剪。
6. 可裁剪的字段属性——其余所有属性；空间不足时按以下顺序删除。

hidden: true 的字段会被完全排除。模型级 ai_chat_topics 控制 Blobby 能看到哪些主题。

裁剪顺序

当某个主题的元数据超出分配额度时，Omni 会从优先级最低的属性开始删除：先从每个字段中移除当前属性，再处理下一个：

all_values → sql → sample_values → description → group_label → label → aggregate_type → data_type → synonyms

需要牢记两点：

• 最先删除 all_values，因为 AI 可以按需获取字段值。最后删除 synonyms，因为它们在将用户用语匹配到字段时作用最大。
• Omni 为特定主题组装上下文时，绝不会裁剪 ai_context——无论它位于哪个层级（模型、主题、视图、字段）。如果仍然放不下，Omni 会从模型搜索中删除整个视图；再超出后，请求就会失败并返回错误。臃肿的 ai_context 并非无关紧要的开销——它可能挤占字段元数据，甚至直接导致查询失败。唯一的例外是主题选择，此时会先裁剪视图级 ai_context（见下方的上限表）。

上下文是指导，而非指令

所有上下文都会一并传递给大模型，由大模型决定如何衡量各项内容的权重：

• 模型级 ai_context 并不能可靠地覆盖主题级 ai_context。 不要依赖无法保证的优先级来设计。
• 指令可能只会部分执行，也可能完全不执行，尤其是在指令复杂或自相矛盾时。
• 行为具有非确定性——同一个问题在不同运行中可能会调用不同的上下文。

与其编写详尽的规则手册，不如优先采用少量明确且互不冲突的指令。使用 workbook inspector 调试 AI 实际收到的内容。

上下文的适用范围

上下文的适用范围不仅限于 Omni Agent，还包括嵌入式聊天（包括主题选择和模型搜索）、Workbook Agent 查询／SQL 生成、Dashboard Agent 摘要、AI 可视化和摘要生成、AI 筛选器生成，以及 Modeling Agent。上下文变更会影响上述所有功能。

编写 ai_context

通过 YAML API 添加：

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",
  "branchId": "{branchId}",
  "commitMessage": "Add AI context to order transactions topic"
}'

优质 ai_context 的特点

术语映射——将业务语言映射到字段名称：

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

数据细节——解释字段名称中不明显的信息：

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.

对于“正确映射这些术语”或“Blobby 把 X 和 Y 搞混了”这类问题，解决方法是在主题级 ai_context 中添加正向映射——仅靠同义词无法裁定两个相互竞争的指标。如果已有同义词，但主题上下文只说明了不要使用什么，就应补上缺少的正向映射，而不是再添加更多同义词。

正确示例：

ai_context: |
  "revenue" or "sales" -> order_items.total_revenue
  "order count" or "number of orders" -> order_items.count
  Never use order_items.count when the user asks for revenue.

不要只停留在：

measures:
  total_revenue:
    synonyms: [revenue, sales]
  count:
    synonyms: [order count, orders]

行为指导——指出常见的处理模式：

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

角色提示——设定分析视角：

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

保持上下文简洁

ai_context 是 Omni 在资源紧张时无法回收的属性，因此它是模型中最稀缺的预算，而不是最充裕的。冗长的条目会优先挤掉字段元数据，最终还可能导致请求失败。

• 每条 ai_context 以 1-2 句话为目标。重点说明如何消除歧义和需要注意的问题，而不是泛泛解释。
• 标签应简短易懂——避免冗余修饰（例如，将“订单总收入金额”简化为“总收入”）。
• 将冗长的 description 改写得直接明了。如果描述只是重述字段名称，就删掉。

模型级上下文

模型级 ai_context 提供适用于所有主题的共享指导，也会影响主题选择——当 Blobby 选错主题而非选错字段时，这一点很有用。

将其用于整个实例通用的约定（货币、财年、语气、隐私规则），并将特定于主题的映射保留在主题中。

此外，还有一个模型级 sample_queries 参数，用于提供涵盖模型多个主题的示例查询。

高级 ai_context 模板

以下内容仅适用于模型、主题和视图级别的 ai_context。

使用用户属性进行个性化设置

在查询时，{{omni_attributes.<attribute_name>}} 会替换为当前用户的属性值：

ai_context: |
  You are a sales analyst. When someone asks about their team or pipeline,
  always filter by account.segment = {{omni_attributes.segment}}
  and account.region = {{omni_attributes.region}}.

注意：维度或度量的 ai_context 不支持此功能——此处的值会按原样使用，不进行替换。字段引用和筛选条件也不受支持，并会触发验证警告。

使用 omni_llm 定向指定模型层级

将指令限定到 AI 模型层级——smartest、standard 或 fastest——避免昂贵的推理指令拖慢快速模型。区段使用 Mustache 语法：{{# ... }} 表示“当……时”，{{^ ... }} 表示“当……不成立时”。

ai_context: |
  This topic focuses on financial transactions.

  {{# omni_llm.smartest }}
  For complex multi-table queries, consider indirect relationships and provide rationale for join path selection.
  {{/ omni_llm.smartest }}

  {{# omni_llm.fastest }}
  Prefer single-table queries when possible.
  {{/ omni_llm.fastest }}

使用 omni_agent 指定目标 Agent

将上下文限定为将要读取它的 Agent，避免特定 Agent 的大量内容挤占其他 Agent 的窗口：

• analyze — 模型搜索和查询生成
• build — 主题元数据生成、从对话中学习
• simple_summarize — 磁贴／可视化摘要、查询元数据

ai_context: |
  {{# omni_agent.build }}
  Modeling conventions: Always define primary keys. Use snake_case for field names.
  {{/ omni_agent.build }}

  {{^ omni_agent.build }}
  Keep queries focused and efficient.
  {{/ omni_agent.build }}

{{ omni_agent.name }} 会插入读取该内容的 Agent 名称。

使用常量复用内容块

定义一次 constants，然后在模型、主题、视图和示例查询的 ai_context 中通过 @{constant_name} 引用——解决同一段语气、隐私或领域说明在十几个地方重复的问题：

constants:
  tone:
    value: "Keep responses concise and professional."
  privacy_high:
    value: "Never show individual customer names or emails."

ai_context: |
  @{tone} @{privacy_high}

使用 ai_fields 精简字段

实际限制

Omni 会限制模型元数据可占用的上下文窗口大小。触发精简的是这些上限，而不是模型的完整上下文窗口：

上限	值	超出后的处理方式
一个主题的字段定义	约 75K 个字符	按照精简顺序精简字段属性
主题选择摘要（所有主题）	约 100K 个字符	首先精简视图元数据（包括视图级 ai_context），然后精简示例查询，最后才精简主题元数据。选中主题后，会恢复被精简的详情。
在主题之外进行搜索	每次搜索 100 个字段	AI 会改为进行范围更窄的重复搜索，而不是精简属性。在启用 query_all_views_and_fields 时适用。

不要以字段数量为优化目标。 注释较少的字段约占 100 个字符；包含丰富说明、示例值和 ai_context 的字段则会占用数倍空间，因此可容纳的字段数量差异很大。请查看工作簿检查器，了解实际传递的上下文，而不是自行估算。

对话历史单独计算预算——请参阅 conversation_prune_length。

精简字段

精简时要注重准确性，而不只是缩减大小：字段集合越精简、描述越清晰，AI 选错字段的机会就越少。针对大型模型减少噪声：

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

# Or explicit list
ai_fields:
  - order_items.created_at
  - order_items.total_revenue
  - order_items.count
  - users.name
  - users.state
  - products.category

运算符与主题 fields 相同：通配符（*）、否定（-）、标签（tag:）。

使用标签是最易于维护的做法——为用户实际询问的字段添加标签，然后用一个选择器进行精简：

ai_fields: [tag:use_for_ai]

使用 ai_chat_topics 控制主题可见性

ai_chat_topics 是模型级属性，用于控制 Blobby 可以看到哪些主题：

• 没有 ai_chat_topics 属性（默认）——Blobby 可以跨所有主题查询。
• ai_chat_topics: []（空列表）——Blobby 无法查询任何主题。这实际上会停用该模型的 AI 聊天功能。
• 显式列表——只有列出的主题（或匹配的标签）可用。支持 all_topics、标签选择器（tag:customer_facing）和否定（-tag:internal、-staging_events）。

请先检查此项——如果某个主题不在 ai_chat_topics 中，那么无论在该主题上设置多少 ai_context 或 ai_fields 都没有作用。使用 omni-model-builder 修改此属性。

添加 sample_queries

通过示例教会 Blobby。对于重复出现的问题，以及 Blobby 容易处理错误的日期筛选模式，这种方式尤其有效。

支持的编写方式是通过工作簿：构建一个能返回正确答案的查询，然后选择 Model > Save as sample query to topic。勾选 Include in AI context（否则它只会显示在主题概览中，不会传递给 AI），并填写可选的 Prompt 和 AI context 字段。

若要直接在 YAML 中编写，则先在工作簿中构建正确的查询，获取其结构，然后将其添加到主题中：

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

注意：从 Omni 工作簿导出查询时，你会得到包含 table、join_paths_from_topic_name 和使用 column_name/sort_descending 的 sorts 的 JSON。按以下方式将它们映射到 YAML：

• table → base_view
• join_paths_from_topic_name → topic
• column_name → field，sort_descending → desc
• 工作簿 JSON 包含 filters、pivots、limit、column_limit，你可以将它们包含在 YAML 中（不过筛选语法需要直接查阅 Model YAML API 文档）

重点关注用户实际会提出的问题——如果你不知道有哪些，就询问用户，不要猜测听起来合理的问题。

AI 专用主题扩展

使用 extends 为 Blobby 创建一个精选的主题变体：

# 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]

扩展主题会继承基础主题的连接和筛选条件，因此只添加有差异的内容：范围更窄的字段集、额外的 ai_context 或 sample_queries（格式同上）。

改进字段描述

将值列表放在 all_values 中，将仅供 AI 使用的规则放在 ai_context 中——如果描述重复了其中任意一项，就是在为同一个事实重复付出代价：

dimensions:
  status:
    label: Order Status
    description: Current fulfillment status of the order.
    all_values: [complete, pending, cancelled, returned]
    ai_context: Use 'complete' for revenue calculations.

枚举分类字段的值

对于封闭集合的枚举，使用 all_values，让 Blobby 知道所有有效的筛选值：

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

对于不适合列出完整值的开放式分类字段，使用 sample_values 提供有代表性的示例：

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

注意：all_values 会最先被裁剪，因此不要指望它在上下文空间紧张的主题中保留下来——应将所有关键内容放在 ai_context 中。

启用 dbt 集成后，dbt 的 accepted_values 测试会自动作为 all_values 导入——手动编写前请先检查。

添加同义词

映射其他名称、缩写和特定领域术语，让 Blobby 将用户查询匹配到正确的字段。维度和度量均适用。

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]

同义词与 ai_context 的区别：字段级名称映射使用 synonyms。主题级行为指导、数据细节和多字段关系使用 ai_context。

何时添加——只有当用户确实会说出模型中没有的词语（AOV、top line、basket size）时，同义词才有价值。重复字段的标签或名称，或重复主题级 ai_context 已建立的映射，都没有价值。对于在主题层面已解决歧义的字段，再添加同义词是这项技能中最常见的无效写入——请参阅安全的模型写入默认值。

裁剪顺序：synonyms 在 description 和 label 之后最后被裁剪。因此，对于确实需要替代词汇的字段，同义词是最耐久的存放位置——但这种耐久性是选择同义词而不是用描述来实现这一目的的理由，绝不是添加更多同义词的理由。

避免重复

ai_context 和 description 面向不同的受众。description 面向用户（显示在字段选择器和文档中）。ai_context 则是仅供 AI 使用的提示。不要在两者中放入相同文本——ai_context 应补充 description 未涵盖的指导（消除歧义、注意事项、何时使用某个字段而非另一个字段）。

在视图级别整合共享上下文。 如果视图中的多个字段共享相同的 ai_context（例如，“所有货币值均以 USD 计”），请将其移到视图级别的 ai_context，而不是在每个字段上重复。字段级别的 ai_context 应针对该字段。

将共享事实提升到视图级别，让 description 和 ai_context 各自只包含对方未涵盖的内容：

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."

优化清单

优先处理影响较大的改动。改善措辞，但不要改变语义。

1. 使用 omni-model-explorer 检查当前状态
2. 检查模型级别的 ai_chat_topics——确保 AI 能看到正确的主题
3. 使用 ai_fields 精选字段，仅保留用户实际会询问的字段，而不是追求特定字段数量
4. 编写 ai_context，将业务术语映射到字段（限 1-2 句话；它永远不会被删减）
5. 为关键维度和度量添加 synonyms（如果与标签重复，则跳过）
6. 改进字段的 description 和 label 值
7. 为分类字段添加 all_values/sample_values
8. 为最常见的 3-5 个问题添加 sample_queries
9. 移除 ai_context 和 description 之间的重复内容；在视图级别整合共享上下文，并将共享代码块整合到 constants
10. 考虑使用 extends 创建面向 AI 的主题变体
11. 使用 omni_llm / omni_agent 限定针对不同层级或 Agent 的指令范围，避免每次请求都为其付费
12. 迭代测试——询问 Blobby 并进行调整

排查顺序：当 Blobby 的回答有误时：确认主题可访问（ai_chat_topics）→ 确认字段已纳入上下文（工作簿检查器；检查它是否因 ai_fields/hidden 而被删减或排除）→ 然后添加或强化 ai_context。如果 AI 根本没有收到某个字段的上下文，再为该字段编写更多上下文也毫无作用。

AI 模型建议

Omni 可以自行生成模型改进建议（CLI ≥ 1.1.2，omni ai-model-suggestions --help）。将这些建议作为上述手动清单的补充——应用之前逐条审核：

# Kick off a generation run, then read it back
omni ai-model-suggestions model-suggestions-generate <modelId>
omni ai-model-suggestions model-suggestions-run-latest <modelId>
omni ai-model-suggestions model-suggestions-run-get <modelId> <runId>

# Work the suggestion list
omni ai-model-suggestions model-suggestions-list <modelId>
omni ai-model-suggestions model-suggestions-ignore <modelId> <suggestionId>
omni ai-model-suggestions model-suggestions-restore <modelId> <suggestionId>
omni ai-model-suggestions model-suggestions-delete <modelId> <suggestionId>

# Recurring generation
omni ai-model-suggestions model-suggestions-schedule-enable <modelId>
omni ai-model-suggestions model-suggestions-schedule-disable <modelId>

Agent 技能

技能是一组已保存的指令；当用户调用其斜杠命令句柄（例如 /quarterly-report）时，Omni Agent 会加载这些指令。ai_context 会影响某个主题下的每个回答，而技能则封装一项可重复执行的任务。使用 omni skills 管理技能（CLI ≥ 1.3.1；目前为实验性功能，因此字段仍可能变更）。使用 create / update 时，通过 --schema 指定正文。

omni skills list                                   # bodies omitted
omni skills list --identifier quarterly-report     # filter by handle; exact match, still returns a list
omni skills list --q revenue                       # free-text search (CLI ≥ 1.4.0)
omni skills get <skillId>                          # includes the body
omni skills create --body @skill.json              # name, identifier, description, body
omni skills update <skillId> --body '{ "body": "…" }'
omni skills delete <skillId>

• list 的结果仅限于调用者可见的范围。 组织管理员可以看到组织中的所有技能；其他人只能看到自己的技能，而 --creator-id / --q 只会进一步缩小范围，不会扩大范围。非管理员密钥返回空列表，并不能证明没有技能占用了某个句柄——如果其他人的技能已占用该句柄，create 仍会返回 409。
• list 永远不会返回 body。 使用 get 读取技能的指令，而不是从列表中读取。
• Agent 会根据 description 在不同技能间进行选择，因此应像编写优质 ai_context 一样编写它：说明技能的用途和适用场景。
• delete 是软删除：技能会从所有读取结果中消失，其句柄也可供重复使用。

文档参考

• 为 Omni AI 优化模型
• ai_context 参考：模型 · 主题 · 视图
• 主题参数：ai_fields · sample_queries · extends · 所有主题参数
• 模型参数：ai_chat_topics · constants · sample_queries · query_all_views_and_fields · conversation_prune_length
• 同义词 · 用户属性 · 工作簿检查器
• 模型 YAML API · Omni AI 概览 · AI 数据安全

相关技能

• omni-model-explorer — 检查现有 AI 上下文
• omni-model-builder — 修改视图和主题
• omni-query — 测试查询以验证 Blobby 的输出