简介这是一份面向AI初学者的扣子Coze智能体快速部署源码包帮助用户在没有编程基础的情况下完成从智能体创建、角色设定、技能配置到插件扩展与多平台发布的完整流程。资源以陪伴机器人为示例重点演示话题引导、情绪共鸣、创意互动等配置方法并展示如何通过必应搜索插件扩展信息检索能力。包内包含3个文件涵盖inscode可运行工程、HTML页面文件及gitignore配置文件整体压缩包仅7KB结构精简便于零门槛上手并直接运行调试。目前已有239人学习使用适合希望快速理解扣子平台核心操作、动手实践智能体部署的开发者。通过这份源码包读者可对照代码理解每个配置环节的实现方式并基于示例快速改造出属于自己的智能体省去从零搭建环境的摸索时间。1. 扣子智能体部署3 分钟跑通云端真正要落地的是本地运行时扣子智能体部署这个标题藏着两类完全不同的诉求一类人刚注册完扣子控制台想知道怎么把 Bot 跑起来、拿到可用的对话服务和源码另一类人已经把手伸到生产环境想把扣子智能体弄到自己服务器上用本地模型接管对话摆脱平台限制和按量计费。先给个反直觉结论扣子智能体本身根本不用你部署云端的 Bot 点一下发布就上线了真正要部署的是你的运行时、你的调用层、你的模型底座。3 分钟能做的是跑通云端最小闭环而想让一份可运行源码实实在在落在自己手里后面还有 Docker、模型接入、工具编排这些硬骨头。这篇文章就把从「云端点几下」到「本地跑起来」的整条路拆开讲每步都能直接抄。2. 拆解扣子智能体四层装配架构与「可运行源码」的三种含义2.1 智能体不是一个程序是四层组件的装配扣子智能体从架构上看是一个典型的四层装配体不理解这四层后面看源码和部署文档会一头雾水。最上层是编排层对应的是工作流画布和 Agent 节点负责决定用户的问题进来之后先走哪个分支、调用哪个工具、哪一步该让大模型生成第二层是运行时层负责对话状态管理、记忆、多轮上下文维护和工具调用的调度逻辑第三层是模型层包括主对话用的大模型和做知识库检索用的 Embedding 模型最底层是工具层涵盖插件、知识库、API以及现在讨论很多的 MCP 工具。扣子官方的实现里编排层是可视化 DAG也就是把节点拖到画布上连线串起来。很多人问扣子是不是 LangGraph 实现的其实不是它只是和 LangGraph 在图执行思路上类似内部完全是另一套实现。理解这一点对部署的意义在于如果你想把扣子智能体迁移到本地开源方案你要迁移的不是代码而是「节点怎么编排、工具怎么接、模型怎么换」这套逻辑如果你只想调用云端扣子那你需要的源码只是调用侧的几十行代码跟 Agent 内部实现毫无关系。2.2 云端扣子怎么工作从配置到运行时再到对外接口在扣子控制台里创建的每个 Bot本质上是一份非常结构化的配置。它包含人设与回复逻辑、模型选择与参数、知识库绑定关系、工作流 DAG 定义以及工具列表。当你点击发布扣子平台会把这堆配置实例化为一个运行中的智能体服务对外暴露两类访问方式一种是直接分享对话链接给终端用户另一种是发布为 API让开发者把 Bot 接进自己的产品里。一份最简 Bot 配置拆开看大致是下面这个样子在扣子里导出时可以看到类似的 JSON 结构{ bot_id: 7389xxxx, model: { provider: doubao, model_name: doubao-pro-32k, temperature: 0.3, top_p: 0.7 }, prompt: 你是一个负责处理售后问题的客服助手回答要简洁、准确不要编造订单信息。, knowledge: [ { datasets: [售后政策, 退货流程], retrieval_mode: mixed } ], tools: [web_search, order_query_api] }这段配置的关键参数值得细说model.provider决定走哪家模型服务商在扣子云端你可以选豆包、DeepSeek、MiniMax 等temperature控制在 0.3 左右适合客服这类要求稳定输出的场景如果做创意文案再调高到 0.7 以上retrieval_mode用mixed时知识库命中结果和生成结果会混合输出回答更稳但 token 消耗会明显上升。工具列表里的order_query_api不是扣子内置的是你自己通过插件或工作流注册的外呼接口这也就是后面「可运行源码」里真正需要自己写代码的部分。2.3 「可运行源码」在扣子生态里到底指什么从业者拿到标题里「可运行源码」这四个字时必须先搞清楚它到底指哪份代码因为不同阶段对应完全不同的东西。第一种是扣子控制台里导出的 Bot 配置包。这个包不是传统意义的程序源码它是描述智能体行为的 DSL 配置可以在控制台之间迁移复用。第二种是调用侧源码也就是你在自己的服务里写的 API 调用、消息接收、鉴权逻辑这是绝大多数业务真正要维护的代码。第三种是开源扣子系智能体平台的源码也就是社区里常说的开源扣子方案这类平台部署到自己的服务器上提供和扣子类似的编排画布和运行时能力模型、知识库、工具全部由自己掌控。想要拿到真正跑得起来的可运行源码先走云端 API 调用是最快的路径这也是下一章 3 分钟能完成的事情等业务要求数据不出内网、模型要换成自己部署的 DeepSeek 时再考虑拿一份开源扣子系方案做本地部署。3. 用控制台 3 分钟搭出最小扣子 Bot创建、发布与 Python 调用全流程3.1 创建项目和选择模型不是所有模型都适合当接待员打开扣子控制台新建一个项目类型选「智能体」而不是「工作流」因为智能体类型自带对话管理和模型调度能力。进入配置页后第一步是选模型。扣子控制台默认会给你豆包系列模型但如果你对输出格式有强要求我一般会直接切到 DeepSeek 或者别的开源模型上原因后面避坑章节会讲。这里有几个参数第一次用就值得记下来。temperature是随机性控制客服、问答类 Bot 设 0.2 到 0.4代码生成类设 0.1剧本写作类设 0.8 以上。max_tokens不建议设太高控制在 1024 以内否则一次回答会把上下文窗口吃掉一大半。reply_before_llm这类预回复规则只在你需要 Bot 先回复固定话术再进入模型生成时才开。人设提示词的写法直接影响整个智能体的表现。最常见的问题是把所有要求糊成一大段模型长上下文一长就漏掉关键约束。我通常把人设拆成「角色定位、行为边界、回答格式、禁忌项」四段每段一两句话禁忌项放最后避免模型被前面的话带偏。3.2 搭一个含知识库的极简工作流节点扣子智能体的核心配置页里除了人设还要挂知识库。进入「知识库」页面创建新的数据集支持上传文本、表格、网页链接。上传之后要注意看分片状态每个文档会被切成固定大小的片段并向量化切片长度默认是 400 到 800 字切片太短召回准但碎太长召回全但混。如果你上传的是 Markdown 格式的说明文档导出时保留标题结构非常重要因为扣子的解析器会把标题作为这个切片的语义标签。工作流画布里第一根线通常是「开始 - 模型 - 结束」三个节点。模型节点里引用前面的人设参数知识库通过「知识库检索」节点接进来。这里有一个新手必踩的坑知识库检索节点一定要在模型节点之前执行把检索结果拼进提示词否则模型只能凭自己的训练记忆回答知识库等于没挂。画完流程后点试运行输入一句测试问题看节点调试面板里检索结果和模型输出是否都正常。3.3 发布到 API 并用 Python 跑通最小调用示例控制台右上角「发布」选择 API 服务方式。发布成功后在 API 管理里能看到 Bot 的唯一标识bot_id然后去个人访问令牌页面生成一个PATPersonal Access Token。这个令牌相当于你调用 API 的钥匙权限范围选默认的应用权限即可密钥一定要存好泄露了随时可以在控制台吊销重新生成。import requests import json BOT_ID 7389xxxx PAT pat_xxxx body { bot_id: BOT_ID, user_id: tester_001, stream: False, auto_save_history: True, additional_input: None } resp requests.post( https://api.coze.cn/v3/chat, headers{ Authorization: fBearer {PAT}, Content-Type: application/json }, jsonbody, timeout30 ) result resp.json() print(json.dumps(result, ensure_asciiFalse, indent2))这段代码是扣子 v3 联调的基本骨架。user_id是业务侧的用户标识用来隔离每个用户的对话历史同一个 user_id 的多轮消息会彼此衔接这个参数在正式环境一定要传真实的用户 ID不传或者传同一个固定值会导致所有用户串聊天记录。auto_save_history设为True时平台自动维护会话状态省得自己管理历史消息但如果你的业务对上下文有定制要求可以关掉它自己传历史消息列表。鉴权用的是Authorization: Bearer PAT我见过很多人把扣子控制台里的别的密钥当成 PAT 用返回 401 一脸懵。响应里的conversation_id和id两个字段要落库前者是会话标识后者是单次回复的消息 ID后续做满意度评价、人工接管都靠这两个值。到这里3 分钟跑通云端扣子智能体的最小闭环就成立了控制台建 Bot、挂知识库、发布 API再到拿到第一条响应。4. 把可运行源码部署到自己的服务器Docker Compose 拉起开源扣子系运行时并接入 DeepSeek4.1 为什么本地部署智能体选「开源扣子系」而不是从零写云端跑通之后很多人会面临一个现实问题扣子控制台的 Bot 玩得再熟数据都在别人平台上模型按 token 计费知识库内容也受平台政策约束。这时候的唯一出路就是本地部署一套和扣子同思路的开源智能体运行时。业界常见做法是使用 Dify 这类开源智能体平台社区里通常叫它「开源扣子系」因为它们都提供可视化编排画布、知识库管理、模型接入和 API 发布能力。这套方案的核心价值在于「可运行源码」可以真正落到自己手里。你需要一台 2 核 4G 以上的服务器Docker 和 Docker Compose 先装好然后从官方源码仓库拉一份部署文件改配置、起容器、接入模型半小时内能跑起来。相比从零用 LangChain 手搓一个 Agent这套方案省掉了对话管理、会话持久化、知识库向量化这些重复造轮子的工作而且模型层替换很容易DeepSeek、Ollama、MiniMax 都能接。4.2 最小可运行部署docker-compose.yml 最小配置部署文件是整个本地部署的核心我把一份能直接启动的最简编排贴出来服务裁剪到 API、数据库、向量存储三件套。注意版本号要根据你自己拉下来的源码指定这里不写死具体版本。version: 3.4 services: api: image: ${RUNTIME_IMAGE:-docker.io/langgenius/dify-api} restart: always environment: MODE: api EDITION: community DB_HOST: db DB_PORT: 5432 DB_DATABASE: dify DB_USERNAME: dify DB_PASSWORD: dify123 VECTOR_STORE: weaviate WEAVIATE_ENDPOINT: http://weaviate:8080 WEAVIATE_API_KEY: wv123 SECRET_KEY: your-random-secret-key depends_on: - db - weaviate ports: - 5001:5001 worker: image: ${RUNTIME_IMAGE:-docker.io/langgenius/dify-api} restart: always environment: MODE: worker EDITION: community DB_HOST: db DB_PORT: 5432 DB_DATABASE: dify DB_USERNAME: dify DB_PASSWORD: dify123 VECTOR_STORE: weaviate WEAVIATE_ENDPOINT: http://weaviate:8080 WEAVIATE_API_KEY: wv123 SECRET_KEY: your-random-secret-key depends_on: - db - weaviate db: image: postgres:15-alpine restart: always environment: POSTGRES_PASSWORD: dify123 POSTGRES_DB: dify POSTGRES_USER: dify volumes: - db_data:/var/lib/postgresql/data weaviate: image: semitechnologies/weaviate:1.19.0 restart: always environment: AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: true DEFAULT_VECTORIZER: none volumes: - weaviate_data:/var/lib/weaviate volumes: db_data: weaviate_data:这份文件把 API 服务和后台 Worker 分离这是开源扣子系平台的标准做法。API 负责接收请求、做编排调度Worker 负责异步跑知识库入库、文档分段、Embedding 生成这些耗时任务。VECTOR_STORE选 Weaviate 是因为社区版默认支持最省心生产环境你可以换成 Qdrant 或者 pgvector换的时候记得把对应的环境变量一起换掉只改VECTOR_STORE一个值会导致启动报错。启动命令就两行cp .env.example .env docker compose up -d启动之后不要急着进页面先看日志docker compose logs -f api看到Application startup complete之类字样说明 API 起来了然后访问服务器 IP 加对应端口首次访问会引导你设置管理员账号。这个过程我踩过的坑是.env里SECRET_KEY不填随机字符串直接用默认值后面对接模型时加密密钥解析会莫名其妙报错。4.3 把模型换成 DeepSeek 或 Ollama开源扣子怎么添加模型的完整操作部署完开源扣子系平台下一步是添加模型。进管理后台的「模型供应商」配置页常见做法是两种。第一种接云端 DeepSeek。在供应商列表里选 DeepSeek填Base URL为https://api.deepseek.com填 API Key模型名填deepseek-chat这是 DeepSeek 官方对话模型的 API 模型标识别想当然填deepseek-v3接口不认。填完点「保存」然后先跑一次测试平台会返回一条测试消息验证连通性。第二种接本地 Ollama。如果你的服务器上已经用ollama pull deepseek-r1:7b拉好了模型那么Base URL要填宿主机 IP而不是localhost因为开源扣子系平台跑在 Docker 容器里容器内的 localhost 指向容器自己。我一般直接填http://172.17.0.1:11434这是 Docker 默认网桥的宿主机入口大多数情况下都通。模型名填你ollama list里看到的那个名字比如deepseek-r1:7b。除了对话主模型还要配置 Embedding 模型。很多人在这一步跳过结果知识库上传后提问时 Bot 回答「没有找到相关内容」。云端方案用text-embedding-ada-002或者开源系默认带的 embedding 模型都行本地方案最常用的是bge-m3同样通过 Ollama 加载同一个供应商连接配置里选模型类型为embedding即可。4.4 把云端扣子智能体迁到本地知识库导入与工作流还原本地平台跑起来之后怎么把扣子上的智能体「搬」过来这是最耗精力的环节。知识库相对简单把扣子数据集里的源文件下载到本地按 Markdown 或纯文本整理在开源平台里重新建数据集上传平台会自己完成分段和向量化。工作流迁移则没有捷径扣子导出的 DSL 是私有格式主流开源平台有自己的一套 DSL两者不能直接互导。我的做法是先在扣子那边把工作流截图成节点图然后在开源平台里重新搭建相同结构的流程。扣子里常见做法是用「开始 - 知识库检索 - 模型 - 结束」这种串联结构平移到本地平台时把每个节点按同样的输入输出接起来再用平台自带的调试功能对照扣子上的试运行结果逐步调整提示词变量。扣子旧版工作流里的几个节点比如快捷回复、意图识别在开源平台的节点类型里不一定有直接对应项。处理办法是用模型节点加上结构化输出解析来模拟也就是在提示词里让模型必须输出 JSON再通过后续节点按字段路由。这块别想着自动化人工逐一映射更稳妥真实项目里 90% 的迁移工作量都花在这里。工具层接 MCP 也不复杂——扣子链接 MCP 在云端是填服务地址本地平台上一样。「工具」配置里新建 MCP 工具填上streamable http或sse端点地址平台会自动拉取工具描述后续工作流节点里就能选用这些工具方法。有一点要注意MCP 服务端的地址要保证容器网络能访问到部署在同一台服务器就用宿主机 IP不要用localhost。5. 扣子系智能体部署避坑五个真实翻车现场的原因与修复5.1 API 返回 401/403密钥明明没问题现象按官方文档填了Authorization头调用扣子 v3 接口一直返回 401检查若干遍感觉密钥没问题。原因八成是把平台里不同类型的令牌搞混了。扣子控制台里「API 密钥」页面生成的是 PAT而一些旧教程里让填的是个人访问令牌页面里另一个入口生成的临时 Token两者权限范围和解码方式不同。另外 PAT 有有效期过期后接口同样报 401。解决统一去「个人访问令牌」页面重新生成 PAT直接覆盖原密钥生成时权限范围勾选你实际要调用的平台能力不要图省事全选。程序里把 PAT 放到环境变量里不要硬编码进仓库否则一旦推送线上就等同公开只能重新生成。5.2 模型输出答非所问人设提示词像没生效现象扣子控制台调试时 Bot 回答正常发布到 API 后同样的输入得到的回答偏离人设甚至开始胡说八道。原因控制台调试环境和 API 服务的上下文处理不一样。发布后如果additional_input传入了额外字段这些字段会拼到系统上下文里干扰 prompt另外temperature设置过高会让模型在长上下文中跑偏。解决把temperature固定到 0.2 到 0.4 区间人设提示词里把最关键的约束放到第一句让模型在任何上下文拼接下优先读到它。逐字检查additional_input里的键名别和系统字段重名平台文档里明令保留的字段名一个都不要用。5.3 工作流中 HTTP 节点反复失败时好时坏现象扣子工作流里接了自己业务系统的查询接口调试时 60% 概率失败错误信息是超时偶尔成功。原因扣子云端执行工作流时HTTP 节点的默认超时时间很短跨网访问你的业务接口只要对方响应超过几秒钟就断。另一个常见原因是接口返回了非标准 JSON扣子节点解析失败直接当错误处理。解决给业务接口做一层薄封装固定返回{code:0,data:{...}}这样的小写字段结构在 HTTP 节点里把超时参数调到允许范围内的最大值并添加失败分支节点超时后返回兜底话术而不是让整个对话报错。5.4 本地部署后 Bot 变成失忆症知识库明明导入了现象开源扣子系平台本地部署完后模型能正常聊天但一问到知识库里的专属内容就回答不知道去向量数据库看文档确实入库了。原因典型的两处配置错误。一是只配置了对话模型没有配置 Embedding 模型系统用默认的空实现入库时向量全是零向量检索自然什么都召不回二是知识库文档分段参数不合理整篇大文档没分段就入库导致每个片段都是几千字的大杂烩检索召回后模型读不懂。解决在模型供应商里把 Embedding 模型补齐重新建数据集强制重新分段和向量化。分段长度我一般设在 500 字左右重叠 50 字这样既保留上下文连贯性又提高召回精度。改完后在知识库页面做一次「召回测试」输入一句典型业务问题看返回的片段是否和自己预期一致。5.5 Docker 部署后内存爆满服务器直接卡死现象Docker Compose 拉起来镜像后跑了半天服务器负载飙升free -m看内存几乎耗尽数据库容器被系统 OOM 杀掉。原因docker-compose.yml没有给每个容器设置内存上限而开源扣子系平台默认会预加载模型多个容器同时吃内存再加上对话并发高时 Worker 里同时跑多个 Embedding 任务内存就像漏斗一样漏下去。解决在docker-compose.yml的 api、worker、weaviate 服务下都加上deploy.resources.limits配置比如 API 限 1GB、数据库限 1GB、向量库限 1GB同时调低 Worker 并发数限制 Embedding 任务的并行度别让一堆入库任务同时在内存里做矩阵运算。6. 上线前的最后一步给智能体写一份可回归的验收脚本部署完成不等于交付真正让人放心的是每次改完 prompt、换完模型、调完参数后能有一份脚本替你把关键场景全部回归一遍。这套东西在团队协作里非常重要开发说「我就改了个提示词」测试说「这轮明显变蠢了」没有回归脚本就只能靠肉眼一轮轮聊。我通常会给每个智能体维护一个cases.json里面是典型场景的输入、期望行为关键词、允许的最大响应时间。回归脚本也很简单import requests import json import time cases json.load(open(cases.json)) for idx, case in enumerate(cases, 1): start time.time() resp requests.post( http://localhost:5001/chat-messages, headers{Authorization: fBearer {API_KEY}}, json{ inputs: {}, query: case[query], user: regression_test, response_mode: blocking, }, timeout60, ) elapsed time.time() - start answer resp.json().get(answer, ) status PASS if resp.status_code ! 200: status FAIL_HTTP elif elapsed case[max_time]: status FAIL_TIMEOUT elif not any(kw in answer for kw in case[expected_keywords]): status FAIL_CONTENT print(fcase {idx}: {status}, {elapsed:.1f}s, {case[query]})这段脚本的作用不是自动化测试框架那么重而是当你在扣子和本地开源平台之间来回调参时的后悔药。每次改完人设先生成一批新旧对照跑一遍别靠手感判断好坏。等稳定了再把它接进 CI每天跑一次模型供应商如果偷偷换了底层模型版本第一时间就能在输出质量变化上观察到。我自己的习惯是验收脚本里固定跑 20 到 30 个真实业务问题覆盖售前、售后、闲聊、对抗输入四类其中对抗输入至少占 5 条专门测越狱和诱导。最初部署第一个扣子智能体时我把全部精力都放在提示词上上线第一天就被并发把服务打崩了后来才意识到部署一件事要看的从来不只是模型输出质量还有超时、限流、资源占用这些更底层的指标。希望这篇能帮你把扣子智能体部署这条路走顺少交几次学费。本文还有配套的精品资源点击获取