Sira AI

主题

2.7 GenAI Toolbox(数据库工具集) ​

GenAI Toolbox 让管理员可以只写一段 SQL/Cypher就把数据库查询能力暴露给 AI,无需手写 MCP Server。

ℹ️ 架构说明(2026-05 起):早期版本依赖一个独立的 mcp-toolbox Go 容器(生成 tools.yaml 推送过去运行)。该容器已下线,工具现在在 Sira 进程内执行(Python 执行器 + 连接池管理器),并通过 Sira 自带的 MCP 端点对外暴露。因此没有"部署"这一步,工具保存即生效。

进入路径:左侧主导航 → 数据集成(/genai-toolbox)。 权限:登录用户均可访问;实际配置建议管理员操作。

ℹ️ Sira 集成 4 个子模块:数据源、工具、工具集、运行状态。

2.7.1 GenAI Toolbox 主页 ​

路径:/genai-toolbox

截图:GenAI Toolbox 主页

4 个功能卡片 ​

卡片颜色路径用途
数据源管理蓝/genai-toolbox/sources注册数据库连接
工具管理绿/genai-toolbox/tools写 SQL/Cypher 创建工具
工具集管理紫/genai-toolbox/toolsets把工具打包成集合
运行状态橙/genai-toolbox/deployment查看连接池、健康检查与配置变更审计

快速开始 5 步 ​

  1. 创建数据源(数据库连接)
  2. 创建工具(参数化的 SQL/Cypher 查询) 3.(可选)把工具组成工具集
  3. 在智能体里勾选工具集(或单个工具),工具即刻可用,无需部署
  4. 在「运行状态」里查看连接池实时状态并触发健康检查

2.7.2 数据源管理 ​

路径:/genai-toolbox/sources

截图:数据源列表

列表页 ​

布局:卡片网格(每页 20),空状态显示创建引导。

每张卡片显示:

  • 数据源显示名称
  • 内部名称(等宽字体)
  • 类型标签(mysql / postgresql / sqlite / bigquery / spanner / ...)
  • 描述
  • 操作菜单(编辑 / 删除 / 验证)

新建/编辑数据源对话框 SourceDialog ​

字段说明
name内部标识
display_nameUI 名称
description描述
kind数据库类型,决定后续字段:mysql / postgresql / sqlite / bigquery / spanner / cloud_sql_postgres / cloud_sql_mysql / ...
连接参数随 kind 变化:host / port / database / user / password / project_id / instance / ...

MySQL/PostgreSQL 示例字段:host、port、database、user、password、ssl_mode

BigQuery 示例字段:project_id、credentials_json(密文)

Cloud SQL 示例字段:project_id、region、instance、database、user、password

验证连接 ​

每个数据源卡片有「验证」按钮,异步发起健康检查:

  • ✅ 通过:绿色 toast,显示数据库版本号
  • ❌ 失败:红色 toast,显示具体错误(网络不通 / 凭证错误 / SSL 失败)

删除数据源 ​

⚠️ 级联影响:删除数据源会让所有引用它的「工具」失效(智能体下次调用时报错)。删除对话框会列出依赖工具数。

2.7.3 工具管理 ​

路径:/genai-toolbox/tools

截图:工具列表

列表页 ​

每个工具卡片显示:

  • 显示名称 + 内部名称(等宽)
  • 类型标签(kind,如 postgres-sql、mysql-sql、bigquery-sql)
  • 数据源标签(关联的 source 名)
  • 激活状态(🟢 / 🔘)
  • 执行次数统计
  • 描述(截断 2 行)
  • Tags
  • 操作菜单(编辑 / 删除)

新建/编辑工具对话框 ToolDialog ​

字段必填说明
name(工具标识)✓内部标识,创建后不可改
display_name(显示名称)✓UI 名称
description(描述)✓重要 — 给 AI 看,决定何时调用此工具
source_id(数据源)✓下拉选数据源
kind(工具类型)✓先选数据源,再从该数据源支持的类型里选:sql / cypher / json / 等
动态字段—随所选 kind 变化:对话框按工具类型 schema 动态渲染字段(SQL 类显示 statement SQL 编辑框,Cypher 类显示 Cypher 编辑框,等等),并自动填入该类型的默认值
parameters(参数)—列表式编辑,每条含 参数名 / 类型(string/int/float) / 必填 开关 / 描述
超时时间(秒)—默认 30
最大行数—默认 1000
分类 / 标签—
需要身份验证—开关

💡 schema 驱动:工具字段不是固定的,而是由所选「工具类型(kind)」的 schema 决定;选定后系统自动填入该类型的默认值。data_query 节点的「🪄 自动生成: 仅必填」按钮依赖参数的必填开关 —— 没勾必填的参数不会被自动生成,所以请准确设置每个参数的必填状态。

SQL 写法示例 ​

简单查询:

yaml
description: 查询客户基本信息
statement: SELECT id, name, email, created_at FROM customers WHERE id = $1
parameters:
  - name: customer_id
    type: integer
    description: 客户 ID

条件聚合:

yaml
description: 统计某个时段的订单总额
statement: |
  SELECT SUM(amount) AS total
  FROM orders
  WHERE created_at BETWEEN $1 AND $2
parameters:
  - name: start_date
    type: string
    description: 开始日期 YYYY-MM-DD
  - name: end_date
    type: string
    description: 结束日期 YYYY-MM-DD

⚠️ 只允许查询(SELECT)。INSERT / UPDATE / DELETE 出于安全默认禁用。如果业务确需写操作,在 kind 字段选 *-execute-sql 类型(需要数据源用具有写权限的用户连接)。

2.7.4 工具集管理 ​

路径:/genai-toolbox/toolsets

工具集 = 一组工具的集合。MCP 协议的最小单元是 toolset 不是 tool,所以发布前必须打包。

截图:工具集列表

列表页 ​

卡片显示:名称、描述、包含工具数、Tags、操作。

新建/编辑对话框 ToolsetDialog ​

字段必填说明
name✓内部标识
display_name✓UI 名称
description✓给 AI 看的工具集说明
tool_ids✓多选已存在的工具
Tags

💡 命名建议:按业务域命名,如 customer_lookup、order_analytics、hr_query。一个工具集 5~15 个工具最佳;太多 AI 不知道选哪个。

2.7.5 运行状态 ​

路径:/genai-toolbox/deployment(路由未变,但渲染的是「运行状态」页)

展示 Sira 内置数据工具执行器的实时状态与配置变更审计。这里没有"部署"操作 —— 工具保存即生效。

截图:运行状态页

顶部三个卡片 ​

卡片内容
执行器模式当前执行器模式 + 版本徽章;标注"不需要外部容器(进程内执行)"
资源清单数据源 / 工具 / 工具集 三个数量
连接池当前活跃池数 / max_pools_per_org 上限;副标题显示空闲驱逐 TTL(idle_ttl_seconds)

顶部按钮 ​

  • 「刷新」— 重新拉取运行状态 + 配置变更审计
  • 「健康检查」— 探活所有数据源(source),toast 汇总"已探活 N 个 / 健康 X / 异常 Y"

健康检查结果 ​

手动触发健康检查后展示的列表,每行:

字段说明
状态图标✅ 健康 / ❌ 异常
名称 + 类型数据源名 + kind
错误详情异常时显示具体错误(hover 看完整)

活跃连接池(表格) ​

当前进程中保持的数据源连接池:

列说明
组织org id(等宽)
类型数据源 kind 徽章
Source ID数据源 ID(等宽,截断)
存活连接池建立至今(age)
空闲距上次使用的时长(idle)— 超过 TTL 会被驱逐

配置变更审计 ​

最近的 source / tool / toolset 编辑记录(时间线),每行:

字段说明
类型徽章source / tool / toolset
名称资源名;已禁用的额外加「已禁用」徽章
时间最近一次 updated_at

2.7.6 Sira 智能体如何用工具集? ​

工具保存后即刻可用,有两种方式:

方式 A(常规):直接在智能体里勾选 在智能体配置里直接勾选工具集或单个工具,即可生效 —— 工具在 Sira 进程内执行,无需额外配置 MCP 端点。

方式 B:作为 MCP 暴露给外部 / 跨系统调用 这些工具同时通过 Sira 自带的内置 MCP 端点 /api/genai-toolbox/mcp(Streamable HTTP)对外暴露。外部 MCP 客户端可直接连这个端点使用,不需要任何独立的 toolbox 容器或外部服务地址。

2.7.7 常见问题 ​

Q1:改了工具,智能体调不到? ​

工具保存即生效,没有部署步骤。如果调不到,检查:工具是否「启用」、智能体是否勾选了对应工具集/工具、数据源是否健康(去「运行状态」点「健康检查」)。

Q2:数据源密码字段安全吗? ​

后端用对称加密存储(同 MCP 工具 API Key)。工具在 Sira 进程内执行,凭证不会再渲染成明文 tools.yaml 推给外部容器。

Q3:能不能让 AI 自动写 SQL 而不需要预先建工具? ​

可以,但不推荐。让 AI 自由写 SQL = 给数据库 root 权限 = 灾难。GenAI Toolbox 的核心价值就是用预定义工具收紧攻击面:管理员审过的 SQL 才暴露给 AI。

如果确实需要"自然语言转 SQL",做法:

  • 给 AI 配一个"查表结构"工具
  • AI 用结构生成 SQL
  • AI 调用一个"执行 SQL"工具(此工具受用户审批 — HITL 模式)

Q4:工具的 description 写不好,AI 总是调错? ​

按以下模板写:

[做什么]:本工具查询客户的最近订单。
[何时调用]:用户问到"我最近买了什么""上次购买记录"等场景。
[参数说明]:customer_id 是必填的客户 ID,可以从对话上下文取。
[返回格式]:订单列表,每项含 order_id, product_name, amount, created_at。
[不要用于]:历史超过 3 个月的查询(走另一个工具)。

description 越具体,AI 选择越准。

Apache-2.0 Licensed

Copyright © 2024 Sira AI Inc.