Semantica Knowledge Explorer 完全指南安装启动、工作区导航与实时图谱工作台【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semanticaSemantica Knowledge Explorer 是 Semantica 平台自带的浏览器端图工作台browser-based graph workbench它把知识图谱的探索、时间线回放、决策因果链追踪、实体去重与本体Ontology可视化管理整合进一个 Web 界面构建于 React 19 Sigma.js 之上。本文以 explorer/README.md 为骨架结合semantica/explorer后端源码、explorer/src 前端源码与 docs/reference/explorer.md 参考文档完整讲解 Explorer 的两种运行方式、CLI 参数、安全模型、工作区能力、环境变量、开发代理与故障排查读完后你可以立即把任意 ContextGraph JSON 文件启动成可交互的图谱仪表盘并理解其前后端协作的底层原理。一、Explorer 是什么从 JSON 文件到交互式图谱工作台Explorer 的定位是一个server process服务进程而不是可导入的 Python 库。它将 Semantica 生态中已经构建好的知识图谱ContextGraph加载进内存通过 FastAPI 提供 REST 与 WebSocket 接口再由 React 前端把图渲染成可平移缩放pan zoom的实时画布。核心能力包括图谱探索拖拽缩放实时画布、ForceAtlas2 物理布局、Ego Mode、语义距离热力图、路径高亮时间线回放拖动时间轴观察图谱随时间演化决策审计浏览每条已记录决策背后的因果链附带结果徽章与置信度分数实体解析基于 blocking 语义去重审查并合并重复实体本体管理SHACL Studio、可视化拖拽编辑器、跨本体对齐、SKOS 浏览器溯源可视化基于 W3C PROV-O 标准展示任意实体的 Lineage。从前端代码看App.tsx 定义了六类导航工作区Knowledge Explorer / Analyze / Decisions / Enrich / Manage / Ontology Hub而 src/workspaces 下实际实现了 14 个具体工作区包括 GraphWorkspace、DecisionWorkspace、DiffMergeWorkspace、EnrichWorkspace、ImportExportWorkspace、LineageWorkspace、ManageWorkspace、OntologyWorkspace、SparqlWorkspace、VocabularyWorkspace以及 MemoryWorkspace 与 ReasoningWorkspace。这说明 README 中的工作区表格是能力的最小集实际前端已覆盖更广。二、环境要求依赖最低版本Python3.8Node.js18.x 或更高推荐 20.xnpm9.x 或更高启动前建议先验证三者的版本python --version node --version npm --version注意Node.js 18 的限制来自 Vite 6详见本文“故障排查”一节如果使用源码开发模式运行前端Node 版本过低会导致npm run dev失败。三、两种运行方式Explorer 提供两条运行路径pip 安装推荐给使用者与源码运行推荐给贡献者 / 前端开发者。两者共享同一套 FastAPI 后端区别仅在于前端是使用预构建 bundle 还是 Vite 开发服务器。Option A — pip 安装推荐安装带 explorer extras 的包wheel 内已包含预构建前端 bundle无需 Node.jspip install semantica[explorer]启动时用--graph指向任意图 JSON 文件semantica-explorer --graph my_graph.json服务默认启动在http://127.0.0.1:8000并自动在默认浏览器中打开仪表盘。CLI 参数完整表格Flag默认值说明--graph/-g(必填)ContextGraph JSON 文件路径--port/-p8000服务绑定端口--host127.0.0.1绑定主机本地开发用127.0.0.1参见下文安全说明--no-browser关闭跳过自动打开浏览器从 CLI 入口源码 可以看到这确实是 Explorer 支持的全部四个参数且--graph是必填项——若文件不存在程序会打印Error: graph file not found并直接sys.exit(1)。图加载完成后终端会输出节点/边统计✓ Graph loaded — 42 nodes, 87 edges常用示例# 默认方式——打开于 http://127.0.0.1:8000 semantica-explorer --graph my_graph.json # 自定义端口 semantica-explorer --graph my_graph.json --port 8080 # 禁止自动打开浏览器 semantica-explorer --graph my_graph.json --no-browser # 等价于 python -m 方式 python -m semantica.explorer --graph my_graph.jsonpython -m semantica.explorer由 semantica/explorer/main.py 提供模块入口最终同样调用main()。安全说明API Key 与匿名访问自 v0.6.5 起Explorer 的 API 在受保护路由上强制要求 API Key设置环境变量SEMANTICA_API_KEY并通过X-API-Key请求头发送未配置 Key 时受保护路由一律 fail closed返回503绝不会匿名放行仅本地开发需要匿名访问时必须显式设置SEMANTICA_ALLOW_ANONYMOUStrue/api/health与/api/info刻意保持免鉴权。这套“默认拒绝”逻辑在 dependencies.py 中有完整的源码实现require_auth依赖先检查SEMANTICA_ALLOW_ANONYMOUS若未开启匿名再检查SEMANTICA_API_KEY是否配置——未配置则抛503 SERVICE_UNAVAILABLE配置了但 Key 不匹配则抛401 UNAUTHORIZED且比较时使用hmac.compare_digest做常数时间比较避免时序侧信道。Key 每次从环境变量实时读取不缓存因此运维可以在不重启进程的情况下轮换 Key。主机绑定风险提示默认--host 127.0.0.1只绑定本地回环局域网内其他机器无法访问。如果绑定到0.0.0.0则任何能触达该端口的主机都可读写全部图数据受 API Key 鉴权约束。CLI 在两种情况下会打印警告见 CLI 源码绑定非回环主机且处于匿名模式SEMANTICA_ALLOW_ANONYMOUStrue绑定非回环主机但未设置SEMANTICA_API_KEY受保护路由将全部拒绝 503。# 典型安全启动组合 export SEMANTICA_API_KEYyour-secret-key semantica-explorer --graph my_graph.json --host 127.0.0.1Option B — 源码运行贡献者 / 前端开发此模式运行 React 开发服务器启用热模块替换HMR前端改动可即时在浏览器中生效无需重新构建。Step 1 — 克隆仓库git clone https://github.com/semantica-agi/semantica.git cd semanticaStep 2 — 安装 Python 包pip install -e .[explorer]Step 3 — 安装前端依赖cd explorer npm ciStep 4 — 启动 Python 后端在仓库根目录打开一个终端semantica-explorer --graph path/to/my_graph.json --no-browserAPI 运行于http://127.0.0.1:8000保持该终端开启。Step 5 — 启动前端开发服务器在explorer/目录打开第二个终端npm run devVite 启动于http://localhost:5173在浏览器打开该地址。所有/api与/ws请求都会自动代理到http://127.0.0.1:8000的 Python 后端。四、构建生产 bundle如果需要让 Python 服务器直接托管 UI而不依赖 Vite 开发服务器cd explorer npm ci npm run build构建产物写入../semantica/static/。之后 Python 服务器会在http://127.0.0.1:8000直接提供完整仪表盘无需额外的 Vite 进程。从 vite.config.ts 可以看清构建细节build.outDir指向仓库根的semantica/staticemptyOutDir: true并通过manualChunks把 Sigma/Graphologygraph-vendor、vis-timelinetimeline-vendor、tanstack/react-queryquery-vendor拆分为独立 vendor chunk优化缓存与首屏加载。后端侧app.py 会挂载/assets静态目录并提供/{full_path:path}的 SPA 回退路由——任何非/api路径都返回index.html交由前端路由接管如果静态目录里没有index.html根路径会返回一个说明修复方式的 HTML 页面Explorer UI not available同时提示 REST API 在/docs仍可用。五、工作区全景工作区你可以做什么Knowledge Graph实时 Sigma.js 画布 · ForceAtlas2 布局 · Ego Mode · 语义距离热力图 · 路径高亮Timeline时间事件滑动条——观察图谱随时间演化Decisions浏览每条已记录决策背后的因果链附带结果徽章与置信度分数Registry每一次图变更add-node、add-edge、delete、update的实时审计日志Entity Resolution通过 blocking 语义去重审查并合并重复实体KG Overview聚合统计、社区分解、中心性热力图Ontology HubSHACL Studio · 可视化拖拽编辑器 · 跨本体对齐 · SKOS 浏览器Lineage任意实体的 W3C PROV-O 溯源可视化各工作区在前端有明确对应实现例如 GraphWorkspace 及其behaviors/点击选择、缩放适配、相机聚焦、悬停激活、路径高亮、搜索聚焦、视图切换与plugins/探索特效、图例、邻域面板、时间叠加层OntologyWorkspace 内含 ShaclStudio、OntologyEditor、SKOSVocabularyManager、AlignmentsTab、HealthTab、VersionsTab 等十余个模块。后端则为每个工作区提供对应 REST 路由完整路由清单见 semantica/explorer/routes共 13 个路由模块analytics、annotations、decisions、enrich、export_import、graph、markdown、memories、ontology、provenance、sparql、temporal、vocabulary。关键 REST API 速查所有 API 的交互式文档在启动后位于http://localhost:8000/docsSwagger UI。以下是 docs/reference/explorer.md 中记录的常用端点端点方法用途/api/graph/statsGET节点数、边数、实体类型分布/api/graph/searchPOST索引化搜索{query, limit, filters, anchor_node}/api/graph/pathGET最短路径?sourcetargetalgorithmbfsdirectedtrue/api/graph/node/{id}/neighborsGET邻域展开?depth11–5/api/analyticsGET图指标?metricscentrality,community,connectivity/api/analytics/validationGET图质量校验报告孤儿节点、缺失类型等/api/enrich/dedupPOST重复检测/api/enrich/mergePOST合并重复节点/api/temporal/snapshotGET指定时刻图快照?atISO8601/api/temporal/diffGET两时刻间的图差异?from_timeto_time/api/ontology/registryGET已加载本体列表/api/ontology/shacl/validatePOST用 SHACL 校验 RDF/api/ontology/skos/concept/{uri}GET获取 SKOS 概念/api/sparqlPOST只读 SPARQL 查询SELECT/ASK/CONSTRUCT/DESCRIBE/api/decisions/{id}/chainGET决策因果链/api/provenanceGET实体溯源?node_id/api/exportPOST导出图{format: json\|csv, node_ids}/api/importPOST从.json/.csv导入上限 50 MB/api/healthGET返回{status: ok}/api/infoGET服务器名称、版本、状态、能力六、环境变量变量默认值说明EXPLORER_CORS_ORIGINShttp://localhost:5173,http://127.0.0.1:5173允许的 CORS 来源逗号分隔EXPLORER_CORS_CREDENTIALSfalse设为true允许带凭据的跨域请求仅当位于需要鉴权的反向代理之后时才需要SEMANTICA_API_KEY(未设置)v0.6.5 起受保护路由所需的 API Key通过X-API-Key头发送未设置时受保护路由返回503SEMANTICA_ALLOW_ANONYMOUSfalse设为true显式开启匿名访问仅限本地开发后端源码中的细节值得补充说明app.py 的_read_explorer_settings读取 CORS 来源时会优先使用ALLOWED_ORIGINS其次EXPLORER_CORS_ORIGINS最后才落到默认值——即两者兼容旧变量名仍然生效CORS 中间件显式放行Content-Type、Authorization、X-API-Key三个请求头方法限定为GET/POST/PUT/DELETE/OPTIONSEXPLORER_CORS_CREDENTIALS默认关闭是因为X-API-Key鉴权本身不需要浏览器携带 Cookie开启凭据反而会扩大跨站请求风险面见 app.py 注释后端还会读取FALKORDB_HOST/FALKORDB_PORT/SEMANTICA_PROVENANCE_DB/EXPLORER_PROVENANCE_DB其中 provenance 存储路径会传给GraphSession用于溯源持久化。一个把 CORS 与安全组合起来的完整启动示例EXPLORER_CORS_ORIGINShttp://myapp.example.com \ SEMANTICA_API_KEYsecret \ semantica-explorer --graph my_graph.json --host 0.0.0.0 --port 8080 --no-browser七、可用脚本npm以下命令需在explorer/目录内执行# 启动开发服务器热模块替换 npm run dev # 类型检查并构建生产 bundle 到 ../semantica/static/ npm run build # 本地预览生产构建 npm run preview # 对全部源码运行 ESLint npm run lint # 运行图存储多边单元测试 npm run test:graph-store # 运行图工作区展示测试 npm run test:graph-workspace从 explorer/package.json 可以看到完整的脚本清单build内部先执行tsc -bTypeScript 严格模式类型检查再执行vite buildtest:graph-workspace通过node --import tsx --test运行一组覆盖 markdown 内容渲染、时间线生命周期、确定性渲染、图谱场景状态、图例、小图布局、实时图属性、本体编辑器模型等模块的测试。仓库explorer/tests/下还有graphStore.multi-edge.test.mjs、temporalSnapshotGuards.test.ts、deterministicExplorerRendering.e2e.ts等 19 个测试文件可作为理解各工作区行为的入口。八、开发模式的 API 与 WebSocket 代理开发期间 Vite 自动转发请求无需额外 CORS 配置模式转发目标/api/*http://127.0.0.1:8000/api/*/ws/*ws://127.0.0.1:8000/ws/*代理配置位于 vite.config.ts后端端口不同时修改server.proxy即可。另外代理目标还支持两个环境变量覆盖VITE_EXPLORER_API_TARGET覆盖 API 代理目标默认http://127.0.0.1:8000VITE_EXPLORER_WS_TARGET覆盖 WebSocket 代理目标默认取 API 目标的http→ws替换结果。WebSocket 实时更新协议实时图变更事件通过ws://127.0.0.1:8000/ws/graph-updates推送。Python 客户端示例来自 docs/reference/explorer.mdimport asyncio import json import websockets async def watch_updates(): async with websockets.connect(ws://localhost:8000/ws/graph-updates) as ws: # 服务端连接后先发 ack ack json.loads(await ws.recv()) print(Connected:, ack) # 发送 ping 验证连接存活 await ws.send(ping) async for message in ws: event json.loads(message) print([{}] {}.format(event[event], event.get(data))) asyncio.run(watch_updates())消息结构{ event: graph_mutation, data: { event_type: ADD_NODE, entity_id: node_123, payload: {} }, timestamp: 2024-01-15T10:30:0000:00 }事件类型包括connection_ack、pong与graph_mutation节点/边经导入或富化被增改删时触发发送文本ping会收到pong。WebSocket 的鉴权与关闭码源码见 ws.py浏览器 Origin 不在 CORS 白名单 → 关闭码4403浏览器无法在 WebSocket 握手时设置自定义头因此必须把 Key 作为查询参数传递ws://127.0.0.1:8000/ws/graph-updates?api_keyyour-key非浏览器客户端原生应用、脚本则可以用X-API-Key头发送Key 缺失或错误 → 关闭码4401SEMANTICA_API_KEY未设置且SEMANTICA_ALLOW_ANONYMOUS不为true时同样拒绝连接单条消息超过 64 KB → 关闭码1009。注意URL 中的 API Key 会出现在服务器日志中非浏览器客户端请优先使用 Header 方式传递。九、项目结构前后端对应README 给出的前端结构已按当前仓库实际内容核对workspaces/下比 README 列出的更多explorer/ ├── src/ │ ├── App.tsx # 根布局、标签路由、工作区装配 │ ├── index.css # 全局 reset、字体、关键帧动画 │ ├── store/ │ │ ├── graphStore.ts # 内存图状态 │ │ └── registryStore.ts # Pub/sub 审计注册表 │ └── workspaces/ │ ├── GraphWorkspace/ # Sigma.js 画布 检查器 行为 │ ├── DecisionWorkspace/ # 因果流程图 决策列表 │ ├── DiffMergeWorkspace/ # 图差异与合并视图 │ ├── EnrichWorkspace/ # 实体解析 注册表标签页 │ ├── ImportExportWorkspace/ # 导入 CSV/JSON、导出图 │ ├── LineageWorkspace/ # W3C PROV-O 谱系图 │ ├── ManageWorkspace/ # KG Overview Ontology Summary │ ├── OntologyWorkspace/ # SHACL Studio、可视化编辑器、SKOS 浏览器 │ ├── SparqlWorkspace/ # 浏览器内 SPARQL 查询编辑器 │ ├── VocabularyWorkspace/ # SKOS 词汇表管理器 │ ├── MemoryWorkspace.tsx # Agent 记忆工作区 │ └── ReasoningWorkspace.tsx # 推理工作区 ├── index.html ├── vite.config.ts # 开发代理 → 127.0.0.1:8000构建 → ../semantica/static └── package.json后端结构semantica/explorersemantica/explorer/ ├── __init__.py # CLI 入口参数解析、图加载、uvicorn 启动、自动开浏览器 ├── __main__.py # python -m semantica.explorer 模块入口 ├── app.py # FastAPI 应用工厂CORS、鉴权装配、静态托管、SPA 回退 ├── dependencies.py # require_auth 鉴权依赖、GraphSession 注入 ├── runtime.py # explorer_capabilities 能力探测、mutation bridge 装配 ├── session.py # GraphSession线程安全会话、节点/边规范化、分页、搜索 ├── ws.py # WebSocket 连接管理 图更新广播 ├── search_index.py # 图搜索索引 ├── markdown_resources.py ├── schemas.py └── routes/ # 13 个 REST 路由模块后端运行链从命令行到 WebSocket 广播把整条链路串起来看均可从源码验证CLI 入口 调用GraphSession.from_file(args.graph)加载 ContextGraph打印节点/边统计create_app 创建 FastAPI 应用将所有业务路由挂上require_auth鉴权依赖仅/api/health、/api/info、静态资源与 SPA 回退免鉴权lifespan 阶段调用 install_mutation_bridge把on_mutation回调挂到session.graph.mutation_callback上——任何节点/边的增改删都会① 同步维护搜索索引与图 revision② 通过asyncio.run_coroutine_threadsafe把graph_mutation事件广播给所有已连接 WebSocket 客户端GraphSession 以threading.RLock保护并发访问提供paginate_nodes/paginate_edges含 cursor 分页与搜索/bbox 过滤、get_neighbors、search、get_temporal_bounds、get_cached_embeddings缓存按图 revision 失效等能力并懒加载CentralityCalculator、CommunityDetector、PathFinder等分析组件依赖semantica[kg]extras缺失时优雅降级。十、故障排查仪表盘显示空白白页或 UI not available 提示说明服务器静态目录中缺少前端 bundle。修复方式pip 安装用户pip install --upgrade semantica[explorer]——wheel 包含预构建 bundle源码安装用户在仓库根目录执行cd explorer npm ci npm run build然后重启服务器开发模式改用 Vite 开发服务器地址http://localhost:5173而不是后端地址。浏览器中图空白 / 无数据加载确认 Python 后端正在运行检查终端有无报错打开浏览器 DevTools → Network 面板查找失败的/api/graph请求如果后端在不同端口更新 vite.config.ts 中的server.proxy。npm ci失败或提示缺少 lockfilepackage-lock.json必须存在。先执行一次npm install生成它并提交之后统一使用npm ci。npm run dev报 Node 版本错误Vite 6 要求Node 18 或更高。执行node --version检查如果仍是 Node 16请升级 Node 版本。端口 5173 被占用Vite 会自动尝试下一个可用端口并在终端打印实际 URL使用终端输出的地址即可。WebSocket 连接不上实时变更不出现确认后端暴露了/ws/graph-updatesWebSocket 端点查看 DevTools → Network → WS 标签的连接状态与错误码确保后端版本与前端匹配——大版本混用可能造成协议不匹配鉴权/ws/graph-updates与 REST 路由使用同一 API Key。浏览器无法在 WebSocket 握手时设置自定义头因此需以查询参数传递ws://127.0.0.1:8000/ws/graph-updates?api_keyyour-key非浏览器客户端可用X-API-Key头。Key 缺失或错误会得到关闭码4401若SEMANTICA_API_KEY未设置且SEMANTICA_ALLOW_ANONYMOUS不为true连接同样被拒绝。注意 URL 中的 Key 会出现在服务器日志非浏览器客户端请用 Header。其他常见问题参考 docs/reference/explorer.mdError: graph file not found--graph必须指向真实存在的文件Error: uvicorn is required执行pip install semantica[explorer]安装 extrasAPI 调用Connection refused默认只绑定127.0.0.1跨机器/容器访问需加--host 0.0.0.0导入后图为空/api/import只解析.json与.csv其他格式返回 HTTP 422JSON 需包含顶层entities/nodes数组或relationships/edges数组PathFinder not available路径查找依赖semantica[kg]extras安装pip install semantica[all]语义邻域返回 503需要节点属性中存有 embedding键为embedding、vector或node2vec_embedding无 embedding 的图会返回 503重启后会话状态丢失会话仅存内存无自动保存。关闭前调用POST /api/exportbody{format: json}下载当前状态。另外docs/reference/explorer.md 中的性能参考在其文档所述硬件环境与 118k 节点图上测得可作为容量规划参考索引化节点搜索 0.004ms、depth-2 邻域展开 5ms、BFS 路径 50ms、简单 SPARQL SELECT 20ms节点搜索索引在启动时构建500k 节点的图需预留额外启动时间距离矩阵单请求上限 50 对节点。大图建议先过滤出相关子图再导出 JSONCLI 会把整个 JSON 载入内存。十一、技术栈React 19 TypeScript严格模式Vite 6babel-plugin-react-compilerSigma.js 3Graphology—— 图渲染与内存图模型ForceAtlas2—— 物理布局tanstack/react-query—— 本体与词汇表标签页的异步数据获取vis-timeline—— 时间事件可视化xyflow/react—— Lineage 图渲染Monaco Editor—— 浏览器内 SPARQL / SHACL 编辑器lucide-react—— 图标集explorer/package.json 还揭示了 README 未展开的细节图算法依赖graphology-communities-louvain社区检测、graphology-layout-forceatlas2、graphology-metrics、graphology-shortest-path前端表单/编辑器还有react-arborist树、react-dropzone文件拖放导入、react-markdownremark-gfmMarkdown 节点内容渲染、sigma/edge-curve与sigma/node-borderSigma 边曲线与节点描边并针对dompurify、uuid、esbuild配置了依赖覆盖overrides。十二、贡献与延伸阅读贡献指南见仓库根目录 CONTRIBUTING.md。以下文档可以继续深入docs/reference/explorer.md —— Explorer 完整 REST API 端点表、WebSocket 消息协议与性能参考docs/explorer-setup.md —— Explorer 安装与启动向导docs/reference/context.md —— 构建并保存 Explorer 加载的 ContextGraphdocs/reference/ontology.md —— 编程式本体管理与 SHACL 生成docs/reference/visualization.md —— 不启动 Explorer 服务器的编程式图渲染docs/reference/export.md —— 导出为 RDF、Parquet 等格式。至此你已经掌握 Semantica Knowledge Explorer 从安装、启动、安全配置到工作区使用、实时协议与排障的完整闭环pip install semantica[explorer]一条命令即可把你的知识图谱 JSON 变成可交互、可审计、支持时间回放与本体治理的浏览器工作台。【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考