【AI学习笔记】Coze平台实现将Excel文档批量导入数据库全过程

背景前摇&原视频教程：

最近看到很多同学都在用Coze平台操作数据，我也想了解一下工作流的搭建和数据处理过程，但是一下子又看不懂太复杂的逻辑，于是上B站搜索相关的基础教程。

Coze官方教程：

之前有看过Coze平台的官方教程：传送门
https://www.bilibili.com/video/BV1zC35eFEyN?spm_id_from=333.788.videopod.sections&vd_source=cdfd0a0810bcc0bcdbcf373dafdf6a82

但是这个教程稍微有些太基础了，学完以后面对真实数据处理场景还是一脸懵逼。而且实操案例的那一p视频顺序有些乱，跟不上思路。
但如果是完全零基础的小白，建议还是先看看官方教程的视频和文档，对Coze的一些诸如创建智能体、各类节点是做什么的有一个基础了解。

@包子AI实验室 的教程：

我换了搜索关键词，在B站上搜“Coze数据处理”相关的视频，然后发现一个还不错的视频专栏——来自@包子AI实验室 的实操系列视频。

本文写作目的：

因为我最常见的用法就是通过Coze操作Excel数据表，所以我最先看的就是《【Coze 功能全解】工作流之“Excel 文档批量导入数据库”》这一篇，然后自己实操了整个流程。
在模仿学习的过程中，作为经验几乎为0的小白，我发现我还是遇到了很多疑难卡点，因此决定把原视频中省略的一些细节，以及我解决问题的一些参考资料记录下来。

正文：

数据准备：

首先我们需要准备一个Excel表格，这个表格的名字跟着作者起名“书籍列表_测试.xlsx”即可（其实这个名称不重要，随便叫啥都行）。如果能要到下图这个原作者的Excel文件更省心，我这里就自己随便照着视频截图写了几行数据。

这个书籍列表里需要有四个字段，并且字段名要严格一致：title,author,purchase_price,description。
具体数据写个几排意思一下就好。

如果不想自己编，可以直接复制我用的数据：

新建数据库：

准备好数据以后，我们需要去Coze平台新建一个名为book_list的数据库。
1.可以通过工作空间——资源库——右上角新建——数据库来新建数据库。

2.也可以在Agent智能体页面点击+号，弹出的页面支持添加已有现成的数据库，也支持新建数据库。

如果要新建数据库的话，步骤是：点击”新建数据库“——自定义数据表，然后建立一个新数据库。

输入数据库信息：

进入新建数据库页面以后，就需要输入数据库的名称和描述，这里我们就按照原作者的来，数据表头像这个无所谓，可以用默认的，也可以点击旁边的按钮让AI重新生成一个：

我们一共需要4个字段，按照原作者这样填写就可以，注意，这几个自定义字段的名称，author,title,puchase_price,description，一定要和Excel文件的列名完全一样！不然可能导致数据无法正确对应，后续编写插件的时候，代码无法正常运行。


假设我们初学就简单点，按照完全对应关系来建立数据库，字段就按照下图原作者的抄成一模一样的：

创建完成后，应该这个数据表会长得跟我这张截图一样：
（关于上面的默认字段，我想应该是版本差异问题？看原作者的数据表里面没有那4个删不掉的默认字段）

创建Bot：

我们创建一个名为”批量导入数据库数据“的Bot。

智能体如何与数据库交互：

原作者提供了两种思路。
1.把文件发给智能体。配合提示词（打字对话），跟智能体说，把这个文件的内容插入到数据库。
但原作者发现这个方法行不通，经过我测试，确实也不行。

2.通过拼接SQL来实现数据库增删改查，也就是我们现在采用的这套工作流的思想。
获取用户上传的Excel文档地址——》读取文档内容——》拼接成SQL语句——》数据库节点执行SQL实现添加数据。
原作者本来想直接使用Coze的代码节点来实现读取文件链接，并且读取文档内容形成SQL的方法，但是发现代码节点不支持安装Python包。
（读取文件链接需要pandas等依赖包，但是代码节点装不了，就没法解析Excel）

于是，只能先创建一个插件，插件就支持安装读取Excel链接必要的Python依赖包，先在插件实现了读取文件链接拼接SQL的功能，然后再在工作流里面调用插件，把SQL写入数据库，最后再把这个工作流给智能体，并且配合提示词，让智能体知道，每次我们给他发个文件链接，就是希望用到这个工作流。

实现流程示意图：

我按照自己的理解画了一张示意图，这里面有一些陌生的工作流和插件的名字，没关系，我们后面会一一讲到他们是什么。

实现读取文件链接功能的插件：

官方插件的尝试和不足：

在新建插件以前，作者先尝试了一个名为“文件读取”的官方插件，这个本来读取文件链接没有什么问题，但是在对文件内容进行处理时，作者提到，“只能通过大模型来输出SQL，这样便对文档的长度做出了限制。倘若文档过长，便会导致输出内容不完整。”

“只能通过大模型来输出SQL”——这一点我也不是很明白是什么意思，也许是这个文件读取节点返回的数据很有限，只能喂给大模型节点，配合提示词来依赖大模型生成SQL？也就是说，这个SQL能不能把数据完好无损地插入数据表，全靠大模型自身对数据的理解和整合SQL的能力？？？如果模型不靠谱，那么就可能导致插入失败，或者漏数据，数据错位？？
“这样便对文档的长度做出了限制。倘若文档过长，便会导致输出内容不完整”——这个我猜测是不是大模型的输出有token限制？如果要插入的数据很多的话，SQL语句会很长，超出限制了模型没法写完，自然插入就会少内容。

我打开这个文件读取的示例，手动连了下工作流测试，看看输入输出。我们就看下图上面那个红框内的输出就好，下面的红框是正式工作流，后面会讲到。

在看工作流的结果之前，先点开节点看看示例输入输出：

文件读取这个节点的输入就是一个普通的url，没什么操作空间：

{
  "url": "https://lf-bot-studio-plugin-resource.coze.cn/obj/bot-studio-platform-plugin-tos/lyc_test.docx"
}

文件读取节点的输出

{
  "code": 0,
  "data": "## 4.1角色游戏中小班幼儿同伴互动主要类型的分析\n\n表2 幼儿角色游戏同伴互动分布表\n\n|      互动类型 |           次数|            百分比||\n|---|---|---|---|\n|        合作|             46|            42.6% ||\n|        冲突|             37|           34.3% ||\n|        协商|             25|           23.1% ||\n\n\n\n通过观察，发现小班幼儿角色游戏同伴互动的类型中，合作、冲突和协商出现的频率最高，所以将这三个维度作为研究的重点。由表2可知，幼儿的合作行为最多，共46次，占42.6% ；冲突行为其次，共37次，占34.3% ，协商行为最少，共25次，占23.1% 。\n\n### 4.1.1 合作行为最多\n\n案例1：我们一起烤串吧\n\n      ![img](福\n-\n♠)\n\n                   图1 我们一起烤串吧场景图\n\n希希一个人在摆摊烤串，依依看到之后走了过来说：“我们一起烤串可以吗希希？”希希说:“好啊，我们一起烤。”不一会儿，烧烤摊旁边的小朋友越来越多，他们一起围在桌子旁边做起了烧烤。但是烤炉只有一个，好几个小朋友都抢着要烤串。老师走过来对他们说：“烧烤店是不是要有收银员和客人呀？”于是幼儿们开始合作开烧烤店，有的幼儿负责烤，有的负责卖，有的幼儿当顾客，他们在一起玩的非常开心。\n\n\n\n",
  "log_id": "20241227172728FE828D29AFD8C77811CD",
  "msg": "success"
}

这是一个json对象，我们需要的文件数据就在“data”字段对应的值里面。
然后我再看了下我刚刚尝试读取的Excel结果，发现翻车了…

这就很搞人心态了，因为我还专门加了个大模型节点上去，并且班门弄斧了一段提示词，想看看大模型拼接SQL的水平，没想到创业未半而中道崩殂。
（我先看看能否跑通工作流，所以提示词写的很随意，建议不要照抄我的，现在有个观点是用AI就像拜神，祈祷词——也就是提需求的提示词不说明白，神满足不了愿望，所以我这个祈祷词绝对会很loser）

但是看我们下面那条链路，也就是原作者最终采用的工作流，就十分顺畅地走到了结束，我们还是把重点放在正确的事情上吧。

新建自定义插件“read_excels"：

还是点击工作空间——资源库——右上角“资源”按钮——选择“插件”选项。




进入插件页面，点击“创建工具”，还是照样输入工具名称，说明等信息。

插件read_excels详细配置：

点击“+”号安装依赖包。

然后在中间区域粘贴实现功能的代码。
代码是原作者写的，我加了点AI解读的注释，详细功能如果逻辑看不明白，转AI问答。

输入是文件链接，数据表名称，和数据表头字段列表（也就是title，author，purchase_price，description这几个），如果程序执行成功，输出拼接好的SQL，如果程序执行失败，输出报错和网址状态码。

from runtime import Args
from typings.read_excels.read_excels import Input, Output
import requests
import io
import pandas as pd

"""
Each file needs to export a function named `handler`. This function is the entrance to the Tool.

Parameters:
args: parameters of the entry function.
args.input - input parameters, you can get test input value by args.input.xxx.
args.logger - logger instance used to print logs, injected by runtime.

Remember to fill in input/output in Metadata, it helps LLM to recognize and use tool.
每个文件都需要导出一个名为handler的函数。这个函数是工具的入口。
参数：
args：入口函数的参数。
args.input：输入参数，可以通过args.input.xxx获取测试输入值。
args.logger：用于打印日志的日志实例，由运行时注入。
请记得在元数据中填写输入和输出信息，这有助于大型语言模型（LLM）识别和使用该工具。

Return:
The return data of the function, which should match the declared output parameters.
"""
def handler(args: Args[Input])->Output:
    # 文档地址url
    url = args.input.file_link
    # 数据库表名
    database_table = args.input.database_table
    # 数据库表字段名（注意：文档的表头名字必须与数据库表字段名相同）
    database_table_list = args.input.database_table_list

    response = requests.get(url)
    values_list = []
    s = ""
    m = ""
    if response.status_code == 200:
        df = pd.read_excel(io.BytesIO(response.content))
        for index, row in df.iloc[0:].iterrows(): #使用df.iloc[0:]选择DataFrame中的所有行 使用iterrows()方法逐行遍历DataFrame
            for i in database_table_list: #遍历database_table_list中的每个字段名
                s = f"{s}'{row[i]}'," #使用row[i]获取当前行中对应字段的值 将每个值用单引号括起来，并用逗号分隔，拼接到字符串s中
            values_list.append(f"({s[:-1]})") #每行数据拼接完成后，去掉最后一个多余的逗号（s[:-1]），然后将整个行的值部分以括号包裹的形式添加到values_list中
            s = "" #清空字符串s，以便下一次循环使用。
        for i in database_table_list: #遍历database_table_list中的每个字段名
            m = f"{m}{i}," #将每个字段名用逗号分隔，拼接到字符串m中
        
        #使用f-string格式化字符串，构建完整的SQL INSERT语句
        '''
        INSERT INTO {database_table}：插入目标数据库表。
        ({m[:-1]})：字段名部分，去掉最后一个多余的逗号。
        VALUES {', '.join(values_list)}：值部分，将values_list中的每个值部分用逗号分隔。
        '''
        content = f"INSERT INTO {database_table} ({m[:-1]}) VALUES {', '.join(values_list)};"
    else:
        content = f"无法从网址获取文件，状态码:{response.status_code}"

    return {"output": content}

代码部分后，在右侧区域输入一个json对象格式的测试用例，点击“运行”查看测试结果。

注意：每次修改插件，必须要有至少一个测试用例跑过测试流程，不然可能导致插件无法发布，如下图。

插件配置的坑：

关于这个插件配置的过程中，有几个我翻车的坑，在这里给大家同步下：

pandas依赖包导入报错：

pandas依赖包明明版本正确，也没有写错名字，但是就是底下标红线，还没有解决办法，删了重新写这行还有一样的问题。

查了原作者教程视频评论区，这个疑似是Coze的老bug了，刷新重开插件即可。

输入测试用例怎么写：

原作者的是视频没提到这一点，应该是想到视频受众都有相关基础。
这个输入需要写成Json对象的格式，其中包含了三个键值对：
file_link：文件的 URL 地址。
database_table：数据库表名。
database_table_list：数据库表的字段名列表。

{
  "file_link": "https://p9-bot-sign.byteimg.com/tos-cn-i-v4nquku3lp/d8c93855ce474d0fad4e375b7aad65c9.xlsx~tplv-v4nquku3lp-image.image?rk3s=68e6b6b5&x-expires=1745072334&x-signature=xfT9Gdp8FB%2Bjkd3neNpY5%2FZa0QI%3D",
  "database_table": "book_list",
  "database_table_list": ["title", "author", "purchase_price", "description"]
}

这个database的名字要写对，不是Excel文件名，是数据库的名字。

输入的这个file_link文件链接如何获取：

输入有三个参数，file_link：文件的 URL 地址，database_table：数据库表名，database_table_list：数据库表的字段名列表。

database_table需要输入数据库的名称，也就是我们定义的book_list。

"database_table": "book_list"

database_table_list需要跟我们Excel文件当中的列名完全一致。

"database_table_list": ["title", "author", "purchase_price", "description"]

那么，file_link，文件链接，应该从哪里来呢？
我试过传到飞书的个人云文档，但是发现获取失败。

教程评论区有人问到这个问题，原作者回复最好直接传到Coze服务器。

那么，如何把Excel文件（图片也可以）传给Coze平台，并且得到对应链接呢？

把文件发给智能体让他返回链接：

其实很简单，只需要随便创建个智能体，把文件/图片发给他，提示词写上需要他返回文件链接，就可以了。
例如：
给这个智能体发张屏幕截图，要求他返回链接。

再比如，给智能体发个Excel，然后请他返回文件链接：

当然，智能体的回复也有不稳定的时候，他找各种理由不愿意，没关系，改改提示词，多许几次愿。
（有句话说得好，重复是最好的催眠，这我感觉对于AI也适用）

在调试区域找文件链接：

另外，还可以按照原作者在评论区说的方法。

点开“调试”按钮，在智能体的思考过程中，找到这个文件或者图片的对应链接。

等调试页面出现后，向下滚动，即可找到模型传入的链接参数。

获取图片/文件链接的原理：

关于为什么可以通过以上两种方法获取图片/文件的链接，这就必须要搬出我搜到的另一个@大圣AI超级个体 的教程了：传送门
https://www.bilibili.com/video/BV18s421M78V/?spm_id_from=333.337.search-card.all.click&vd_source=cdfd0a0810bcc0bcdbcf373dafdf6a82

大概原理我摘抄过来了：

图片和文件在Coze中，都是被转换成链接处理的。也就是说，我们不用自己把图片上传到某个自已的图床，然后转换成链接给到扣子，扣子它本身就会把图片存到自己的服务器，然后转换成链接供后续使用。
所以，后面我们处理图像流也好，OCR工作流识别也好，都是用这个链接作为一个输入的——处理文件的时候，其本质是处理文件的链接。只要能把文件转成URL，剩下的就和文字处理是类似的了。

所以，即便是这位UP主演示的，这样什么提示词都没有的空白草台班子智能体。也是可以返回存储图片/文件的链接的。

搭建专门的“文件上传测试机器人”：

视频中还介绍了把这个功能专门包装成了一个智能体，名为“文件上传测试机器人”，只要跟着知道提示词写哪里，工作流怎么搭建就能跟着这个视频完成。
我在这只放出我跟着视频里面敲的提示词、工作流等关键要点截图，就不仔细详解该怎么搭这个返回链接用的智能体了。

人设与回复逻辑——提示词：

你是一个文件处理工具机器人。
### 处理文件
当用户上传文件时，你会返回该文件的url给用户。

### 处理图片
1.当用户上传一张图片时，你应该首先获取图片的链接。
2.然后将图片的链接作为参数调用工作流{image_ocr}
3.你应该使用将图片的地址作为入参'image_url'传递给工作流{image_ocr}

image_ocr工作流：
这个工作流的主要作用是接受图片链接，理解图片内容并输出。
我们就把下面这个截图的链接喂给智能体，然后把返回的链接传给工作流识别测试一下。


点击打开工作流，把图片链接给它，能看到更直观的节点运行过程：

开场白文案——非必须，可以根据发布时提供的AI自动生成文案修改：

嗨，我能处理各种文件和图片哦。你好呀！如果你想要获取文件的url，请把你的文件发给我吧，如果你发我的是图片，除了返回url，我还能解读图片内容噢~

如果还有不清楚的，建议辅助原视频学习搭建测试。

batch_import工作流搭建：

我们已经介绍完了read_excels插件中涉及到的代码，以及输入参数必须的图片链接该如何获取，现在让我们回到主线，搭建完整的Excel链接读取、SQL写数据库的工作流batch_import。
可以理解为，read_excels是一块拼图，batch_import工作流是一整块大图，有了read_excels才能完整实现功能。
之前为了测试官方的插件，我在原作者工作流的基础上加了一条和主流程互不干扰的测试链路，大家可以忽略上面那条线，只需按照原作者的工作流搭建下方的线路。

完整工作流：

怕大家不清楚，放出一张大家可以照抄的图：

详细解读：

第一个节“开始”节点接受读者传入的url，然后进入一个代码节点。

代码节点双击打开，点击”在IDE中编辑“——切换编程语言为Python，并且删除多余的变量，比如key，key2，“输出”那一栏按照现有逻辑，只需保留key1。

粘贴下列代码：

async def main(args: Args) -> Output:
    params = args.params
    array = params["input"].split(",")
    ret: Output = {
        "key1": array,
    }
    return ret

这段代码定义了一个异步函数 main，它的作用是接收一个输入字符串，将字符串按照逗号分隔成一个列表，然后将这个列表作为值，以键 “key1” 存储在一个字典中并返回。
在这里，input是一句话，里面是我们输入的四个book_list字段名，代码节点会帮我们分割成列表，并且给下一个节点。

接下来，代码节点即可链接我们之前做好的read_excels插件。
file_link是我们传入的文件url，database_table就是我们数据表的名字，book_list，database_table_list就是我们代码节点解析出的字段列表。

read_excels当中的代码会把我们传入的参数自动拼接成符合SQL语法的INSERT语句，并且将SQL语句传给下一个数据库自定义节点。
原作者的工作流这里数据库节点跟我名字不一样，其实就是双击节点名字改了下。

这里如果发现老代码报错SQL执行失败，但是传入的参数又都是正确无误的，建议看看是不是read_excels插件里面代码的问题。

content = f"INSERT INTO {database_table} ({m[:-1]}) VALUES {', '.join(values_list)};"

这句代码如果空格少了，比如写成f"INSERT INTO{database_table}，看着不影响什么，但是会导致SQL报错，就是这么邪门。

最后，链接结束节点，选择“返回文本”，（返回变量只能得到单纯变量的值，返回文本才可格式化输出其他信息），这里我们让结束节点输出我们成功插入的行数。

试运行工作流，如果无误的话，打开book_list数据库，会发现Excel中原有的4行数据已经插入成功了。

注意，目前没有去重功能，如果多次执行工作流，并且传入同一个文件链接，会导致数据库中有重复数据，不过可手动勾选删除。

智能体制作：

最后即可搭建一个智能体，将batch_import工作流加到智能体的“工作流”部分，book_list加到智能体的“数据表”部分，这样智能体在遇到符合这个工作流应用场景的需求的时候，就知道自己判断调用这个工作流了。（如果在人设和回复逻辑那里写一些提示词，效果会更好！）

快捷指令添加：

为了进一步简化调用这个功能的流程，可以给智能体加一个快捷指令。

输入按钮指令名称，类型，描述等，勾选“直接使用插件、工作流”，然后在弹窗中选择刚刚搭建好的batch_import工作流。

在“组件”栏写上组件名称，描述，并且把组件类型改为“上传文件”。

指令内容，我理解为一个简单的提示词。只要执行了这个快捷指令，相当于就是同时给模型发送了文件+这段预设好的指令。

到这里，智能体制作就完全结束了。

评论区提到的其他讨论问题：

最大数据量的限制：

这个问题我目前没遇到，看评论区讨论的内容，似乎扣子工作流对于运行时间超过一定限制的情况有超时处理？

在Coze官方文档中，也有关于超时限制的描述：传送门
https://www.coze.cn/open/docs/guides/workflow_limits

我把原始数据文件复制粘贴到了超过200行，然后再喂智能体测试看看：
果然报错了。

看看调试部分。

果然是插件工具调用这里就开始报错：

把错误给KIMI解读一下：

关于评论区这位大神提到的异步运行的方法，我在扣子官方文档传送门里面查了下，但是似乎只有扣子专业版用户才能使用异步。

https://www.coze.cn/open/docs/developer_guides/workflow_run?from=search

异步这块我也不是很了解，看了一下扣子官方文档的《查询工作流异步执行结果》部分传送门，好像之前看到别的同学的代码似乎有跟这部分相似的内容，我还正好没太读懂这部分，或许可以结合今天发现的官方文档内容辅助理解。
对于这篇文章，就先不涉及异步的探索内容了，如果有突破性进展，也许会再写一篇学习笔记记录。

扣子平台官方文档关于开启异步工作流的方法：https://www.coze.cn/open/docs/guides/use_workflow
传送门
打开链接后向下滚动网页：

按照官方文档，我尝试把batch_import节点开启异步：


然后再把那个200多行的文件喂给模型，确实是返回了异步执行的回复内容。
这个时候再跟智能体聊别的跟读取文件无关的内容，他也能响应。

但依旧没有读取成功，报异常System exception, please try again later（我想应该就是我没开通要氪金的Coze专业版？？）

完整对话：