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

5.2 KiB
Raw Blame History

外部数据源导入 · Ontology Platform

把外部数据源(API、文件、数据库、其他平台)导入到平台,让本体从"人工编辑"变成"实时镜像"。

平台提供两条导入路径,各有所长:

路径 适用 入口
平台内 AI 摄取 文本/少量文件/外部资源定义 POST /api/v1/ai/ingest / POST /api/v1/km/extract
外部脚本(自定义 importer) 大批量、异构、定时同步 自己写 Node/Python 脚本,upsert 到 /api/v1/objects

下面重点说第二种:平台本身只提供管理 API,导入逻辑由采用方按需编写。


通用模式(三步)

任何外部数据源都可以按下面三步走:

外部 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 示例)

#!/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)。

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 第 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);链接是两端具体对象的关系,任意一端缺失都建不上去。