文档核对日期：2026 年 11 月 7 日。部署步骤按当日官方仓库 main 分支整理。

1. 信息摘要

NVIDIA 开源的 Auto Ontology 用来解决一类常见问题：数据库里有数据，但智能体不知道业务名词对应什么字段，也不清楚应该按什么口径计算。

例如，用户问“上个月的销售额是多少”，数据库里可能同时有订单金额、开票金额、实收金额，还涉及退款、取消订单和统计日期。即使 SQL 能执行，选错字段或漏掉条件，结果也会出错。

Auto Ontology 会读取数据库的结构和部分数据，建立业务术语、计算表达式与表关系的初稿，再由使用者检查和确认。智能体回答问题时，可以检索这些定义、生成 SQL，并返回查询结果和所用 SQL，方便核对。

项目采用 Apache-2.0 许可证，提供 Web 界面，以及供程序和智能体使用的 API、MCP 接口。

来源：官方仓库与项目说明。

2. 具体功能

把业务名称对应到数据库字段

系统可以为“客户”“订单”“发票明细”等概念建立说明、别名及字段映射，也可以整理表之间的连接关系。

这里的“本体”可以理解为一套业务词典，加上词语之间的关系和计算规则。例如：

客户 → 有哪些订单
订单 → 包含哪些明细
销售额 → 使用哪个金额字段、按什么条件汇总

这些信息存入语义层后，智能体查询时就有了可参考的定义。

保存可复用的指标计算规则

业务指标可以关联经过审核的 SQL 表达式。这样，不同问题涉及同一个指标时，可以复用已确认的计算规则。

以“净销售额”为例，是否扣除退款、如何处理折扣，需要业务人员先说清楚。系统可以帮助生成初稿，但审核这一步仍然必要。

用自然语言查询，并查看计算过程

用户可以直接提问。系统会检索相关术语、字段和计算表达式，生成并执行 SQL，返回答案、SQL 和结果数据。

这让使用者能够核对时间范围、过滤条件和关联关系。查询可以执行，只说明语法和运行条件满足要求，业务结果仍需与已确认的口径对照。

工作流程见：官方原理说明。

接入多种数据库

当前文档列出的数据源包括 PostgreSQL、MySQL、Databricks、Snowflake、ClickHouse、Trino、Apache Kyuubi、HeavyDB、DuckDB 和 SQLite。

数据源既可以通过界面配置，也可以写入环境变量。DuckDB、SQLite 目前需要使用连接字符串配置。

来源：数据库连接文档。

给已有智能体提供查询工具

MCP 接口提供的主要工具包括：

工具	作用
check_readiness	检查语义层和数据库连接是否具备查询条件
search_terms	查找业务术语
get_term	查看术语定义和关联关系
check_answerable	检查现有语义层能否覆盖问题
ask_question	执行问答，返回答案、SQL 和数据行

这些工具采用只读方式提供查询能力，并按登录用户的权限工作。它们适合接到已有的数据助手或业务问答智能体中。

来源：MCP 文档。

3. 如何接入

第一步：准备运行环境

本地试用可以使用 Docker Compose。先准备：

• Git、Docker 和 Docker Compose v2。
• 可访问的测试数据库，建议使用只读账号。
• NVIDIA API Key，用于调用默认配置中的模型服务。

项目默认调用 NVIDIA NIM 服务，也支持配置自托管 NIM。使用托管服务试用时，不需要在本机加载这些模型；推理、向量化和重排序请求需要能访问相应服务。

模型配置见：官方环境变量示例。

第二步：下载并配置

Windows PowerShell 中执行：

git clone https://github.com/NVIDIA/auto-ontology.git
cd auto-ontology
Copy-Item .env.example .env

打开 .env，至少检查以下配置：

配置项	填写内容
DEFAULT_MODELS_API_KEY	从 NVIDIA 平台获取的密钥
REASONING_API_KEY、NON_REASONING_API_KEY、EMBED_API_KEY、RERANK_API_KEY	替换各处密钥占位符；或删除这些密钥行，使其回退到默认密钥
AUTH_SECRET	自行生成的长随机字符串
POSTGRES_PASSWORD	项目自身 PostgreSQL 的密码
AUTO_ONTOLOGY_ADMIN_EMAIL	初始管理员邮箱
AUTO_ONTOLOGY_ADMIN_PASSWORD	初始管理员密码
PGADMIN_PASSWORD	pgAdmin 密码
APP_URL	本地试用设为 http://localhost:3000
CONNECTION_STRINGS	本文通过界面添加业务数据库，因此设为空值

保留 .env.example 中各模型的地址和模型名，先按默认方案跑通。向量模型需要与数据采集时使用的模型一致。

项目自身的 PostgreSQL 用于保存目录、语义定义和应用数据；需要分析的业务数据库另行连接。

不要一边在 CONNECTION_STRINGS 填写一套连接，一边在界面配置另一套。当前文档说明，采集和问答对两种配置的优先顺序不同，混用容易造成采集、查询的数据源不一致。

第三步：启动服务并连接测试数据库

执行：

docker compose up -d --build

打开 http://localhost:3000，使用配置的管理员账号登录。在 Settings → Connections 中添加测试数据库连接，填写数据库地址、账号和密码，并按需要限制可采集的 schema 和表。

数据库地址必须能从容器内访问。如果数据库在 Docker Desktop 所在的电脑上，可按网络配置使用 host.docker.internal；容器里的 localhost 指向容器自身。

完成连接后，发起数据采集，在 Settings → Semantic Compilation 中启用语义编译，等待语义层准备完成。然后检查生成的术语、指标和关联关系，修正后再认证，尤其要核对金额、时间范围和去重方式。

先选几条已知答案的问题，将返回 SQL 和结果与人工查询进行对比，再接入正式应用。

部署方式见：官方快速开始。

第四步：通过 API 接入应用

在用户菜单的 API Tokens 中创建令牌，保存为环境变量：

pip install requests
$env:AUTO_ONTOLOGY_API_TOKEN = "替换成应用内创建的令牌"

Python 调用示例：

import json
import os

import requests

with requests.post(
    "http://localhost:3000/api/chat/completions",
    headers={
        "x-api-key": os.environ["AUTO_ONTOLOGY_API_TOKEN"]
    },
    json={"question": "上个月各产品的销售额是多少？"},
    stream=True,
    timeout=(10, 900),
) as response:
    response.raise_for_status()
    response.encoding = "utf-8"

    for line in response.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        payload = line[5:].strip()
        if payload == "[DONE]":
            break
        event = json.loads(payload)
        if event.get("type") == "result":
            answer = event["answer"]
            print(answer["response"])
            print(answer["sql_code"])
            print(answer.get("sql_response_from_db"))
        elif event.get("type") == "error":
            raise RuntimeError(event["message"])

这里的返回值是 SSE 事件流，不能直接把整个响应当成一个 JSON 解析。result 事件包含最终结果，[DONE] 表示本轮结束。

如需多轮追问，请在请求中传入 conversation_id：首次由客户端生成 UUID，后续复用同一个值，并等待上一轮结束后再发送。省略该字段时，接口按单次问答处理。

接口说明：Conversation API。

第五步：通过 MCP 接入智能体

如果已有支持 MCP 的客户端，可以安装 uv 后，在 PowerShell 启动 MCP 服务：

$env:AUTO_ONTOLOGY_API_URL = "http://localhost:3000"
uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp

在客户端的 MCP 配置中添加：

{
  "mcpServers": {
    "auto-ontology": {
      "url": "http://localhost:3003/mcp"
    }
  }
}

该示例适用于支持 HTTP MCP 和登录授权的客户端；不同客户端的配置入口可能不同。连接后按提示登录 Auto Ontology，先调用 check_readiness，再用 check_answerable 检查问题是否有数据支持，最后交给 ask_question 查询。

部署到服务器时，应用请求应经过 3000 端口的认证网关。按官方部署说明，3001、3002 端口应保留在私有网络中；业务数据库权限也应由数据库账号本身限制。

MCP 配置和登录说明：官方 MCP 文档。