构建本体知识库（Ontology）
本体（Ontology）是知识库的 schema 定义，用于声明业务领域中的实体类型、属性与关系，让知识图谱精准理解您的业务语义，实现多跳推理与关联检索。本文介绍如何在上下文服务（Context0）中创建支持图谱的知识库、定义并应用 Ontology 版本、利用图谱增强检索，以及图谱维护、版本管理、限制与权限说明。
什么是本体（Ontology）
用数据库做类比：Ontology 像表结构（Schema），知识图谱像表数据（Data）。Ontology 定义您的业务领域中有哪些实体类别、属性和关系；知识图谱则是文档入库后，系统按 Ontology 自动抽取实体与关系所得到的结果。也就是说，Ontology 是 schema 定义，知识图谱是按 Ontology 抽取实体关系后的结果，两者是「定义」与「数据」的关系。
构建一个本体知识库共分四步，本文按此顺序展开：
创建支持图谱的知识库：建库时设置 graph_enabled: true。
定义 Ontology Schema：通过样本发现、手动定义或导入 JSON 三种方式之一生成候选版本。
应用 Ontology 版本：把候选版本显式应用为活跃版本，此后新入库文档才会按该 schema 抽取。
利用图谱增强检索：开启图谱后，检索请求会自动融合图谱多跳推理结果，无需额外操作。
为什么需要本体（Ontology）
理赔专员问 Agent「重疾险的理赔流程涉及哪些部门」，纯关键词搜索只能找到包含这些词的片段；有了 Ontology，Agent 理解「理赔流程」是 Process 类型实体，沿 involves 关系找到所有关联部门——即使这些信息分散在不同文档中。
#zIGWxVFwCwlh text { white-space: pre; }#zIGWxVFwCwlh .fb0 { stroke: var(--N900-FG, 0.15); }#zIGWxVFwCwlh .fb0 {stroke: rgba(31,35,41, 0.15)}#zIGWxVFwCwlh .fx0 { stroke-miterlimit: 10; }#zIGWxVFwCwlh .fx0 {stroke-miterlimit: 10}#zIGWxVFwCwlh .fa1 { fill: rgb(187, 191, 196); }#zIGWxVFwCwlh .fa1 {fill: rgb(187, 191, 196)}#zIGWxVFwCwlh .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#zIGWxVFwCwlh .fx1 {font-style: normal}#zIGWxVFwCwlh .fx2 { text-anchor: middle; }#zIGWxVFwCwlh .fx2 {text-anchor: middle}#zIGWxVFwCwlh .fx3 { dominant-baseline: central; }#zIGWxVFwCwlh .fx3 {dominant-baseline: central}#zIGWxVFwCwlh .fx4 { stroke: none; }#zIGWxVFwCwlh .fx4 {stroke: none}#zIGWxVFwCwlh .fc0 { fill: var(--text-caption); }#zIGWxVFwCwlh .fc0 {fill: #646a73}#zIGWxVFwCwlh .fa2 { fill: var(--text-link-disabled); }#zIGWxVFwCwlh .fa2 {fill: rgb(187, 191, 196)}#zIGWxVFwCwlh .fa3 { fill: rgb(229, 229, 229); }#zIGWxVFwCwlh .fa3 {fill: rgb(229, 229, 229)}#zIGWxVFwCwlh .fx5 { font: 700 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#zIGWxVFwCwlh .fx5 {font-style: normal}#zIGWxVFwCwlh .fx6 { text-anchor: start; }#zIGWxVFwCwlh .fx6 {text-anchor: start}#zIGWxVFwCwlh .fx7 { dominant-baseline: alphabetic; }#zIGWxVFwCwlh .fx7 {dominant-baseline: alphabetic}#zIGWxVFwCwlh .fc1 { fill: rgb(0, 0, 0); }#zIGWxVFwCwlh .fc1 {fill: rgb(0, 0, 0)}#zIGWxVFwCwlh .fx8 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#zIGWxVFwCwlh .fx8 {font-style: normal}#zIGWxVFwCwlh .fb1 { fill: var(--N900-FG, 0.15); }#zIGWxVFwCwlh .fb1 {fill: rgba(31,35,41, 0.15)}#zIGWxVFwCwlh .fb2 { fill: rgb(216, 216, 216); }#zIGWxVFwCwlh .fb2 {fill: rgb(216, 216, 216)}#zIGWxVFwCwlh .fa4 { fill: var(--bg-body); }#zIGWxVFwCwlh .fa4 {fill: #fff}ABC12345维度无 Ontology有 Ontology检索方式问题处理举例实体识别纯向量 + BM25 关键词匹配适合事实型直接问答「XX 产品的保费是多少」这类可直接命中的问题无类型约束，可能混淆同名概念向量 + BM25 + 图谱多跳关系推理支持关系推理、因果分析、跨文档关联「理赔流程涉及哪些角色和部门」这类需要关联的问题按 Ontology 类型精确分类
什么时候需要 Ontology
并非所有知识库都需要 Ontology。您可以对照下表判断：
#OQNSNVsapqwo text { white-space: pre; }#OQNSNVsapqwo .fb0 { stroke: var(--N900-FG, 0.15); }#OQNSNVsapqwo .fb0 {stroke: rgba(31,35,41, 0.15)}#OQNSNVsapqwo .fx0 { stroke-miterlimit: 10; }#OQNSNVsapqwo .fx0 {stroke-miterlimit: 10}#OQNSNVsapqwo .fa1 { fill: rgb(187, 191, 196); }#OQNSNVsapqwo .fa1 {fill: rgb(187, 191, 196)}#OQNSNVsapqwo .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#OQNSNVsapqwo .fx1 {font-style: normal}#OQNSNVsapqwo .fx2 { text-anchor: middle; }#OQNSNVsapqwo .fx2 {text-anchor: middle}#OQNSNVsapqwo .fx3 { dominant-baseline: central; }#OQNSNVsapqwo .fx3 {dominant-baseline: central}#OQNSNVsapqwo .fx4 { stroke: none; }#OQNSNVsapqwo .fx4 {stroke: none}#OQNSNVsapqwo .fc0 { fill: var(--text-caption); }#OQNSNVsapqwo .fc0 {fill: #646a73}#OQNSNVsapqwo .fa2 { fill: var(--text-link-disabled); }#OQNSNVsapqwo .fa2 {fill: rgb(187, 191, 196)}#OQNSNVsapqwo .fa3 { fill: rgb(229, 229, 229); }#OQNSNVsapqwo .fa3 {fill: rgb(229, 229, 229)}#OQNSNVsapqwo .fx5 { font: 700 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#OQNSNVsapqwo .fx5 {font-style: normal}#OQNSNVsapqwo .fx6 { text-anchor: start; }#OQNSNVsapqwo .fx6 {text-anchor: start}#OQNSNVsapqwo .fx7 { dominant-baseline: alphabetic; }#OQNSNVsapqwo .fx7 {dominant-baseline: alphabetic}#OQNSNVsapqwo .fc1 { fill: rgb(0, 0, 0); }#OQNSNVsapqwo .fc1 {fill: rgb(0, 0, 0)}#OQNSNVsapqwo .fx8 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#OQNSNVsapqwo .fx8 {font-style: normal}#OQNSNVsapqwo .fb1 { fill: var(--N900-FG, 0.15); }#OQNSNVsapqwo .fb1 {fill: rgba(31,35,41, 0.15)}#OQNSNVsapqwo .fb2 { fill: rgb(216, 216, 216); }#OQNSNVsapqwo .fb2 {fill: rgb(216, 216, 216)}#OQNSNVsapqwo .fa4 { fill: var(--bg-body); }#OQNSNVsapqwo .fa4 {fill: #fff}AB123456您的场景建议文档简单，主要是事实查询需要跨文档关联推理领域有明确的实体类型和关系（保险、医疗、组织架构）文档量小（<20 篇），先快速验证文档数百篇，需精确控制抽取逻辑不需要，纯 RAG（检索增强生成）即可。建议定义 Ontology强烈推荐先用 RAG，后续再加强烈推荐
核心概念
Ontology 由以下五类要素组成：
•
实体类型（Type）：业务领域中的对象类别。每个类型有唯一 ID、显示名称和可选别名。
•
属性（Attribute）：实体的结构化字段。支持 string、number、boolean，可标记 required 和 allowedUnits。
•
关系（Relation）：实体间的语义连接，指定源类型（domain）和目标类型（range）。min 与 max 设置基数约束，max: null 表示无上限。
•
约束与指令：约束分为两类。
◦
结构化约束：属性的 required、allowedUnits，关系的 min 与 max。
◦
自然语言指令：通过 graph_extraction_instructions 和 ontology_discovery_instructions 引导抽取行为，随版本保存，抽取时自动注入 LLM 提示词。
•
实例（Instance）：文档入库时按 Ontology 自动抽取的实体和关系，每个实例带原文出处（evidence）。
Schema 示例
以下 Schema JSON 示例定义了产品、理赔流程、部门三个实体类型，以及 involves、belongs_to 两条关系：
代码块
JSON
{
"types": [
{"id": "product","name": "Product","aliases": ["产品", "保险产品"],"attributes": [{ "id": "premium", "name": "Premium", "valueType": "number", "required": true, "allowedUnits": ["元", "万元"] },{ "id": "effective_date", "name": "EffectiveDate", "valueType": "string", "required": false, "allowedUnits": [] }]},{"id": "claim_process","name": "ClaimProcess","aliases": ["理赔流程"],"attributes": []},{"id": "department","name": "Department","aliases": ["部门"],"attributes": []}],"relations": [{ "id": "involves", "name": "involves", "domain": "claim_process", "range": "department", "min": 0, "max": null },{ "id": "belongs_to", "name": "belongsTo", "domain": "product", "range": "department", "min": 0, "max": 1 }
说明：类型最多 100 个，关系最多 300 条，每个类型最多 50 个属性。max 为 null 表示无上限。
保存 schema 时可附带抽取指令：
代码块
JSON
{
"instructions": {
"ontology_discovery_instructions": "仅关注产品与理赔流程",
"graph_extraction_instructions": "严格遵守固定类型和单位"
准备工作
本文的接口示例均调用数据面 /v1/* 接口，并统一使用下列变量。执行示例前，请先将变量替换为您的实际值；示例中出现的知识库 ID、任务 ID、版本号等数值均为示例值，也请替换为您环境中的实际值。
•
$HOST：Context0 实例的服务地址，例如 http://
•
$API_KEY：调用接口时通过 X-API-Key 请求头携带的 Key。Context0 提供三类 Key（Owner Key、Admin Key、User Key），各类 Key 的权限范围与获取方式请参见权限与访问控制。
•
$KB_ID：知识库 ID，即第一步创建知识库后响应中的 data.id。
•
$TASK_ID：样本发现任务 ID，即提交样本发现后响应中的 task_id。
•
$VERSION_ID：Ontology 版本号，可从版本目录中获取。
说明
•
服务地址与 API Key 在开通上下文服务时获取，操作步骤请参见快速入门。
•
不同操作要求的 Key 类型与知识库 ACL 角色不同，本文各操作所需的角色见权限一览章节。
第一步：创建支持图谱的知识库
创建知识库时设置 graph_enabled: true 开启知识图谱。
通过 API
调用创建知识库接口，在请求体中指定 graph_enabled: true：
代码块
Bash
curl -X POST "$HOST/v1/knowledge/bases" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "保险产品知识库",
"description": "涵盖保险产品、理赔流程、合规条款",
"graph_enabled": true,
"visibility": "workspace"
}'
响应中 data.graph_enabled 为 true 即表示图谱已开启。请记下 data.id，后续步骤中的 $KB_ID 即为该值。
说明：已有知识库想开启图谱？通过 PUT /v1/knowledge/bases/{kbId}/settings 转入{"graph_enabled": true} 即可，需 owner 权限。
通过 Dashboard
在知识库列表页单击创建知识库。
填写名称和描述。
开启知识图谱开关。
选择可见性，单击确认。
第二步：定义 Ontology Schema
Context0 提供三种方式创建 Ontology：样本发现、手动定义、导入 JSON。定义保存后为候选版本，不会自动生效——需要在第三步中显式应用。
样本发现（推荐新手使用）
上传 1–4 份示例文档（PDF / DOCX / TXT / MD，总计 ≤ 20 MiB），由模型自动发现实体类型和关系，生成候选 schema。
•
通过 API
◦
提交样本发现任务：
代码块
Bash
curl -X POST "$HOST/v1/knowledge/bases/$KB_ID/ontology/discoveries" \
-H "X-API-Key: $API_KEY" \
-F 'files=@sample-product.pdf' \
-F 'files=@sample-claim.txt' \
-F 'options={"request_id":"discovery-001","ontology_discovery_instructions":"仅关注产品与理赔流程","competency_questions":["某产品适用哪些免责条款？","理赔流程涉及哪些部门？"]};type=application/json'
◦
返回 HTTP 202，包含 task_id。发现为异步过程，完成后自动生成候选版本。
◦
说明
◦
competency_questions（选填）：希望 Ontology 能回答的业务问题（最多 10 条）。schema 无法支撑时，质量报告给出 competency_unsupported 提示。
代码块
Bash
curl "$HOST/v1/knowledge/bases/$KB_ID/ontology/discoveries/$TASK_ID" \
-H "X-API-Key: $API_KEY"
•
通过 Dashboard
a.
进入知识库详情的本体（Ontology）页签。
b.
单击上传文档发现，上传文档，可选填发现指令和能力问题。
c.
提交后等待任务完成，结果出现在版本目录中。
手动定义
适合已清楚领域模型的场景，直接提交完整 schema JSON。
•
通过 API
代码块
Bash
•
说明
•
expected_version_id 传 null 表示首个版本。后续保存新版本时需取目录返回的 head_version_id，避免并发冲突。
•
通过 Dashboard
a.
进入知识库详情的本体（Ontology）页签。
b.
在编辑器中添加类型、属性和关系。
c.
单击保存生成候选版本。
导入 JSON
已有 schema JSON 文件（如从另一个知识库导出或团队模板），可直接导入。
•
通过 API
代码块
Bash
curl -X POST "$HOST/v1/knowledge/bases/$KB_ID/ontology/candidates" \
•
通过 Dashboard：进入本体（Ontology）页签，单击导入 JSON，选择文件确认。
保存前校验（可选）
提交 schema 前可先做结构校验：
代码块
Bash
返回 {"valid": true, "issues": []} 表示通过；否则 issues 列出每个问题的路径和说明。
质量报告
样本发现完成后，查询任务详情可获取质量报告（quality_report）：
代码块
Bash
curl "$HOST/v1/knowledge/bases/$KB_ID/ontology/discoveries/$TASK_ID" \
-H "X-API-Key: $API_KEY"
任务完成后的响应示例如下，其中 issues 逐条列出 schema 存在的问题：
代码块
JSON
{"task_id": "...", "status": "done", "schema_version_id": 12,"quality_report": {"metrics": {"type_count": 8, "relation_count": 5, "live_coverage": 0.71},"issues": [{"path": "types/vendor", "rule": "type_occurrence", "severity": "warning", "message": "类型 vendor 在样本中仅命中 1 次"},{"path": "cq/1", "rule": "competency_unsupported", "severity": "warning", "message": "能力问题「某产品适用哪些免责条款？」缺少可支撑的类型或关系"}]}
常见 issue 规则如下：
#DOtziLEMnPFt text { white-space: pre; }#DOtziLEMnPFt .fb0 { stroke: var(--N900-FG, 0.15); }#DOtziLEMnPFt .fb0 {stroke: rgba(31,35,41, 0.15)}#DOtziLEMnPFt .fx0 { stroke-miterlimit: 10; }#DOtziLEMnPFt .fx0 {stroke-miterlimit: 10}#DOtziLEMnPFt .fa1 { fill: rgb(187, 191, 196); }#DOtziLEMnPFt .fa1 {fill: rgb(187, 191, 196)}#DOtziLEMnPFt .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#DOtziLEMnPFt .fx1 {font-style: normal}#DOtziLEMnPFt .fx2 { text-anchor: middle; }#DOtziLEMnPFt .fx2 {text-anchor: middle}#DOtziLEMnPFt .fx3 { dominant-baseline: central; }#DOtziLEMnPFt .fx3 {dominant-baseline: central}#DOtziLEMnPFt .fx4 { stroke: none; }#DOtziLEMnPFt .fx4 {stroke: none}#DOtziLEMnPFt .fc0 { fill: var(--text-caption); }#DOtziLEMnPFt .fc0 {fill: #646a73}#DOtziLEMnPFt .fa2 { fill: var(--text-link-disabled); }#DOtziLEMnPFt .fa2 {fill: rgb(187, 191, 196)}#DOtziLEMnPFt .fa3 { fill: rgb(229, 229, 229); }#DOtziLEMnPFt .fa3 {fill: rgb(229, 229, 229)}#DOtziLEMnPFt .fx5 { font: 700 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#DOtziLEMnPFt .fx5 {font-style: normal}#DOtziLEMnPFt .fx6 { text-anchor: start; }#DOtziLEMnPFt .fx6 {text-anchor: start}#DOtziLEMnPFt .fx7 { dominant-baseline: alphabetic; }#DOtziLEMnPFt .fx7 {dominant-baseline: alphabetic}#DOtziLEMnPFt .fc1 { fill: rgb(0, 0, 0); }#DOtziLEMnPFt .fc1 {fill: rgb(0, 0, 0)}#DOtziLEMnPFt .fx8 { font: 400 14px LarkHackSafariFont, LarkEmojiFont, Menlo, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, "Noto Sans", Tahoma, "Nimbus Sans L", Arial, "Liberation Sans", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", "Microsoft YaHei", "Wenquanyi Micro Hei", "WenQuanYi Zen Hei", STHeiti, SimHei, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", system-ui; }#DOtziLEMnPFt .fx8 {font-style: normal}#DOtziLEMnPFt .fx9 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#DOtziLEMnPFt .fx9 {font-style: normal}#DOtziLEMnPFt .fb1 { fill: var(--N900-FG, 0.15); }#DOtziLEMnPFt .fb1 {fill: rgba(31,35,41, 0.15)}#DOtziLEMnPFt .fb2 { fill: rgb(216, 216, 216); }#DOtziLEMnPFt .fb2 {fill: rgb(216, 216, 216)}#DOtziLEMnPFt .fa4 { fill: var(--bg-body); }#DOtziLEMnPFt .fa4 {fill: #fff}ABC123规则级别含义type_occurrencecompetency_unsupportedwarning / errorwarning类型在样本中命中次数偏低（0 次为 error，1 次为 warning）某条能力问题缺少可支撑的类型或关系
质量门模式：默认为 warn 模式，正常生成候选版本，issue 只提示不拦截。strict 模式下存在 error 级 issue 时任务判定失败（status: dead），不产出候选版本。
说明
Dashboard 中，发现任务面板会展示质量报告卡片；版本历史详情中也能回看。
第三步：应用 Ontology 版本
候选版本不会自动生效，需显式应用为活跃版本。
查看当前活跃版本
查询知识库当前生效的 Ontology 版本：
代码块
Bash
返回 {"generation": 0, "schema_version_id": null} 表示尚未应用。
应用版本
•
通过 API
代码块
Bash
curl -X PUT "$HOST/v1/knowledge/bases/$KB_ID/ontology/active" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expected_generation": 0,
"schema_version_id": "你的版本ID"
}'
•
expected_generation 取自 /active 返回的 generation，用于乐观并发控制；冲突时返回 409。
•
通过 Dashboard：在版本目录中找到目标版本，单击应用为活跃版本并确认。
•
说明
•
应用不等于全库重建。已有文档需重新摄入才会按新 schema 抽取，新文档自动使用活跃 schema。
停用 Ontology
将 schema_version_id 设为 null 即可停用：
代码块
Bash
curl -X PUT "$HOST/v1/knowledge/bases/$KB_ID/ontology/active" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expected_generation": 1,
"schema_version_id": null
}'
停用后新文档不再进行图谱抽取，已有图谱数据保留。
第四步：利用图谱增强检索
开启 graph_enabled 的知识库检索时自动走 graph-augmented RAG 路径（查询解析 → 图谱多跳遍历 → 与传统 RAG 结果融合 → Rerank），无需额外操作。
通过 API
发起一次知识库检索，例如查询「理赔流程涉及哪些部门」：
代码块
Bash
curl -X POST "$HOST/v1/knowledge/search" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "理赔流程涉及哪些部门",
"kb_ids": [1],
"top_k": 5
}'
响应中同时包含图谱路径匹配项和传统 chunk 匹配项。
通过 Dashboard
在知识库详情的图谱页签中，可视化查看实体和关系、按类型筛选、单击节点展开一跳邻域。支持 Canvas 视图（节点按类型着色）和 Table 视图。
图谱维护
冲突检测与评审
多文档合并时可能出现类型或别名冲突：
冲突检测与评审共四个端点，路径前缀为 /v1/knowledge-bases/$KB_ID：
•
触发检测：
代码块
Bash
curl -X POST "$HOST/v1/knowledge-bases/$KB_ID/graph/conflicts/detect" \
-H "X-API-Key: $API_KEY"# => {"scanned_documents":12,"conflicts":3,"opened":2,"refreshed":1,"staled":0}
•
裁决冲突：
代码块
Bash
# type 冲突：选定正确类型（必须在候选集内）
curl -X POST "$HOST/v1/knowledge-bases/$KB_ID/graph/conflicts/11/decision" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{"action":"resolve","chosen_type":"project"}'# alias 冲突：选定别名归属
curl -X POST "$HOST/v1/knowledge-bases/$KB_ID/graph/conflicts/12/decision" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{"action":"resolve","chosen_owner":"阿里云"}'# 忽略：同指纹冲突不再提醒
curl -X POST "$HOST/v1/knowledge-bases/$KB_ID/graph/conflicts/12/decision" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"action":"dismiss"}'
说明：裁决异步生效。dismiss 后同指纹冲突不再重开；信号消失转 stale，复现时恢复 open。Dashboard 在图谱页签提供冲突检测按钮和评审队列。
抽取增强
图谱抽取阶段内置两项自动增强，均默认开启：
•
指代消解：自动将代词或简称（「它」「该系统」）回指到实体名，减少实体割裂。
•
实体自动确认：对归一名称相同的高置信度候选自动确认，减少人工消歧负担。Jaccard 高相似度确认可选启用。
版本管理
查看版本目录
分页查询该知识库的全部 Ontology 版本：
代码块
Bash
curl "$HOST/v1/knowledge/bases/$KB_ID/ontology/catalog?page=0&size=20" \
-H "X-API-Key: $API_KEY"
每个条目包含 source_kind、type_count、relation_count、is_active 等信息。来源标识含义如下：
删除版本
删除指定的候选版本：
代码块
Bash
curl -X DELETE "$HOST/v1/knowledge/bases/$KB_ID/ontology/versions/$VERSION_ID?expected_generation=1" \
-H "X-API-Key: $API_KEY"
说明：活跃版本和运行中任务使用的版本不能删除（返回 409）。删除仅隐藏目录条目，历史数据仍可按 ID 读取。
限制与注意事项
•
Ontology 仅影响 graph-augmented RAG 路径，不影响纯向量、BM25 和 Wiki 检索。
•
图谱构建为异步过程，单篇文档抽取上限 64,000 字符，超限文档会失败并保留旧图谱。
•
Schema 变更后已有文档需重新摄入，只有新入库文档按新 schema 抽取。
•
Ontology 按知识库独立管理，不支持跨知识库共享。需要在多个知识库间复用时，导出 JSON 再分别导入。
•
样本发现限制：每批 1–4 个文件，格式为 PDF、DOCX、TXT、MD，单文件 ≤ 10 MiB，总计 ≤ 20 MiB。样本不入库。
•
权限：查看需 viewer，保存、校验、发现、应用、删除需 editor。
权限一览
Ontology 与图谱各操作所需的知识库 ACL 角色如下表所示。Key 类型与 ACL 角色的对应关系请参见权限与访问控制。