Auto Ontology 写 API 实战指南:Terms、SQL Attributes、编译与模型交换的权限与校验边界

原创2026-11-05 14:59:261,827 阅读
文章标签:AI 应用MCP 服务数据治理知识图谱数据目录数据建模后端前端大模型人工智能

Auto Ontology 写 API 实战指南:Terms、SQL Attributes、编译与模型交换的权限与校验边界

本指南以 Auto Ontology 的写接口索引文档为骨架,逐条拆解 Terms、ColumnAttribute、SqlAttribute、目录节点描述、语义编译、模型导入导出与可复用分析定义这些写操作的路径、权限、请求体与错误语义。读完后,你可以直接基于 Next.js 网关(默认 :3000)编写脚本或 Agent 工具,完成一次"校验—写入—回读—行为验证"的完整闭环,并清楚知道哪些接口不应被当作写入入口。

原文强调的一条主线是:请求成功不等于语义正确,更不等于持久化一致。本文在继承该骨架的同时,结合仓库中的 OpenAPI 产物、路由实现与后端 handler,补全了字段级细节与源码级依据。

一、先确定调用入口与权限模型

1.1 调用 Next.js 网关,而不是 FastAPI 直连

写操作必须打到 Next.js 源站(APP_URL,本地为 :3000),而不是 FastAPI 的 :3001。原因在仓库的部署结构里有明确依据:

服务 技术栈 职责 端口
Frontend Next.js 16 / React 19 / Better Auth / Prisma Web UI、认证、API 网关 3000
Backend FastAPI(Python 3.12+)/ LangChain Chat / NL-to-SQL、catalog、datasource API 3001

见 README.md。Python 服务仅在集群内可达,对外唯一的公共 API 面是 auto-ontology-api.json,它在 docs/openapi/README.md 中被明确定义为 "The public API",而 backend.json、ingestion.json 只是内部服务面。Next.js 侧的转发逻辑在 proxy-backend.ts 中实现:它把收到的 pathname + search 原样拼到 PYTHON_API_URL(默认 http://127.0.0.1:3001)后面,并重新构造头信息,因此客户端无法通过伪造头把身份注入后端。

1.2 每个写路由都由 withPermission 包裹

with-auth.ts 规定每个 route 导出必须且只能是 withPublic 或 withPermission 两种包装之一。withPermission 的动作序列是:

  1. resolveUser() 解析调用者;
  2. 无法解析返回 401;
  3. userCan(user, permissions) 不通过返回 403;
  4. 通过后把 user 注入 handler 上下文。

resolve-user.ts 按顺序接受四种凭证:Better Auth 会话 Cookie、Auto Ontology API Token(x-api-key: auto_ontology_...)、Auto Ontology 签发的 OAuth access token、以及 SSO id token(按 email 再按 subject 映射用户)。

API Token 的语义在 api-token.ts 中写得很清楚:令牌自身不带任何权限,它只解析为持有者用户,随后按该用户的角色做 userCan() 判定;同时 Authorization: Bearer 也被接受,但只认带 auto_ontology_ 前缀的值。这意味着:

  • 用 viewer 的 token 做 catalog:edit 一定 403,且这不代表路径写错;
  • 吊销 token 或删除其所有者,脚本访问立即失效;
  • token 无法再铸造新 token,创建和吊销需要在 UI(用户菜单 → API Tokens)中以登录会话完成,见 SKILL.md 与 UserMenu.tsx。

1.3 权限从哪来:x-auto-ontology-permissions

OpenAPI 产物里每个 operation 都带 x-auto-ontology-permissions,它由生成器读取 withPermission({...}) 得出(docs/openapi/README.md)。角色到权限的映射在 access.json:

权限 admin viewer
catalog:read ✅ ✅
catalog:edit ✅ ❌
chat:use ✅ ✅
analysis:read ✅ ✅
analysis:manage ✅ ❌
semanticCompilation:read / manage ✅ ❌
modelInterchange:export / import ✅ ❌
conversation:read / write ✅ ✅

因此本文涉及的写入基本都是 admin 级能力:catalog:edit、analysis:manage、semanticCompilation:manage、modelInterchange:import。

1.4 后端还有第二层:账号角色或行所有者组

有些路由在网关只要求 catalog:read,真正的写授权由 Python 侧完成。例如 nodes/[node_id]/route.ts 的注释说明:后端按"账号角色或该节点的所有者组"授权,网关要求 read 只是为了让 owner-group 中的 viewer 能进到后端判定;而 Column 不存 owner,所以这类 viewer 在列节点上仍会被拒绝。

后端的判定实现在 owners.py:can_edit_entity 先看用户角色是否具备该权限,否则看该行的 owner 组是否存在、用户是否为成员、以及该组角色是否具备同权限。也正因如此,write-api.md 才会在 PATCH /api/terms/{term_id} 上标注权限为 catalog:edit,同时提醒 403 反映的是所有者角色的权限不足。

二、Terms:可裁剪、可认证,但没有"创建空术语"

2.1 三个操作

Method Path Permission Notes
GET /api/terms catalog:read Query query、skip、limit
GET /api/terms/{term_id} catalog:read
PATCH /api/terms/{term_id} catalog:edit TermUpdate:name、description、name_certified、description_certified。重命名会使缓存的 SQL attribute 描述建议失效。

原文明确写着:/api/terms 上没有公开的"创建空 Term" POST,新术语只能通过编译(compilation)、摄入(ingest)或模型导入(model import)产生。这与 modeling.md 的表述一致:"Auto Ontology has no direct public create-empty-Term endpoint and no complete direct structural relationship mutation workflow. Do not invent one." 如果设计无法用已安装版本的公开 API 表达,应返回 model gap,而不是降低设计质量。

2.2 列表查询:分页语义与限额

GET /api/terms 的参数定义见 terms/router.py 与 pagination.py:

  • query:对 term name 做大小写不敏感子串过滤;
  • skip:默认 0,ge=0;
  • limit:1..100,省略则一次返回全部匹配行;上限常量 MAX_PAGE_SIZE = 100 就是"单次请求不能把整个集合拉回来"的硬约束。

返回结果按 name 排序,total 报告全量匹配数,因此调用方可以据此决定是否继续翻页。列表里的每个 term 自带解析后的 zones,并带有 column_attribute_counts、sql_attribute_counts、related_counts 这类按 term 的计数分解——它们让列表卡片不必逐个 term 再发请求(避免 N+1)。真正的属性节点只在聚焦某个 Term 时才通过下面两个接口拉取。

2.3 PATCH 的字段与副作用

TermUpdate 的 schema 见 auto-ontology-api.json 组件段,实际上比原文表格多了一个 owner_id:

字段 类型 约束
name string | null minLength: 1
description string | null
name_certified boolean | null
description_certified boolean | null
owner_id string | null 指向用户或具备该权限的组

handler 的行为在 terms/router.py:

  • 空 patch 直接 422(No Term fields to update);
  • name 会先 strip(),strip 后为空则 422(Term name cannot be blank);
  • Term 不存在返回 404;
  • 只有 name 或 description 变化才算 content_changed;仅改认证标志不会触发 embedding 刷新,因为认证标志不携带嵌入内容;
  • 真正重命名(新名与旧名 strip 后不等)时,调用 clear_sql_attribute_description_suggestions_for_term(term_id),把该 Term 下所有 SQL attribute 上缓存的描述建议清空——这正是原文"Renaming invalidates cached SQL-attribute description suggestions"的实现依据(见 terms/router.py 与 dal/sql_attributes.py);
  • content_changed 时调用 refresh_term_embeddings(term_id, refresh_dependent_attrs=name_changed),失败仅记录 warning(best-effort),不影响响应返回。

嵌入刷新的细节在 terms/service.py:先 vdb.delete_by_id(term_id),若需要刷新依赖项,还要逐个删除 ColumnAttribute 和 SqlAttribute 的向量 ID 再重新写入,避免旧文本残留。

响应体返回 data(id、name、description、两个认证标志、owner_id)以及 certification。certification 是聚合值,取值 certified / partial / pending,计算规则在 dal/terms.py:Term 自身的两个布尔 + 每个 ColumnAttribute 与 SqlAttribute 的 certified,全部为真才是 certified,全为假是 pending,否则 partial。

三、Column attributes:改名字/描述/样例值,会刷新向量

Method Path Permission Notes
GET /api/terms/{term_id}/column-attributes catalog:read Term 映射到的物理列
PATCH /api/terms/{term_id}/column-attributes/{attr_id} catalog:edit name/description/certified/sample_values。{attr_id} 是 ColumnAttribute 的 id,不是 SqlAttribute 的 id。会刷新语义 embedding。

请求体 ColumnAttributeUpdate:

字段 类型 说明
name string | null minLength: 1
description string | null
sample_values string[] | null 样例值
certified boolean | null 参与 Term 聚合认证

实现要点(terms/router.py):

  • 空 patch → 422 No ColumnAttribute fields to update;
  • 名称 strip 后为空 → 422;
  • 目标不存在 → 404;
  • sample_values 会持久化到所属 Column,并刷新该 Column 的 data-VDB 嵌入(与目录列编辑行为一致);
  • 响应是专用结构 ColumnAttributePatchResponse:{"data": {...}, "term_certification": "..."}。之所以不用通用 DataResponse,是因为 Term 的聚合徽标依赖该属性的 flag,写回时同步算出,列表无需二次请求。

GET 列表支持同样的 skip/limit,返回 data、count(本页条数)、total(全量条数)。注意 total 的计算条件:只有当 skip 与 limit 都未给出时 len(data) 才等于全量;只给 skip 也必须单独查一次 count。

四、SQL attributes:校验、创建、元数据补丁与整体替换

这是写 API 中语义最细的一组,也是最容易踩坑的一组。

Method Path Permission Notes
POST /api/sql-attributes/validate catalog:edit Body:expression,可选 term_id、attribute_id。解析失败是 422,不是 valid: false。
POST /api/sql-attributes catalog:edit SqlAttributeCreate:必填 name、description、expression、term_id;可选 source(默认 manual)。201。
GET /api/sql-attributes/{attr_id} catalog:read 亦对应 MCP get_sql_attribute
PATCH /api/sql-attributes/{attr_id} catalog:edit 仅元数据(name/description)。不改 SQL 表达式。
PUT /api/sql-attributes/{attr_id} catalog:edit 重新解析 SQL 并刷新 embedding。必填字段与创建相同。
DELETE /api/sql-attributes/{attr_id} catalog:edit 图清理 + embedding 删除
GET /api/terms/{term_id}/sql-attributes catalog:read 某 Term 下的列表
GET /api/sql-attributes/{attr_id}/description-suggestion catalog:edit 编辑流程用的 LLM 建议

4.1 一个需要说明的权限差异

原文表格把 validate 标为 catalog:edit。但当前仓库的 validate/route.ts 实际声明的是 catalog:['read'],注释写明"Catalog read is enough. Creating an attribute and saving one both require catalog:edit",OpenAPI 中该 operation 的 x-auto-ontology-permissions 也是 catalog: ["read"]。后端 handler 文档串同样写着"Catalog read is enough"。

因此以部署版本的 OpenAPI 为准:只读角色也能调用 validate 做预检,但创建与保存必须 catalog:edit。写自动化脚本时建议先 GET 一次 OpenAPI 或直接按最严格权限准备凭证,避免跨版本差异。

4.2 校验:为什么解析失败是 422

POST /api/sql-attributes/validate 的请求体是 SqlAttributeValidate:

{
  "expression": "net_amount - tax_amount",
  "term_id": "term_123",
  "attribute_id": "sqlattr_456"
}

后端 validate_sql_attribute 做两件事:

  1. 若给了 term_id,检查同 Term 下是否已有等价表达式(attribute_id 用于编辑时排除自身)。命中重复会抛 SqlAttributeExpressionConflict("SQL snippet already exists")。
  2. 解析 SQL 并确认它引用了目录中已知的表。

validate_sql(sql_utils.py)用 sqlglot 的 parse_query_single 解析,失败或"不引用任何目录中已知表"都会抛 SqlParseError。router 把 SqlAttributeExpressionConflict 与 SqlAttributeSqlError 统一转成 HTTP 422(router.py)。

这就是原文那句"Parse failure is 422, not valid: false"的机制:成功响应的 body 才是 {"data": {"valid": true, "expression": "..."}};一旦返回 422,valid 字段根本不存在,客户端不能写 if (!resp.valid) 这种判断。

连接器永远不由客户端选择。_resolve_database_name(service.py)的规则是:只配置了一个 connector 就用它的方言/目录校验;零个或多个则退化为全目录(所有方言、所有 schema)校验,与 CustomAnalysis 一致。内部调用者(如逐库处理的语义流水线)才可能显式传 connector。

4.3 创建

{
  "name": "Net Revenue",
  "description": "Gross revenue net of tax",
  "expression": "SUM(net_amount)",
  "term_id": "term_123",
  "source": "manual",
  "owner_id": "group_finance"
}
  • 必填:name(minLength: 1)、description、expression(minLength: 1)、term_id;
  • 可选:source(默认 manual)、owner_id(必须是可编辑目录的用户或组,否则 400);
  • 成功返回 201;
  • 名称冲突 409,表达式冲突 422,Term 不存在或 SQL 不可解析 422。

写入路径在 _persist_attr_with_sql:它把 SQL 文本挂到 sql_full_query,创建 Sql 节点并通过 add_query 建立边,然后返回包含 sql_id 与 sql 的 body。也就是说,SQL attribute 在图中是"属性节点 + SQL 节点 + 边"的组合,而不是一行纯文本字段。

4.4 PATCH 与 PUT 的分界线

  • PATCH /api/sql-attributes/{attr_id} 的 schema 是 SqlAttributeMetadataPatch:name、description、certified、owner_id。它走 patch_sql_attribute,不触碰表达式。空 patch → 422,名称 strip 后为空 → 422,不存在 → 404。
  • PUT /api/sql-attributes/{attr_id} 用 SqlAttributeUpdate,必填 name、description、expression、term_id,可选 source。它会重新解析 SQL、重新链接 Term,并刷新 embedding。

要改公式只能用 PUT;想只改文案却误用 PUT,就可能因为表达式重新解析失败而拿到 422——这是实践中很常见的误操作。

4.5 删除与向量生命周期

DELETE 执行图清理并删除 embedding。嵌入侧的逻辑在 _reembed_sql_attribute:先 vdb.delete_by_id(attr_id),再从 store 取文档重新 upsert。创建/更新流程里还会调用 PII 重对齐(realign_sql_attribute_pii)并把标签(如 PII)考虑进来,因此删除后再重建同名属性,其向量与标签状态是重新计算的,不继承旧值。

4.6 描述建议:缓存、404 与 data: null

GET /api/sql-attributes/{attr_id}/description-suggestion 需要 catalog:edit(见 description-suggestion/route.ts 与 OpenAPI 的 x-auto-ontology-permissions)。行为见 description_suggester.py:

  • 属性不存在 → 404;
  • 已缓存 description_suggestion → 直接返回,不再调用 LLM;
  • 未缓存 → 用固定 system prompt 生成,限制 500 字符、最多 3 句,做空白归一并截断到最后一句完整句子,然后写回节点缓存;
  • LLM 失败或无可用输出 → 返回 {"data": null},这不是错误。

由于结果被缓存,"重命名 Term 清空建议"才显得重要:否则用户会看到旧术语名生成的、语义已过期的描述。

五、目录节点描述:一个接口覆盖 Database、Schema、Table、Column

Method Path Permission Notes
PATCH /api/nodes/{node_id} catalog:edit Database、Schema、Table 或 Column 节点的可变属性

node_id 可以是任意目录节点。请求体 NodeUpdate 的字段:

字段 类型
description string | null
description_certified boolean | null
owner_id string | null
sample_values string[] | null

响应 NodeUpdateResult 有个容易误解的语义:它只回显请求真正 patch 的键加 id,未提交的键不会出现;每个键都可能为 null;当 patch 为空或节点不存在时,整个响应为 null。这与"返回完整节点"的直觉不同,用它做前端状态合并时要按"部分对象"处理。

权限上,网关只要求 catalog:read,由后端按账号角色或节点所有者组判定;Column 不存 owner,所以 owner-group 的 viewer 在列上仍然被拒。这类"网关宽松、后端收紧"的设计让 403 的来源有两个层级,排查时需要区分。

六、语义编译:状态可查,重置是危险操作

Method Path Permission Notes
GET /api/semantic-compilation/status chat:use 全局状态。calculated 仅表示至少存在一个 Term;running: false 不能证明 ingestion 服务可达。
PUT /api/configurations/semantic-compilation semanticCompilation:manage 设置 enabled;启用会 best-effort 触发一次运行。
POST /api/semantic-compilation/reset semanticCompilation:manage 破坏性且异步。 接受对所有数据库编译层的删除重建。202 不代表完成,需要轮询验证。不是小改之后的清理手段。

6.1 status 四个字段的真实含义

响应 SemanticStatusResponse 固定四个字段:calculated、running、last_success_at、last_failure_at。实现见 semantic_compilation/router.py:

  • calculated 来自 semantic_layer_calculated()(dal/terms.py):只查是否存在 source == SEMANTIC_SOURCE 的 Term。一个 Term 就够,它不衡量覆盖度或质量。
  • running 必须问活的 ingestion 进程;proxy.py 在请求失败时降级返回 False。所以 running: false 可能是"没在跑",也可能是"问不到"。
  • last_success_at / last_failure_at 直接读 Postgres 的 semantic_compilation_history,不经过 ingestion 代理,因此服务暂时不可达时历史仍然可见。

这三点合起来解释了原文的警告:不要用 calculated 或 running 推断服务健康。

6.2 开关:PUT 的 best-effort 语义

PUT /api/configurations/semantic-compilation 的 body 是 {"enabled": true}。OpenAPI 描述明确指出:启用会立即触发一次编译并启动 ingestion 服务的调度器,无需重启;但该触发是 best-effort——服务宕机时设置仍会保存,调度器下次启动时再读取该标志。所以 200 不代表服务可达。

6.3 reset:有序、异步、可能耗时数分钟

后端 reset 实际委托给 ingestion 服务的 /semantic/reset(ingestion_service/router.py),其文档串说明了严格顺序:停止正在运行的 pass → 等待其停止 → 删除 → 重建,作为后台任务执行,接口立即返回 202,但等待可能持续数分钟。

为什么必须等待?同一段注释给出了事故复盘:pass 在开始时读取一次工作列表,如果它先于删除完成开始,会看到每张表都仍挂着 Term 而什么都没编译;如果它在删除期间继续运行,会把它已扫过的 Term 又写回去。两个方向都会丢数据。

因此 SKILL.md 的措辞是"Do not call POST /api/semantic-compilation/reset as cleanup"。它需要 semanticCompilation:manage,返回 202 必须轮询 status 并做行为验证,不能当作完成信号。

七、模型交换:备份、替换与回读

Method Path Permission Notes
POST /api/model/export modelInterchange:export JSON body ExportRequest:databases 里放目录数据库 ID(空 = 全部),format 取 auto_ontology 或 ossie。响应是 YAML。
POST /api/model/import modelInterchange:import YAML 导入;请求形式与查询参数见 OpenAPI。坑点:replace 默认 true,覆盖既有定义前必须与用户确认。

7.1 export 的完整参数

ExportRequest 有三个字段:

字段 类型 默认 说明
databases string[] [] 目录数据库 ID 列表;空数组表示导出所有
format auto_ontology | ossie auto_ontology 序列化方言
include_ontology boolean false 仅 Ossie:额外把 terms 导出为 Ossie ontology 及到语义模型的映射,打成三份文档的 zip

实现见 model_interchange/router.py:include_ontology 为真时走 export_ossie_documents,media_type 为 application/zip、文件名为 ossie-model.zip;否则 media_type 为 application/x-yaml、文件名为 {format}-model.yaml,并以 Content-Disposition: attachment 下发。传入未知数据库 ID 会得到 422。

注意:原文强调用数据库 ID 而不是名字。<a href="https://link.gitcode.com/i/8a9bf5ad895db353ea410ebc50787afe" target="_blank">publication.md</a> 第 55-57 行把这条写成了发布流程的第一步——导出精确的 database-ID 范围,保留原始 YAML 与 SHA-256 作为回滚工件。因为"同名不同 ID"的数据库在导入侧可能触发 HTTP 500(issue #267),用名字做 scope 是不可靠的。

7.2 import 的两种请求体与两个查询参数

handler 接受两种输入(router.py):

  • multipart/form-data 的 file 字段;
  • 或者直接把 YAML 作为原始请求体。

两者都为空 → 422;非 UTF-8 → 422 YAML must be UTF-8。查询参数:

参数 默认 含义
replace true 是否替换既有定义
embed true 是否同时生成嵌入

成功响应为 {"success": true, "summary": {...}}。但 success: true 与面向 payload 的 summary 计数不能证明持久化一致——publication.md 明确说了这一点。错误码覆盖 ValidationError、Ossie 转换失败、ModelImportValidationError、未知数据库 ID,全部映射到 422。

7.3 导入前的硬性纪律

SKILL.md 要求:replace=true 前先与用户确认,先在隔离环境应用;publication.md 给出了七步流程:导出并保存原 YAML + SHA-256 → 保留物理 ID → 校验 diff 与受影响查询 → 隔离环境应用 → 同范围再导出并比对 ID/结构/属性/关系/计数 → 跑正负向就绪性、可答性、SQL、行数与答案探针 → 只晋升通过评审的工件。

已知产品限制需要 fail closed,且不能用直接改 Postgres 绕过:

  • issue #250:替换可能保留被省略的语义外键;
  • issue #265:替换可能保留既有属性而不更新;
  • issue #267:不同物理 ID 但相同自然库名可能表现为 HTTP 500。

八、可复用分析定义:发布定义,不发布结果行

原文的一句话是理解这组接口的关键:它们发布可复用定义,而不是任意外部结果行。

Method Path Permission Notes
POST /api/custom-analyses/validate analysis:manage 针对已编目表校验 SQL;解析或解析失败为 422。
POST/PUT/DELETE /api/custom-analyses 或 /api/custom-analyses/{analysis_id} analysis:manage 创建、替换、删除受支持的 SQL 定义。名称或 SQL 冲突返回 409。
GET /api/custom-analyses analysis:read 列出可复用 SQL 定义。
POST/PUT/DELETE /api/pql-analyses 或 /api/pql-analyses/{analysis_id} analysis:manage 创建、替换、删除 PQL 定义。PQL 在预测时校验。
GET /api/pql-analyses analysis:read 列出可复用 PQL 定义。

字段层面:

  • CustomAnalysisCreate:name(minLength: 1)、description、sql(minLength: 1);
  • PqlAnalysisCreate:name、description、pql。

OpenAPI 对 POST /api/custom-analyses 的描述补充了两条实现事实:

  1. 采用严格插入:输入形状由 CustomAnalysisCreate 约束,前端负责 trim 与拒绝空值;更新走 PUT /custom-analyses/{analysis_id}。
  2. 当 name 或 sql 已被其他 CustomAnalysis 使用(两者都是唯一自然键)时返回 409;当 SQL 无法按当前目录解析、识别不到任何表时返回 422——因为缺少这些引用,该分析对检索是"不可见"的。

PQL 的差异在描述里写得很直白:"The PQL text is stored as-is — it is validated against the prediction graph at predict time, not here." 即 PQL 在创建时不做语义校验,校验被推迟到预测阶段。

权限上还有一处容易忽略:这些列表接口给的是 analysis:read,创建/替换/删除是 analysis:manage,validate 与创建同权(analysis:manage),因为校验是创建/编辑流程的一部分。

九、Exploration:只读的语义关系面

这一组全部是 catalog:read:

  • GET /api/exploration/tables/{table_id}/details
  • GET /api/exploration/terms/{term_id}/details
  • GET /api/exploration/terms/{term_id}/path/{other_term_id}
  • GET /api/exploration/graph
  • GET /api/exploration/semantic-graph
  • GET /api/exploration/edges
  • GET /api/exploration/nodes/{node_id}/relationships

它们回答的是"这个数据集是什么意思"这类问题,而不是生成溯源。SKILL.md 对此有明确边界:停留在语义层,不要为了回答"含义"去翻原始 schema。其中 Term → columns、Term → derived SQL、Table → terms 与 SQL attributes、两 Term 之间的语义跳链,是四个最常用的入口。

需要特别提醒:这些是语义关系路径,不是生成溯源、源修订、认证历史或版本谱系。

十、写完怎么验证:回读与行为探针

原文的"Verify after a write"给出了明确顺序:模型导入先按同一 database-ID 范围重新导出,比对精确的持久化结构与属性;然后用 MCP 的 check_answerable 与 ask_question 做正向与负向行为检查。REST 等价物是:

  • POST /api/question-entity-coverage
  • POST /api/chat/completions(SSE,需 chat:use)

10.1 question-entity-coverage

请求体 EntityCoverageRequest:

字段 类型 默认 说明
question string 必填,minLength: 1 自由文本问题
max_distance number 0.75 候选计入的最大 L2 向量距离(分数越小越接近),exclusiveMinimum: 0

MCP 工具 check_answerable 就是这条路(tools.py),被定位为"便宜的预检":先判断语义层是否能覆盖问题中的实体,再决定是否付费调用更慢更贵的 ask_question。

10.2 chat/completions 的流式契约

OpenAPI 描述了几个必须知道的行为:

  • 响应是 text/event-stream,以 data: [DONE] 结束;
  • FastAPI 先发 result(SQL + 格式化答案),若答案有执行结果,会在同一条连接上再发 charts 事件,不需要二次请求;
  • 传 conversation_id 会持久化该轮并额外要求 conversation: ['write'];该会话已有运行中的请求时返回 409;
  • 省略 conversation_id 则无状态运行:没有历史,也没有图表步骤;
  • 未知 UUID 会创建会话,属于他人的 ID 返回 404;
  • 另一个 409 来源是"语义层尚未编译"。

十一、端到端实操:一次受控的属性写入

下面用一个完整脚本串起"校验 → 创建 → 回读 → 状态确认 → 行为探针"。变量替换为你自己的部署地址、token、ID。

export AO_BASE="http://localhost:3000"          # Next.js 网关,不是 :3001
export AO_TOKEN="auto_ontology_xxxxxxxxxxxx"     # 在 UI: 用户菜单 -> API Tokens 铸造
export TERM_ID="term_123"

# 1. 先确认调用者身份与权限(403 说明所有者角色不足,不是路径错)
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "x-api-key: $AO_TOKEN" \
  "$AO_BASE/api/terms?query=revenue&limit=5"

# 2. 校验 SQL 表达式(解析失败 = 422,不是 valid:false)
curl -sS -X POST "$AO_BASE/api/sql-attributes/validate" \
  -H "x-api-key: $AO_TOKEN" -H 'Content-Type: application/json' \
  -d "{\"expression\":\"SUM(net_amount)\",\"term_id\":\"$TERM_ID\"}"

# 3. 创建 SQL attribute(201)
curl -sS -X POST "$AO_BASE/api/sql-attributes" \
  -H "x-api-key: $AO_TOKEN" -H 'Content-Type: application/json' \
  -d "{
    \"name\": \"Net Revenue\",
    \"description\": \"Gross revenue net of tax\",
    \"expression\": \"SUM(net_amount)\",
    \"term_id\": \"$TERM_ID\",
    \"source\": \"manual\"
  }"

# 4. 只改文案用 PATCH(不会重解析 SQL)
curl -sS -X PATCH "$AO_BASE/api/sql-attributes/$ATTR_ID" \
  -H "x-api-key: $AO_TOKEN" -H 'Content-Type: application/json' \
  -d '{"description":"Gross revenue net of tax, reviewed by Finance"}'

# 5. 改公式用 PUT(重解析 + 重嵌入,必填字段齐全)
curl -sS -X PUT "$AO_BASE/api/sql-attributes/$ATTR_ID" \
  -H "x-api-key: $AO_TOKEN" -H 'Content-Type: application/json' \
  -d "{
    \"name\": \"Net Revenue\",
    \"description\": \"Gross revenue net of tax\",
    \"expression\": \"SUM(net_amount) - SUM(tax_amount)\",
    \"term_id\": \"$TERM_ID\"
  }"

# 6. 回读并检查持久化结果
curl -sS -H "x-api-key: $AO_TOKEN" "$AO_BASE/api/sql-attributes/$ATTR_ID"

# 7. 编译状态(calculated 只代表至少有一个 Term)
curl -sS -H "x-api-key: $AO_TOKEN" "$AO_BASE/api/semantic-compilation/status"

# 8. 行为探针:先做便宜的覆盖度预检
curl -sS -X POST "$AO_BASE/api/question-entity-coverage" \
  -H "x-api-key: $AO_TOKEN" -H 'Content-Type: application/json' \
  -d '{"question":"What was net revenue last quarter?","max_distance":0.75}'

若第 8 步通过,再调用 POST /api/chat/completions 看实际 SQL 与答案,并同时准备一个负向问题(例如问一个语义层未覆盖的实体),确认它不会因为"总是返回非空答案"而被误判为通过。这正是 modeling.md 要求的正负向测试。

十二、模型导入的备份与回读骨架

# 备份:使用精确的 database-ID 范围,保存 YAML 并计算哈希作为回滚工件
curl -sS -X POST "$AO_BASE/api/model/export" \
  -H "x-api-key: $AO_TOKEN" -H 'Content-Type: application/json' \
  -d '{"databases":["db_aaa","db_bbb"],"format":"auto_ontology"}' \
  -o before-model.yaml
sha256sum before-model.yaml

# 导入:注意 replace 默认 true,覆盖既有定义前先确认
curl -sS -X POST "$AO_BASE/api/model/import?replace=false&embed=true" \
  -H "x-api-key: $AO_TOKEN" \
  -F "file=@proposed-model.yaml"

# 回读:同范围再导出,逐项比对 ID/结构/属性/关系/计数
curl -sS -X POST "$AO_BASE/api/model/export" \
  -H "x-api-key: $AO_TOKEN" -H 'Content-Type: application/json' \
  -d '{"databases":["db_aaa","db_bbb"],"format":"auto_ontology"}' \
  -o after-model.yaml
diff -u before-model.yaml after-model.yaml

replace=false 只用于增量场景;一旦确认要替换,仍必须保留 before 工件并在隔离环境先行验证。若回读出现差异,按 publication.md 的做法是隔离该工件并在支持的情况下恢复并验证先前状态。

十三、权限与错误码速查

13.1 按操作归类

需求 最小权限
读 Term / ColumnAttribute / SqlAttribute / Exploration catalog:read
改 Term、ColumnAttribute、Catalog Node、SqlAttribute(含 validate 的写侧) catalog:edit
查编译状态、跑问答与覆盖度 chat:use
改编译开关、重置编译 semanticCompilation:manage
导入/导出模型 modelInterchange:import / export
创建或删除可复用分析 analysis:manage(列表只需 analysis:read)
生成 SQL 属性描述建议 catalog:edit

13.2 错误码语义

状态码 典型含义
400 owner_id 无法分配为可编辑该行的用户或组
401 无法解析调用者(token 无效/过期/所有者被禁用)
403 所有者角色缺少该权限;owner 组不匹配;列节点无 owner 时 owner-group viewer 被拒
404 Term / ColumnAttribute / SqlAttribute 不存在;属于他人的 conversation
409 SQL attribute 名称冲突;CustomAnalysis 的名称或 SQL 冲突;会话已有运行中的请求
422 空 patch、名称为空白、SQL 解析失败、表达式在该 Term 下重复、Term 不存在、YAML 非 UTF-8 或校验失败
500 已知限制:不同物理 ID 但同名自然数据库的导入

特别注意两类 422:一是请求体结构不合法(FastAPI/Pydantic 校验),二是业务校验失败(SQL 解析、重复表达式、空 patch)。两者都是 422,靠 detail 区分。原文的"distinguish HTTP 422 parse failures from validation results"说的就是这件事。

十四、排障清单

按 SKILL.md 的地点顺序逐层排查:

  1. 确认入口:打的是 Next.js :3000 而不是 FastAPI :3001。直连后端的请求不经过 withPermission,会得到不同的失败形态。
  2. 确认身份与权限:403 先查 token 所有者角色的权限,再查行的 owner 组。用 GET /api/terms 这类只读接口先确认 token 有效。
  3. 区分 422 的两种来源:No SqlAttribute fields to update 是业务校验;SQL parse error: ... 或 SQL snippet already exists 是解析与冲突。
  4. 不要在编译状态上过度解读:calculated 只代表存在至少一个 Term;running: false 可能只是 ingestion 服务不可达;历史时间戳来自数据库,比 running 更可靠。
  5. 不要用 reset 做小修后的清理:它是异步、全库、破坏性的重建,202 之后必须轮询并验证。
  6. 导入失败不要改库绕过:已知的替换保留、属性未更新、同名不同 ID 这三类限制应表现为 fail closed,而不是直接编辑 Postgres。

十五、相关文件索引

一句话收束:这套写 API 的设计取向是"最小可用写面 + 强回读纪律"。它提供的是可校验、可审计的增量修改通道,而不是一个能任意重建语义模型的通用 CRUD;凡是没有公开端点的能力(创建空 Term、任意结构关系变更、任意结果行写回),都应当视为产品边界,按 fail closed 处理。

登录后查看全文
auto-ontology