GenAI Toolbox - 数据集成

GenAI Toolbox 为 AI 智能体提供数据库访问能力。通过可视化界面配置数据源和工具，AI 可以直接查询企业数据库。

架构说明（2026-05 起）

早期版本依赖一个独立的 mcp-toolbox Go 容器（把配置渲染成 tools.yaml 推过去运行）。该容器已下线。工具现在在 Sira 进程内执行：由 SiraSQLToolFactory + 13 个 kind 适配器 + 连接池管理器驱动，并通过 Sira 自带的 MCP 端点 /api/genai-toolbox/mcp 对外暴露。

因此没有"部署"这一步 —— 工具配置存在数据库里，保存即生效。

什么是 GenAI Toolbox

GenAI Toolbox 专门为 AI 模型提供结构化数据访问能力，让您可以：

连接多种数据库：MySQL、PostgreSQL、BigQuery、MongoDB 等
可视化创建工具：无需编写代码即可定义数据查询工具
智能体自动调用：AI 智能体根据需求自动选择合适的工具
进程内执行 + 连接池：工具在 Sira 后端进程内运行，由连接池管理器复用数据库连接
MCP 对外暴露：通过 /api/genai-toolbox/mcp 把这些工具以 MCP 协议暴露给外部客户端

核心概念

1. 数据源 (Source)

数据源是数据库连接的抽象，支持多种类型：

关系型数据库：

MySQL
PostgreSQL
SQL Server
Oracle

云数据仓库：

Google BigQuery
Amazon Redshift
Snowflake

NoSQL 数据库：

MongoDB
Redis
Elasticsearch

图数据库：

Neo4j
TigerGraph

2. 工具 (Tool)

工具是对数据源的具体操作定义，AI 通过调用工具来访问数据：

工具类型：

SQL 查询类：postgres-sql、mysql-sql、bigquery-sql
NoSQL 查询类：mongodb-query、redis-command
执行类：execute-sql（动态 SQL 执行）

工具属性：

name：工具唯一标识
description：工具描述（供 AI 理解用途）
statement：SQL 语句或操作定义
parameters：参数定义（AI 需要提供的参数）

3. 工具集 (Toolset)

工具集是工具的逻辑分组，方便管理和部署：

可以将相关的工具组织到一个工具集
便于一次性把一组工具挂给 Agent
便于在不同场景下使用不同的工具组合

快速开始

步骤 1：配置数据源

导航到 GenAI Toolbox → 数据源管理
点击创建数据源按钮
填写数据源信息：

名称: customer_db
显示名称: 客户数据库
数据源类型: MySQL
主机: localhost
端口: 3306
数据库名: customers
用户名: app_user
密码: ********

点击测试连接验证配置
保存数据源

步骤 2：创建查询工具

导航到 GenAI Toolbox → 工具管理
点击创建工具按钮
填写工具信息：

工具名称: get_customer_info
显示名称: 获取客户信息
描述: 根据客户ID查询客户详细信息，包括姓名、邮箱、电话、注册时间等
工具类型: mysql-sql
数据源: customer_db

SQL 语句:
SELECT
  customer_id,
  name,
  email,
  phone,
  created_at
FROM customers
WHERE customer_id = :customer_id

参数定义:
- 名称: customer_id
  类型: integer
  描述: 客户ID
  必填: 是

点击验证工具测试 SQL 语法
保存工具

步骤 3：创建工具集

导航到 GenAI Toolbox → 工具集管理
点击创建工具集按钮
填写工具集信息：

工具集名称: customer_service_tools
显示名称: 客服工具集
描述: 客服人员使用的客户查询工具集

选择要包含的工具：
- get_customer_info
- get_customer_orders
- get_customer_tickets
保存工具集

步骤 4：在 Agent 中使用

创建或编辑一个 Agent
在工具配置中选择工具集（或单个工具）
保存即生效 —— Agent 立刻获得调用这些数据库工具的能力，无需部署

工具集同时通过 /api/genai-toolbox/mcp 以 MCP 协议对外暴露，外部 MCP 客户端也可直接连这个端点使用。如需查看连接池实时状态或对数据源做健康检查，进入 GenAI Toolbox → 运行状态。

使用场景

场景 1：智能客服查询

需求：客服智能体能够查询客户信息、订单、售后记录

方案：

创建客户数据库数据源
创建以下工具：
- get_customer_by_phone：根据手机号查询客户
- get_customer_orders：查询客户订单
- get_refund_records：查询退款记录
将工具添加到"客服工具集"
部署并关联到客服 Agent

效果：

客户："我想查询我的订单"
AI："请提供您的手机号"
客户："138****5678"
AI 自动调用 get_customer_by_phone → get_customer_orders
AI："您有3个订单，分别是..."

场景 2：数据分析助手

需求：分析师可以用自然语言查询业务数据

方案：

连接数据仓库（BigQuery/Snowflake）
创建常用分析工具：
- get_daily_sales：每日销售额
- get_top_products：热销商品排行
- get_user_growth：用户增长趋势
关联到数据分析 Agent

效果：

分析师："本月销售额是多少？"
AI 自动调用 get_daily_sales 并汇总
AI："本月累计销售额为 1,234,567 元，同比增长 15%"

场景 3：运维监控助手

需求：运维智能体监控系统状态

方案：

连接监控数据库
创建监控工具：
- get_system_metrics：系统指标
- get_error_logs：错误日志
- get_api_performance：API 性能
设置告警规则

效果：

运维人员："最近有哪些错误？"
AI 调用 get_error_logs
AI："过去1小时有3个错误，主要是数据库连接超时..."

场景 4：财务报表生成

需求：自动生成财务报表

方案：

连接财务数据库
创建报表工具：
- get_revenue_by_department：按部门收入
- get_expense_summary：费用汇总
- get_profit_margin：利润率
使用 Deep Agents + Filesystem 保存报表

效果：

财务人员："生成本月财务报表"
AI 依次调用多个工具获取数据
AI 生成报表并保存为 Excel 文件

数据源配置详解

MySQL / MariaDB

yaml

kind: mysql
config:
  host: localhost
  port: 3306
  database: mydb
  username: user
  password: pass
  ssl_mode: required  # 可选: disabled, required, verify_ca, verify_identity
  max_connections: 10
  timeout: 30

PostgreSQL

yaml

kind: postgres
config:
  host: localhost
  port: 5432
  database: mydb
  username: user
  password: pass
  ssl_mode: require
  max_connections: 10

MongoDB

yaml

kind: mongodb
config:
  connection_string: mongodb://user:pass@localhost:27017/mydb
  database: mydb
  auth_source: admin

BigQuery

yaml

kind: bigquery
config:
  project_id: my-project
  dataset_id: my_dataset
  credentials_json: |
    {
      "type": "service_account",
      ...
    }

Redis

yaml

kind: redis
config:
  host: localhost
  port: 6379
  password: pass
  db: 0

工具定义最佳实践

1. 清晰的描述

工具描述是 AI 理解工具用途的关键：

✅ 好的描述：
根据客户手机号查询客户信息，返回客户ID、姓名、邮箱、会员等级、注册时间。
适用于客户咨询时快速定位客户身份。

❌ 差的描述：
查询客户

2. 参数化 SQL

使用参数而不是拼接 SQL：

sql

✅ 好的写法：
SELECT * FROM orders WHERE customer_id = :customer_id

❌ 差的写法：
SELECT * FROM orders WHERE customer_id = {customer_id}

3. 限制返回行数

避免返回过多数据：

sql

✅ 好的写法：
SELECT * FROM logs WHERE created_at > :start_date LIMIT 100

❌ 差的写法：
SELECT * FROM logs WHERE created_at > :start_date

4. 只读操作优先

除非必要，优先创建只读查询工具：

sql

✅ 安全：
SELECT * FROM customers WHERE id = :id

⚠️ 谨慎使用：
UPDATE customers SET status = :status WHERE id = :id

5. 添加使用示例

为工具添加示例，帮助 AI 理解：

json

{
  "examples": [
    {
      "description": "查询客户张三的信息",
      "parameters": {
        "customer_id": 12345
      },
      "expected_result": "返回客户ID 12345的详细信息"
    }
  ]
}

安全和权限

1. 数据源权限

使用只读账户连接数据库
限制账户只能访问必要的表
定期轮换数据库密码

2. 工具权限

默认工具需要组织权限才能使用
可以设置认证要求（auth_required）
支持自定义认证配置

3. SQL 注入防护

使用参数化查询，不要拼接 SQL
系统会自动验证 SQL 语法
禁止使用 DROP、TRUNCATE 等危险操作

4. 数据脱敏

对敏感数据进行脱敏处理：

sql

SELECT
  customer_id,
  name,
  CONCAT(LEFT(phone, 3), '****', RIGHT(phone, 4)) AS phone,
  CONCAT(LEFT(email, 3), '***@', SUBSTRING_INDEX(email, '@', -1)) AS email
FROM customers
WHERE customer_id = :customer_id

性能优化

1. 添加索引

确保查询字段有索引：

sql

-- 为常用查询字段添加索引
CREATE INDEX idx_customer_phone ON customers(phone);
CREATE INDEX idx_order_date ON orders(created_at);

2. 限制查询范围

使用时间范围和分页：

sql

SELECT * FROM logs
WHERE created_at > :start_date
  AND created_at < :end_date
LIMIT 100

3. 使用缓存

为查询结果设置缓存：

json

{
  "cache_ttl": 300  // 缓存5分钟
}

4. 连接池配置

合理配置连接池大小：

yaml

max_connections: 10  // 最大连接数
connection_timeout: 30  // 连接超时（秒）

监控和日志

1. 工具执行统计

系统自动记录：

工具调用次数
平均执行时间
错误率

2. 查看执行日志

导航到 GenAI Toolbox → 工具管理
点击工具详情
查看执行历史标签

3. 告警设置

可以设置告警规则：

执行时间超过阈值
错误率超过阈值
返回空结果

与其他功能集成

1. 与 Agent System 集成

在 Agent 中启用 GenAI Toolbox 工具：

yaml

agent:
  name: customer_service_agent
  tools:
    - type: genai_toolbox
      toolset: customer_service_tools

2. 与 Deep Agents 集成

Deep Agents 可以使用数据库工具：

yaml

orchestrator:
  type: deep_agents
  config:
    mcp_tools:
      - genai_toolbox:customer_service_tools

3. 与知识库集成

将数据库查询结果作为知识库的数据来源：

yaml

knowledge_base:
  sources:
    - type: genai_toolbox
      tool: get_product_catalog

常见问题

Q1: GenAI Toolbox 和 MCP 工具有什么区别？

GenAI Toolbox：

专注于数据库访问
可视化配置工具
支持多种数据源

MCP 工具：

通用工具协议
支持任意类型的工具
需要编写代码实现

两者可以同时使用，互补优势。

Q2: 支持动态 SQL 吗？

支持！使用 execute-sql 工具类型：

json

{
  "kind": "execute-sql",
  "description": "执行动态SQL查询",
  "parameters": [
    {
      "name": "sql",
      "type": "string",
      "description": "要执行的SQL语句"
    }
  ]
}

注意：动态 SQL 有安全风险，谨慎使用。

Q3: 如何处理复杂的多表查询？

创建视图或使用 JOIN：

sql

-- 方式1: 创建视图
CREATE VIEW customer_summary AS
SELECT
  c.customer_id,
  c.name,
  COUNT(o.order_id) AS order_count,
  SUM(o.amount) AS total_amount
FROM customers c
LEFT JOIN orders o ON c.customer_id = o.customer_id
GROUP BY c.customer_id, c.name;

-- 方式2: 直接JOIN
SELECT * FROM customer_summary WHERE customer_id = :customer_id;

Q4: 工具执行超时怎么办？

检查 SQL 性能，添加索引
增加超时时间：
json
```
{
  "timeout": 60  // 60秒
}
```
分批查询大数据量

Q5: 如何调试工具？

使用验证工具功能测试 SQL
查看执行历史了解实际执行情况
使用测试参数进行调试
查看 Agent 日志中的工具调用详情

技术架构

进程内执行器（无独立容器）

工具不再推送到外部 toolbox 容器，而是在 Sira 后端进程内执行：

┌─────────────────┐
│   Sira AI UI    │   配置数据源 / 工具 / 工具集
└────────┬────────┘
         │
         ▼
┌──────────────────────────────────────────┐
│              Sira AI Backend              │
│  ┌────────────────────────────────────┐  │
│  │  内置数据工具执行器                  │  │
│  │  SiraSQLToolFactory + 13 kind 适配器 │──┼──► 数据库 (多种类型)
│  │  + 连接池管理器                      │  │
│  └────────────────────────────────────┘  │
│            │                  │           │
│            ▼                  ▼           │
│      AI Agent          /api/genai-toolbox │
│      (进程内直调)        /mcp (MCP 对外)   │
└──────────────────────────────────────────┘

配置存储：数据源 / 工具 / 工具集都存在数据库里（不再渲染成 tools.yaml）
执行：AI Agent 在进程内直接调用；连接池管理器按 org 复用数据库连接
对外：通过 /api/genai-toolbox/mcp（Streamable HTTP）以 MCP 协议暴露

下一步

Agent 配置指南 - 为 Agent 添加数据库工具
Deep Agents 模式 - 在 Deep Agents 中使用
MCP 工具 - 了解其他类型的工具
安全最佳实践 - 保障数据安全

提示：GenAI Toolbox 让 AI 能够访问企业数据库，是构建"数据AI"应用的关键能力。建议从只读查询开始，逐步扩展到更复杂的场景。

GenAI Toolbox - 数据集成 ​

什么是 GenAI Toolbox ​

核心概念 ​

1. 数据源 (Source) ​

2. 工具 (Tool) ​

3. 工具集 (Toolset) ​

快速开始 ​

步骤 1：配置数据源 ​

步骤 2：创建查询工具 ​

步骤 3：创建工具集 ​

步骤 4：在 Agent 中使用 ​

使用场景 ​

场景 1：智能客服查询 ​

场景 2：数据分析助手 ​

场景 3：运维监控助手 ​

场景 4：财务报表生成 ​

数据源配置详解 ​

MySQL / MariaDB ​

PostgreSQL ​

MongoDB ​

BigQuery ​

Redis ​

工具定义最佳实践 ​

1. 清晰的描述 ​

2. 参数化 SQL ​

3. 限制返回行数 ​

4. 只读操作优先 ​

5. 添加使用示例 ​

安全和权限 ​

1. 数据源权限 ​

2. 工具权限 ​

3. SQL 注入防护 ​

4. 数据脱敏 ​

性能优化 ​

1. 添加索引 ​

2. 限制查询范围 ​

3. 使用缓存 ​

4. 连接池配置 ​

监控和日志 ​

1. 工具执行统计 ​

2. 查看执行日志 ​

3. 告警设置 ​

与其他功能集成 ​

1. 与 Agent System 集成 ​

2. 与 Deep Agents 集成 ​

3. 与知识库集成 ​

常见问题 ​

Q1: GenAI Toolbox 和 MCP 工具有什么区别？ ​

Q2: 支持动态 SQL 吗？ ​

Q3: 如何处理复杂的多表查询？ ​

Q4: 工具执行超时怎么办？ ​

Q5: 如何调试工具？ ​

技术架构 ​

进程内执行器（无独立容器） ​

下一步 ​

GenAI Toolbox - 数据集成

什么是 GenAI Toolbox

核心概念

1. 数据源 (Source)

2. 工具 (Tool)

3. 工具集 (Toolset)

快速开始

步骤 1：配置数据源

步骤 2：创建查询工具

步骤 3：创建工具集

步骤 4：在 Agent 中使用

使用场景

场景 1：智能客服查询

场景 2：数据分析助手

场景 3：运维监控助手

场景 4：财务报表生成

数据源配置详解

MySQL / MariaDB

PostgreSQL

MongoDB

BigQuery

Redis

工具定义最佳实践

1. 清晰的描述

2. 参数化 SQL

3. 限制返回行数

4. 只读操作优先

5. 添加使用示例

安全和权限

1. 数据源权限

2. 工具权限

3. SQL 注入防护

4. 数据脱敏

性能优化

1. 添加索引

2. 限制查询范围

3. 使用缓存

4. 连接池配置

监控和日志

1. 工具执行统计

2. 查看执行日志

3. 告警设置

与其他功能集成

1. 与 Agent System 集成

2. 与 Deep Agents 集成

3. 与知识库集成

常见问题

Q1: GenAI Toolbox 和 MCP 工具有什么区别？

Q2: 支持动态 SQL 吗？

Q3: 如何处理复杂的多表查询？

Q4: 工具执行超时怎么办？

Q5: 如何调试工具？

技术架构

进程内执行器（无独立容器）

下一步