Auto Ontology:自动本体(2)：从安装到认证：部署与上手实战

在上一篇《给智能体装一层可信的语义上下文》中，Auto Ontology（仓库 NVIDIA/auto-ontology）的定位是：它不是聊天问数工具，而是为企业数据构建语义化、图结构的推理层，让智能体先搞懂业务含义再去查数——即给智能体补一层「上下文层」。

概念清楚了，今天直接动手实战。NVIDIA/auto-ontology 由 NVIDIA 维护，采用 Apache License 2.0 许可证，自 2026-04-27 创建以来获 9,825 个 Star、799 次 Fork 与 1,367 次提交（暂无正式 Release，不接受外部 Pull Request，集成需求与缺陷报告走 issue，安全漏洞按 SECURITY.md 报告）。后端与核心库主要采用 Python，前端为 Next.js 16 + TypeScript。

组件与端口：前端 Next.js 16（3000）、后端 FastAPI（3001）、摄取服务 FastAPI（3002）、MCP 服务器 FastMCP（3003）、Postgres 17 + pgvector（5432），另可选 HashiCorp Vault（存连接凭证）。

一、部署实战：Docker Compose 快速上手六步走

本地用 Docker Compose 六步跑通（Kubernetes 用 Helm Chart，细节见 DEPLOYMENT.md）。前置：Docker（含 Compose v2）、uv、NVIDIA API Key（nvapi- 开头）。

第 1 步：克隆仓库与配置环境变量

克隆仓库，复制 .env.example 为 .env，填入核心键：DEFAULT_MODELS_API_KEY、AUTH_SECRET、APP_URL、POSTGRES_PASSWORD、CONNECTION_STRINGS、AUTO_ONTOLOGY_ADMIN_PASSWORD、PGADMIN_PASSWORD。注意：Compose 会把 Postgres、pgAdmin 与 Web 应用发布到宿主机，启动前须换掉默认密码；每个模型角色在 .env.example 里有单独的 key 行，不填则回落到 DEFAULT_MODELS_API_KEY。

第 2 步：启动 Postgres 并灌入示例数据库

先起 Postgres，灌入微软示例销售库 Wide World Importers：执行 docker compose up -d --wait postgres，再克隆 auto-ontology-eval 仓库，用种子脚本 seed_wwi.py 灌库（库名 wideworldimporters）。

第 3 步：构建并启动全栈服务

执行 docker compose up -d --build 构建并启动其余服务。

第 4 步：登录 Web 应用并开启语义编译

打开本地 3000 端口 Web 应用，用 .env 里的管理员账号密码登录，进「Settings → Semantic Compilation」打开语义编译；摄取在启动时已自动运行，编译随即开始，完成时提示「Semantic compilation is ready」。

第 5 步：正向提问验证（有据可查的精确回答）

在 Chat 提问验证：2015 年 6 月宾州某款 U 盘寿司卷造型食品闪存盘收入多少，答案 588.80 美元、来自 3 条发票行，附完整 SQL 与推导步骤；每个答案都展示 SQL，可查看数据行、下载 CSV 或看成图表。

第 6 步：反向提问验证（「答不了会明说」的边界感）

再问一个数据答不了的问题验证边界：示例库没有广告数据，问广告投入回报率时，经 MCP 的智能体会先做可答性检查（示例中 coverage 0.5，无术语覆盖「广告花费」），明确说算不了并反问澄清。

部署排错小贴士

重启后若左侧导航栏消失，是浏览器缓存了过期会话 cookie，清除该站点的站点数据后重新登录即可；其他问题见安装技能里的排错指南。

二、接入自己的数据源：十种引擎与两种配置路径

系统支持十种数据源引擎：PostgreSQL、MySQL、Databricks、Snowflake、ClickHouse、Trino、Apache Kyuubi、HeavyDB、DuckDB、SQLite。

添加方式有两种：界面在「Settings → Connections」里添加，或写进 CONNECTION_STRINGS。

注意：DuckDB 与 SQLite 只支持连接字符串方式。连接细节、写法、作用域与凭证存放见 docs/connections.md。

三、模型配置：四个角色与三元组设计

系统设四个功能角色加一个共享默认角色：

• DEFAULT_MODELS：共享默认，其他角色未填字段回落到它；
• REASONING：主聊天与自然语言转 SQL；
• NON_REASONING：实体抽取等较轻步骤；
• EMBED：文本嵌入；
• RERANK：检索流程里的重排。

每个角色由三元组（端点、API Key、模型名）配置。默认走 NVIDIA NIM（托管或自托管），也可配任意 OpenAI 兼容端点。推理模型默认是 Nemotron 3.5 Lightning 30B（REASONING 与 NON_REASONING 均为该模型），嵌入与重排默认走 Nemotron 系列。最省事是只填 DEFAULT_MODELS_*，有差异的角色再单独覆盖。

两条硬约束：模型须支持结构化输出；嵌入模型在摄取与查询两端须保持一致。

四、认证流程深挖：从自动生成到业务闭环

1. 本体里到底存了什么？（三种核心定义）

术语：业务概念（如客户、发票行），带描述、同义词、映射列；SQL 属性：经审核的 SQL 表达式（如利润率、滚动合计），智能体复用以保证同一指标每次算出来一致；关系：表如何连接，含桥接表。

2. 生成阶段四步：把物理库嚼成语义图谱

读源库：抽 Schema、画像列、采样值进目录；抽术语：逐表抽术语并映射到列；推关系与建议属性：从键与数据推断表间连接与桥接表，并从查询历史建议 SQL 属性；持久化落库：术语、关系、SQL 属性存入 Postgres，嵌入向量存 pgvector（示例编译 Wide World Importers 得到 31 个术语）。

3. 认证阶段三步：把自动草稿打磨成「可信黄金标准」

真题实测：用真实问题在聊天里测试，或经 MCP 的 check_answerable 与 ask_question 测试；打磨修正：在界面或 API 里打磨术语、描述与 SQL 属性；正式认证：确认无误后认证。

4. 回答阶段五步与学习闭环

意图分类与实体抽取；向量召回：用嵌入搜索召回候选术语、列与 SQL 属性；编写 SQL；校验与自愈修复：对照数据库校验过滤值与查询，失败时修复 SQL；执行与透明返回：返回答案、SQL 及推导步骤；无法支撑的问题明确说答不了。

学习闭环会把认证过的修正与使用反馈折回本体。

五、从自己的智能体调用：三种标准化接入方式

方式一：MCP 服务器（面向通用 MCP 客户端与九大只读工具）

MCP 服务器提供只读工具，每个用户经 Auto Ontology 登录、按该用户权限调用：

命令行：设 AUTO_ONTOLOGY_API_URL 后用 uvx 从 mcp 子目录运行 auto-ontology-mcp；Cursor：在 ~/.cursor/mcp.json 里配本地 3003 端口 /mcp；Claude Desktop：经 mcp-remote 桥接。

改完配置重启客户端并按提示登录，细节见 docs/mcp.md。MCP 工具共 9 个，分 4 组：

就绪检查（1 个）：check_readiness；术语类（6 个）：search_terms、get_term、get_term_columns、get_term_sql_attributes、get_sql_attribute、describe_table；可答性（1 个）：check_answerable；提问（1 个）：ask_question（返回答案、SQL 与数据行）。

方式二：编程智能体技能（面向 Coding Agents 的三项内置技能）

仓库自带三项技能，入口在 AGENTS.md：nvidia-ontology-setup：安装、接数据源、编译、验证就绪；nvidia-ontology-management：检查、建模、认证、导入导出、发布；nvidia-ontology-query：提问并验证 SQL、行与答案。

方式三：REST API（面向自研应用与后端集成）

在用户菜单下开通 API Token，调用 POST /api/chat/completions（示例请求体 {"question": "How many orders shipped last week?"}）。响应为服务器发送事件流，result 事件带答案，data: [DONE] 结束流；事件类型、多轮会话与网关信任边界见 docs/conversation-api.md，其余操作见 OpenAPI 文档。

六、进阶玩法：预测路由与开放标准互操作

1. 接入 KumoRFM 处理预测类问题

配好 KUMO_RFM_API_KEY，预测类问题路由给 KumoRFM。KumoRFM 是托管服务，回答时须把连接的表上传给它，默认最多 20 张表（KUMO_MAX_TABLES），每表行数默认不限（KUMO_MAX_ROWS_PER_TABLE）。启用前须先审查会发送什么数据并完成组织的数据评审。

2. 兼容 Apache Ossie 实现语义模型互操作

兼容 Apache Ossie（交换语义模型的开放标准），可在设置里导入导出模型定义，或调用接口 POST /api/model/import、POST /api/model/export；跑 BIRD 等文本转 SQL 评测可参考仓库提到的本体 SQL 评估仓库。

七、安全与运维红线：生产落地的必读清单

3001 与 3002 端口应放在私有网络。

鉴权边界：后端（3001）信任前端（3000）转发的用户身份请求头，摄取服务（3002）的接口（摄取、删除、重置、编译）没有独立鉴权，客户端应走 3000 端口的 Web 应用。

参考文档：DEPLOYMENT.md（Helm 部署）、docs/connections.md（连接与 Vault）、docs/authentication.md（认证、单点登录、API Token）、docs/conversation-api.md（会话 API）、docs/mcp.md（MCP）、OpenAPI 文档。

八、适用人群与实战小结

这个项目适用于企业级智能体/数据分析开发者、数据团队、需要在大模型与数据库之间加一层可信语义的架构师，以及被「智能体查数不准」困扰的团队。通过「生成四步 + 认证三步 + 回答五步」闭环与三种接入方式，它把物理表沉淀为兼容 Apache Ossie 的可信语义上下文，让查数走向可控与可信。