背景前搖&原視頻教程：

最近看到很多同學都在用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。
具體數據寫個幾排意思一下就好。

如果不想自己編，可以直接復制我用的數據：

title	author	purchase_price	description
活著	余華	35	我只想活著
哈利·波特系列	J.K.羅琳	299	魔法世界
小王子	安托萬·德·圣埃克蘇佩里	25	童話故事
1984	喬治·奧威爾	45	反烏托邦小說

新建數據庫：

準備好數據以后，我們需要去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:# 文檔地址urlurl = args.input.file_link# 數據庫表名database_table = args.input.database_table# 數據庫表字段名（注意：文檔的表頭名字必須與數據庫表字段名相同）database_table_list = args.input.database_table_listresponse = 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()方法逐行遍歷DataFramefor 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.paramsarray = 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專業版？？）

完整對話：