NVIDIA 这个项目在 README 开头放了一句很硬的话：*a revenue metric answered faster is worth nothing if the number is wrong*。它接着给了两个例子，一个能答，一个拒绝答。

能答的那次，问的是 2015 年 6 月宾夕法尼亚州「USB food flash drive - sushi roll」的收入。系统给出 `$588.80，来自 3 条 invoice lines`，附上一条六表 JOIN 的 SQL，以及它解析出的术语和连接路径。拒绝的那次，问的是同一款产品的广告支出回报率：样例库里没有广告数据，MCP 客户端先跑了一次 `check_answerable`，得到 `coverage 0.5`，然后回复「这份数据没有广告支出，算不出 ROAS，要不要换成 2015 年 6 月的收入，或者广告支出在另一个数据源里？」

第二个例子才是这个项目的主题。它把「这题在不在范围内」做成了一次独立、便宜、可解释的判断，放在写 SQL 之前。整个仓库 434 个 Python 文件、约 12.2 万行代码，多数力气都花在让答案值得信上。本文按三道闸门来拆：能不能答、答得对不对、以及把结果交给 agent 时守住什么边界。

## 一、先有一层编译过的语义

Auto Ontology 接在数据库之上，把元数据编译成一张语义图，存进 Postgres，向量放 pgvector。图里三类定义：

- **Terms**：`Customer`、`Invoice Line` 这类业务概念，带描述、同义词，映射到真实列。
- **SQL attributes**：挂在术语下、经过审阅的 SQL 表达式，比如毛利率、滚动累计。agent 直接复用，同一个指标每次都按同一套算术算。
- **Relationships**：表怎么 JOIN，含桥表，从键和数据里推出来。

流程分三段。**Generate**：读 schema、profile 列、采样值；逐表抽术语并映射列；推 JOIN 和桥表，还会从查询历史里建议 SQL 属性；最后写入本体。一次 Wide World Importers 编译出 31 个术语。**Certify**：人拿真实问题去试，改术语、描述和 SQL 属性，确认后逐个认证 `name` / `description` / SQL 属性。**Answer**：意图分类 → 抽实体 → 向量召回候选 → 写 SQL → 校验字面值与查询 → 执行 → 连 SQL 和步骤一起返回。模型定义可以通过 Apache Ossie 的 YAML 导入导出。

组件是标准的一套微服务：Next.js 前端 3000、FastAPI 后端 3001、ingestion 3002、MCP 3003、Postgres 17 + pgvector，Vault 可选。数据源列了十种（PostgreSQL、MySQL、Databricks、Snowflake、ClickHouse、Trino、Kyuubi、HeavyDB、DuckDB、SQLite），推理走 NVIDIA NIM 的四个模型角色（`REASONING` / `NON_REASONING` / `EMBED` / `RERANK`），每个角色用 `_ENDPOINT` / `_API_KEY` / `_MODEL` 三元组配置，没填的字段回落到 `DEFAULT_MODELS_*`。

## 二、第一道闸门：这题能不能答

`check_answerable` 对应一条独立的 LangGraph 流水线，只有三步：一次 LLM 调用完成问题清洗和实体抽取，做向量召回，然后**确定性地**打分。

抽取那一步的 prompt 写得很具体：保留品牌名、产品名和描述性常量，丢掉数字字面量、日期和数值阈值；几个词共同描述一个可过滤项时合成一个短语。打分那一步在 `entity_coverage/agents/coverage.py`，逻辑简单到可以一眼看完：

```python
def _compute_coverage(entities, col_attr_hits):
    if not entities:
        return 0.0
    return len(_covered_entities(entities, col_attr_hits)) / len(entities)
```

召回结果先按距离阈值过滤（`DEFAULT_MAX_DISTANCE = 0.75`），命中的候选再回库补齐属性名、所属术语。覆盖率就是被覆盖的实体数除以抽出的实体数。响应体是 `coverage` 加 `candidates`，还可以显式返回 `uncovered_entities`——**没有覆盖的实体是数据，不是让模型自己体会的暗示**。所以 README 里那句「no term covers "ad spend"」才说得出来。

MCP 的 `INSTRUCTIONS` 把这道闸门放在工作流第二步，理由写在工具描述里：`check_answerable` 比 `ask_question` 便宜得多，后者要跑一整条 text-to-SQL agent。一次答不上来的问题，代价从几分钟的模型调用降成一次召回加一次除法。

## 三、第二道闸门：SQL 写出来之后一路自检

真正写 SQL 的图有 16 个业务节点，从 `question_intent` 走到 `format_and_respond`，中间挂了一串检查：

```txt
question_intent → question_extraction → retrieve_candidates
  → prepare_candidates → refine_evidence → construct_sql_from_candidates
  → validate_sql_values → validate_sql_query → [precheck_combined]
  → execute_sql_query → check_empty_like_result → check_value_repair
  → format_and_respond
         ↘ reconstruct_sql（检查失败时回炉，再回到校验）
```

生成节点按情况先去两道校验之一，两者最终都汇到 `validate_sql_query`；通过后若装了预检节点就走它，再执行。三个预执行检查（字面值、JOIN 路径、JSONB key 路径）被合并成**一个** `precheck_combined` 节点。代码注释给了理由：一条 SQL 同时踩中多个检查时，只付一次重构往返，不需要每个检查各修一轮。它们由 `DB_PROBE_PROACTIVE`、`DB_PROBE_JOIN_PATH_CHECK`、`DB_PROBE_JSONB_PATH_CHECK` 三个开关控制，建图时决定装不装。执行之后挂着 `check_empty_like_result` 和 `check_value_repair` 两级软检查，空结果会触发回库核对真实值再重写。注释里把这条设计说得很清楚——**连库取值是修复信号，不常驻上下文**。

重试这里有个我觉得最值得抄的细节，检查被分成硬软两级：

```python
MAX_RECONSTRUCTION_ATTEMPTS = 7          # 硬上限，超过就 unconstructable
INTENT_VALIDATION_SKIPPED_AFTER = 5      # 软检查到此放行
```

`route_sql_validation` 数 `failed_attempts`，到 7 次就走 `unconstructable_sql_response`。而 `_make_soft_check_router` 走另一条路：到第 5 次之后，软检查即使还在报 `invalid_sql` 也直接放行，让 SQL 原样过去。它的 docstring 解释了原因——一个持续失败的软检查会一直把 SQL 送回重构，直到 LangGraph 的全局递归上限把整个 run 掐掉。硬检查防的是错答案，软检查防的是永不返回，后者需要自己的逃生口。

## 四、一个「宁可不知道」的小例子

`auto_ontology/semantic/date_format.py` 的模块注释讲了一类很隐蔽的错：`950324` 和 `1995-03-24` 是同一天，却不存在共同的比较谓词。模型猜错存储格式，写出的 SQL 能跑、返回空、看起来完全正确。所以日期列是唯一被排除在「采样值不进 prompt」规则之外的类型。

它的做法是用验证代替形状匹配：24 个候选 `strptime` 模式，逐个拿去解析最多 200 个样本值，只有能解析**全部**样本的候选才留下；四位年份限制在 1900–2099（这样 `201208` 被判成 `YYYYMM` 而非 `YYMMDD`）；日在前和月在前无法区分时，直接返回 `None`。这个模块只依赖标准库，我把它单独加载跑了十几组样本：

| 样本 | 返回 |
| --- | --- |
| `1995-03-24`, `2015-06-01` | `YYYY-MM-DD` |
| `950324`, `950401` | `YYMMDD` |
| `13/07/2011`, `24/12/2010` | `DD/MM/YYYY` |
| `03/04/2011`, `05/06/2012` | `None`（两种读法都成立） |
| `13/4/20`, `24/12/20` | `D/M/YY`（补零状态也写进记号） |
| `2020-01-01 19:39:07.0` | `YYYY-MM-DD HH:MM:SS.f` |
| 同一个字段混两种格式 | `None` |

注意 `03/04/2011` 那行。它完全可以猜一个方向，代码选择交白卷，因为模型会把任何记号当成事实写进 SQL。这套「歧义即弃权」的思路，和前面 `coverage 0.5` 时主动拒答是同一套判断。

## 五、第三道闸门：给 agent 的工具面

随包发布的 OpenAPI spec 有 **81 条路径、119 个操作**，其中 65 个是写操作。MCP 服务器最终只暴露 **9 个工具**：7 个从 spec 里挑出来（`search_terms`、`get_term`、`get_term_columns`、`get_term_sql_attributes`、`get_sql_attribute`、`describe_table`、`check_answerable`），加 2 个手写的（`ask_question`、`check_readiness`）。

`tools.py` 顶部的注释解释了收敛的理由：工具一多，模型选工具的能力就先垮了；SSO 配置、令牌管理、编译控制这些端点更不该由 agent 触发。还有一条更根本的约束——**故意不提供浏览数据库、schema、原始列的工具**，`describe_table` 之所以保留，因为它返回的是这张表参与的术语和 SQL 属性。工具描述也全部重写，注释里那句「a tool description is a prompt」点得很准：spec 的说明是给读 API 文档的人写的，工具说明得告诉模型什么时候该伸手。

实现上有三处防漂移：`route_maps()` 最后一条是 catch-all `MCPType.EXCLUDE`，spec 里新增端点默认对 agent 不可见；`missing_from_spec()` 在启动时检查 7 条精选路径还在不在，缺了就拒绝启动（工具静默消失比报错危险）；路径正则全部锚定，`/api/terms` 不会顺手匹配到 `/api/terms/{term_id}`。

两个手写工具都因为「一个端点答不了」而存在。`ask_question` 要处理 SSE：后端每个图节点推一个 step 事件，MCP 把它转成 progress notification，最后返回结构化的 `DataAnswer`（answer、sql、rows、row_count、truncated、reasoning），最多 100 行，超了明说截了多少。`check_readiness` 并发探三个端点（编译状态、连接、catalog），把「能不能答」和「这次答得对不对」分开。它的文档写了一个很实在的故障：编译好的术语表配上一条已经断掉的连接，`search_terms` 照样返回术语，界面一切正常，直到 `ask_question` 花几分钟写出一条永远执行不了的 SQL，返回一个空答案——从调用方看，和「问题没被理解」长得一模一样。

权限处理也细：401 是凭据问题，直接报「重新登录」，避免让人去修部署；403 是这个调用者看不见这条路由，记进 `unverified`，不记进 `blockers`。注释里的说法是，看不见属于「能看到的少」，属于「坏掉了」的是另一回事。

## 六、身份边界：谁在问，比怎么问更要紧

MCP 服务器不保存任何凭据，配置里连一个可以填密钥的字段都没有。调用者在浏览器里对 Auto Ontology 自己做 OAuth 登录（靠动态客户端注册，不用预先登记 redirect URI），拿到的是不透明 token；验证方式是拿它去问 `/api/auth/oauth2/userinfo`，因为只有签发方能判断它还作不作数。用户被禁用、授权被撤销、角色被改，下一次调用就生效。

出站请求统一挂一个 `httpx.Auth`：

```python
for name in (API_KEY_HEADER, BEARER_HEADER):
    if name in request.headers:
        del request.headers[name]
request.headers[BEARER_HEADER] = f"Bearer {token}"
```

先把 `x-api-key` 和 `authorization` 两个头都删掉，再设登录者的 bearer。原因写在注释里：FastMCP 会把入站请求的头复制到出站请求上，而 Auto Ontology 优先解析 API key；一个偷偷带上管理员 key 的调用者，会立刻以 key 主人的身份行动。「一个请求永远不能带两个身份」这条原则被放在共享 client 上执行，后来新增的工具也不会漏掉。没有登录会话时抛带指引的 `ToolError`，绝不匿名放行。

背面是另一条同样直白的边界。FastAPI 通过 `x-auto-ontology-user-id` 读取用户 id，`identity.py` 写着「the header is not independently authenticated here」，文档要求 3001 和 3002 只能待在私有网络，ingestion 的 ingest / delete / reset / compile 端点自身没有鉴权。合起来看是一个干净但要求明确的取舍：对外零凭据，对内零校验，中间那道网络边界必须真的成立。

## 七、我实测到的

这次没有跑起完整的部署（需要 Docker Compose、Postgres/pgvector、NVIDIA NIM 的 `nvapi-` key，样例库还得另克隆 `auto-ontology-eval`）。能跑的部分我尽量跑实了：

- 装了 MCP 子包的四个依赖（fastmcp 3.4.11 / httpx 0.28.1 / pydantic 2.14.3 / python-dotenv），在源码上跑它自带的测试：**88 passed in 1.21s**，覆盖工具白名单、身份走私、spec 漂移、就绪判定、SSE 解析和配置校验。
- 自己写探针组装了一次 server，`list_tools()` 返回正好上述 9 个工具及各自参数；`route_maps()` 是 8 条（7 精选 + 1 条 EXCLUDE）；锚定正则对 `/api/terms/{term_id}` 不匹配。
- **反向验证**：把 spec 副本里 `GET /api/terms` 删掉，`load_spec()` 抛 `ConfigError: The OpenAPI spec no longer publishes these curated operations: GET /api/terms`。
- **反向验证**：给请求塞一个 `x-api-key: smuggled-admin-token` 和另一个人的 bearer，经过 `CallerAuth` 后服务端只收到 `Bearer opaque-token-of-signed-in-user`，走私的 key 消失；去掉登录会话则得到「Sign in again」的 `ToolError`。
- 起了一个假网关端到端跑 `check_answerable` 的请求路径，返回 `coverage: 0.5`、`uncovered_entities: ["ad spend"]`，与 README 的例子对齐。
- `docs/openapi/auto-ontology-api.json` 与包内 `mcp/auto_ontology_mcp/auto-ontology-api.json` 的 SHA-256 完全相同（`21da3df5…f587267`），代码注释里说的「CI 强制两份同步」有可复核的落点。
- 第四节的日期格式表是直接加载 `date_format.py` 跑出来的真实输出。

顺带发现一处文档漂移：`tools.py` 顶部注释仍写着「The spec describes 87 operations」，随包发布的 spec 现在是 119 个操作。工具面没受影响（allow-list 是显式列名），只是注释落后了。

## 八、代价与边界

上手门槛不低：一套 Compose 栈、十个数据库驱动、`~450 个包 / 1GB+` 的后端依赖（这句是 MCP 的 pyproject 注释里自己写的，用来解释它为何要单独发一个只装 4 个依赖的包）。四个模型角色都要配置，且 embedding 模型在 ingest 与 query 两侧必须一致。仓库 Apache-2.0，但 README 明说**目前不接受外部 PR**，只收 issue 和集成请求；GitHub 上也没有发布任何 release。

数据外发要单独评估：预测类问题会路由到托管服务 KumoRFM，agent 会把连接的表上传过去，默认上限 `KUMO_MAX_TABLES=20`，行数默认不限。README 直接要求启用前先完成组织的数据审查。本体的可信度依赖人去认证，「Certify」是一段流程，代码不会替你保证术语描述是对的。信任头那条边界前面已经说过：一旦有人能直连 3001，RBAC 就绕过去了。

**没有验证的部分**：真实数据库连接、NIM 推理、语义编译全流程、text-to-SQL 全链路、Web UI、Ossie 导入导出、KumoRFM，以及仓库里另外 159 个后端测试文件（依赖太重，未安装）。文中所有关于编译和问答效果的描述都来自 README、docs 与源码，README 里 `$588.80` 那条 SQL 属于项目给出的示例，我没有复现。

## 九、什么值得抄

**把「能不能答」做成独立且便宜的一步。** 一次召回加一次除法，返回覆盖率和没覆盖的实体名，让 agent 有依据地追问或换个问法。这比在 prompt 里写「不确定就说不知道」有效得多。

**给检查分硬软两级，软检查必须有逃生口。** 7 次硬上限防错答案，5 次之后软检查放行防死循环。两类失败的代价不同，用同一个计数器管就会互相拖累。

**工具面用 allow-list，身份只转发不落地。** 119 个操作收敛到 9 个只读工具、启动时的漂移校验、剥离走私凭据、把「FastAPI 不可公网可达」写进文档——这几条合起来，才是「给任意 agent 用」这句话能成立的前提。

---

**验证说明**：本文基于 2026-11-05 的 `main` 分支（commit `c449567`，版本 1.2.0，7416 stars / 589 forks / 57 open issues）。实测环境为 macOS 上的 Python 3.13 独立虚拟环境，只安装了 `mcp/` 子包的运行时依赖与 pytest；假网关是本地临时 HTTP 服务，未连接任何真实数据源或模型服务。所有数字、错误文本和命令输出均来自本次实际运行，未复现的项目自测结果已明确标注。


NVIDIA 这个项目在 README 开头放了一句很硬的话：a revenue metric answered faster is worth nothing if the number is wrong。它接着给了两个例子，一个能答，一个拒绝答。

Auto Ontology 拆解：先问能不能答，再写 SQL

NVIDIA 这个项目在 README 开头放了一句很硬的话：a revenue metric answered faster is worth nothing if the number is wrong。它接着给了两个例子，一个能答，…

软件研发

数据库

人工智能

开发工具

NVIDIA的AutoOntology通过三道闸门保障数据可信：预检覆盖率、SQL硬软校验、工具白名单。其MCP服务仅暴露9个只读工具，用check_answerable低价拦截不可答问题，7次重构上限防错答，5次软检查逃生口防死循环。系统拒绝广告支出ROAS查询，因覆盖率仅0.5且无术语覆盖"adspend"。

代码解释

私有网络

PostgreSQL

服务器

LangGraph

Python

GitHub

SQLite

路由

Agent

OAuth

MacOS

MySQL

JSON

让每一个 Agent，都跑在云上

tchousec

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Auto Ontology 拆解：先问能不能答，再写 SQL-腾讯云开发者社区-腾讯云

Auto Ontology 拆解：先问能不能答，再写 SQL

Auto Ontology 拆解：先问能不能答，再写 SQL

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐