NVIDIA Auto Ontology：给智能体一套可验证的数据语义层

目录与语义编译

语义层不是靠一次提示词凭空生成。Auto Ontology 的编译流程先读取数据库目录，再对表进行受控采样。默认情况下，每张表最多抽取 1,000 行，用来发现实际取值、候选枚举和潜在关系。低基数文本列可以使用带数量上限的 DISTINCT 查询，避免把高基数标识符当成类别字段。采样是有限的，所以目录反映的是被检查过的样本，而不是对全库分布作出统计保证。

在结构层面，编译器会收集表、列、键与约束，尝试识别外键关系，并发现桥接表。名称相似的列并不自动等于可连接关系；候选关系仍需要进入目录，供后续审核或查询规划使用。桥接表的识别尤其重要，因为多对多关系往往没有直接外键路径，单纯根据表名很难稳定推断。

在解释层面，三个工作进程可以并发执行昂贵的语言模型抽取。每种抽取任务的并发还受 SEMANTIC_LLM_MAX_INFLIGHT 控制，默认值为 6。这个配置限制的是同时在途的模型请求，不等于数据库连接数或工人数。生产环境需要同时考虑模型额度、数据库采样负载和任务队列，不能只根据工作进程数量估算容量。

编译结果会生成术语、描述、关系和 SQL 属性。术语负责业务概念到列的归一，关系负责可追踪的连接路径，SQL 属性负责把指标或过滤条件固化成可审查的表达式。写入时按规范表顺序提交，减少不同编译任务之间因提交次序产生的非确定性。单表编译失败会被记录下来并跳过，其余表继续处理；这种方式提高了部分成功的可用性，但也要求管理员查看失败清单，不能把“任务结束”误认为“所有表都已完成”。

人工认证与来源可信度

自动生成可以扩大覆盖范围，却不能替代责任归属。Auto Ontology 允许人工编辑并认证术语名称、描述及 SQL 属性。认证后的定义是智能体可依赖的承诺：一个指标表达式为什么这样写、一个术语为什么对应这些列、哪些连接关系已经过业务确认，都可以回到目录中检查。

这种设计把“模型是否自信”换成了更可审计的问题：答案使用了哪些语义定义，这些定义是否经过认证，查询工具是否确认目录已经编译完成，目标数据库连接是否仍然可用。它不会自动让定义正确，但能把定义质量变成可管理的工程对象。对于财务、运营或客户指标，认证流程应当优先覆盖高频术语、容易混淆的枚举以及跨表连接，而不是只追求目录中条目数量。

编译时的模型输出应当被视为候选材料。语言模型可能把相似列合并错，也可能从少量样本中过度概括枚举。迁移数据库后、业务规则改变后或新增重要表后，需要重新编译并复核受影响的已认证资产。认证记录不是永久正确性的证明，而是对某个时间点语义内容的明确责任。

从问题到 SQL 的受控链路

查询请求不是直接从自然语言跳到执行。系统先识别用户意图，抽取问题中的实体，再从语义目录检索相关术语、列属性、表描述和关系。候选整理阶段会准备可用的表、列和连接路径，随后才进入 SQL 构造。

生成的 SQL 会经过语法与执行前检查，在失败时进入有限次修复。如果一次尝试完全无法构造 SQL，系统会从不可变的原始请求状态重新开始一次，而不是继续在已经偏离的中间结果上叠加修改。仍然无法构造时，返回明确的 SQL cannot be constructed.，避免把一段看似合理但没有语义依据的 SQL 交给数据库执行。

执行结果为空时还有一次基于相同请求状态的修复机会。这个设计针对的是连接条件、过滤范围或字段选择可能造成的空结果，而不是无限重试。有效防护来自停止条件：修复次数有界、请求状态可回溯、执行前有检查，失败时能返回可识别的拒绝，而不是把不确定性隐藏在最终答案中。

实体覆盖率是一个容易被误解的指标。它用已经覆盖的抽取实体数量除以抽取实体总数，只有列属性匹配才会让实体计入覆盖。SQL 属性本身和自定义分析不会自动提高覆盖率。因此，当界面显示覆盖充分时，仍要检查关键业务实体是否被具体列定义支持；反过来，一个复杂分析即使执行成功，也不代表问题中的每个实体都找到了可信映射。

九个只读 MCP 工具

MCP 是 Auto Ontology 面向智能体的主要接口之一，但项目刻意没有把数据库浏览能力整套暴露出去。服务提供九个经过筛选的只读工具：check_readiness、search_terms、get_term、get_term_columns、get_term_sql_attributes、get_sql_attribute、describe_table、check_answerable 与 ask_question。

前八个工具帮助智能体确认目录状态、搜索业务术语、读取术语对应的列与 SQL 属性，并理解相关表。它们不提供任意 schema 列表、表枚举、原始列扫描或数据库执行入口。ask_question 则把自然语言问题交给完整的受控查询链路，并把结果限制为最多 100 行，同时返回 row_count 与 truncated，让调用方知道结果是否被截断。

这种工具面比“给智能体一个 SQL 执行器”更窄，却更容易建立边界。智能体必须通过术语和关系表达自己的信息需求，服务可以统一实施校验、修复、行数限制与错误返回。对于需要自定义 SQL 或复杂分析的工作流，项目仍可通过 HTTP API 提供能力，但 MCP 明确服务于可发现、可回答、可追溯的只读问答。

check_readiness 会检查语义目录是否已完成编译、实时数据库连接是否可用以及目录是否可读取。若查看者没有管理员权限，读取连接信息可能得到 403，此时状态应视为“未验证”，不能解释成“系统未就绪”。这个区别很重要：权限不足只说明当前身份无法确认连接状态，不代表数据库连接一定失败。

连接器、模型角色与可替换性

连接器覆盖 PostgreSQL、MySQL、Databricks、Snowflake、ClickHouse、Trino、Apache Kyuubi、HeavyDB、DuckDB 和 SQLite。不同数据库在目录查询、类型系统、SQL 方言与连接限制上差异很大，因此“支持某个连接器”仍要在真实数据库版本和权限模型下验证。只读账号、网络白名单和查询超时应当由部署方配置，不能依赖模型自行遵守。

模型角色分为 REASONING、NON_REASONING、EMBED 和 RERANK。推理模型承担语义抽取和查询规划，非推理模型处理较机械的生成步骤，嵌入模型用于目录检索，重排模型用于改善候选顺序。默认配置面向 NVIDIA NIM 与 Nemotron，但项目支持 OpenAI 兼容端点。

更换模型时，最容易出错的是嵌入模型。编译阶段写入的向量必须与查询阶段使用的嵌入模型和维度保持一致；只替换查询侧模型，会让目录检索失真甚至无法匹配。升级模型前应当规划重新嵌入的范围，并在切换后重新验证术语检索与关键问答。

部署时需要明确的边界

项目支持 Apache Ossie 语义模型的导入与导出，便于把语义定义纳入版本管理或迁移到兼容工具。可选 KumoRFM 功能会把已连接的表上传到托管预测服务，默认最多上传 20 张表。启用这个功能前必须确认数据分类、表范围、托管区域与组织的数据出境政策；这是独立于本地文本转 SQL 的数据流向。

Auto Ontology 没有在本仓库中给出可直接引用的统一性能基准。仓库链接了外部评估项目，但评价一个部署仍需使用自己的数据库、自己的术语、自己的模型和真实问题集。可以测量目录认证覆盖率、关键实体命中率、不可构造请求比例、空结果修复成功率、查询延迟与人工纠错成本，但不应把架构描述当成性能结论。

从工程视角看，最适合先落地的范围是一个权限清晰、术语稳定、问题重复度高的数据域。先把关键表、枚举和连接关系整理成经过认证的术语与属性，再让少量智能体通过 MCP 调用。观察失败问题，补充语义定义，再扩大表范围。这样得到的是可审查的数据语义资产，而不是一次性生成、之后无人维护的 schema 摘要。

项目不接收外部 pull request，部署与扩展应以 Apache-2.0 许可证允许的本地分支和集成为准。它的价值也不在于替代数据库或 BI 平台，而在于把“智能体凭什么理解这些数据”变成可以编译、检索、认证、查询和追溯的系统能力。