2.1 私有数据访问¶

学习目标¶

掌握知识库的创建和使用
了解知识库检索相关的核心原理
掌握数据库的创建和使用
掌握在工作流中使用数据库进行增删改查

一、概述¶

在前面的内容中，我们已经学习了如何使用工作流搭建一个功能复杂的agent，以及工作流调用插件，使工作流具备处理文件、联网搜索等能力。但是在某些业务场景下，我们还需要让agent具备访问私有数据库的能力：

比如，我们有一些医疗知识文档，想通过和agent对话的方式，直接去询问医疗知识文档中的知识，这需要让agent具备访问”知识库“的能力；再比如，我想让agent作为一个签到代理，能够记录和更新用户的签到信息，同时我还可以查询有哪些用户已经签到，这需要让agent具备读写”数据库“的能力。

什么时候使用知识库，什么时候使用数据库：

知识库：知识库可以理解为是一个支持快速检索的文件夹，里面存放的都是一些文档，类比word文档、pdf文档等。适合存储文字内容
数据库：数据库可以理解为是一张巨大的表格，里面存放的是一些结构化的数据，类比excel表格数据。

二、在工作流中使用知识库¶

知识库功能包含两个能力，一是存储和管理外部数据的能力，二是增强检索的能力。

数据管理与存储
扣子开发平台支持从多种数据源渠道上传文本和表格数据，例如本地文档、在线数据、Notion、飞书文档等。
上传后，扣子可将知识内容自动切分为一个个内容片段进行存储，同时支持用户自定义内容分片规则，例如通过分段标识符、字符长度等方式进行内容分割。
增强检索：
扣子开发平台的知识功能还提供了多种检索方式来对存储的内容片段进行检索，例如使用全文检索通过关键词进行内容片段检索和召回。
大模型会根据召回的内容片段生成最终的回复内容。

1 创建一个知识库¶

1.1 新建一个知识库资源¶

在资源库页面点击右上角的”+资源“，选择知识库

然后，选择”创建扣子知识库“：

扣子支持使用扣子知识库和火山知识库，两者对应的分类方式不同。

使用知识库功能的第一步就是上传知识内容。上传知识内容又分为两步，首先选择要上传的知识类型和上传方式，然后对上传的内容进行切分。合理的内容分片可以提升召回内容的相关性，从而提升大模型回复问题的准确性。

在上传知识前，建议先了解不同的知识类型的使用场景和导入方式，以便更好地管理知识内容。

扣子知识库：

适用于轻量检索，低代码，轻量级应用的场景（以下内容来自官方文档。了解即可，涉及未学术语较多，不必深究）

对比项	文本类型	表格类型	照片知识库
使用场景	文本知识库支持基于内容片段进行检索和召回，大模型结合召回的内容生成最终内容回复，适用于知识问答等场景。	表格知识库支持基于索引列的匹配（表格按行进行划分），同时也支持基于 NL2SQL 的查询和计算。	照片知识库支持基于标注信息的匹配，适用于图像生成场景。
导入方式	本地文档：从本地文件中导入文本内容，支持.txt、.pdf、doc、.docx 文件格式。在线数据：通过自动和手动方式采集指定网页的内容。第三方渠道：从飞书文档和 Notion 文档中导入内容。自定义：手动输入要导入的文本内容。	本地文档：从本地文件中导入表格内容，支持.csv和.xlsx文件格式。在线数据：通过 API 导入数据。第三方渠道：支持从飞书表格中导入数据。自定义：手动输入要导入的表格数据。	本地图片：从本地文件中导入图片，支持JPG、JPEG和PNG图片格式。
内容分段	支持自动内容分段和手动分段方式。	对于表格内容，默认按行分片，一行就是一个内容片段，不需要再进行分段设置。	不涉及。
索引	不涉及。	扣子支持设置索引字段。用户输入的问题会与设置的索引字段内容对比，根据相似度匹配最相关的内容给大模型用于内容生成。	扣子支持设置图片的标注信息。用户输入的问题会与设置的标注信息对比，根据相似度匹配最相关的图片给大模型用于内容生成。

火山知识库：

适用于企业用户，以及大规模的查询场景。（以下内容来自官方文档。了解即可，涉及未学术语较多，不必深究）

对比项	结构化数据	非结构化数据
使用场景	文件内容为结构一致、字段明确的数据，无需平台额外分段处理。例如问答数据（问题与答案）、用户数据（姓名、年龄、偏好等）、商品数据（名称、价格、库存）等。问答总结：在 Excel 文档中定义问题列和答案列，上传至知识库后，指定问题列用于知识库检索，答案列用于大模型回答参考。商品数据整理：适用于电商平台商品信息管理，包括商品名称、描述、价格、库存等字段，方便商品搜索、分类、推荐。	文件内容丰富且版面复杂，如文章、报告、书籍等，通常结构不固定，需要平台进行解析和分段处理。知识文档管理：存储和管理知识文档，通过知识库解析分段转化为可检索、可引用的知识资源，便于查阅和学习。
导入方式	本地上传从 TOS 中导入公开下载链接	本地上传从 TOS 中导入公开下载链接
切片方式	不涉及	支持如下切片规则：默认切片规则：系统会自动保留完整语义进行切片。自定义切片规则：通过指定切片最大长度、图片 OCR、合并短文本片等参数定义切片规则。
索引	支持设置索引字段，并提供 HNSW-Hybrid、HNSW、FLAT 等索引算法供用户选择。	不涉及

在这里使用火山知识库的场景会比较少，因为如果选型选择coze，大多数开发的都是一些轻量级的C端提效的应用。比较重量级的应用不太会使用coze进行，如果是想更好的和本地海量的知识库联动，可以考虑dify，或者更加企业级的langchain、langgraph等框架。但是对于少数用户来讲，还是可能会存在使用coze + 海量知识检索的场景。

最后，选择“文本格式”以及“本地文档”。

1.2 解析文件和分段¶

将物料 03-大模型发展史.docx 上传到知识库：

点击下一步，进到“创建设置”页面：

支持精准解析和快速解析：

精准解析：支持从文档中提取图片元素、扫描件（OCR）、表格元素；支持设置过滤策略，以文档页的粒度过滤掉当前文档中不需要导入的内容。精准解析需要耗时更长的时间。
快速解析：不支持从文档中提取图像、表格等元素，适用于纯文本。

上传本地文档时，支持以自动分段与清洗、自定义分段和层级分段这三种方式对文本内容进行分段处理。

对比项	按层级分段	自动分段	自定义分段
分段原理	根据文档的目录结构、章节划分等层级信息，将内容划分为不同层级的文本单元。	扣子可对上传的内容进行自动分段，支持复杂布局的文件处理，例如：可识别段落。可识别页眉/页脚/脚注等非重点内容。支持跨页跨栏的段落合并支持解析表格中的图片信息。支持解析文档中的表格内容（目前，仅支持解析带线框的表格内容）。	根据用户需求，灵活配置分段标识符、分段最大长度、分段重叠度等参数，同时还能通过设置文本预处理规则，在分段前对文本进行特定处理。
适用场景	适用于表示复杂、层次分明的知识体系，例如技术手册、法律条文、标准规范等。这些文档通常具有明确的结构层次，需要按照章节、小节等进行组织和检索。	适用于结构较为规范的文档，例如新闻文章、学术论文等，这些文档通常使用标准的标点符号进行分隔。	适用于对分段有特殊需求的场景，如需要根据特定的业务规则或语义关系进行分段，或者处理结构不规则的文本数据。

然后是配置存储，这里我们使用平台共享存储即可。如果应用对性能要求比较高，可以再火山引擎上购买独立的存储服务，使用云搜索服务。

最后需要给同学们强调的是：文档分段的好坏直接影响检索的效果，如何选择分段的策略非常重要。但因这部分内容原理比较复杂，不适宜在coze阶段给同学们深度讲解，所以这部分知识作为拓展内容，同学们可根据个人的情况自行学习，详见 1.3 拓展：分段详细解读部分。 如觉得晦涩难懂，可在学习完RAG阶段后复习时再来学习。

1.3 分段预览和数据处理¶

分段预览：

在使用不同的解析方式时，会有分段预览这个阶段，让用户查看分段以后的效果大概是什么样的，以便确认分段是否符合预期。如果不符合预期，可以选择上一步，重新选择。需要注意的是，在这一步处理的时候，数据并没有存储到知识库中，当确认无误，点击下一步时，才会执行数据处理

数据处理：

点击下一步后，等待服务器处理完成数据。点击确认后，知识库就完成了数据写入。

将文档写到知识库以后，我们可以看到左侧的文档列表，代表已经有哪些文档被写到了里面，它和上传时的文件名保持一致。点击文档名以后，可以看到具体的分段的信息。这里如何分段，

2 在工作流中使用知识库¶

在前面的课程中，我们已经建好了知识库，并且把数据导入到了知识库中，接下来我们将在工作流中使用我们已经建好的知识库，完成一个知识库检索的demo。

2.1 创建一个知识库检索节点¶

首先，我们创建一个新的工作流，并添加一个“知识库检索”节点：

给知识库检索节点赋值，把开始节点的输入传如给知识库检索，目标知识库选择我们前面刚建好的

输入：只有一个query字段，且必须是str类型。就是要去知识库检索时的查询，执行检索时，这个query会被和知识库中已有的文档段落进行匹配，并返回给用户匹配度最高的（1-20条，默认1条）
输出：outputList，数组类型，匹配到几个文档，就返回几条数据

细心的同学可能会注意到检索策略下面会有一堆参数，如下图。这些参数是知识库检索的核心参数，除了分段的策略以外，这些参数同样影响着知识库检索的效果，这里我们先使用默认参数，稍后将给同学们介绍参数的原理和如何设置。

2.2 使用大模型润色检索结果和兜底¶

有时候我们检索知识库的时候结果可能是空的，或者检索出来一些无关的段落，以及话术比较生硬等情况。所以我们在工作流中使用知识库时，不会直接把知识库检索出来的结果返回给用户，而是使用大模型做一些润色和兜底的工作，再把结果给到用户。结合知识库创建，到此位置，这就是一个简单的RAG的流程。如果是在做一个轻量级的agent，就可以考虑使用这种方式，快速实现。

接下来，我们在工作流中添加一个LLM节点，把query、查询结果都给到它，并赋予联网搜索能力

prompt如下：

你是一个知识库查询结果润色和兜底的助手，能够根据用户输入的问题对查询结果做润色。也可以在检索结果为空时，负责调用搜索插件，在互联网检索相关内容并返回给用户。  你的职责如下：
1.  如果检索结果不为空，根据用户输入的问题进行优化，并使用比较大方和专业的话术回复用户。这个过程不需要联网搜索。
2. 如果检索结果为空，则调用工具，在互联网检索对应的内容，并根据用户输入的问题进行优化，并使用比较大方和专业的话术回复用户

输入query:

什么是深度学习

调用大模型过程略，结果如下：

知识库检索结果：

润色以后的结果：

可以看到，经过大模型的润色，结果的可读性更好，更专业。

3 知识库的核心知识¶

3.1 检索策略¶

从知识库中获取知识的检索方式，不同的检索策略可以更有效地找到正确的信息，提高其生成的答案的准确性和可用性。支持的检索策略包括：

混合：结合全文检索和语义检索的优势，并对结果进行综合排序召回相关的内容片段。

语义：像人类一样去理解词与词、句与句之间的关系。推荐在需要理解语义关联度和跨语言查询的场景使用。例如下面两组句子，第一组的语义关系更强。

"狼追小羊"和"豺狼追山羊"

"狼追小羊"和"我爱吃炸猪排"

全文：基于关键词进行全文检索。推荐当查询内容包含以下场景时使用：

特定名称或专有名词、术语等，例如比尔盖茨、特斯拉 Model Y。
缩写词，例如 SFT。
ID，例如 12s1w1s2 系列。

3.2 召回数量与匹配度¶

最大召回数量：

从知识库中返回的最大段落数量。数值越大，返回的条目越多。默认召回 5 条检索结果。

最小匹配度：

匹配度指的query和段落的匹配程度。设置最小匹配度参数后，系统会根据设置的匹配度选取段落，低于指定匹配度的内容不会被召回。默认的最小匹配度为 0.5。

3.3 查询改写¶

在多轮对话中，用户的 Query 和对话的上下文息息相关，仅凭借用户最新一条提问可能无法正确识别用户的真实检索意图。查询改写是指根据对话历史对用户输入的 Query 进行优化或重构，从而更准确地捕捉真实的用户意图，提升信息检索的效率。知识库检索节点默认开启查询改写。

例如用户对话的上下文为：

问题1：知识库检索节点可以用来做什么？

回复1：知识库检索节点可以基于用户输入查询指定的知识库，召回最匹配的信息，并将匹配结果以列表形式返回。

问题2：怎么用？

对于问题2，不参考上下文的情况下无法判断用户的真实意图。开启查询改写后，问题2会被改写为“知识库检索节点怎么用？”

3.4 结果重排¶

结果重排是指根据相关性或质量对检索到的文档切片进行重新排序，以提高生成答案的准确性和相关性，适用于追求回答高精度和高相关性的场景，例如智能客服、专业技术答疑等场景。未开启结果重排时，节点输出的是向量检索的结果，根据匹配度从大到小排序。

假设用户查询“如何制作意大利面？” ，首先会从知识库中检索得到以下几个文档片段，其中先按照ABCD先后顺序排列：

切片 A：介绍意大利面的历史。
切片 B：讨论了不同种类的意大利面和它们的搭配。
切片 C：详细描述了制作意大利面的步骤，包括所需材料和烹饪技巧。
切片 D：提供了一些意大利面食谱。

在结果重排的过程中，知识库检索节点会分析用户的真实意图，对切片重新排序，使得最相关的内容排在前面。最终的排序可能变为：

切片 C：详细描述了制作意大利面的步骤，包括所需材料和烹饪技巧。
切片 D：提供了一些意大利面食谱。
切片 B：讨论了不同种类的意大利面和它们的搭配。
切片 A：介绍意大利面的历史。

4 拓展：分段详细解读¶

自动分段与清洗：选择该分段策略，会自动利用句号、分号、问号、感叹号等标点符号作为分段依据，将文档分割成一个个独立的句子或段落，无其他配置项。

自定义：选择该分段策略，完成以下配置。

分段标识符：分段标识符是用于识别和划分文本段落的特定字符或字符串。支持的分段标识符包括换行、2个换行、中文句号、中文叹号、英文句号、英文叹号、中文问号、英文问号、自定义分隔符（如"###"）等。例如，在英文文本中，句号通常作为自然语言句子的结束标志，可以作为分段标识符。
分段最大长度：分段最大长度是指每个文本段落允许的最大字符数。设置分段最大长度可以防止段落过长，导致后续处理（如检索、匹配）的效率降低。同时，也能够确保每个段落包含的信息量适中，便于理解和分析。
分段重叠度%：分段重叠度%是指相邻段落之间共享的字符数占分段最大长度的比例。设置分段重叠度可以在一定程度上保留段落之间的上下文信息，避免因分段导致信息的割裂。这对于需要考虑上下文关系的文本处理任务（例如语义理解、上下文推理）尤为重要。
文本预处理规则：文本预处理规则是指在进行分段之前，对原始文本进行的一系列处理操作的规则。通过文本预处理，可以去除文本中的噪声信息、统一文本格式、纠正错误等，从而提高分段的准确性和后续文本处理的效果。支持的文本预处理规则包括：
替换连续的空格、换行符和制表符
删除所有 URL 和电子邮箱地址

按层级分段：选择该分段策略，完成以下配置。

分段层级：分段层级是指在文档结构中，根据内容的重要性和逻辑关系设置为多个层级。例如在一个企业产品手册中，分段层级可以包括产品概述（一级标题）、产品特点（二级标题）、技术参数（三级标题）等。产品概述作为一级标题，其下的“产品特点”和“应用场景”可以是二级标题，进一步细分的“特点一”、“特点二”则是三级标题。设置分段层级为 2 时，系统会将知识库内容按照一级和二级标题进行划分，形成清晰的结构化信息。

743d7ba21bfc4820864ea3575fbbc945

检索切片保留层级信息：检索切片保留层级信息是指在进行检索时，是否保留文档段落的层级结构信息，以便在检索结果中展示段落之间的层次关系。保留层级信息有助于更好地理解检索结果的上下文和逻辑结构，便于快速定位到所需的具体信息，并把握文档的整体内容布局。默认切片检索不保留层级信息，勾选后切片检索会保留层级信息。

afc4ec737a2c4e358a5cee51c970ac21

配置完按层级分段，在预览分段时，还支持以下操作：

拖拽调整层级结构：通过拖拽操作，可以调整段落或章节之间的层级关系和顺序。例如，将一个二级标题拖拽到另一个一级标题下，使其成为新的子章节，或者调整两个同级标题的顺序。

a63ecaf01b2641049185349f596db09a

按照层级合并为切片：右击层级标题，选择合并为一个分段，将选定层级及其子层级的所有内容合并为一个分段。例如，选择一个二级标题，系统会将其下的所有三级标题和对应内容合并为一个完整的分段。

c83077ab8e834b82a7949d3aaa65bfc7

删除切片：右击层级标题或分段内容，选择删除，从知识库中移除选定的分段及其所有内容。例如，如果某个章节不再需要，可以直接删除对应的分段，包括其下的所有子层级。

d0f8bfd04f9f4277b3c61927da242f11

三、在工作流中使用数据库¶

扣子的数据库功能适用于组织和管理结构化数据，例如客户信息、产品列表、订单记录等。目前，扣子支持使用扣子官方数据库和火山数据库。

接下来，我们将以一个“绩效录入和查询agent”的一个简单的demo，帮助同学们理解怎么在工作流中使用数据库。这个agent支持绩效数据的查询、修改、增加、删除，我们将通过意图识别节点，实现这个agent的功能。

1 创建一个数据库¶

在资源库中创建一个数据库，如下图：

对比如下：

扣子数据库：扣子官方数据库，提供了类似传统软件开发中数据库的功能，允许用户以表格结构存储数据。
火山数据库：火山数据库是指云数据库 MySQL 版，它是火山引擎基于开源数据库 MySQL 打造的弹性、可靠的在线关系型数据库服务。MySQL 实例使用云原生方式部署，结合本地 SSD 存储类型，提供高性能读写能力；完全兼容 MySQL 引擎，并提供实例管理、备份恢复、日志管理、监控告警、数据迁移等全套解决方案，帮助企业简化繁杂的数据库管理和运维任务，使企业有更多的时间与资源聚焦于自己的核心业务。

扣子数据库和火山数据库在功能上无明显差异，均能满足数据的存储与分析需求。扣子数据库免费且易于使用，适合轻量级数据存储与分析场景，你可以先通过扣子数据库体验数据库功能；而火山数据库作为企业级云数据库，提供高性能和高扩展性，但会产生成本，当涉及企业级大规模、复杂的数据处理和分析时，你可以选择火山数据库。以下是两者的主要区别：

对比维度	扣子数据库	火山数据库
产品定位	扣子官方数据库，适合轻量数据存储与分析场景。	火山引擎提供的企业级数据库服务，支持处理与分析大规模、复杂的数据，适合于企业客户场景。
性能与扩展性	轻量级数据存储与分析操作。	高性能、高可用，支持海量数据存储和高效读写操作；可根据业务增长灵活扩展。
数据隔离	线上数据和测试数据隔离。各个发布渠道数据隔离。	仅存储线上数据，无测试数据。各个发布渠道数据互通，无隔离。
操作难度	操作流程简单便捷，用户可以轻松上手。	配置相对复杂、繁琐。

在这里我们使用扣子数据库。对于使用coze大部分场景来讲，扣子数据库足够应对。

1.1 设置表结构¶

创建数据库表以后，选择单用户模式（默认选项），这里需要注意：

单用户模式：开发者和用户都可以添加记录，但仅能读/修改/删除自己创建的来自同渠道的数据。
多用户模式：开发者和用户都可读/写/修改/删除表中来自同渠道的任何数据，由业务逻辑控制读写权限。

新建一个数据表，结构如下图：

这里需要注意：id、sys_platform、uuid、bstudio_create_time 字段为系统内置。work_code、name、performance_level 字段为我们这个案例中所使用的字段，分别代表工号、人名、绩效等级。

点击保存按钮，就完成表的创建。

1.2 导入数据¶

有了表结构以后，接下来我们导入数据。在测试数据中，点击批量导入，并把我们的素材 04-绩效数据.xlsx 文件上传。这里需要注意，数据库分测试数据和线上数据两个环境，这两个环境相互隔离：

测试数据：用于在发布之前调试使用，和线上数据互相不影响
线上数据：发布后，从应用商店、api等各种渠道调用时使用。和测试数据相互隔离

配置表结构，表头选择第1行、数据起始行选择第2行

对应原文件：

预览数据，无误后点击下一步即可。

确认数据已经完全写入：

2 在工作流中使用数据库¶

接下来，我们新建工作流，然后新建一个意图识别节点，如下图：

分为以下几个意图：

查询数据
查询某个人的绩效数据
新增数据
新增某个人的绩效数据
更新数据
更新某个人的绩效数据
删除数据
删除某个人的绩效数据

整体业务流程如下图：

2.1 使用LLM提取命名实体¶

在实现增删改查数据之前，我们需要先研究一下数据库节点的特性，首先数据库节点分为增删改查和自定义SQL5种类型。因为我们还没有学过SQL，所以这种使用方法我们先不关注，大家知道支持这种用法即可。

查看更新数据节点，如下图，在这里我们可以发现一个问题，我们查询数据需要根据：字段名 = 某个值，这种方式去实现查询数据。但是实际用户和agent交互时往往说的是自然语言，比如：

用户输入：帮我查一下张三的绩效是多少

或者：帮我查一下绩效，张三的

这里就会涉及到一个问题，帮我查一下张三的绩效是多少 -> name = '张三' 这一步怎么转化，也就是说，我们需要把“帮我查一下张三的绩效是多少”这句话以及相同语义不同表达方式的语句中的人名提取出来。这一步如何完成？

这种场景在生活中其实非常常见，比如我们在快递程序中输入一串人名、地址、手机号的一段话，点击智能识别，快递程序就可以帮助我们把这些“实体”进行解析，并填到对应的表格中。这里就涉及到了一种自然语言处理算法中常见的方法，叫做“命名实体识别”，也可以叫做“实体提取”，这里我们了解就行，后续会有其他课程进行深入讲解。

在这里，我们可以使用大模型的能力实现这个功能。比如我们要从用户输入的input中提取人名，执行以下两步：

编写提示词：说明要抽取人名实体，当返回结果只有一个字段时，不需要指定变量名；多个字段时，需要说明哪个实体对应哪个变量名。
指定输出：在输出的变量中，指定变量名

单独试运行该节点，结果如下：

2.2 查询数据¶

查询某个人的绩效数据，需要添加一个人名提取节点，和一个数据库查询节点，这两个节点和上个知识点中的是一致的，不做赘述。为了结果可读性更好，还需增加一个结果整理的节点，整体如下图：

结果整理提示词：

查询结果整理助手，能够根据用输入的问题和数据库中查询到的结果进行整合，并给到用户一个专业、得体的答复。

输入提示词

查询王大锤的绩效

试运行后，结果如下：

2.3 新增数据¶

对于新增数据，我们需要把用户输入的内容中人名、工号、绩效3个字段全部提取出来，然后再通过新增数据节点，把数据更新到数据库中。整体流程如下

如果我们要通过LLM同时提取多个实体，则需要这样操作：

对应的提示词如下：

你是一个人人名提取助手，能够根据用户输入的内容，提取出来里面的人名{name}、工号{work_code}、绩效{performance_level}，以json格式返回

设置新增数据节点中的变量，把3个字段需要新增的值填入

输入以下内容，试运行流水线：

新增绩效记录， 老邢，工号1050，绩效S

去数据库中查看数据是否成功写入：

2.4 更新数据¶

更新数据和新增数据流程类似，区别在于更新数据需要先根据更新条件找到对应的数据，再更新这条数据中的内容。

试运行该工作流，输入提示词

更新绩效记录， 老邢，工号1050，绩效A

查看数据库中的数据，可以看到数据没有新增，而绩效字段确实是由S改为了A，说明了功能生效。

2.5 删除数据¶

删除数据只需要删除条件定位到这条数据，即可完成。对于我们当前的业务场景，一般是工号+人名确定唯一一条数据，所以这里我们需要提取出来name和work_code两个字段，并形成过滤条件，