SonnetDB Graph Workbench 运维：有界可视化、审批维护与 GraphRAG 引用

SonnetDB Graph Workbench 运维：有界可视化、审批维护与 GraphRAG 引用

SonnetDB 的 Graph Workbench 为原生属性图提供有界的巡检、导入导出、受限编辑和两阶段维护入口；本文用当前源码中的 Graph Beta 合同说明怎样把一次运维操作做成可回读的步骤，而不是把画布、快速检查或知识图谱示例误称为生产图数据库验收。

SonnetDB Graph Workbench 运维：有界可视化、审批维护与 GraphRAG 引用

AI 主题示意图，并非实测截图。

先确认版本和适用范围

本文依据 SonnetDB 当前 main 的提交 7255f0104a1176fd15b883814222dd0f23591d8d，而不是把开发分支中的 Graph 合同自动等同于已安装的包能力。公开 NuGet 版本目录包含 4.0.0，也包含一个 4.5.0-preview.ef266.5 预览版本；部署前应以实际 Server、SDK 和包版本为准，并重新运行对应版本的验收。

Graph 当前是 SonnetDB 的 Beta 模型。已有合同覆盖 Graph V1 存储、事务、遍历、运维入口和知识图谱投影；它没有关闭固定 x64/ARM64 硬件、LDBC/Graphalytics、外部 Neo4j/PostgreSQL 对拍、Native AOT 发布物、168 小时 mixed workload、真实 kill/reopen、备份恢复或 Couplet 联合门禁。下面的命令用于了解和操作已授权的图，不构成这些尚未运行的证据。

第一步：用有界概览和画布判断该看什么

先建立一个已获授权的连接字符串，然后指定数据库与 Graph 名称。下面的命令只读；overview 需要 Read 权限：

sndb graph overview --connection "<connection>" --graph knowledge
sndb graph visualize --connection "<connection>" --graph knowledge --limit 250

概览会返回 schema/index 摘要、statement snapshot sequence、顶点和边数量、label/index cardinality、degree histogram、最近慢遍历诊断以及 capability flags。画布不是全图 dump：默认取 250 个顶点，参数范围是 1 到 1,000，内部最多扫描 100,000 条边，并用 truncated 明确指出结果是否被截断。因而下面三种解释必须区分：

  1. truncated=false 只说明这一次受限可视化没有被该限制截断。
  2. truncated=true 可以帮助定位子图，但不能据此断言图中不存在其它顶点或边。
  3. 嵌入式连接没有 Server SQL 慢查询环时，slowTraversalDiagnostics 会是 false，原因是 not_available_embedded，不是“没有慢遍历”。

Workbench 的 Canvas、Schema & diagnostics、Edit、Import/export 与 Maintenance 五个任务页复用同一连接、数据库选择和权限模型。普通元素编辑仍要求本地高风险写确认；这一步不会替代维护审批。

第二步：导出时保存 snapshot 语义，而不是把部分 JSON 当备份

导出命令使用流式 JSON，并可以把输出交给 importer：

sndb graph export --connection "<connection>" --graph knowledge \
  --output ./knowledge.graph.json --max-elements 100000

max-elements 默认 100,000，允许范围为 1 到 1,000,000。输出中的 snapshotSequence 固定读取时刻，elementCount 是实际写出的顶点和边总数。只有 truncated=false 才能把该文件视作完整的 round-trip 数据集；truncated=true 的 JSON 只适合有界检查或部分导入，不能替代 Graph 完整备份或恢复证据。

导入应使用已有 Graph import transaction，并为可重放任务保留稳定 request ID：

sndb graph import --connection "<connection>" --graph knowledge \
  --input ./knowledge.graph.json --batch-size 1000 --request-id <stable-guid>

batch-size、请求 ID、导入前后计数和 truncated 状态都应进入本次运维记录。没有这些信息时，无法从一个导入成功提示推断结果是否完整或是否重复写入。

第三步：把 GraphRAG 的证据留在合适的模型中

SonnetDB 的知识图谱合同不是一个“把文档、向量和模型输出都塞入 Graph”的接口。它将 Entity、Alias、Claim、Source、Chunk、Community 和 Summary 映射为通用 Graph V1 顶点与边；Document/Object 保存权威文本和字节，Vector 保存 embedding 与索引生命周期，Graph 只保存小型属性和稳定引用。

一个批次经过校验器后，仍通过既有 Graph import transaction 写入：

using SonnetDB.Data.Graphs;
using SonnetDB.Data.KnowledgeGraphs;
using SonnetDB.KnowledgeGraphs;

using var graphClient = new SndbGraphClient(connectionString);
await graphClient.CreateGraphAsync("plant-knowledge");

KnowledgeGraphValidationResult validation = KnowledgeGraphValidator.Validate(batch);
if (!validation.IsValid)
    throw new InvalidOperationException("知识图谱批次未通过合同校验。");

GraphImportResponse result = await graphClient.ImportKnowledgeGraphAsync(
    "plant-knowledge", batch);

单个 KnowledgeGraphBatch 最多包含 256 个节点和关系，并映射到一个有界 Graph 原子事务。大任务应分页，每页使用稳定 request ID；跨页不具备原子性。更新时指定 ExpectedElementVersion，软撤回使用 validToUtc，物理删除继续遵守既有 DeleteEdgeAsync / DeleteVertexAsync 与顶点 RESTRICT 规则。实体抽取、消歧、事实判断、embedding 和社区摘要生成由上层 job 完成，本文不把它们描述为 SonnetDB 已验证的模型质量或 RAG 效果。

第四步：维护必须暂存、审批、回读

repair/rebuild、checkpoint 和 compact 不是普通元素编辑。先由 Admin 权限暂存，再由持有审批 ID 的操作者决定：

sndb graph maintenance stage --connection "<connection>" --graph knowledge \
  --action repair --max-work-units 64

sndb graph maintenance approve --connection "<connection>" --graph knowledge \
  --approval <approval-id>

sndb graph maintenance audit --connection "<connection>" --graph knowledge --limit 200

暂存不会执行维护。服务端返回的审批 ID 有效期为 10 分钟；同一 ID 只能决策一次。典型状态是 staged -> applying -> completed|paused|failed，也可能是 rejected 或 expired。repair 可以在 maxWorkUnits 耗尽时返回 paused，此时应读取 audit 并根据返回状态继续决定，而不是把一次 HTTP 202 或一次批准点击当作完成。

compactOnCompletion 只适用于 repair/rebuild；checkpoint 和 compact 不应携带该选项。审计事件会写入 <DataRoot>/.system/graph-maintenance-audit.ndjson（嵌入式则位于 <embedded-db>/.system/...），坏行会在打开时明确拒绝，不能静默跳过。因此不同 CLI 进程可以分别暂存和批准，但必须针对同一个数据库与 Graph 回读审批记录。

发布与生产边界

这一套入口关闭的是受限运维产品面，不是 Graph Production gate。当前快速管线能执行本地 reader/update、checkpoint、正常重开、一次子进程 kill/reopen、invariant 和 BackupService verify/restore，但其报告字段仍为 correctness_recovery: NOT_RUN、performance_capacity: NOT_RUN、release_decision: NOT_RUN。固定硬件上的 1m vertex/10m edge、外部对拍、Native AOT 发布物、7 天或 168 小时负载和真实恢复证据仍需在对应环境中独立取得。

可核查来源

关注我们，扫码进群沟通

欢迎关注我们，扫码加入微信或 QQ 交流群，一起交流技术实践，分享使用经验和问题反馈。

微信交流二维码

微信交流二维码

QQ 交流群：IoTSharp，群号 63631741

IoTSharp QQ 交流群二维码，群号 63631741

请扫码并关注我们，进群沟通。若二维码暂时无法使用，可通过 QQ 群号 63631741 搜索加入。

posted @ 2026-10-30 02:26  IoTSharp  阅读(6)  评论(0)    收藏  举报