业务故事站
P1 AIP

数据源接入：注册、测试与导入元数据

NLQ 能查什么，取决于先接进什么数据源、导入了什么元数据。从注册 SQLite、测试连接、导入表结构，到失败排查与切换 MySQL，看懂 AIP 取数前"地基"怎么打。看完这 4 个故事，你就能自己接入一个新数据源并让它可被查询。

数据工程师 IT 管理员 数据源 连接测试 元数据 SQLite 共 4 个故事

能 / 不能速览

✅ 这个主题能做
  • 注册数据源：MYSQL / SQLSERVER / POSTGRESQL / SQLITE 等类型，填写连接配置并保存
  • 测试连接：POST /datasources/:id/test，返回 success / message
  • 导入元数据：把外部表结构导入 table_schemas / column_schemas，供 RAG 与 Text2SQL 使用
  • 数据源 CRUD：查询、更新、删除（DELETE 返回 deleted）
  • 用 ai_generate_descriptions=true 让 LLM 生成表 / 列的业务描述
⛔ 这个主题做不了
  • SQLite 需绝对路径且目录必须已存在，否则报 "unable to open database file"
  • 连接器工厂默认只放行 MYSQL / SQLSERVER / POSTGRESQL；ORACLE / CLICKHOUSE 等可创建落库但连接层拒绝，SQLITE 需显式授权
  • 导入元数据默认不调用 LLM（ai_generate_descriptions=false 时仅复制表结构，无描述）；无 regenerate_all 参数，人工维护的描述不会被覆盖
  • 导入即对账清理：import-metadata 默认 prune_stale=true，自动删除实库已不存在的陈旧表 / 列（不再需手工先清；要旧 upsert 行为显式传 prune_stale=false）
  • 多数据源并存时 NLQ 默认取第一个活跃数据源，切换要留意 Active 标记

适用角色

本主题面向两个角色：

  • 数据工程师：核心使用者，负责注册数据源、测试连接、导入元数据、排障——是 NLQ 好用的"地基"。
  • IT 管理员：负责连接器驱动白名单的授权（如 SQLITE 的 AllowAdvancedTypes）与数据源账号权限。

业务分析师不直接操作数据源，但数据源接得好不好，直接决定他们能不能查到数。

能力速览（能做什么）

数据源注册（/datasources）

支持 MYSQL / SQLSERVER / POSTGRESQL / SQLITE 等类型，填 Host / Port / User / Password / Database 后保存，也可设 Active 决定是否参与 NLQ。

连接测试

POST /datasources/:id/test 对配置做真实建连，返回 {"success": true, "message": "Connection successful."}，测试连接器用完即关、不残留。

元数据导入

POST /datasources/:id/import-metadata 读取外部表结构写入 table_schemas / column_schemas，返回 status=success 与建表建列统计。

LLM 描述生成

import-metadata 带 ai_generate_descriptions=true 时调用 LLM 生成表 / 列业务描述与同义词，提升 RAG 中文命中率（需 LLM 返回合法 JSON）。

数据源 CRUD

GET 列表 / GET 单个 / PUT 更新 / DELETE 删除（返回 {"deleted": true}），删除前可先停用 Active。

驱动白名单

连接器工厂按 allow-list 放行驱动：默认仅 MYSQL / SQLSERVER / POSTGRESQL；SQLITE 等需 AllowAdvancedTypes("SQLITE") 显式授权（AIP 启动引导已授权）。

调整指南（怎么调整）

  • 改连接配置：保存后仍可 PUT 更新；改完务必重新测试连接，再决定是否重新导入元数据。
  • 改元数据新鲜度：源表结构变了就重新 import-metadata；导入默认对账清理（prune_stale=true）自动删除实库已不存在的陈旧表 / 列，无需手工先清（需要旧 upsert 行为可显式传 prune_stale=false）。
  • 改描述质量：想让中文问法命中率更高，用 ai_generate_descriptions=true 重新导入，让 LLM 补 description 与 synonyms。
  • 改活跃源：多个数据源时，NLQ 默认取第一个 Active 数据源；把目标数据源置 Active 且排到最前，或停用不需要的源。
  • 改 SQLite 路径：必须用绝对路径，且文件所在目录要先创建，否则测试连接报 "unable to open database file"。

做得好的场景

数据源接入在"配置正确 + 驱动已授权 + 元数据已导入"时非常顺：
  • 几分钟接入一个源：注册 → 测试 → 导入元数据三步走完，业务马上能用 NLQ 查它。
  • 测试即时报错：连接失败会直接返回原因（路径、权限、驱动），不用猜。
  • 元数据可再加工：导入后还能用 LLM 补业务描述，让中文 RAG 从"碰运气"变成"可调优"。

限制与不足

以下是明确的边界，使用前先知道：
  • SQLite 文件路径陷阱：目录不存在即报错，必须 ensureDir 先建目录；相对路径也不可靠，用绝对路径。
  • 驱动白名单（创建≠连接）：ORACLE / CLICKHOUSE 等类型创建侧枚举放行（可成功落库），但连接器工厂默认仅放行 MYSQL / SQLSERVER / POSTGRESQL——建连 / 测试 / 导入会被拒（"access to database type 'ORACLE' is not authorized"），SQLITE 需 AllowAdvancedTypes 授权。
  • 无描述元数据：默认导入只复制表结构，description / synonyms 为空，中文 RAG 命中率低。
  • 残留元数据已有内建对账清理：导入默认 prune_stale=true，会把实库已不存在的陈旧表 / 列删掉，不会残留旧表名误导 RAG 与 Text2SQL（显式传 false 才保留旧 upsert 行为）。
  • 单源执行：NLQ 一次只查一个数据源（默认第一个活跃源），跨源 JOIN 不支持。

场景故事

故事 1 数据工程师注册本地 SQLite 数据源并测试连接成功
场景：数据源注册 角色：数据工程师 耗时：约 5 分钟
背景
张工手头有一个本地销售数据文件 D:\sourcedata\sales.db（SQLite，含 orders / customers 两张表）。他想把它接进 AIP，让业务同事能用 NLQ 直接查。他登录 http://127.0.0.1:18080，进入"数据源管理"页（/datasources）。
传统做法对比
以前要写数据同步脚本、建接口、配 BI 连接，至少半天；现在在页面填一张连接表单，几分钟注册完成，马上可测试。
角色
数据工程师（数据源管理权限；驱动白名单由启动引导授权 SQLITE）。
操作步骤
  1. 进入"数据源管理"页，点击"新建数据源"
  2. 填写名称 sales_analysis、类型 SQLITE、Database 填绝对路径 D:\sourcedata\sales.db
  3. 保存（POST /api/v1/datasources，返回 201 与数据源对象）
  4. 点击"测试连接"
系统响应
测试连接返回：
{
  "success": true,
  "message": "Connection successful."
}
数据源列表出现 sales_analysis，类型 SQLITE，Active 为开启状态。
结果洞察
张工确认 SQLite 驱动已被允许（AIP 启动引导里执行了 AllowAdvancedTypes("SQLITE")），绝对路径也写对了，所以建连一次通过。连接测试用的是临时连接器，测试完自动释放，不会锁住数据库文件。
调整建议
多环境部署时把 SQLite 路径写成配置项管理；若不想让该数据源参与 NLQ 默认查询，可把 Active 关掉，需要时再开。
动手试一试
登录：admin / admin1。页面路径：/datasources → 新建数据源。输入内容：name=sales_analysis、type=SQLITE、database=D:\sourcedata\sales.db（目录须已存在）。预期结果：创建返回 201，测试连接返回 {"success": true, "message": "Connection successful."}。
限制提示
SQLite 类型默认不在连接器白名单，需服务端 AllowAdvancedTypes("SQLITE") 授权（AIP 启动引导已做）；数据库文件所在目录必须已存在，否则报 "unable to open database file"。
故事 2 导入元数据：把 sales.db 的表结构灌进 table_schemas / column_schemas
场景：元数据导入 角色：数据工程师 耗时：约 3 分钟
背景
sales_analysis 数据源能连上了，但张工知道光能连没用——NLQ 的 RAG 和 Text2SQL 依赖 table_schemas / column_schemas 里的表结构。他点击数据源行里的"导入元数据"。
传统做法对比
以前要把表结构整理成文档给模型或写进配置，一次表变更要同步一轮；现在平台连接数据源后直接读取外部表结构导入，一条命令搞定。
角色
数据工程师（导入元数据只需登录与数据源存在，默认不调 LLM）。
操作步骤
  1. 在 /datasources 找到 sales_analysis
  2. 点击"导入元数据"（POST /api/v1/datasources/:id/import-metadata）
  3. 等待返回导入结果
  4. 到 /chat 输入"查询所有订单"验证可查
系统响应
导入返回：
{
  "status": "success",
  "message": "Metadata import complete. Created 2 tables and 8 columns. Updated 0 tables and 0 columns."
}
table_schemas 里多了 orders / customers，column_schemas 里对应列出每张表的列（order_id、sales_amount、customer_name、city 等）。
结果洞察
张工去 /chat 输入"查询所有订单"，NLQ 的 RAG 命中 orders 表、Text2SQL 生成 SELECT 并成功执行——"能连"升级成了"能查"。他注意到默认导入不带业务描述，字段名是英文原样，后续可用 ai_generate_descriptions=true 补中文描述。
调整建议
中文问法命中率不高时，用 ai_generate_descriptions=true 重新导入，让 LLM 生成表 / 列描述与同义词；源表结构变更后记得重新导入，保持元数据新鲜。
动手试一试
登录：admin / admin1。页面路径：/datasources → 导入元数据。输入内容：对 sales_analysis 点"导入元数据"。预期结果：返回 status=success 与表 / 列统计；随后在 /chat 输入"查询所有订单"能查到该库数据。
限制提示
导入默认对账清理（prune_stale=true）自动删除实库已不存在的陈旧表 / 列，无需手工先清；默认导入不生成中文描述，描述列与同义词为空。
故事 3 连接失败排查：路径、目录权限与驱动白名单
场景：失败排查 角色：数据工程师 + IT 管理员 耗时：约 10 分钟
背景
张工给同事小陈建的 SQLite 数据源一直测试失败。他点了"测试连接"，页面直接返回报错。他叫上 IT 管理员赵工一起排查：这类问题十有八九出在路径、目录权限或驱动白名单上。
传统做法对比
以前连接报错要去翻后端日志、猜原因，来回 1 天；现在测试连接直接返回失败原因，按三类常见问题逐项核对即可。
角色
数据工程师（改配置、核对路径）+ IT 管理员（驱动授权、目录权限）。
操作步骤
  1. 看测试连接的返回 message，判断失败类型
  2. 若报 "unable to open database file"：检查 Database 是否绝对路径、所在目录是否存在
  3. 若报连接器创建失败 / 驱动不支持：检查类型是否在连接器白名单（默认仅 MYSQL / SQLSERVER / POSTGRESQL）
  4. 修正后重新测试连接
系统响应
小陈最初填的是相对路径 temp/sales.db，返回：
{
  "success": false,
  "message": "Connection failed: unable to open database file"
}
改成绝对路径 D:\sourcedata\sales.db 且确认目录存在后，重新测试返回 {"success": true, "message": "Connection successful."}。
结果洞察
根因是 SQLite 特性：文件所在目录不存在时无法自动创建（需先 ensureDir），相对路径在不同工作目录下还会飘。赵工补充说明驱动侧：SQLITE 默认不在连接器工厂白名单，AIP 启动引导执行了 AllowAdvancedTypes("SQLITE") 才放行，否则会报 "Failed to create connector" 一类错误。
调整建议
SQLite 一律用绝对路径并先创建目录；新环境接入非 MYSQL / SQLSERVER / POSTGRESQL 类型前，先确认服务端驱动授权；把数据库文件放在统一目录（如 data/），便于权限管理。
动手试一试
登录：admin / admin1。页面路径：/datasources → 新建 → 测试连接。输入内容：先填相对路径 temp/sales.db 测试（预期失败），再改绝对路径 D:\sourcedata\sales.db（预期成功）。预期结果：第一次报 "unable to open database file"，第二次返回 Connection successful.
限制提示
连接测试对 SQLite 会锁文件，测试完平台自动关闭临时连接器释放句柄；若手工建连不释放，Windows 上可能一直占用 .db 文件导致后续操作失败。
故事 4 切换到 MySQL 数据源并重新导入元数据
场景：数据源切换 角色：数据工程师 耗时：约 8 分钟
背景
演示数据源跑通后，张工想把生产库（MySQL，sales_data_warehouse，库名 chatbi_forge_dev）接进来，让业务查真数。MySQL 在连接器默认白名单内，他按表单填 Host / Port / User / Password / Database。
传统做法对比
以前新库接入要走审批、建账号、改配置、重新验证，层层流转一周；现在填写连接参数、测试、导入元数据三步，个把小时就能让 NLQ 指向新库。
角色
数据工程师（拥有数据库账号与平台数据源管理权限）。
操作步骤
  1. 在 /datasources 新建数据源，类型选 MYSQL
  2. 填写 Host / Port(3306) / User / Password / Database=chatbi_forge_dev
  3. 测试连接，确认 {"success": true}
  4. 导入元数据，确认新表进入 table_schemas
  5. 把该数据源置 Active（并调整顺序或停用演示源），到 /chat 验证查询
系统响应
测试连接返回成功；导入元数据返回：
{
  "status": "success",
  "message": "Metadata import complete. Created 4 tables and 22 columns. Updated 0 tables and 0 columns."
}
table_schemas 里出现该库的业务表（如 sales_orders、sales_customers 等）。
结果洞察
张工在 /chat 查询，NLQ 默认取第一个活跃数据源——他把 sales_data_warehouse 置 Active 并停用演示源后，查询结果来自 MySQL 真数。他确认换源后不会有旧表名残留带偏 RAG：导入新源时默认 prune_stale=true 会对账清理实库已不存在的陈旧表 / 列，无需手工先清旧源元数据。
调整建议
多个数据源并存时，用 Active 标记与列表顺序控制 NLQ 默认取数对象；给生产库的只读账号配置最小权限，避免 NLQ 生成的 SQL 触碰写操作；上线前在测试库先跑一遍示例问题。
动手试一试
登录：admin / admin1。页面路径：/datasources → 新建（MYSQL）。输入内容：连接 sales_data_warehouse（chatbi_forge_dev 库）→ 测试 → 导入元数据 → 置 Active。预期结果：测试返回 success；导入返回表 / 列统计；/chat 查询结果来自 MySQL 库。
限制提示
NLQ 一次只查一个数据源（默认第一个活跃源），跨源 JOIN 不支持；MySQL 方言由连接器 TransformSQL 处理（CURRENT_DATE→CURDATE()，PG / SQLite 为 no-op），复杂语法仍可能执行失败。

常见问题

哪些数据源类型可以直接接？

创建侧枚举支持 POSTGRESQL / MYSQL / SQLSERVER / SQLITE / ORACLE / CLICKHOUSE / SNOWFLAKE 等 14 类；但连接器工厂的驱动 allow-list 默认只放行 MYSQL / SQLSERVER / POSTGRESQL，SQLITE 等其余类型需服务端显式授权（AIP 启动引导已为演示 SQLite 授权）。注意 ORACLE 这类"能创建不等于能连"：创建可成功落库，测试连接 / 导入元数据时被连接器层拒绝。

import-metadata 有哪些参数？

URL query 参数有两个：ai_generate_descriptions（true / false，默认 false）与 prune_stale（true / false，默认 true，导入即对账清理实库已不存在的陈旧表 / 列）。没有请求体；也没有 regenerate_all 参数——传了也会被忽略，导入始终保留人工维护的描述与同义词（regenerateAll 在服务端硬编码为 false）。

"测试连接成功"和"能查数"是一回事吗？

不是。测试连接只验证建连；要能被 NLQ 查询，还必须导入元数据（写入 table_schemas / column_schemas）。不导入元数据，RAG 无表可用，Text2SQL 也就无从生成。

导入元数据会调用 LLM 吗？

默认不会（ai_generate_descriptions=false 时仅复制表结构，无业务描述）。想生成中文描述与同义词，用 ai_generate_descriptions=true，此时会调用 LLM 并要求返回合法 JSON，失败会返回 400。

为什么测试 SQLite 老报 "unable to open database file"？

SQLite 文件所在目录必须先存在（平台用 ensureDir 建目录），且建议用绝对路径。相对路径会随进程工作目录漂移，容易找不到文件。

接了多个数据源，NLQ 查哪个？

默认取第一个活跃（Active）数据源。多源并存时，把目标数据源置 Active 并调到列表前面，或停用其他源；跨数据源 JOIN 当前不支持。

主题小结

一句话：数据源接入 = 注册 + 测试 + 导入元数据三步，是 NLQ 好用的前提。记住五个坑：SQLite 用绝对路径并先建目录、驱动白名单要授权、默认导入无中文描述、导入即对账清理（prune_stale 默认 true，无需手工先清陈旧元数据）、多源并存时 NLQ 只取第一个活跃源。