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