Files
ssw-ontology/docs/USAGE.md
T
admin 993f74c2b2 feat: Docker 单镜像分发 + 默认端口统一 8081 + seed 极简化
新增 Dockerfile + docker/entrypoint.sh:
- 基础 crpi-.../ssw188/postgres:16-alpine + ontology 二进制,单镜像
- 默认端口 8081 / 库 ssw-ontology / 用户 ssw / 密码 ssw
- /data/pg 自动挂 PG 数据,/data/archive 挂文档根目录
- trap 收尸保证 PG + ontology 同生命周期

seed 极简化为 1 个对象类型「合作企业」+ 3 条示例
(尚数网/腾讯/阿里巴巴),便于演示也便于清理。

默认 HTTP_PORT 统一为 8081(覆盖 server/config.go、run.sh、
vite.config.js、importer/import-from-xeo.js、docs/README.md、
docs/USAGE.md、docs/IMPORT.md、.env.example 等所有文档/代码)。

docs/README.md / .env.example 默认 DATABASE_URL 改为
ssw/[email protected]:5432/ssw-ontology(与 Docker 镜像自带 PG 一致);
run.sh 删 dacli 硬编码 fallback,改从 .env 读(不存在则报错退出)。

README 重整:分「方式 A Docker 镜像 / 方式 B 本机 ./run.sh」,
新增 AI 智能导入(-e AI_*)与管理接口鉴权(-e MANAGER_API_KEY)说明。
2026-08-13 15:59:27 +08:00

5.9 KiB
Raw Blame History

尚数网本体管理平台 · 使用说明

本体把尚数网的真实业务(数据资源 / 数据产品 / 可信数据空间 / 会员单位·数据集团 / 数据交易所 / 应用场景 / 分支机构 / 密算一体机 / 五大服务 / 知识产权)沉淀成可查询的「对象类型 + 实例 + 关系」。连接器让 WorkBuddy 等外部应用随时精准调取这些信息。


1. 启动

后端以 Go 二进制直接运行(./run.sh),数据库复用 workspace 内已部署的 PostgreSQL(jnpf-postgres,宿主机映射 15432),无需 docker。

./build.sh   # 构建前端 + 编译后端二进制
./run.sh     # 直接运行,连 workspace pg,监听 http://localhost:8081
# 停止:Ctrl+C 结束进程即可(无后台容器需清理)

首次启动(SEED_ON_START=true)会自动灌入尚数网种子本体(见 server/db.go 的 seedIfEmpty)。


2. 连接器 API(只读,供外部消费)

所有连接器接口前缀 /api/v1/connector,默认无需鉴权;可在 .env 设置 CONNECTOR_API_KEY 开启(X-API-Key 头)。

方法 路径 作用
GET /connector/object-types 列出全部对象类型及属性定义(先了解有哪些实体类别)
GET /connector/objects/:type 列出某类型的全部实例(?limit=)
GET /connector/object/:type/:pk 取单个实例详情
GET /connector/search?q= 精准检索:按名称优先排序,支持 type/field/limit
GET /connector/facets 发现维度:返回各类型可过滤的取值(region/industry/type…)
POST /connector/query 图式查询:按类型+属性过滤,可 expand 展开关系
GET /connector/graph 全量图谱(节点+边),用于可视化
GET /api/v1/mcp/manifest MCP 工具清单(WorkBuddy 据此注册工具)

3. 精准查询配方(不要再「莫名其妙」地全模糊搜)

3.1 先发现有哪些可过滤值 → get_facets

curl 'http://localhost:8081/api/v1/connector/facets?type=TrustedDataSpace'
# 返回 {"facets":{"region":["深圳","北京","江西",...],"industry":["物流","茶业",...],"deploy_mode":[...]}}

拿到真实取值后,再精确过滤,避免瞎猜字段值。

3.2 按名称精准查某个实体 → search_ontology

# 默认只匹配名称、按相关度排序
curl 'http://localhost:8081/api/v1/connector/search?q=广州数据集团'
# 限定类型,更准
curl 'http://localhost:8081/api/v1/connector/search?q=数据空间&type=TrustedDataSpace'
# 全字段(名称+属性)模糊(噪杂,慎用)
curl 'http://localhost:8081/api/v1/connector/search?q=信创&field=all'

用 facets 拿到的取值做过滤,结果确定、可复现:

curl -X POST 'http://localhost:8081/api/v1/connector/query' \
  -H 'Content-Type: application/json' \
  -d '{"type":"TrustedDataSpace","filters":{"region":"深圳"}}'
# → 深圳的所有可信数据空间

curl -X POST 'http://localhost:8081/api/v1/connector/query' \
  -d '{"type":"TrustedDataSpace","filters":{"industry":"物流"},"expand":"SpaceUsesAppliance"}'
# → 物流数据空间 + 其部署的密算一体机

3.4 查会员单位里的地方数据集团

curl -X POST 'http://localhost:8081/api/v1/connector/query' \
  -d '{"type":"MemberOrg","filters":{"type":"数据集团"}}'

4. 接入 WorkBuddy / 其他应用(MCP)

连接器同时暴露一份 MCP 工具清单(GET /api/v1/mcp/manifest),WorkBuddy 可据此把本体注册成可调用的工具:

  • get_object_types — 有哪些实体类别
  • get_objects_by_type — 某类别全部实例
  • get_object — 单个实例详情
  • search_ontology — 精准检索(支持 type / field / limit)
  • get_facets — 发现可过滤维度
  • query_related — 类型+属性精确过滤,并可展开关系

接入方式:在 WorkBuddy 的 MCP 配置里指向 http://<host>:8081/api/v1/mcp/manifest(或将其包成 MCP server)。之后即可用自然语言问,例如:

“尚数网在深圳部署了哪些可信数据空间?分别用了哪款密算一体机?”

WorkBuddy 会先用 get_facets 拿到 region=深圳,再 query_related 过滤并 expand 关系,返回确定答案。


5. 用 AI 动态维护本体(提交资料自动更新 / 按指令更新)

管理接口前缀 /api/v1(可设 MANAGER_API_KEY 鉴权)。AI 摄取把一段资料自动抽取成本体增量并入库。

5.1 提交资料,自动更新(mode=auto 直接入库)

curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
  -H 'Content-Type: application/json' \
  -d '{"raw_text":"会员单位「广州数据集团」与「物流行业可信数据空间」达成合作,并推出数据产品「数小美」用于企业估值。","mode":"auto"}'

返回会列出抽取到的对象(已自动分类、生成稳定主键并写入)。

5.2 按指令更新(只抽你想要的部分)

curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
  -d '{"raw_text":"...同上资料...","directive":"只提取其中的数据产品","mode":"auto"}'

directive 会约束抽取范围(如「只提取数据产品」「提取所有数据集团并标注区域」)。

5.3 先审后入(mode=review)

把 mode 设为 review,接口只返回 suggestion 不写库,由人工确认后再调用管理接口写入。

若配置了 AI_BASE_URL + AI_KEY + AI_MODEL(OpenAI 兼容),则走真实大模型抽取;否则用内置启发式兜底(识别「」""()包裹的实体 + 就近关键词分类)。


6. 管理平台界面

浏览器打开 http://localhost:8081 即前端:概览统计、本体编辑(对象类型/属性/关系/动作)、实例 CRUD、AI 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)。