Datasource 与 Dataset

控制台的数据模块管理三个不同概念：关系型数据访问、GeniSpace 托管 Dataset，以及平台提供的数据。为智能体、工作流或 Workbench 配置绑定前，应先选择正确的数据类型。

打开数据模块

打开 控制台 → 数据并选择标签页：

标签页	用途
Datasource	连接数据库并定义受控的 SQL 操作
Dataset	创建支持结构化、全文和向量搜索的托管集合
平台数据	查看平台或已安装应用暴露的数据资源

Datasource

Datasource 连接关系型数据库，暴露明确的数据操作，而不是提供不受限制的数据库访问。

典型步骤：

1. 使用安全凭据配置数据库连接。
2. 基于该连接创建 Datasource 操作。
3. 定义 SQL、参数和允许的读写行为。
4. 使用非生产数据测试。
5. 将 Datasource 授权给工作流、智能体或 Workbench 组件。

读取、创建、更新和删除应使用独立操作。用户只需要查询时，不要授予通用写入能力。

Dataset

Dataset 存储由 Schema 定义、由 GeniSpace 管理的记录，可以支持：

• 主键与精确过滤查询
• 记录总数
• 插入、更新和删除
• 对已配置文本字段进行全文搜索
• 对已配置向量化来源字段进行向量搜索

Dataset 与智能体知识库存储相互独立。将 Dataset 绑定到智能体不会把它变成知识库。

创建 Dataset

1. 打开 数据 → Dataset。
2. 点击创建 Dataset。
3. 填写名称和描述。
4. 定义业务字段和主键。
5. 只在需要时启用向量搜索或全文搜索。
6. 使用向量搜索时，标记需要参与检索的文本字段。
7. 使用全文搜索时，启用符合要求的文本字段，并在界面提供时选择分词器。
8. 核对生成的索引字段并创建 Dataset。

字段名会成为 API 和智能体工具契约。应使用稳定、含义明确的名称；应用依赖后不要随意重命名。

向量化与 Embedding 模型

启用向量搜索后，GeniSpace 会通过平台模型网关将所选来源字段内容转换为向量并保存。查询文本使用该 Dataset 绑定的同一个模型进行向量化。

• 普通用户提供文本，不需要提供预计算向量。
• Dataset 会记录实际使用的 Embedding 配置。
• 写入和查询的模型、维度必须保持一致。
• 文本 Dataset 使用当前版本配置的 Dataset 默认 Embedding 模型。
• 需要图片或视频语义检索时，必须显式配置支持的多模态模型。

修改模型或向量化字段组合后，已有记录可能需要重新向量化，应由管理员协调执行。

选择正确的搜索方式

需求	操作
已知 ID 或精确字段条件	Query
记录总数	Count
字面词语、姓名、编码或短语	全文搜索
相似语义、经历、能力或跨语言概念	向量搜索

向量 Top-K 返回距离最近的记录，并不证明记录满足必须条件。例如，可以先通过语义找候选人，再使用结构化字段核对证书、地点或学历等硬性要求。

Dataset 详情与预览

详情页显示 Schema、索引/搜索设置、统计和记录预览。调整显示字段不会修改底层 Schema。预览中较长的向量值可能只显示一部分。

集合加载中或向量数据库暂不可用时，统计信息可能临时获取失败。统计错误本身不表示 API 请求没有权限。

API 试验场

打开 Dataset 后选择 API 试验场。试验场根据当前 Dataset Schema 生成请求体和代码示例。

操作	接口后缀	主要请求字段
插入	/insert	记录数组 data
更新	/update	filter、update_data
查询	/query	ids 或 filter、limit、offset、outputFields
计数	/count	根据接口契约可选过滤条件
删除	/delete	filter；试验场要求二次确认
向量搜索	/search	text、limit，以及可选输出字段/过滤条件
全文搜索	/full-text-search	查询数据、稀疏索引字段、数量和输出字段

所有接口都是以下路径下的 POST 请求：

https://api.genispace.cn/api/datasets/{datasetId}/data/{operation}

试验场提供 cURL、Python 和 JavaScript 示例。请将 YOUR_TOKEN 替换为有效 API Key 或访问令牌，且不要公开该凭据。

插入记录

{
  "data": [
    {
      "name": "示例记录",
      "description": "用于检索的内容"
    }
  ]
}

向量化字段按记录单独生成 Embedding。多条记录可以使用批量数据库写入，但每条记录的语义内容仍是独立 Embedding 输入。

类型安全的 IDs 查询

已知主键时使用 ids：

{
  "ids": ["record-001", "record-002"],
  "limit": 10,
  "offset": 0,
  "outputFields": ["name", "description"]
}

字符串主键使用字符串，数值主键使用数字。API 会安全构造数据库表达式，调用方不需要手工拼接 IN (...)。

更新记录

{
  "filter": "id == \"record-001\"",
  "update_data": {
    "description": "更新后的描述"
  }
}

更新向量化来源字段时，系统会重新生成对应向量。

删除记录

删除会永久移除所有符合过滤条件的记录。应先使用 Query 测试相同过滤条件，并完成试验场二次确认。

过滤条件与字段规则

• 只使用 Dataset Schema 中声明的字段。
• outputFields 只能请求真实存在的字段；未知字段会被向量数据库拒绝。
• 使用试验场展示的表达式语法，不要在 Dataset 过滤器中编造 SQL 函数。
• 主键批量查询优先使用 ids，不要手工拼接 IN 表达式。
• 将硬性结构化条件与语义查询文本分开。

将 Dataset 绑定到智能体

1. 在控制台中编辑智能体。
2. 授权所需 Dataset。
3. 启用合适的 Dataset 工具。
4. 为智能体提供准确的 Schema 和业务含义说明。
5. 分别测试精确查询、全文和语义场景。
6. 确认空结果和工具错误会被如实报告。

故障排除

问题	检查项
向量搜索没有记录	集合数据、向量化来源字段、Embedding 状态、Dataset 绑定模型和查询过滤条件
field ... not exist	删除未知输出/过滤字段，使用 Dataset Schema
过滤表达式解析失败	使用支持的比较语法，主键查询改用 ids
全文结果过宽	检查来源字段、分词器和查询词
插入成功但语义搜索无结果	检查向量生成状态，以及目标来源字段是否标记为向量化
统计信息失败	检查集合就绪状态和向量数据库健康状态，服务恢复后重试

相关文档

• 智能体工具与 MCP
• Workbench
• 工作流概览
• API 认证