Files
ssw-ontology/docs/IMPORT.md
T
admin e5fc024217 chore: 删除 importer/import-from-xeo.js(尚数网业务专用)
沙数网 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
(字段映射表 / 抓取器路径 / 重新启用方式)
2026-08-24 14:11:29 +08:00

144 lines
5.2 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.
# 外部数据源导入 · 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`);链接是两端具体对象的关系,任意一端缺失都建不上去。