用途：通过 Omni Analytics 的 YAML API 创建和编辑语义模型，覆盖视图（views）、主题（topics）、维度（dimensions）、度量（measures）、关系（relationships）与查询视图（query views）。建议先使用 omni-model-explorer 了解已有模型。
使用前提：设置环境变量 OMNI_BASE_URL 与 OMNI_API_KEY，并具备 Modeler 或 Connection Admin 权限。不确定接口或参数是否存在时，可先获取 OpenAPI 规范： curl -L "$OMNI_BASE_URL/openapi.json" -H "Authorization: Bearer $OMNI_API_KEY"
安全开发流程：始终在分支上操作，不要直接写生产。先向分支写入 YAML（POST /api/v1/models/{modelId}/yaml，含 fileName、yaml、mode: "extension"、branchId、commitMessage），branchId 为 UUID，可从 List Models 端点加 ?include=activeBranches 获取，不存在时会自动创建；再进行校验（GET /api/v1/models/{modelId}/validate?branchId={branchId}），返回 message、yaml_path 等错误与警告及可能的 auto_fix；最后合并分支（POST /api/v1/models/{modelId}/branch/{branchName}/merge）。合并前必须向用户确认，因为会应用到生产模型且不易撤销；若配置了必需 PR 的 git，则改用 git 流程。
文件类型：视图 .view、主题 .topic 及全局关系定义。使用 mode: "extension" 写入共享模型层，发送空 yaml 可删除文件。视图可定义维度与度量；度量 filters 可在聚合前限定行，支持 is、is_not、greater_than、less_than、contains、starts_with、ends_with。主题包含 base_view、joins、ai_context、default_filters、always_where_sql、fields 等元素。关系需指定 join_from_view、join_to_view、on_sql、relationship_type（many_to_one、one_to_many、one_to_one、many_to_many）与 join_type；类型正确可避免扇出与对称聚合错误。查询视图为基于保存查询或原始 SQL 的虚拟表。
常见校验错误包括视图不存在、无连接路径、字段重名、YAML 语法错误（缩进用 2 空格、不用制表符）。更完整的维度、度量参数与文档参考见相关资料。