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

125 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 尚数网本体管理平台 · 使用说明
本体把尚数网的真实业务(数据资源 / 数据产品 / 可信数据空间 / 会员单位·数据集团 / 数据交易所 / 应用场景 / 分支机构 / 密算一体机 / 五大服务 / 知识产权)沉淀成可查询的「对象类型 + 实例 + 关系」。连接器让 WorkBuddy 等外部应用随时**精准**调取这些信息。
---
## 1. 启动
> 后端以 Go 二进制直接运行(`./run.sh`),数据库复用 workspace 内已部署的 PostgreSQL(`jnpf-postgres`,宿主机映射 `15432`),无需 docker。
```bash
./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`
```bash
curl 'http://localhost:8081/api/v1/connector/facets?type=TrustedDataSpace'
# 返回 {"facets":{"region":["深圳","北京","江西",...],"industry":["物流","茶业",...],"deploy_mode":[...]}}
```
拿到真实取值后,再精确过滤,避免瞎猜字段值。
### 3.2 按名称精准查某个实体 → `search_ontology`
```bash
# 默认只匹配名称、按相关度排序
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'
```
### 3.3 结构化过滤 → `query_related`
用 `facets` 拿到的取值做过滤,结果确定、可复现:
```bash
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 查会员单位里的地方数据集团
```bash
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 直接入库)
```bash
curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
-H 'Content-Type: application/json' \
-d '{"raw_text":"会员单位「广州数据集团」与「物流行业可信数据空间」达成合作,并推出数据产品「数小美」用于企业估值。","mode":"auto"}'
```
返回会列出抽取到的对象(已自动分类、生成稳定主键并写入)。
### 5.2 按指令更新(只抽你想要的部分)
```bash
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 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)。