【2026 最新】Auto Ontology 教學：用訂單與退款定義營收，接上 MCP 前的五步驗收

你問資料庫 Agent：「10 月營收是多少？」它很快交出 SQL，執行也成功。可是訂單有未付款、同一筆訂單有兩次退款，11 月才核准的退款又該算在哪裡？Auto Ontology 教學要解的，就是這一段從「欄位存在」到「意思一致」的距離。

這篇專為第一次接觸語意層的讀者寫：先用四筆虛構訂單和五筆退款，算出一個能手算的答案，再看 NVIDIA Auto Ontology 如何把業務詞彙、欄位和 SQL 串起來，最後接到 MCP。你會需要辨認終端機指令，但每個步驟都會說明它在做什麼。

本文以 2026 年 11 月 7 日查閱的官方文件與固定程式版本為基礎。AlphaLab 執行了文中的獨立 SQLite 教材，未啟動 Auto Ontology、呼叫模型或測量其答對率；下方接線步驟是文件導讀，驗收數字則來自明確的教材規則。

先說結論：先定義營收，再請 Agent 算

語意層＝業務定義＋資料對應＋可重用計算規則。把它想成餐廳的點餐規則：資料表是食材架，業務詞典是菜名，計算規則是食譜。食材找得到，還得知道這道菜用哪一份食譜。

Auto Ontology 可以協助產生起始 ontology（本體：概念和關係的結構化描述），再讓人修訂。NVIDIA 官方產品頁也把它定位為業務專家可以測試、精修與認證的起點。本篇要建立的能力，是替一個指標留下可核對的定義，而非把自動生成的描述當作財務結論。

Auto Ontology 教學：先分清四個零件

• ① Schema「抽屜標籤」：記錄表、欄位、型別和鍵。amount_cents 告訴你有個整數金額，單靠名字仍分不出訂單金額或退款金額。
• ② 業務詞典「大家同意的用語」：寫清楚什麼是已付款訂單、核准退款與淨額，包含同義詞和排除條件。
• ③ Ontology「概念地圖」：把訂單、退款、欄位與關係連起來；例如一筆訂單可能對應多筆退款，這會影響加總。
• ④ RAG「先找資料再回答」：檢索增強生成會先找相關內容。本工具也用向量檢索找候選語意資訊；檢索命中某個詞，與計算規則經過驗收，是兩個檢查點。

這裡的 ontology 是應用系統的語意模型，不必先學完哲學或知識表示才能開始。若想補整體執行架構，可讀 Agent Harness 的模型與工具迴圈；本篇聚焦的是迴圈每次查數字前，要拿到什麼業務脈絡。

第一步：把「10 月營收」改寫成可驗收問題

先把問題縮小為：2026 年 10 月已付款訂單，截至 11 月 1 日零時之前核准的退款扣除後，淨額是多少？本例所有金額都是美元分，日期以 UTC 日期字串表示，不含稅、運費、匯率或收入認列調整。因此我們把指標命名為「10 月訂單群組淨額」，避免把教學口徑當成正式財報營收。

• 訂單 101：10 月 3 日已付款，10,000 分；兩次核准退款為 2,000 分與 1,000 分。
• 訂單 102：10 月 4 日已付款，20,000 分；4,000 分退款仍待核准，另有 5,000 分在 11 月 2 日才核准。
• 訂單 103：9,000 分仍未付款；訂單 104：9 月 30 日已付款，5,000 分，10 月退款 1,000 分。
• 本題選的是「10 月付款的訂單群組」，因此 103、104 排除；102 的兩筆退款也不符合本次截止條件。

手算是 （10,000－2,000－1,000）＋20,000＝27,000 分，也就是 US$270。若你要問「10 月實際流入與流出的現金」，9 月訂單在 10 月的退款就可能要列入。兩個問題都合理，但要使用不同名稱和規則。

把這段定義保存為 revenue-definition-v1，旁邊註明負責人、時間範圍、幣別、每列代表什麼，以及五個排除案例。官方建模流程同樣要求先寫問題契約、關係基數與度量口徑。白話說，先約好怎樣才算答對。

第二步：用小資料建立標準答案

把以下內容存成 revenue.sql。這是本文自建教材，使用整數分避免金額浮點誤差；COALESCE 把「沒有符合條件的退款」轉成零。先按訂單彙總退款，再連接訂單，讓每筆訂單只出現一次。

CREATE TABLE orders (
  id INTEGER PRIMARY KEY, paid_at TEXT,
  status TEXT NOT NULL, gross_cents INTEGER NOT NULL
);
CREATE TABLE refunds (
  id INTEGER PRIMARY KEY, order_id INTEGER NOT NULL,
  approved_at TEXT, status TEXT NOT NULL,
  amount_cents INTEGER NOT NULL,
  FOREIGN KEY (order_id) REFERENCES orders(id)
);
INSERT INTO orders VALUES
(101,'2026-10-03','paid',10000),
(102,'2026-10-04','paid',20000),
(103,NULL,'pending',9000),
(104,'2026-09-30','paid',5000);
INSERT INTO refunds VALUES
(1,101,'2026-10-05','approved',2000),
(2,101,'2026-10-06','approved',1000),
(3,102,NULL,'pending',4000),
(4,102,'2026-11-02','approved',5000),
(5,104,'2026-10-08','approved',1000);
CREATE VIEW october_order_net_revenue AS
WITH refunded AS (
  SELECT order_id, SUM(amount_cents) AS refunded_cents
  FROM refunds
  WHERE status = 'approved'
    AND approved_at < '2026-11-01'
  GROUP BY order_id
)
SELECT o.id AS order_id, o.gross_cents,
       COALESCE(r.refunded_cents,0) AS refunded_cents,
       o.gross_cents - COALESCE(r.refunded_cents,0) AS net_cents
FROM orders o
LEFT JOIN refunded r ON r.order_id = o.id
WHERE o.status = 'paid'
  AND o.paid_at >= '2026-10-01'
  AND o.paid_at < '2026-11-01';

有 Python 3 就能先在記憶體裡檢查，無須購買模型額度。以下命令要在放有 revenue.sql 的資料夾執行；它只建立這次程序內的 SQLite 資料，不連企業資料庫。

python3 - <<'PYSQL'
import sqlite3
from pathlib import Path
con = sqlite3.connect(':memory:')
con.executescript(Path('revenue.sql').read_text())
print(con.execute(
    'SELECT order_id, net_cents '
    'FROM october_order_net_revenue ORDER BY order_id'
).fetchall())
print(con.execute(
    'SELECT SUM(net_cents) AS net_revenue_cents '
    'FROM october_order_net_revenue'
).fetchone())
PYSQL

這份固定資料的預期輸出是 [(101, 7000), (102, 20000)]，總額 (27000,)。AlphaLab 在 Python 3.9.6、SQLite 3.51.0 得到相同結果。這驗證的是教材 SQL；模型是否會挑對 view，仍要在接線後另外檢查。

第三步：依官方文件準備 Auto Ontology

想接上完整系統，先備妥 Docker 與 Compose v2、uv，以及你有權使用的模型端點。下列指令固定到本文查閱的程式提交，讓你能對照同一份檔案；這是程式提交雜湊，不是套件版號。官方安裝導引說明 Compose 可以在一台機器上運行整個堆疊。

git clone https://github.com/NVIDIA/auto-ontology.git
cd auto-ontology
git checkout c447003f72a822301e927196a4ecb5b597c308d5
cp .env.example .env
chmod 600 .env

在編輯器內填寫 .env：AUTH_SECRET、APP_URL=http://localhost:3000、管理者 email 與密碼、Postgres 和 pgAdmin 密碼。模型端點的 key 也在這裡填，別把真實值貼進聊天紀錄。.env.example 為不同模型角色各放了假 key，要逐項替換，或刪除角色的假 key 行讓它繼承預設 key。

以這份固定版本的環境範例為例，聊天、embedding 與 rerank 分別使用 nvidia/nemotron-3.5-lightning-30b-a3b、nvidia/nemotron-3.5-embed-1b、nvidia/nemotron-3.5-rerank-8b。Rerank 的端點與聊天端點不同；建索引與查詢則要沿用同一個 embedding 模型，別只換查詢端。

先選資料來源：若要跑官方 Wide World Importers 範例，照官方 Quickstart 的建庫與 seed 步驟完成，再啟動全套服務；其中 --drop 會重建指定範例資料庫，只適合新的隔離練習環境。若要測本文案例，請把 revenue.sql 載入獨立的 PostgreSQL 練習資料庫，再將它設為來源；上面的記憶體 SQLite 不會自動出現在 Compose 裡。

在 CONNECTION_STRINGS 填入練習庫的連線字串，或清空它後在 Settings → Connections 新增。官方連線文件指出，兩條來源路徑的優先順序不同：回答優先採 UI 連線，ingestion 則在環境變數有值時優先採它。練習時選一條路徑，避免「索引 A 庫，回答卻查 B 庫」。來源帳號只授權讀取這組練習表與 view。

docker compose up -d --build
docker compose ps -a
docker compose logs frontend-migrate

開啟 http://localhost:3000，以設定的管理者登入，再開啟 Settings → Semantic Compilation。依官方流程等待 Semantic compilation is ready，並核對來源資料確實已被收錄。看到首頁、資料表名稱或服務在跑，都還不是完整查詢成功的證據。

費用要分開算：程式碼的 Apache 2.0 授權、模型呼叫額度、主機與維護是不同項目。託管端點先核對帳號可用額度與速率限制；自架 NIM 則另核對 NVIDIA NIM 的使用與正式環境授權條件。本文不給每問固定價格，因一次問題可能觸發多次模型呼叫；先限制測試問題數，再記錄實際用量。

第四步：Auto Ontology 教學的核心，是校訂詞彙與計算

在語意圖或資料目錄找出訂單、退款及對應欄位，先看系統產生的草稿。把「10 月訂單群組淨額」的定義與 view 對應補完整，確認一筆訂單對多筆退款的關係。別只改成看起來專業的名稱；要讓定義能排除 103、104 和截止日後的退款。

需要程式化處理時，官方寫入 API 索引列出 PATCH /api/terms/{term_id} 可編輯既有詞彙；SQL attribute（可重用 SQL 定義）先走 POST /api/sql-attributes/validate。驗證請求的 expression 可用本例 SELECT SUM(net_cents) AS net_revenue_cents FROM october_order_net_revenue，但 term_id 要使用你部署內查到的真實 ID，並依該版本 OpenAPI 核對完整請求。

驗證通過後，才在測試環境建立或更新相應 SQL attribute，讀回 expression、欄位與描述再核對。該版本的 PATCH SQL attribute 用於名稱與描述；修改 SQL expression 使用 PUT，所需欄位見同一份 API 索引。只通過解析仍不足以證明口徑正確，US$270 的小資料測試必須另外做。

把「認證」視為你已完成檢查的標籤：先讀回內容、核對樣本，再認證。官方建模流程明確區分成功執行與語意正確；把錯誤定義標成 certified，只是替錯誤蓋上章。每次改動記錄日期、理由、修改前後定義，以及正反例結果；這就是語意層持續維護的工作量。

第五步：透過 MCP 查詢，分三層驗答案

MCP 是讓 Agent 接工具的共同通訊方式。依官方 MCP 文件啟動下列服務；AUTO_ONTOLOGY_API_URL 指向 Web app 的 3000 埠。若固定套件程式碼版本，可使用下列 Git 提交指定法。

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

在支援遠端 HTTP MCP 的客戶端加入 http://localhost:3003/mcp，重啟客戶端後透過 Auto Ontology 登入。AUTO_ONTOLOGY_MCP_PUBLIC_URL 在 frontend 與 MCP 兩側必須一致；localhost 和 127.0.0.1 的混用也可能造成資源位址不符。

• 先查就緒：呼叫 check_readiness，確認語意層與來源連線兩者可用。
• 再查定義：用 search_terms、get_term 與 get_term_sql_attributes 找到本文指標，確認幣別、訂單群組和截止日。
• 最後查答案：先 check_answerable，再 ask_question；要求回傳使用的 SQL、資料列與金額單位。

驗收分三層：第一層 SQL 可執行；第二層回傳列與教材一致；第三層業務定義確實是你要的訂單群組。預期總額為 27,000 分，顯示成美元則是 US$270。定義改好後，要重新跑相同問題，保存修改前後的實際結果；文章不預設系統修改前一定答錯，也不預設修改後一定答對。

這個 MCP 工具集依官方文件提供讀取功能；詞典變更走 UI 或 API。工具的讀取範圍與來源資料庫帳號權限仍須分別設好。正式驗收若涉及持續變動資料，可接著用 Text-to-SQL 的快照與結果比較方法，把這次語意驗收延伸成回歸測試。

三個容易踩的坑：重複、重名、模糊時間

一對多重複：若直接把訂單連上退款，再逐列加總訂單金額，101 會出現兩次。對本教材的已核准退款與截止條件，這種錯法得到 37,000 分，較正確值多 10,000 分。修法是先把退款聚合到訂單層級；這是關係粒度問題，換一個模型也要驗。

欄位重名：查兩個 id 時，明確寫 o.id AS order_id、r.id AS refund_id，別讓後續程式猜欄位。這是本篇的輸出契約要求，並未把題目線索中的個別 issue 推論為所有版本都有相同錯誤。

時間與資料流向：問「上個月」前，先寫出時區和起訖；本例特別把 11 月 2 日退款放進反例。連接企業資料前，依官方架構說明確認來源 schema、欄位 profiling 與樣本值如何流入 catalog 和模型端點。練習先用假資料；3001、3002 依官方安全說明限制在私有網路，外部客戶端經 Web app 存取。

常見問題：Auto Ontology 教學 FAQ

1. 它會自動決定公司的營收定義嗎？

定義要由業務負責人確認。它提供起始語意模型與修訂工具；本例的退款截止日就是人先選定的規則。

2. Schema 和 ontology 差在哪？

重點不同。Schema 描述資料結構，ontology 把業務概念、欄位及關係組織起來；兩者需要互相對應。

3. 已有 RAG，還要做這件事嗎？

看問題。找政策段落可先做文件檢索；要算退款後金額，就要把檢索到的定義落到資料與計算。

4. SQL validation 通過就能認證嗎？

還要驗資料與口徑。把本例 103、104 排除，並核對 101 的兩筆退款，是解析成功以外的必要檢查。

5. 一定要在本機跑模型嗎？

可以使用託管端點。官方環境範例包含 NVIDIA 託管設定，也提供角色端點設定；算力與額度由你選的部署方式決定。

6. MCP 能幫我修改詞典嗎？

這份官方 MCP 工具集是讀取用途。要改定義，使用對應 UI 或有權限的 API，改完讀回再驗。

7. 為什麼 10 月發生的退款有時被排除？

因為本文選「10 月付款訂單群組」。若改成月內現金流問題，9 月訂單的 10 月退款可能需要計入，要另建指標。

8. 第一個專案應該做多大？

先做一個指標。只接一組假資料，留下定義、SQL、兩筆逐單淨額和一筆總額；能解釋每個反例，再擴充到下一個問題。

給新手的三個重點

• 先決定「哪批資料、哪個時間、哪種單位」，再讓 Agent 查。
• 定義、SQL 和逐列結果一起驗；認證標籤要對應可追查的檢查紀錄。
• 記錄一次定義修正花多少時間、哪些反例仍失敗，再決定是否擴大使用。