用途：通过 Omni 的 YAML API 创建和修改其语义模型，覆盖视图（.view）、主题（.topic）、维度、度量、关系与查询视图。使用前建议先用 omni-model-explorer 了解现有模型。
架构：Omni 采用分层建模：Schema 层由数据库自动生成并同步表/列结构；Shared Model 层存放可复用的维度、度量、连接与主题；Workbook 层用于工作簿内临时扩展；Branch 层用于合并前的分支开发。Schema 层是表/列结构的来源，数据库变更后需刷新 schema。
环境准备：需设置 OMNI_BASE_URL 与 OMNI_API_KEY，并具备 Modeler 或 Connection Admin 权限。写 SQL 前应据连接确定方言，可用 /api/v1/models/{modelId} 与 /api/v1/connections 查询 connectionId 和 dialect。
安全开发流程：始终在分支中工作，不直接写生产。分支是 modelKind 为 BRANCH 的模型，通过 POST /api/v1/models 创建，返回的 model.id 作为 branchId 传入后续调用；可用 GET /api/v1/models?include=activeBranches 列出分支。随后用 POST /api/v1/models/{modelId}/yaml（mode 为 extension，带 branchId 与 commitMessage）写入 YAML，再调用 /validate 校验，最后经用户确认后合并分支。Git 连接模型可选择一种工作流，避免混用产生冲突。
Schema 刷新：数据库出现新表、列增删改名或类型变化时，用 POST /api/v1/models/{modelId}/refresh 触发后台刷新，可能自动生成不需要的维度，可用 hidden: true 抑制。
编写要点：每个视图必须有 primary_key: true 的维度，否则连接查询会出现 fanout 或聚合错误；无单一唯一列时可用 sql 构造复合键。维度常用参数含 sql、label、description、hidden、format、group_label、synonyms；度量支持 filters 在聚合前过滤行，条件含 is、is_not、greater_than、less_than、contains、starts_with、ends_with。主题含 base_view、joins、ai_context、default_filters、always_where_sql、fields。关系需正确指定 relationship_type（many_to_one、one_to_many、one_to_one、many_to_many）以防 fanout。查询视图由保存查询或原始 SQL 定义，同样必须有主键。
限制与排查：常见错误包括视图名拼写、缺少连接路径、字段重名、YAML 缩进（2 空格、不可用 tab）等；模型与数据库不同步时可刷新 schema 后再校验。具体参数完整清单及其他细节参考官方文档，暂未提供更多收费或平台信息。