第13章 Coze进阶:插件开发、工作流深度编排与知识库优化
AI智能体实战训练营 · 章节 13/33 · 45 学时
Coze进阶:插件开发、工作流深度编排与知识库优化
上一章我们学习了Coze的基础操作,搭建了第一个智能体。本章将深入Coze的进阶功能——自定义插件开发、工作流深度编排、知识库优化技巧、多智能体协作、数据库使用等。掌握这些进阶功能,你才能真正发挥Coze的强大能力,构建复杂的企业级智能体应用。
• 基础功能的局限:内置插件和简单配置只能满足简单需求,复杂业务场景需要自定义插件和工作流
• 效果提升:知识库优化、工作流编排能显著提升智能体的回答质量和任务完成率
• 企业级应用:数据库、多智能体、API集成是构建企业级应用的必备能力
• 差异化竞争:只会基础操作的人很多,掌握进阶功能才能做出有竞争力的智能体
一、自定义插件开发
Coze内置了大量现成插件,但有时候你需要的功能内置插件没有——比如调用企业内部的API、对接特定的业务系统、实现自定义的计算逻辑。这时候就需要开发自定义插件。
1.1 插件的本质
Coze的插件本质上是一个REST API的封装。你定义一个API的地址、请求方法、参数格式,Coze就会把它封装成一个插件,大模型可以像调用内置插件一样调用它。
所以,开发自定义插件的前提是:你有一个可以访问的API接口(可以是企业内部的API、第三方服务的API、或者你自己开发的API)。
1.2 插件开发步骤
- 进入插件开发页面:在Coze工作台,点击"插件"→"创建插件",选择"自定义插件"
- 填写插件基本信息:
- 插件名称:清晰描述功能,如"查询设备维修记录"
- 插件描述:详细说明功能、适用场景、返回结果,这是大模型判断是否调用的依据
- 图标:选择或上传插件图标
- 配置API信息:
- 请求URL:API的完整地址
- 请求方法:GET/POST/PUT/DELETE
- 认证方式:如果API需要认证,配置API Key、Bearer Token等
- 请求头:需要的Header参数
- 定义输入参数:
- 参数名称:英文,如device_id、start_date
- 参数类型:string/integer/number/boolean/array/object
- 是否必填:是/否
- 参数描述:清晰说明参数含义、格式、取值范围
- 默认值:可选参数的默认值
- 定义输出参数:
- 定义API返回的数据结构,方便大模型理解和使用
- 可以用JSON Schema定义,也可以导入示例响应自动生成
- 测试插件:
- 输入测试参数,点击"测试",查看API返回结果
- 检查返回结果是否符合预期,参数是否正确
- 保存并发布:测试通过后,保存插件,就可以在智能体中添加使用了
1.3 插件开发最佳实践
- 插件描述要详细:大模型是根据插件描述来判断是否调用的。描述要包含:功能是什么、什么时候用、返回什么、和其他类似插件的区别。
- 参数描述要清晰:每个参数都要有清晰的描述,包括含义、格式、示例。比如日期参数要说明格式是"YYYY-MM-DD"。
- 单一职责:一个插件只做一件事。不要把多个API塞进一个插件,拆分成多个单一职责的插件。
- 错误处理友好:API返回错误时,要返回清晰的错误信息,让大模型知道哪里错了、该怎么修正。
- 结果结构化:API返回JSON格式的结构化数据,不要返回纯文本。结构化数据更容易被大模型理解。
- 安全考虑:不要在插件中硬编码敏感信息(如密码、密钥),用Coze的变量或认证配置管理。
1.4 实战:开发一个"设备维修记录查询"插件
假设企业有一个设备管理系统的API,可以查询设备的历史维修记录。我们来把它封装成Coze插件。
API信息:
- URL:https://api.example.com/v1/equipment/maintenance-records
- 方法:GET
- 认证:Bearer Token
- 参数:
- device_id (string, 必填):设备编号
- start_date (string, 可选):开始日期,格式YYYY-MM-DD
- end_date (string, 可选):结束日期,格式YYYY-MM-DD
- limit (integer, 可选):返回记录数,默认10,最大50
插件配置:
- 名称:查询设备维修记录
- 描述:根据设备编号查询该设备的历史维修记录,包含维修时间、故障描述、维修措施、维修人员、维修费用。当用户询问"某设备的维修历史"、"之前修过什么问题"、"维修记录"时使用。
- 参数配置:按上述API参数配置,每个参数添加清晰的描述
- 输出:定义返回的JSON结构(records数组,每条包含date、fault、solution、engineer、cost)
在智能体中使用:
添加这个插件后,智能体就可以在用户询问设备维修历史时,自动调用API查询真实数据,而不是靠记忆编造。这大大提升了回答的准确性和实用性。
二、工作流深度编排
工作流是Coze中最强大的功能之一。上一章我们简单提到了工作流,本章将深入学习如何用工作流编排复杂的多步骤任务。
2.1 什么时候用工作流?
不是所有任务都需要工作流。以下场景适合用工作流:
- 多步骤任务:任务需要多个步骤按顺序完成,每步的输出是下一步的输入
- 固定流程:任务的流程是固定的、标准化的,不需要大模型自主决定步骤
- 需要精确控制:需要精确控制每一步的输入输出、格式、逻辑,不能让大模型自由发挥
- 多工具串联:需要调用多个工具/API,按特定顺序执行
- 条件分支:需要根据不同条件走不同的处理路径
不适合用工作流的场景:开放式的问答、需要灵活应对的对话、流程不固定的任务。这些场景用普通的智能体(带插件)更合适。
2.2 工作流的核心节点类型
| 节点类型 | 功能 | 典型应用 |
|---|---|---|
| 开始(Start) | 工作流的入口,定义输入参数 | 每个工作流都有一个开始节点 |
| 大模型(LLM) | 调用大模型进行文本生成、分析、推理 | 写报告、分析数据、生成回复、分类判断 |
| 插件(Plugin) | 调用内置或自定义插件 | 搜索、API调用、计算、数据查询 |
| 知识库(Knowledge) | 从知识库中检索相关信息 | RAG检索、文档查询 |
| 条件判断(IF/ELSE) | 根据条件选择执行路径 | 如果是VIP走特殊流程,如果审核通过继续 |
| 代码(Code) | 执行自定义代码(Python/JavaScript) | 复杂数据处理、格式转换、计算逻辑 |
| 变量(Variable) | 设置或修改变量 | 存储中间结果、传递数据 |
| 循环(Loop) | 遍历数组,对每个元素执行子流程 | 批量处理多条数据、逐条分析 |
| 结束(End) | 工作流的出口,定义输出结果 | 返回最终结果 |
2.3 工作流设计实战:客户投诉自动处理流程
业务需求:自动处理客户投诉,包括分类、分析、生成回复、创建工单、通知相关人员。
工作流设计(8个节点):
节点1【开始】
- 输入参数:customer_name(客户名称)、complaint_text(投诉内容)、contact_info(联系方式)
节点2【投诉分类】(大模型节点)
- 输入:complaint_text
- 提示词:"请将以下客户投诉分类为:产品质量、服务态度、物流配送、价格问题、其他。只返回分类结��,不要解释。"
- 输出:category(分类结果)
节点3【条件判断】
- 条件:category == "产品质量" OR category == "服务态度"
- 如果是(高优先级)→ 走节点4a
- 如果否(普通优先级)→ 走节点4b
节点4a【紧急处理】(高优先级分支)
- 调用插件:发送企业微信消息通知客服主管
- 消息内容:"紧急投诉!客户{customer_name}投诉{category},内容:{complaint_text}"
节点4b【普通处理】(普通优先级分支)
- 调用插件:创建普通工单,分配给客服团队
节点5【知识库检索】
- 输入:complaint_text + category
- 从"客户服务知识库"中检索类似投诉的处理方案和回复模板
- 输出:similar_cases(类似案例)、reply_template(回复模板)
节点6【生成回复】(大模型节点)
- 输入:customer_name、complaint_text、category、similar_cases、reply_template
- 提示词:"你是一位专业的客服经理。请根据客户投诉内容、类似案例和回复模板,生成一封专业、诚恳、有解决方案的回复邮件。要求:1)先道歉并表达理解;2)说明问题原因;3)给出具体解决方案和时间承诺;4)感谢客户反馈。语气要真诚,不要模板化。"
- 输出:reply_content(回复内容)
节点7【代码节点】(数据整理)
- 输入:所有节点的输出
- 代码:用Python整理成结构化的工单数据
- 输出:ticket_data(JSON格式的完整工单数据)
节点8【结束】
- 输出:category(分类)、priority(优先级)、reply_content(回复内容)、ticket_id(工单编号)、notification_status(通知状态)
工作流亮点:
• 有条件分支(高优先级/普通优先级不同处理)
• 有知识库检索(基于历史案例生成回复)
• 有大模型节点(分类、生成回复)
• 有插件调用(通知、创建工单)
• 有代码节点(数据整理)
• 输入输出清晰,可追溯
2.4 工作流调试技巧
- 单节点测试:每个节点都可以单独测试,输入测试数据,查看输出是否正确。先确保每个节点都正确,再连起来测试。
- 逐步运行:用"逐步运行"功能,一步一步执行,查看每个节点的输入输出,定位问题出在哪一步。
- 检查变量传递:最常见的问题是变量传递错误——节点A的输出字段名和节点B的输入字段名不匹配。仔细检查每个节点的输入引用是否正确。
- 大模型节点加约束:大模型节点的输出格式不稳定时,在提示词中明确要求输出格式(如"只返回JSON,不要其他文字"),或用代码节点做格式校验和修正。
- 异常处理:对可能失败的节点(如API调用),设置失败后的处理逻辑(重试、默认值、走异常分支)。
- 日志记录:工作流运行后可以查看完整的执行日志,包括每个节点的输入输出、执行时间、是否成功。用日志来定位问题。
三、知识库优化技巧
知识库(RAG)的效果直接影响智能体的回答质量。很多人用不好RAG,不是因为技术不行,而是因为知识库没有优化好。以下是经过实践验证的知识库优化技巧。
3.1 文档预处理优化
- 格式统一:尽量用PDF或Markdown格式,避免用扫描件(OCR效果差)。如果是扫描件,先做OCR并校对。
- 内容清洗:去除页眉页脚、目录、页码、广告、重复内容。这些无关内容会干扰检索。
- 结构清晰:保留文档的标题层级(H1/H2/H3)。结构化的文档更容易被正确分段和检索。
- 内容完整:确保文档内容完整,不要有缺失的章节或模糊的表述。不完整的文档会导致检索到的信息不完整。
- 命名规范:文件名要能反映内容(如"空压机维修手册_V2.0.pdf"比"文档1.pdf"好)。文件名也会被索引,影响检索。
3.2 分段策略优化
- 分段大小:一般建议256-512个token(约500-1000中文字符)。太小上下文不完整,太大包含无关信息。可以根据文档类型调整——技术文档可以小一点(300-500),故事性文档可以大一点(500-800)。
- 重叠(Overlap):相邻分段之间保留10-20%的重叠,避免关键信息被切断。比如分段大小500,重叠设50-100。
- 按结构分段:如果文档有清晰的标题结构,优先按标题分段(每个小节一个分段),而不是固定大小分段。这样每个分段的语义更完整。
- 避免切断:不要在一个完整的句子、表格、列表中间切断。分段边界应该在段落之间、标题之后等自然断点。
- 元数据标注:为每个分段添加元数据(如文档名称、章节标题、设备类型、发布日期),可以基于元数据过滤检索,提高准确性。
3.3 检索策略优化
- 混合检索:同时使用语义检索(向量相似度)和关键词检索(BM25),合并结果。语义检索能理解同义词和改写,关键词检索能精确匹配专有名词、型号、编号。两者结合效果最好。
- 召回数量:先召回较多的结果(如10-20条),再用重排序(Rerank)模型精选出Top 3-5条。直接召回3-5条可能漏掉相关结果。
- 相似度阈值:设置合理的最低相似度阈值(如0.5-0.7),过滤掉不相关的结果。阈值太高可能漏掉相关结果,太低会引入噪声。
- 查询改写:在检索前,先用大模型把用户的问题改写成更适合检索的查询(如扩展关键词、修正错别字、补充上下文)。特别是多轮对话中,要结合上下文改写问题。
- 多路召回:对同一个问题,用不同的查询方式(原问题、改写问题、关键词提取)分别检索,合并去重后再排序。
3.4 提示词优化
- 明确约束:在提示词中明确要求"必须基于检索到的参考资料回答,不要使用参考资料以外的知识。如果参考资料中没有相关信息,请明确说明。"
- 标注来源:要求回答中标注信息来源(如"根据《维修手册》第3章"),这样可以验证回答的准确性,也让用户更信任。
- 引用格式:在提示词中给每个检索结果编号(如资料1、资料2),要求回答中引用编号。这样大模型更容易对应到具体的资料。
- 处理冲突:如果检索到的资料之间有矛盾,要求大模型说明冲突,并给出判断依据或建议人工核实。
- 信息不足处理:明确告诉大模型"如果检索到的信息不足以回答问题,不要编造,要说明缺少什么信息,并建议用户提供更多信息或查阅其他资料。"
3.5 知识库持续优化
- 用户反馈收集:在智能体的回答下方加"有用/没用"的反馈按钮,收集用户反馈。对"没用"的回答,分析是检索问题还是生成问题,针对性优化。
- bad case分析:定期查看对话记录,找出回答不好的案例,分析原因(检索不到、检索到但没用、生成错误、信息不足),逐一优化。
- 知识库更新:定期更新知识库内容,添加新的文档、更新过时的内容、删除无用的文档。知识库不是建一次就完事,需要持续维护。
- A/B测试:对分段策略、检索参数、提示词等进行A/B测试,用数据找到最优配置。
- 检索效果评估:准备一批测试问题和标准答案,定期评估检索准确率(召回率、精确率),监控效果变化。
四、多智能体协作
Coze支持多智能体协作——可以在一个工作流中调用多个智能体,也可以让智能体之间互相调用。这为构建复杂的团队协作系统提供了可能。
4.1 Coze多智能体的实现方式
- 工作流中调用智能体:在工作流中添加"智能体"节点,调用另一个已创建的智能体。这是最简单的多智能体协作方式——主智能体负责协调,子智能体负责具体任务。
- 智能体插件化:可以把一个智能体发布为插件,其他智能体可以像调用插件一样调用它。
- 多智能体对话:Coze的多智能体功能支持多个智能体在一个对话中轮流发言,模拟团队讨论。可以设置每个智能体的角色、发言顺序、终止条件。
4.2 多智能体实战:市场研究团队
团队组成(4个智能体):
1. 项目经理:负责拆解任务、协调进度、汇总最终报告
2. 市场研究员:负责搜索市场信息、分析市场规模和趋势
3. 竞品分析师:负责分析竞争对手的产品、定价、策略
4. 数据分析师:负责整理数据、生成图表、做统计分析
协作方式(工作流编排):
1. 项目经理接收研究主题,拆解成3个子任务(市场分析、竞品分析、数据分析)
2. 并行调用3个智能体(市场研究员、竞品分析师、数据分析师),同时开始工作
3. 3个智能体分别完成各自的分析报告,提交给项目经理
4. 项目经理汇总3份报告,整理成完整的市场研究报告
5. 项目经理做最终审核,确保逻辑一致、数据准确
实现要点:
• 每个智能体有明确的角色和职责,提示词中详细定义
• 用工作流的并行分支实现3个智能体同时工作
• 每个智能体的输出有固定的格式,方便汇总
• 项目经理有汇总和审核的提示词,确保最终报告质量
五、数据库(Database)的使用
Coze内置了轻量级数据库功能,可以让智能体存储和查询结构化数据。这对于需要持久化存储的场景(如用户信息、业务记录、配置数据)非常有用。
5.1 数据库的适用场景
- 用户数据存储:存储用户的基本信息、偏好、历史记录
- 业务数据记录:记录智能体处理的业务数据(如工单、订单、预约)
- 配置数据管理:存储智能体的配置参数、规则、模板
- 简单的业务系统:用数据库+智能体+工作流,可以搭建简单的业务系统(如预约系统、工单系统、库存管理)
5.2 使用步骤
- 创建数据表:在Coze工作台的"数据库"功能中,创建数据表,定义字段(字段名、类型、是否必填、默认值)
- 配置数据库操作:在智能体或工作流中,可以添加数据库操作节点(查询、插入、更新、删除)
- 在智能体中使用:大模型可以根据用户需求自动判断要执行什么数据库操作(如用户说"帮我预约明天下午3点",智能体自动插入一条预约记录)
5.3 注意事项
- 数据量限制:Coze的内置数据库适合轻量级应用,数据量大或复杂查询建议用外部数据库+自定义插件
- 数据安全:不要在数据库中存储敏感信息(如密码、身份证号、银行卡号),或做好加密
- 权限控制:如果是多用户场景,要做好数据隔离,确保用户只能看到自己的数据
- 备份:重要数据要定期备份,避免误操作导致数据丢失
六、Coze进阶常见问题
| 问题 | 解决方案 |
|---|---|
| 自定义插件调用失败 | 检查API地址是否正确、认证是否配置、参数格式是否匹配、网络是否能访问(Coze服务器能否访问你的API) |
| 工作流变量传递错误 | 仔细检查每个节点的输入引用,确保字段名完全匹配(大小写敏感)。用"逐步运行"查看每个节点的实际输入输出 |
| 大模型节点输出格式不稳定 | 在提示词中明确要求输出格式(如"只返回JSON,不要其他文字"),给出格式示例,或用代码节点做格式校验和修正 |
| 知识库检索不到相关内容 | 检查文档是否解析成功、分段是否合理、改用混合检索、降低相似度阈值、增加召回数量、优化查询改写 |
| 智能体不调用插件/工作流 | 优化插件/工作流的描述(说明功能和适用场景)、减少插件数量(避免选择困难)、在提示词中明确说明什么时候应该调用 |
| 多智能体协作混乱 | 明确每个智能体的角色和职责边界、用工作流控制协作流程(而不是自由对话)、设置清晰的输入输出格式 |
| 响应速度慢 | 减少工作流节点数、优化大模型调用(用轻量模型做简单任务)、减少知识库文档量、并行执行没有依赖的节点 |
| 成本过高 | 优化提示词(减少不必要的长度)、用轻量模型做简单任务、减少大模型调用次数、缓存重复查询的结果 |
• 自定义插件本质是REST API的封装,开发步骤:创建→配置API→定义参数→测试→发布。插件描述和参数描述要清晰
• 工作流适合多步骤、固定流程、需要精确控制的任务。核心节点:开始/结束、大模型、插件、知识库、条件判断、代码、循环
• 工作流调试:单节点测试→逐步运行→检查变量传递→大模型加格式约束→异常处理→查看日志
• 知识库优化五维度:文档预处理(清洗、结构化)、分段策略(256-512 token、重叠10-20%、按结构分段)、检索策略(混合检索、多路召回、查询改写)、提示词(明确约束、标注来源、处理冲突)、持续优化(用户反馈、bad case分析、A/B测试)
• 多智能体协作:用工作流编排多个智能体,明确角色职责,并行执行,汇总审核
• 数据库:适合轻量级数据存储和简单业务系统,注意数据量限制、安全、权限、备份
下一章,我们将学习另一个重要的平台——Dify。Dify是开源可私有化部署的智能体平台,在企业级应用中应用广泛。我们将学习如何搭建和使用Dify,构建私有化部署的智能体应用。
📝 本章练习(5题)
答案与解析请在 互动学习看板 中作答查看。
📚 AI智能体实战训练营 课程目录(33 章)
- 第1章 什么是AI智能体:从聊天机器人到自主决策系统
- 第2章 智能体的四大核心能力:感知·思考·行动·记忆
- 第3章 范式转移:智能体与传统软件的本质区别
- 第4章 2025年主流智能体平台全景对比与选型
- 第5章 智能体应用场景地图:从个人效率到企业级落地
- 第6章 编排思维:如何把大模型变成可执行的业务流程
- 第7章 Prompt工程实战:写出让智能体精准执行的指令
- 第8章 工作流编排入门:节点、连线、条件分支与循环
- 第9章 知识库RAG实战:让智能体拥有你的专业数据
- 第10章 工具调用实战:搜索·计算·API·数据库全掌握
- 第11章 多智能体协作:角色分工、任务分发与结果汇总
- 第12章 Coze/扣子入门:30分钟搭建你的第一个智能体
- 第13章 Coze进阶:插件开发、工作流深度编排与知识库优化
- 第14章 Dify入门:开源可私有化部署的智能体平台搭建
- 第15章 Dify进阶:RAG管道优化、Agent模式与工作流编排
- 第16章 LangChain入门:用代码构建可定制的智能体应用
- 第17章 LangChain实战:自定义Agent、工具链与记忆系统
- 第18章 Agent Harness与新一代框架:2025年智能体开发趋势
- 第19章 平台选型决策树:不同业务场景下的最优平台选择
- 第20章 任务拆解方法论:把复杂问题变成智能体可执行的步骤
- 第21章 提示词编排艺术:System·User·Function的三层协同
- 第22章 记忆系统设计:短期记忆、长期记忆与向量数据库选型
- 第23章 错误处理与容错:智能体执行失败时的兜底策略
- 第24章 评估与优化体系:如何量化衡量智能体的效果并持续改进
- 第25章 安全与合规:智能体应用的数据安全、隐私保护与风险防控
- 第26章 实战项目一:企业知识库智能问答助手(全流程实操)
- 第27章 实战项目二:制造业设备故障诊断智能体
- 第28章 实战项目三:供应链采购智能分析与比价助手
- 第29章 实战项目四:多智能体协同的项目管理办公室(PMO)
- 第30章 实战项目五:智能体与MES/ERP系统的深度集成
- 第31章 智能体落地路线图:从POC验证到规模化应用的完整路径
- 第32章 AI智能体工程师/产品经理的能力模型与成长路径
- 第33章 作品集打造与面试准备:如何拿到AI智能体岗位Offer
