#业务知识接口与工具

业务知识用于把 Data Agent 中的语义层建模结果输出给 AI 员工、第三方系统或实施工具使用。它返回的是当前空间、当前用户可见的业务语义元数据，包括业务对象、字段、指标和关系；它不返回订单、客户、合同等业务明细数据。

本文中的业务知识对应系统内置工具 getBusinessKnowledge 和接口：

POST /api/schema:getBusinessKnowledge

#可组合工具总览

第三方系统可以把 Data Agent 的能力拆成多个工具组合使用。常见组合如下：

一个典型第三方 AI 机器人可以这样组合：

1. 先调用 getBusinessKnowledge 获取业务对象、指标口径、指标分析思路和 Schema Edge。
2. 如果用户要查具体数值，调用 askAlisa。
3. 如果用户问“为什么变化”“差异由什么造成”，调用 attribution。
4. 如果问题涉及外部事实、新闻、政策或实时信息，调用 webSearch。
5. 如果问题涉及企业制度、产品手册、FAQ、实施文档等内部资料，调用 searchKnowledgeBase。

getBusinessKnowledge 更像“业务语义地图”，其他工具负责执行查询、归因或检索。第三方系统可以根据意图路由选择一个或多个工具，而不是把所有问题都交给同一个接口。

#和知识库检索的区别

系统中容易混淆的两个工具如下：

如果目标是让 AI 理解“有哪些业务对象可以问、字段和指标是什么意思、对象之间怎么关联”，应使用 getBusinessKnowledge。如果目标是查询制度、产品手册、FAQ、流程文档等非结构化资料，应使用 searchKnowledgeBase。

#适用场景

#AI 员工业务理解

AI 员工在回答业务问题前，可以调用 getBusinessKnowledge 获取可用的业务对象、字段、指标和关系。这样模型可以先确认“用户提到的概念是否存在于业务语义层”，再决定如何回答或调用数据查询工具。

例如用户问“订单转化率按客户等级怎么看”，AI 可以先获取业务知识，确认是否存在订单、客户、客户等级、转化率等对象和指标。

#自然语言查数

自然语言查询需要把用户问题映射到结构化数据模型。业务知识可以帮助查询链路判断：

• 应该使用哪个 Schema。
• 应该选择哪些字段或指标。
• 字段是否有同义词、枚举值或业务说明。
• 多个业务对象之间是否存在可用的关联路径。
• Schema Edge 是否定义了业务流程上的先后关系、推荐分析路径或非物理外键关系。

#BI Copilot 和报表助手

报表助手可以使用业务知识完成图表推荐、维度下钻、指标解释和口径说明。例如在生成图表前，先确认某个指标属于哪个业务对象，哪些字段适合作为分组维度。

#数据目录和业务词典

第三方系统可以把业务知识作为数据目录或业务词典使用，展示当前用户可见的业务对象、字段、指标、同义词、枚举值和业务说明。

#业务知识图谱

前端知识图谱页面也使用该接口拉取数据，然后根据 schemas、relations 中的 schema_edge 和 metric_relation 绘制业务关系图。

#建模审查和影响分析

实施人员可以用该接口检查语义层建模结果，例如：

• 某个字段是否已暴露给 AI。
• 某个 Schema 是否有可用指标。
• Schema Edge 的 joinOn 是否完整。
• 指标之间是否存在依赖关系。

#权限与数据边界

接口和工具会按照当前请求上下文裁剪结果：

• 只返回当前 x-spaces 指定空间中的业务知识。
• 只返回当前登录用户有权限访问的 Schema。
• 字段会按列权限过滤；无字段权限的字段不会出现在输出中。
• 默认只返回启用状态的 Schema Edge。
• 返回的是语义元数据，不返回业务明细数据。

因此，第三方系统拿到的是“当前用户可见的业务语义地图”，不是全局裸数据库字典。

#API 调用方式

#请求地址

POST /api/schema:getBusinessKnowledge

#请求头

#请求参数

schemaSids 和 schemaIds 可以同时传入。接口会在当前用户可见范围内取交集式过滤；请求了但无权限或不存在的 Schema，会体现在 missingRequestedSchemaSids 或 missingRequestedSchemaIds 中。

#获取全部可见业务知识

curl 'http://localhost:13000/api/schema:getBusinessKnowledge' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: default' \
  -H 'Content-Type: application/json' \
  --data '{}'

#只获取指定 Schema

curl 'http://localhost:13000/api/schema:getBusinessKnowledge' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: default' \
  -H 'Content-Type: application/json' \
  --data '{
    "schemaIds": ["order", "customer"]
  }'

也可以按 sid 过滤：

curl 'http://localhost:13000/api/schema:getBusinessKnowledge' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: default' \
  -H 'Content-Type: application/json' \
  --data '{
    "schemaSids": ["schema_order_sid", "schema_customer_sid"]
  }'

#包含禁用的 Schema Edge

实施检查或知识图谱编辑场景下，可能需要查看禁用的 Schema Edge：

curl 'http://localhost:13000/api/schema:getBusinessKnowledge' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: default' \
  -H 'Content-Type: application/json' \
  --data '{
    "includeDisabledSchemaEdges": true
  }'

#响应结构

接口响应形态如下：

{
  "knowledge": {
    "spaceName": "default",
    "selectedSchemaSids": ["schema_order_sid"],
    "selectedSchemaIds": ["order"],
    "requestedSchemaSids": [],
    "requestedSchemaIds": [],
    "missingRequestedSchemaSids": [],
    "missingRequestedSchemaIds": [],
    "summary": {
      "schemaCount": 1,
      "propertyCount": 3,
      "metricCount": 1,
      "relationCount": 1,
      "propertyRefRelationCount": 0,
      "schemaEdgeRelationCount": 1,
      "metricRelationCount": 0
    },
    "schemas": [],
    "metrics": [],
    "relations": []
  }
}

#summary

#schemas

schemas 表示业务对象列表。

{
  "sid": "schema_order_sid",
  "id": "order",
  "name": "订单",
  "type": "fact",
  "description": "订单业务对象",
  "db": "main",
  "from": "dwd_order",
  "properties": [
    {
      "sid": "property_amount_sid",
      "id": "amount",
      "name": "订单金额",
      "type": "number",
      "semanticType": "currency",
      "fieldType": "decimal",
      "description": "订单实付金额",
      "syno": ["金额", "销售额"],
      "enumValues": []
    }
  ]
}

常用字段说明：

#properties

properties 表示业务对象下的字段。

#metrics

metrics 表示业务指标列表。

{
  "sid": "metric_gmv_sid",
  "id": "gmv",
  "name": "销售额",
  "type": "measure",
  "description": "订单金额求和",
  "prompt": "分析销售额时，优先按时间趋势、区域、客户类型、产品分类拆解，并结合订单数和客单价判断增长来源。",
  "ask": "按订单金额求和，剔除已取消订单",
  "calculationType": "atomic",
  "schemaSid": "schema_order_sid",
  "schemaId": "order",
  "schemaName": "订单",
  "syno": ["GMV", "成交额"],
  "isObservation": false,
  "isAdditive": true
}

常用字段说明：

prompt 是指标级的数据分析思路沉淀。它可以把公司内部对某个指标的分析方法固化下来，例如“先看趋势，再按区域和产品拆解”“需要同时关注分子、分母和目标值”“异常波动优先排查渠道、价格和客群变化”等。

这个字段适合直接提供给外部 AI 机器人或第三方 Agent 使用。它解决的不是“指标怎么算”，而是“拿到指标后应该怎么分析、怎么解释、怎么归因”。和其他指标字段的分工如下：

因此，第三方 AI 在调用 askAlisa 查到指标结果后，可以继续读取该指标的 prompt，按公司沉淀的方法生成分析结论，而不是只做通用的同比、环比描述。

#relations

relations 表示业务关系，当前主要有三类。

#property_ref

字段关联关系，表示某个字段引用另一个业务对象。

{
  "kind": "property_ref",
  "sourceSchemaSid": "schema_order_sid",
  "sourceSchemaId": "order",
  "sourceSchemaName": "订单",
  "sourcePropertySid": "property_customer_id_sid",
  "sourcePropertyId": "customer_id",
  "sourcePropertyName": "客户ID",
  "targetSchemaSid": "schema_customer_sid",
  "targetSchemaId": "customer",
  "targetSchemaName": "客户"
}

#schema_edge

Schema Edge 表示业务对象之间的流程边或业务流转关系。目前边类型主要是 process，关系类型主要是 precedes，即“前置于”。

它不是数据库外键的简单复制。数据库外键、字段 ref 或物理表 Join 通常只能说明“两个表可以通过哪个字段连接”，但很难表达“业务上谁先谁后、谁推动谁、应该沿哪条路径解释问题”。Schema Edge 用来补充这类业务语义。

Schema Edge 适合表达以下数据层面难以直接表达的关系：

例如，数据库里可能只有 order_no、contract_no、customer_id 等字段，数据层能说明字段可以 Join，但无法稳定表达“线索 -> 商机 -> 订单 -> 合同 -> 回款”是一条销售业务链路。Schema Edge 可以把这些 Schema 串成带方向、带流程名、带说明的业务图，供 AI 员工、知识图谱和实施检查使用。

典型使用方式：

• 流程理解：告诉 AI “订单前置于合同”“合同前置于回款”，回答流程追踪类问题。
• 漏斗分析：表达线索、商机、订单、成交等阶段关系，辅助识别转化链路。
• 归因路径：当指标变化可能由上游业务对象影响下游业务对象时，提供分析方向。
• 图谱展示：在知识图谱中以有向边展示业务对象之间的业务流转。
• 建模校验：检查关键业务链路是否缺边、方向是否反了、joinOn 是否缺失。

需要注意的是，Schema Edge 当前不是直接执行查询的替代品。真正查数时仍需要查询引擎、Logicform 或 SQL 执行能力；Schema Edge 提供的是“应该如何理解和选择关系”的业务语义。

{
  "kind": "schema_edge",
  "sid": "edge_order_contract_sid",
  "name": "订单到合同",
  "edgeKind": "process",
  "relationType": "precedes",
  "processName": "销售流程",
  "description": "订单前置于合同",
  "enabled": true,
  "sourceSchemaSid": "schema_order_sid",
  "sourceSchemaId": "order",
  "sourceSchemaName": "订单",
  "targetSchemaSid": "schema_contract_sid",
  "targetSchemaId": "contract",
  "targetSchemaName": "合同",
  "joinOn": [
    {
      "sourcePropertySid": "property_order_no_sid",
      "sourcePropertyId": "order_no",
      "sourcePropertyName": "订单号",
      "targetPropertySid": "property_contract_order_no_sid",
      "targetPropertyId": "order_no",
      "targetPropertyName": "订单号"
    }
  ]
}

joinOn 只会输出当前用户有字段权限的关联字段。如果关联字段不可见，该关联字段不会出现在 joinOn 中。

#metric_relation

指标关系表示指标之间的依赖、组成或业务关系。

{
  "kind": "metric_relation",
  "sid": "metric_relation_sid",
  "name": "销售额组成销售目标达成率",
  "relationType": "component_of",
  "description": "销售额是达成率计算的组成指标",
  "enabled": true,
  "sourceSchemaSid": "schema_order_sid",
  "sourceSchemaId": "order",
  "sourceSchemaName": "订单",
  "sourceMetricSid": "metric_gmv_sid",
  "sourceMetricId": "gmv",
  "sourceMetricName": "销售额",
  "targetSchemaSid": "schema_target_sid",
  "targetSchemaId": "sales_target",
  "targetSchemaName": "销售目标",
  "targetMetricSid": "metric_achievement_rate_sid",
  "targetMetricId": "achievement_rate",
  "targetMetricName": "销售目标达成率"
}

#AI 工具调用方式

getBusinessKnowledge 已注册为 Data Agent 的公共工具。AI 员工绑定该工具后，模型可以在需要理解业务语义时自动调用。

工具入参和 API 基本一致：

{
  "schemaSids": ["schema_order_sid"],
  "schemaIds": ["order"],
  "includeDisabledSchemaEdges": false
}

工具返回给模型的是精简后的 JSON 字符串，主要包含：

• summary
• schemas
• metrics
• relations

其中 metrics.prompt 会随指标一起返回，用于向模型提供指标分析思路。

工具展示内容会显示一段摘要，例如：

已获取业务知识：2 个 Schema、18 个字段、4 个指标、3 条关系。
示例 Schema：订单、客户
示例指标：销售额、订单数

AI 员工可以用这些内容完成以下动作：

• 判断用户提到的业务概念是否存在。
• 选择正确的 Schema 和指标。
• 解释字段、指标、枚举值和同义词。
• 按 metrics.prompt 中沉淀的企业分析方法生成指标解读。
• 判断业务对象之间是否有关联路径。
• 基于 Schema Edge 理解业务流程先后关系。

#第三方系统集成建议

#优先使用直连 API

第三方系统如果只是要获取语义层元数据，建议直接调用：

POST /api/schema:getBusinessKnowledge

这样可以稳定拿到结构化 JSON，适合用于：

• 外部 AI Agent 上下文注入。
• MCP 或函数工具封装。
• 数据目录同步。
• 建模质量检查。
• 知识图谱展示。
• 指标分析思路同步。

#组合调用建议

第三方系统通常可以按下面的策略组合工具：

如果第三方系统自己有编排能力，可以把这些工具封装成 MCP、Function Calling 或后端 API 网关；如果希望 Data Agent 自己完成工具选择，可以通过 AI 员工对话接口发起请求，由 AI 员工在对话中调用已绑定的工具。

#使用 schemaIds 控制上下文大小

如果业务空间中 Schema 很多，不建议每次都拉取全量业务知识。可以先通过业务问题或外部路由判断候选 Schema，再传入 schemaIds 或 schemaSids 获取局部业务知识。

#不要把它当作查数接口

业务知识接口只说明“有哪些数据、怎么理解这些数据、对象之间如何关联”。如果需要查询实际指标值或明细数据，应继续调用数据查询、Logicform 执行或资源 CRUD 接口。

#常见问题

#为什么返回的字段比建模页面少？

接口会按当前用户的字段权限过滤。用户没有列权限的字段不会返回。

#为什么请求了某个 Schema 但结果里没有？

常见原因包括：

• schemaIds 或 schemaSids 写错。
• 当前空间不是该 Schema 所在空间。
• 当前用户没有该 Schema 的访问权限。

可以查看响应中的 missingRequestedSchemaSids 和 missingRequestedSchemaIds。

#为什么没有 Schema Edge？

可能原因包括：

• 该空间没有建模 Schema Edge。
• 相关 Schema 不在本次返回范围内。
• Schema Edge 被禁用，且请求未传 includeDisabledSchemaEdges: true。
• joinOn 涉及的字段对当前用户不可见。

#能否直接暴露给外部 AI 机器人？

可以，但建议外部机器人使用服务端代理调用该接口，由代理负责 token、空间、用户身份和权限控制。不要把高权限 token 直接放到前端或第三方不可控环境中。