Auto Ontology:自动本体(3)：生产落地与治理：Helm 上云、SSO 与模型生命周期

前两篇已摸透 NVIDIA/auto-ontology 的概念与单机实操：第一篇讲本体概念与三大阶段，第二篇跑通 Compose 部署、数据源、模型三元组、认证流程、MCP 工具、三项技能、REST API、KumoRFM 预测与 Ossie 互操作。

概念清楚了、单机跑通了，今天讲怎么把它搬上生产环境。作为完结篇，本文聚焦生产落地与治理：Helm 上云、认证与权限、模型生命周期治理、评测验证与安全红线。

项目近况：NVIDIA/auto-ontology 由 NVIDIA 维护，Apache License 2.0 许可证，创建于 2026-04-27，最近推送在 2026-11-07，暂无正式 Release，未关闭 issue 约 88 个。Star 约 1 万（10,479，一日涨约 650），Fork 约 850（853）。不接受外部 Pull Request，集成与缺陷走 issue，安全漏洞按 SECURITY.md 报告。

技术栈：后端与核心库以 Python 为主，基于 FastAPI（Python 3.12+，LangChain）；前端 Next.js 16 + TypeScript；数据库 Postgres 17 + pgvector。默认模型：推理 nvidia/nemotron-3.5-lightning-30b-a3b、嵌入 nvidia/nemotron-3-embed-1b、重排 nvidia/llama-nemotron-rerank-vl-1b-v2，默认走 NVIDIA NIM，也可配任意 OpenAI 兼容端点。定位始终明确：为企业数据构建语义化、图结构的推理层，让智能体先搞懂业务含义再查数。

一、Helm 上云

Compose 适合单机体验，上 Kubernetes 跑生产推荐 Helm 部署（核实自 DEPLOYMENT.md）；两条路径共用同一套环境变量语义。

1. NGC 发布物

生产发布物托管在 NGC Catalog（nvidia 组织）下：后端 + 摄取镜像 nvidia/auto-ontology、前端镜像 nvidia/auto-ontology-frontend、MCP 镜像 nvidia/auto-ontology-mcp，外加名为 auto-ontology 的 Helm Chart。每次发布给三个镜像打上对应 Chart 版本号标签，Chart 把镜像引用钉死在该标签上，版本严格配套。

2. Helm 安装四步

在 Kubernetes 集群拉起服务只需四步：

第一步：添加并更新 NGC Helm 仓库：helm repo add nvidia 后 helm repo update；安装前可用 helm search repo nvidia/auto-ontology --versions 查看可选版本。

第二步：用编辑器写 values 文件。不要走命令行传参，以免密钥进入 shell 历史与进程参数；写完 chmod 600 锁死权限，绝不进 git。要求如下：

• 必填项：模型 API Key、Postgres 密码、管理员邮箱与密码（对应 adminEmail 与 adminPassword）。
• 可选：业务数据源连接字符串（也可启动后在界面里添加）。
• 管理员邮箱与密码必填：自助注册关闭，首次安装全靠它俩创建首个管理员账号，缺了安装直接失败（Compose 时对应 AUTO_ONTOLOGY_ADMIN_EMAIL 与 AUTO_ONTOLOGY_ADMIN_PASSWORD）。
• 外部访问须把 appUrl 设成实际访问地址。

第三步：安装并锁定版本：helm install auto-ontology nvidia/auto-ontology -f 指定 values 文件；生产加 --version 钉死版本，部署后 helm list 查看 Chart 版本。

第四步：端口转发暴露界面：kubectl port-forward svc/frontend 3000:3000，随后按配置的管理员账号密码登录。

二、认证与权限

多人协作与自动化接入需要严密的权限管控。认证底座走 Better Auth 框架，每次调用按调用者角色授权；自助注册关闭，第一个账号即启动管理员（核实自 docs/authentication.md）。

1. 四层身份解析顺序

网关在统一入口按四顺位识别调用者身份：

• 浏览器会话 cookie：前端登录后的会话凭证。
• API Token：请求头 x-api-key 或 Authorization: Bearer 传递的自动化令牌。
• 转给 MCP 客户端的 OAuth 令牌：智能体经 MCP 接入时的授权凭证。
• 受信任调用者转发的 SSO ID Token：受信任上游服务转发的单点登录身份令牌。

2. SSO 单点登录配置

单点登录在「Settings → Single Sign-On」里配置；向身份提供方（IdP）注册回调地址，即应用访问地址后接 /api/auth/sso/callback。

3. API Token 与四条准则

脚本、笔记本与定时任务脱离浏览器会话，系统为此提供 API Token：「用户菜单 → API Tokens → New token」里起名、可设过期时间（默认永不过期）；底层只存 SHA-256 哈希，明文只显示一次，丢了只能重新生成。

API Token 遵循四条严格的行为准则：

• Token 就是它的主人：没有独立权限，每次调用按主人角色授权；主人是查看者，该 Token 也只能做查看者能做的事。
• 全路由通用：所有需要认证的路由都接受 Token。
• 吊销立即生效：删 Token、删主人或封禁主人后，下一次请求立即返回 HTTP 401。
• Token 管不了 Token：创建与吊销须在浏览器已登录会话中完成；Token 泄露了也造不出后继 Token。

4. 403 含义与 MCP 只读边界

写入操作一般需要 catalog:edit 权限；请求返回 HTTP 403，意思是该账号或 Token 主人角色缺权限，不是路径写错了。

读写分离：MCP 工具完全只读；本体概念的创建、修改、模型导入与编译重置，全部走 Next.js 的 /api/... 网关；系统也没有通用的结果行回写接口。

三、模型生命周期治理

管理技能 nvidia-ontology-management（0.2.1）把治理拆成三条线：日常检查与元数据编辑走主流程；概念、关系、度量、单位、粒度、策略走建模流程；模型晋升与可复用分析结果走发布流程。

1. 语义契约十维度

改业务含义前，先把“语义契约”写清楚，涵盖十个维度：来源绑定、身份、覆盖人群、关系基数、度量表达式、单位、粒度、分母、时间、有效期与反例。任何改动（改术语名、新增 SQL 属性、导入模型等）都要先向用户说明，绝不在后台悄悄重写术语表。

2. SQL 属性校验与编译状态

创建或更新 SQL 属性前，先调 POST /api/sql-attributes/validate 校验；解析失败直接返回 HTTP 422，而不是返回 valid: false。

语义编译不是隐藏的自动副作用：改完主动调 GET /api/semantic-compilation/status 查状态。别把 POST /api/semantic-compilation/reset 当清理工具——它是异步的破坏性全库重建，返回 HTTP 202，需要 semanticCompilation:manage 权限。

3. 模型导入导出与发布门禁

跨环境迁移靠导入导出接口：

• 导出：POST /api/model/export 导出目录加语义层的 YAML（需 modelInterchange:export 权限，可指定数据库，格式原生或 Ossie）。
• 导入：POST /api/model/import 上传 multipart YAML 文件（支持原生或 Apache Ossie 格式，需 modelInterchange:import 权限；replace 默认 true、embed 默认 true）。

导入可能直接替换已有数据，replace=true 前先和用户确认、先在隔离环境试跑，再走发布门禁：

• 限定范围备份：导入前先对目标环境做限定范围的导出备份。
• 分阶段回读与 Fail Closed：导入与认证接口目前不能证明原子晋升能力；晋升须按分阶段回读走，精确回读拿不到预期状态就一律按失败处理。
• 验证看持久化结果：不只看 HTTP 请求成功；导入后须精确重导出并与源 YAML 比对，再用 check_answerable 与 ask_question 做正反检查。

4. 语义关系查询的边界

语义关系查询接口支持：术语到列、术语到 SQL 属性、表到术语与 SQL 属性、两个术语间的语义跳链、全局语义图谱。但要注意：它们反映的只是当前语义关系路径，不是生成来源、源修订记录、认证历史或版本谱系。

四、评测验证

量化验证本体层效果，分基准评测与日常巡检两层：

• BIRD 评测：用主仓库 README 提到的配套评估仓库 NVIDIA/ontology-sql-eval 跑 BIRD 文本转 SQL 评测。
• 日常正反行为检查：运维与发布后，用 MCP 的 check_answerable 与 ask_question，或 REST 接口 POST /api/question-entity-coverage 与 POST /api/chat/completions，结合业务问题集做正向（已覆盖口径能否算准）与反向（反例或未覆盖口径能否诚实拒答）检查。

五、安全运维红线

生产环境落地必须守住以下安全与运维底线：

• 隔离 3001 与 3002 端口：后端与摄取服务必须放在私有网络——后端信任前端转发的用户身份请求头，摄取服务接口没有独立鉴权；外部流量统一走 3000 端口的 Web 应用。
• 严管凭证：密钥与密码绝不进 shell 历史、绝不进 git，values 文件必须 chmod 600。
• 参考文档：DEPLOYMENT.md（Helm 部署）、docs/authentication.md（认证、单点登录与 API Token）、docs/conversation-api.md（会话 API）、docs/mcp.md（MCP 规范）、OpenAPI 文档、管理技能附带的三份参考文档。

六、适用人群与系列总结

NVIDIA/auto-ontology 适合做企业级智能体与数据分析的开发者、数据团队、需要在大模型与数据库之间加一层可信语义的架构师，以及被“智能体查数不准”困扰的团队。它不是聊天问数工具，而是替智能体补齐“上下文层”——告诉智能体数据在哪、是什么意思、能不能用、怎么用、从哪来、和什么相似。

至此三篇完结：第一篇厘清“生成、认证、回答”的本体概念与架构，第二篇跑通本地部署、数据源接入与工具调用实战，本篇补齐 Helm 上云、SSO 与 Token 权限管控、模型生命周期治理的最后一块拼图，助力团队把这套可信语义推理层落地为企业级数据基建。