沙数网 shangshuwang.cn mobileApi 专用 importer 不属于通用本体平台的一部分, 按业务专用代码剥离。 - 删除 importer/import-from-xeo.js(200 行, Node 脚本) - 删除空目录 importer/ 文档同步: - docs/README.md 项目结构去掉 importer/ 行 - docs/IMPORT.md 删除"尚数网示例"整节,改为通用 Node 骨架 历史信息归档在 .workbuddy/memory/2026-08-24.md (字段映射表 / 抓取器路径 / 重新启用方式)
144 lines
5.2 KiB
Markdown
144 lines
5.2 KiB
Markdown
# 外部数据源导入 · Ontology Platform
|
||
|
||
把外部数据源(API、文件、数据库、其他平台)导入到平台,让本体从"人工编辑"变成"实时镜像"。
|
||
|
||
平台提供两条导入路径,各有所长:
|
||
|
||
| 路径 | 适用 | 入口 |
|
||
|---|---|---|
|
||
| **平台内 AI 摄取** | 文本/少量文件/外部资源定义 | `POST /api/v1/ai/ingest` / `POST /api/v1/km/extract` |
|
||
| **外部脚本(自定义 importer)** | 大批量、异构、定时同步 | 自己写 Node/Python 脚本,upsert 到 `/api/v1/objects` |
|
||
|
||
下面重点说第二种:平台本身只提供管理 API,**导入逻辑由采用方按需编写**。
|
||
|
||
---
|
||
|
||
## 通用模式(三步)
|
||
|
||
任何外部数据源都可以按下面三步走:
|
||
|
||
```text
|
||
外部 API/数据库/文件
|
||
↓ ① 抓取 + normalize(字段映射 + 中文翻译 + 字段类型归一)
|
||
↓ ② 映射为本体对象(加前缀避免 pk 与种子冲突 + 决定 object_type)
|
||
POST /api/v1/objects (upsert by (object_type, pk))
|
||
↓ ③ 尽力匹配 → POST /api/v1/links (建关系)
|
||
```
|
||
|
||
要点:
|
||
- **抓取与翻译**用采用方已有的代码(没有就 `fetch` + JSON.parse),平台不强制抓取实现
|
||
- **upsert** 靠平台主键策略 + `source` 字段做溯源,撞 pk 时是覆盖
|
||
- **链接**按采用方业务规则建,匹配不上保留原始字段
|
||
|
||
---
|
||
|
||
## 通用模式:你自己接入任意数据源
|
||
|
||
> 平台不绑定任何特定数据源。**采用方按需编写自己的 importer**,三步不变:
|
||
|
||
1. **抓取 + normalize**:用你最熟悉的方式(fetcher / ORM / parser)
|
||
2. **字段映射**:在脚本里维护一个 `externalType → ontologyType + props` 的转换表
|
||
3. **upsert + 链接**:调 `POST /api/v1/objects`(撞 pk 自动更新)+ `POST /api/v1/links`
|
||
|
||
建议放在 `scripts/` 目录下(平台本身不提供 importer,只提供管理 API)。
|
||
|
||
### 最小骨架(Node.js 示例)
|
||
|
||
```javascript
|
||
#!/usr/bin/env node
|
||
/**
|
||
* 通用 importer 骨架:抓取 → normalize → upsert
|
||
* 替换 fetch 逻辑与映射表即可适配任意数据源
|
||
*/
|
||
const BASE = process.env.ONTO_API_BASE || 'http://localhost:8081';
|
||
const KEY = process.env.MANAGER_API_KEY || '';
|
||
|
||
async function req(method, p, body) {
|
||
const r = await fetch(BASE + p, {
|
||
method,
|
||
headers: { 'Content-Type': 'application/json', ...(KEY ? { 'X-API-Key': KEY } : {}) },
|
||
body: body ? JSON.stringify(body) : undefined,
|
||
});
|
||
if (!r.ok) throw new Error(`${method} ${p} failed: ${r.status} ${await r.text()}`);
|
||
return r.json();
|
||
}
|
||
|
||
// 1. 抓取
|
||
async function fetchAll() {
|
||
// 这里换成你的数据源:DB query / REST API / file parser / ...
|
||
return [];
|
||
}
|
||
|
||
// 2. 字段映射:externalItem → { type, pk, properties, link? }
|
||
function map(externalItem) {
|
||
return {
|
||
type: 'YourObjectType',
|
||
pk: 'ext_' + externalItem.id, // pk 加前缀避免冲突
|
||
properties: { name: externalItem.name }, // 按需映射字段
|
||
source: 'my-importer-2026-08', // 删除时按 source 级联
|
||
};
|
||
}
|
||
|
||
async function run() {
|
||
const items = await fetchAll();
|
||
for (const it of items) {
|
||
const o = map(it);
|
||
await req('POST', '/api/v1/objects', o);
|
||
}
|
||
console.log(`Imported ${items.length} items.`);
|
||
}
|
||
|
||
run().catch(e => { console.error(e); process.exit(1); });
|
||
```
|
||
|
||
### 关键约定
|
||
|
||
- **`pk` 加前缀**避免冲突(如 `crm_` / `wiki_` / `mkt_`)
|
||
- **`source` 字段**填本次导入的标识(如 `crm-monday-sync` / `wiki-export-2026-08`),删除时按 source 级联
|
||
- **稳定映射**:每次重跑都生成**相同 pk**,这样 upsert 是覆盖而非重复写入
|
||
- **链接建不上不硬连**:匹配不上保留原始字段作属性,后续手工补
|
||
|
||
---
|
||
|
||
## 平台内导入(更简单,无脚本)
|
||
|
||
### `POST /api/v1/ai/ingest`
|
||
|
||
粘一段文本 → AI 抽取 → 自动落库(`mode=auto`)或仅生成建议(`mode=review`)。
|
||
|
||
```bash
|
||
curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"raw_text":"合作伙伴「XX」与「XX 行业空间」达成合作,推出数据产品「X」...","mode":"auto"}'
|
||
```
|
||
|
||
### `POST /api/v1/km/extract`
|
||
|
||
知识管理 Tab 上传文件后,批量调 AI 抽取。
|
||
|
||
详见 [docs/USAGE.md](USAGE.md) 第 5 节。
|
||
|
||
### `POST /api/v1/km/connections/:id/import`
|
||
|
||
数据连接资源:定义外部数据库/API/文件 → 一键导入本体,source=`conn:<id>`。
|
||
|
||
---
|
||
|
||
## 增量与定时同步
|
||
|
||
- 每类按外部 id 生成稳定 pk(如 `mkt_{id}`),`POST /objects` 是 upsert(按 `(object_type, pk)` 冲突更新),重跑覆盖、不重复
|
||
- 可做成定时任务(如每日一次)调用本脚本,外部新增的数据自动同步进本体,连接器与 MCP 实时可读
|
||
- **删除时按 source 级联**:`DELETE /api/v1/km/files?source=mkt_*` 会一并清掉 objects + links + 关联记录
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
**Q:导入撞 pk 时 source 字段不更新?**
|
||
A:升级到 2026-08-24 后已修复。`ON CONFLICT ... DO UPDATE SET source=COALESCE(NULLIF(EXCLUDED.source,''), objects.source)` 是统一语义(必须加表名限定 `objects.source`)。
|
||
|
||
**Q:导入后 AI 摄取为啥查不到?**
|
||
A:检查 `source` 字段是否正确写入,管理接口 `/api/v1/objects?type=xxx&source=xxx` 可按 source 过滤。
|
||
|
||
**Q:链接建不上?**
|
||
A:先确认目标对象存在(`get_objects_by_type` 或 `search_ontology`);链接是两端具体对象的关系,任意一端缺失都建不上去。 |