- 将 shangshu-ontology/ 子目录内容移至仓库根一级 - 修复 run.sh 的 REPO_ROOT 计算(扁平化后不再需要 cd ..),ARCHIVE_DIR 正确指向仓库根/archive - 文档(README/PLAN/USAGE/IMPORT/product-intro)移至 docs/,同步更新结构树与导入命令中的旧路径 - 新增根 README.md 索引指向 docs/ - 新增 .gitignore:忽略 bin/、web/node_modules/、web/dist/、server/webroot/、.env、.workbuddy/ 等噪音 - main.go 的 ARCHIVE_DIR fallback 基于可执行文件相邻上级,扁平化后仍正确,无需改动
125 lines
5.9 KiB
Markdown
125 lines
5.9 KiB
Markdown
# 尚数网本体管理平台 · 使用说明
|
||
|
||
本体把尚数网的真实业务(数据资源 / 数据产品 / 可信数据空间 / 会员单位·数据集团 / 数据交易所 / 应用场景 / 分支机构 / 密算一体机 / 五大服务 / 知识产权)沉淀成可查询的「对象类型 + 实例 + 关系」。连接器让 WorkBuddy 等外部应用随时**精准**调取这些信息。
|
||
|
||
---
|
||
|
||
## 1. 启动
|
||
|
||
> 后端以 Go 二进制直接运行(`./run.sh`),数据库复用 workspace 内已部署的 PostgreSQL(`jnpf-postgres`,宿主机映射 `15432`),无需 docker。
|
||
|
||
```bash
|
||
./build.sh # 构建前端 + 编译后端二进制
|
||
./run.sh # 直接运行,连 workspace pg,监听 http://localhost:8080
|
||
# 停止: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:8080/api/v1/connector/facets?type=TrustedDataSpace'
|
||
# 返回 {"facets":{"region":["深圳","北京","江西",...],"industry":["物流","茶业",...],"deploy_mode":[...]}}
|
||
```
|
||
拿到真实取值后,再精确过滤,避免瞎猜字段值。
|
||
|
||
### 3.2 按名称精准查某个实体 → `search_ontology`
|
||
```bash
|
||
# 默认只匹配名称、按相关度排序
|
||
curl 'http://localhost:8080/api/v1/connector/search?q=广州数据集团'
|
||
# 限定类型,更准
|
||
curl 'http://localhost:8080/api/v1/connector/search?q=数据空间&type=TrustedDataSpace'
|
||
# 全字段(名称+属性)模糊(噪杂,慎用)
|
||
curl 'http://localhost:8080/api/v1/connector/search?q=信创&field=all'
|
||
```
|
||
|
||
### 3.3 结构化过滤 → `query_related`
|
||
用 `facets` 拿到的取值做过滤,结果确定、可复现:
|
||
```bash
|
||
curl -X POST 'http://localhost:8080/api/v1/connector/query' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"type":"TrustedDataSpace","filters":{"region":"深圳"}}'
|
||
# → 深圳的所有可信数据空间
|
||
|
||
curl -X POST 'http://localhost:8080/api/v1/connector/query' \
|
||
-d '{"type":"TrustedDataSpace","filters":{"industry":"物流"},"expand":"SpaceUsesAppliance"}'
|
||
# → 物流数据空间 + 其部署的密算一体机
|
||
```
|
||
|
||
### 3.4 查会员单位里的地方数据集团
|
||
```bash
|
||
curl -X POST 'http://localhost:8080/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>:8080/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:8080/api/v1/ai/ingest' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"raw_text":"会员单位「广州数据集团」与「物流行业可信数据空间」达成合作,并推出数据产品「数小美」用于企业估值。","mode":"auto"}'
|
||
```
|
||
返回会列出抽取到的对象(已自动分类、生成稳定主键并写入)。
|
||
|
||
### 5.2 按指令更新(只抽你想要的部分)
|
||
```bash
|
||
curl -X POST 'http://localhost:8080/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:8080` 即前端:概览统计、本体编辑(对象类型/属性/关系/动作)、实例 CRUD、AI 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)。
|