Dify 应用怎么交付才算完成:九个环节,九道验收门禁
摘要:一次九个环节全链交付演练的实测复盘:需求收集到巡检维护,每个环节一个门禁、一份产出物。页面打开、演示通过、尾款待签那天,客户的三句话——装上了吗、怎么证明是对的、以后谁维护——这篇用演练留痕逐条回答。14 执行阶段 150.5 秒、用例 15/15、备份恢复 143 张表,全部自有实例实测。
一、验收现场的三个常见追问
AI 应用项目的最后一天通常是这样的:会议室投屏,页面点开,演示问题答得流畅,验收单摆在桌上等签字。客户方有人站起来,问的话一般就三句:
「这算装上了吗?——我们自己的服务器上,备份啊端口啊这些,到底是什么状态?」 「你怎么证明它是对的?——答错了算谁的?」 「以后谁来维护?——手册下个月就更新,资料换了它知道跟吗?」
这三个问题就是本篇的正题。答案在九个环节里——每一环怎么查,往下逐个给。
问完,有人把合同附件翻了一遍——验收条款里没有这三句的对应项。投屏上还停在演示通过的那条回答。这三句在多数项目里成了「新需求」。怪合同没写到吗?合同确实没给它们留位置——行业里多数合同到「上线」为止,这三句全在「上线」之后。交付方做了不少工作是真实的;被问住,是因为默认了三个没人查过的想当然:
打得开=能用。跑通了=交对了。做完了=交付完了。
三句话合起来就是那句「我们做完了」。这篇拿来跟这三句核对的,是一次九个环节全链演练留下的记录——从需求收集到巡检维护,每步留痕,材料为模拟。为什么要用模拟材料?客户的真实资料拿不出客户的环境;就算拿到了,数字对不上时,分不清是方法错还是材料本身有问题。模拟材料的答案先知,所有偏差只能归到方法上。这是实验设计,不是条件不讲究。
二、第一句:「打得开」的页面,不显示的东西比显示的多
「打得开=能用」,页面只负责「能不能打开」这一件事,环境的全部风险都发生在页面看不见的地方。
环境落地这一步的门禁是自检十项:容器在不在跑、端点通不通、磁盘与内存余量、数据库能不能查、备份在不在、管理入口有没有暴露到公网等。演练当场两项直接不合格(实测):
- 备份目录是空的——实例跑了很久,一次备份都没做过。这个坑是我们自己的:平时对客户讲数据必须可恢复,自己家的服务器一次都没备过。发现它的,正是那十项用来防客户环境的自检——这道门禁第一次跑,拦下的第一个问题就是我们自己的;
- 一个组件在反复重启——7 次,不影响当前使用,是事故的前兆。
另一次对外部实例做外部视角审计(攻击者视角:不进环境,从公网直接探它的门),报出的三件事同样都不影响「打开」:控制台登录页对公网返回 200、一个非必要端口对外开着、证书只剩 61 天(实测)。
通过标准:严重项清零才往下走;暴露面按「限制来源 / 加访问控制 / 收紧端口」逐条处置(严重度分级见 FAQ)。空备份目录不是一句标准就完——后面备份恢复验证真导入过一份 142.3 MB 的备份(实测),这份备份是那时补的:这道门禁在演练里被执行过,不是写在纸上看着的。
应用上线这一环,「打得开」还要再过两关。一关是依赖检查:导入前先跑——缺一个插件,导入客户环境就是打不开。演练里这条门禁没有东西好拦,空跑通过(实测);但它在实际项目里拦过人(经验)。另一关是冒烟三问:库内问题答出具体参数,库外问题明确说「资料里没有」,越界问题直接拒绝——三问都有留痕(实测),「能用」才算当场成立。顺带发现一个细节:回答里没有出处引用,查下去是配置的引用开关关着——想要「答案+出处」,开关必须打开,这也是「打开页面」看不见的事。
一句话收住第一句:中间隔着的是容器、端点、依赖、库、索引、备份、暴露面这一整层,每项都得有自己的实测值。
三、第二句:跑通证明的是这条路,不是这个系统
「跑通了=交对了」这句最硬,得两头检验:先问「跑通」的定义是谁定的,再问「对」怎么证明。
**「跑通」的定义,得在开工前定死。**拿到资料先回答「能不能做」,四个问题:答案在不在资料里、问题分布什么样、是检索还是要推理、边界在哪。演练里就撞上一个:「这个型号什么时候停产」——手册里根本没有答案。这怪不得「做得不好」——资料里就不存在。于是提前说清三类问题的处理口径:库内答对、库外明说没有、越界拒绝。这句话后来就是验收标准本身——验收标准在这时候定,等不到交付那天(经验)。
需求访谈是同一件事的另一头:五个问题——要解决的问题、每天用的人、资料在哪、谁说算数、答错一次伤什么。答不齐,后面每个环节都在替一个没确认的目标服务。产出:三类问题口径+每类 3 条样例,客户确认「这就是我要的」;确认不了的,要么「先补资料」,要么直说做不了。配套一页纸边界卡:做什么、不做什么、验收口径、环境与 key 归属、资料更新责任、分期——「不做什么」和「做什么」一样重要,交付纠纷里「做不出来」的占少数,多数争执发生在我以为做完了,你没说要(经验)。
**「对」的证明,要两层一起给。**验收拆两层:静态检查+用例执行。静态检查查的是 DSL 本身配置有没有毛病——DSL 是把应用全部节点、提示词、检索设置打包成的一个文件,可导出可导入,所以能离线查;规则库 112 条零第三方依赖,可直接进流水线。用例执行是真的问、真的答、按事先口径判定。两层各管各的门:静态抓的是「兜底缺失」(知识库没命中时该走什么分支、提示词有没有防注入隔离),用例证的是「当前这条路没出事」——一个防未来,一个证现在。「跑通了=交对了」恰好是把这两层都省了:跑通只证明了测过的几条路。
演练里静态检查报出一条「严重」:某节点变量名像凭据。看见「严重」两个字,第一反应是把变量名改掉、让规则不再报警——省得解释。翻代码核实,才看清那是检索结果去重用的键,不是密钥,属误报。这就到了岔路口:改代码刚好过关,还是让它留在报告里?选择:写豁免+理由,报告单列一节「已豁免」。选留痕不选压下报警,理由很实在:客户信得过什么样的报告?报了错肯认、说得清的。全绿反而没人信——绿的越多,问的人越多。豁免成立卡三条(经验):证据可复核(指到代码行)、理由具体到能被人反驳、客户知情;安全、数据出域、合规三类不开放豁免——那类只能修,不能解释;翻代码仍解释不清的,结论是「先修,不豁免」。随后 15 条用例跑下来 15/15 通过(实测)。最后把结果基线化:这次的分、这次的用例结果、这次的异常清单存档——之后每次变更拿它核对,回答那句「这次改动有没有把原来好的弄坏」。
四、第三句:尾款签完,客户的问题才刚开始
「做完了=交付完了」这句在行业里默认成立,因为合同到交付为止。要推翻这句默认,得靠实测记录。
交付这一步,过的是清单,不是握手庆祝:应用与知识库可用、验收证据齐、环境自检过、巡检基线有、凭据已单独移交、客户侧有人能自己跑一遍——逐条勾完才算交付。演练里把交付链从头到尾贯通跑了一遍:执行日志 14 个阶段、150.5 秒(演练实测)。九个环节是业务链,14 是执行日志的切分(部署、上线等环节各有前置步)。要说清这个数字:单次串联记录,自有实例、热态(服务已热,无冷启动开销)、只算机器时间,不含需求访谈、口径确认、语料准备这些人工环节;冷启动或网络受限的服务器会明显变长。它给量级(不到三分钟),不是承诺。凭据一条硬规矩:Service Key 单独渠道移交,不进报告、不进包——报告里只有数量、体积、状态。
交付的三样东西:能用的应用、能复跑的工具与验收标准、逐阶段交付报告——外一层是结果,内一层是自己维持下去的能力(经验)。「做完了=交付完了」最先被推翻的地方就在这:交付走到终点只剩一问——**你能不能自己维持?**清单最后一条(客户侧有人独立跑通「提问—看引用—改语料」)勾不上,就不叫交付。
这句第二次被推翻:资料、模型、机器、证书都在动,而合同不动。客户的问题从这一刻才开始,所以链上必须有第九个环节,规矩有五条:
- 巡检五组二十二项:服务(容器与重启、日志错误量)、资源(磁盘、内存)、数据(库体积、备份新鲜度)、应用(知识库规模、索引状态、失败率)、暴露面(端口、控制台、证书)。演练里报红的正是那个重启 7 次的组件(实测);
- 备份不问文件在不在,只问能不能恢复:起临时容器把最新备份真导一遍,142.3 MB 恢复出 143 张表、关键表 120 行(实测),验完删容器,生产库全程不动——没验证过恢复的备份等于没有备份;
- 资料更新走流程:文档 ID 不变、约 5 秒重索引(实测),同时跑回归门禁问题集(更新后该中的还中不中)与残留检查(旧说法没有残留),两道全绿才算更新完成。更新要按事实来数,不能按文件来数:手册改了参数、FAQ 里同参数那条没动,残留检查当场判 FAIL,补上才过;
- 任何变更后拿基线回归,看清哪些变好、哪些退化;
- 巡检严格只读:脚本不改任何环境配置,只出清单与建议,改不改、何时改由人定——客户环境里的自动改动,是事故的常见来源。
「做完了=交付完了」拆开只剩一句实话:做完是瞬间,交付是状态——第九个环节就是维持这个状态的机制。
五、九个环节与通过标准总表
三句话各管各的环节,整条链摊开在前。先交代表里两个词的关系:每个环节的「通过标准」是那道门禁自己的依据;与客户商定的「验收口径」挂在第 3 个环节——定下来之后,拆挂到各环节成为各自的通过标准。照做的人按这张表走——
| 环节 | 通过标准 | 不达标时的动作 |
|---|---|---|
| 1 需求收集 | 五问答齐:目标 / 使用者 / 资料来源 / 验收人 / 答错后果 | 不进入分析,先把问题问清楚 |
| 2 需求分析 | 三类问题样例(库内 / 库外 / 越界)经客户确认 | 改为「先补资料」,或直接说这类需求做不了 |
| 3 方案与边界 | 边界卡与验收口径双方确认后才开始实施 | 确认不齐,不动手实施 |
| 4 环境落地 | 自检十项严重项为零 | 先修环境(补备份 / 查重启 / 收端口),不装应用 |
| 5 语料工程 | 短段率低于 10%、破碎段为零、目标问题能召回 | 回到清洗与分段重做 |
| 6 应用上线 | 无缺失依赖、发布成功、冒烟三问口径成立 | 停在该步:补依赖 / 修配置 / 打开引用开关 |
| 7 验收 | 严重项为零或已豁免留痕、通过率达标 | 修应用或修用例,然后重新回归 |
| 8 交付 | 清单逐条勾完、客户侧有人能独立跑通 | 不交付,先补能力转移 |
| 9 巡检维护 | 巡检严重项为零、备份能被恢复 | 出清单与建议,安排变更窗口 |
第五个环节(语料工程)在前面三节还没出现数据:51 段里 8 个纯标题段(15.7%)把答案段挤出检索前五,删到 43 段、短段率归零,答案段回到第一位(实测);检索按词匹配打分、不知道「是不是答案」,所以语料必须适配检索工具的性质——分段不是越细越好(经验)。
链条背后的七条固定做法,每条指回对应环节:
- 交付物是能跑的东西(第四、六节)——能执行的东西+能复跑的证据,说明书不算;
- 门禁驱动,过不了不往下走(第二至四节的各道门禁)——停在原地只为一个目的:不让问题走到客户手里;
- 验收口径前置(第三节)——「好不好用」定死了,就不再各说各话;
- 证据可复算(第三和四节)——同一份 DSL 同一套工具复跑,过程可复现、结论逐条可核对——可复算是证据和截图的区别;
- 环境层也纳入交付(第二和四节)——应用能不能用是看得到的一面,环境有没有基线是看不到的一面;
- 语料工程有质量门禁(第五环节通过标准)——不上门禁,检索效果就毫无保证;
- 能力转移,变更可回归(第四节)——交付走到终点只问一句:你能不能自己维持下去?
想复跑的人:四道门禁的工具层
交付链的实现层这样拆:每道门禁由什么构成、输出什么,按第四节的组序和上面总表的环节号走。实际交付过一个
60.6 KB
的包(样板-部署与巡检-v1.0.zip),包里四个脚本、一部规则库、一份清单。
装后自检(第 4
个环节门禁):01_preflight.py,十项——容器、端点、磁盘与内存、数据库可查、备份在否、管理入口暴露面等,输出逐项状态(ok
/ warn / skip / fail);通过标准:严重项清零才放行。
定期巡检(第 9
个环节门禁):02_inspect.py,五组 22
项,每项有编号:服务组
S1-S5(容器总览、重启与健康、平台版本、服务端点、24h
日志错误量)、资源组 R1-R4(磁盘、Docker 占用、内存、负载)、数据组
D1-D4(库体积、备份新鲜度、数据卷、索引状态)、应用组
A1-A4(应用与知识库规模、7 天运行量与失败率、API Key
数、账号成员)、暴露面组
E1-E5(端口、控制台可达性、证书、SSH、防火墙)。编号与验收标准定义在同包《巡检项清单》;在
Windows 与 Linux 上各跑过一遍,关键值逐条一致(实测:库 282 MB、索引
completed=20、应用 120/知识库 14/文档 20/消息
556)。全部只读命令采集:命令级白名单+破坏性动作拦截。
备份检查与恢复验证:03_backup_check.py
查备份存在与新鲜度;恢复验证起临时容器导入备份,核对表数与关键表行数(142.3
MB → 143 表、apps 120
行,实测),验完删除;生产库与生产卷全程不挂载、不写入。报告由
04_report.py
汇总,带异常分级、修复建议、与上次对比——与上次的差值,就是回归记录。
静态检查(第 7
个环节门禁,验收侧):rule_engine.py,规则从真实交付踩过的坑沉淀,按「严重
/ 一般 / 提示」三级,编号 R-xx(如 R30:prompt_template 每项须有不重复的
id;R31:code 节点每个 return 分支须含全部声明 outputs 键);本次 112
条全量跑通(实测),只有标准库依赖,可直接挂流水线,每条结论带规则编号与代码位置。误报豁免:豁免必须成表才生效——每条写「规则编号+命中位置+理由」,理由为空不生效;报告单列一节「已豁免」;安全、数据出域、合规不开放豁免。用例执行:期望值来自对目标应用的实际探测——换了语料要重新探测,判定按事先口径(关键词命中
/ 明确拒答 /
明说未找到)。回归基线:静态缺陷集合与用例结果落成基线文件,变更后
diff,输出三类结论——新增、已修复、回归。
六、验证:这一跑证明了什么,没证明什么
数据总表(实测):交付链 14 个执行阶段串联 150.5 秒;用例 15/15;静态检查 112 条跑通、一条误报走豁免留痕;备份恢复 143 张表、关键表 120 行;语料更新后残留检查与回归门禁全过。三句话各拿到反证:页面打开≠环境合格(空备份、重启 7 次)、跑通≠交对(兜底缺失要靠静态层抓、误报要豁免留痕)、做完≠交完(客户侧独立跑通与第九个环节都在清单里)。
没证明的也要写清楚:一次演练的样本量,支持「交付链走得通、通过标准执行得了」,支持不了「这套做法在多数项目里都成立」——本篇所有数字站在「单案实测值」那一层。流程是完整的,验证还在路上,两件事得分开说。
七、演进:这条链的三个薄弱点
链最可能从三处开始松:材料规模差一个数量级,先松的是分段策略和巡检节奏;客户中途改边界,先松的是验收口径与基线;真实脏资料进场,先松的是清洗通过标准(要从「格式质量」扩到「事实一致性」)。下一轮要做的事只有一件:拿一份难一个量级的真实资料把这条链重跑一次,看三处哪一处先出裂纹——裂纹出现在哪,流程的下一步改进就写到哪。
三处薄弱点各配一个可检查的信号和一个动作。巡检节奏:信号是巡检报告超过约定周期没有新留痕;动作是核对短段率、新鲜度、备份三项还在正常出数。验收口径:信号是客户边界变了、验收清单没有跟着改版;动作是交付前逐条核对清单与最新功能是否一致。清洗通过标准:信号是新入库资料没有事实一致性的复测记录;动作是把同一事实的多版本表述抽出来逐条对。
八、适合什么项目,不适合什么项目
适合:资料相对稳定(有明确维护人)、有明确使用者、能接受「答不出要明说」而不是要求「什么都能答」、愿意把验收标准在开工前定下来的项目。
不适合:要求三天出个能演示的壳(门禁环节省不掉,能做到什么程度、哪些门禁可以裁剪,见 FAQ 第一条)、要求承诺「回答 100% 准确」(大模型做不到,能做的是口径与兜底)、资料散落且没人能确认哪份最新(语料质量不可控,效果容易引发争议)的项目。
读完这篇,明天能做的分工:
如果您是买家,把「打得开=能用、跑通了=交对了、做完了=交付完了」三句话抄在白板上,验收前让交付方逐句确认;确认不了的,落成合同条款——对应通过标准总表的第四、七、八环节。签了字的条款,就是下次开会这三句话不再出现的保证。
如果您是交付方,下次开工前把总表的「产出物」列打印出来摆在项目组桌面——哪个环节的产出物拿不出来,那个环节就还没干完,别用一句「做完了」盖过去。
常见问题
这套门禁要花多少时间?时间紧的项目要不要做全链?
先分两类时间。机器时间可以忽略:交付链一次串联跑通 150.5 秒(14 个执行阶段,单次记录)。真正花时间的是人工环节:需求访谈与验收口径确认、语料清洗与分段选型、豁免核实、异常处置——这些按项目规模算,压不掉,但门禁可以裁剪。
裁剪的取舍:自检、冒烟、用例这三件不能省,省了等于没验证就交付;巡检与备份恢复验证在首次交付时至少各做一次,否则回答不了「坏了能不能恢复」;静态检查与回归基线是给后续变更用的,如果这个应用确定不再改,可以先不做。反过来——如果后面还要改(换模型、更新资料),没有基线的话,每次改动都只能靠感觉判断有没有改坏。
怎么判断一个知识库类 AI 项目能不能做?
先看四个问题:答案在不在资料里、问题分布能不能覆盖、是检索还是需要推理、哪些必须明确拒绝。判断的关键就一个问题:资料里有没有答案。「技术上能不能实现」这句放在后面。资料里没有的,模型只能编,这类问题要在需求阶段就挑明。做法是出三类问题样例(库内 / 库外 / 越界)各三条,项目能不能做,看这三类样例答得怎么样。
知识库分段到底怎么选?为什么短段率是个指标?
分段不是越细越好。分段过细会把「续航与充电」这类纯分类标题切成独立段——它们没有答案内容,却因为主题词密度高在检索里排前,把真正的答案段挤出候选。做法是先按资料结构选分段方式,建完库看两个数:短段率(低于 10%)和破碎段(为零)。演练里清掉孤立标题行之后,段数从 51 降到 43,短段率从 15.7% 归零,同一个问题的答案段回到了第一位。
检索效果不好,先调参数还是先调语料?
先看根因在哪一层,别急着动参数。演练里试过一轮:把候选池从 3 调到 5 有效;再往上加、调相似度阈值、加 rerank 都没有明显增益——因为问题出在问法覆盖与语料表达上,调参数调不动它:一个口语化的短问法根本没能把正确段召回候选里,参数再调也救不回来。做法是分层判读:先看候选池里有没有正确段(没有 = 检索 / 语料问题),再看它在池里的排序(有但排后 = 排序 / 问法问题),最后才动参数。
静态检查和用例执行,为什么两个都要做?
两者证明的不是一回事。静态检查看的是配置毛病与兜底缺失——比如知识库没命中时该走什么分支、提示词里有没有防注入的隔离约定;用例执行证明的是当前这条路径没出事。一个防未来,一个证现在。只跑用例,等于只证明了你测过的那几条路是通的;只跑静态,等于只有防范没有实测。
语料更新后为什么还要跑「残留检查」?
因为「更新」要按事实来数,不能按文件来数。演练里改了一个参数,更新了手册那一份,却漏了常见问题里同样写着这个参数的地方——残留检查(按事实扫,不按文件扫)当场判 FAIL。同一个事实往往写在多处:手册、FAQ、工单模板、对外文档。改完不回扫,客户就会在另一处读到旧说法。NASA 也付过这笔学费:1999 年火星气候探测器,两拨软件各用磅力秒和牛顿秒计算冲量,探测器进入大气层后解体,代价 1.25 亿美元——「各自的文件都对」不算数,全体口径对上才算数。
误报豁免什么时候成立,什么时候不成立?
成立要同时满足三条:证据可复核(能指到具体代码行)、理由具体到能被人反驳、客户知情(报告单列一节)。反过来,涉及安全、数据出域、合规的告警不允许豁免——那类问题只能修,不能解释。还有一条经验:花时间翻代码仍然解释不清的,结论就该是「先修,不豁免」。
为什么不能承诺「回答 100% 准确」,能保证的是什么?
因为大模型的输出是概率性的,而资料本身也可能有缺口、有多版本矛盾——这两件事都不是靠调参能消除的。能承诺的是三件具体的事:能答的答准(有资料有出处)、答不了要明确说没找到(不许编)、超出范围的拒绝(越界问题不作答)。把这三条做成可验收的口径,比承诺一个做不到的准确率有用。
多语言支持什么时候该做?
先问一句:谁在用这门语言。如果使用者都是中文,多语言只会增加语料与检索的噪声(同一份资料的不同语言版本会互相竞争召回)。做法是先只把一门语言的流程做顺——分段、检索、验收口径都跑通了,真有多语言需求时,按语言分库而不是把多语言语料并到一个库。分库赢在两处:不同语言的检索互不竞争候选,每门语言各自一套可复算的验收基线;换来的能力是:某一门语言的口径变差,只降它自己的级,不牵连另一门语言。
备份为什么要做抽样恢复,而不是只看备份文件在不在?
因为「脚本跑成功、文件也在」和「这份备份真能恢复」是两件事。备份可能被截断、可能写在只剩几兆的分区上、可能权限不对——这些在「文件存在」这个检查里全都看不出来。抽样恢复的做法是起一个临时容器,把最新备份导进去一遍,看能恢复出多少张表、关键表有多少行;验证完容器立即删除,生产库全程不动。演练里 142.3 MB 的备份恢复出 143 张表、关键表 120 行——这才叫「有备份」。
巡检为什么只读,不做自动修复?
因为客户环境里的自动改动是事故来源:磁盘满了自动删日志,可能把需要排查的证据一起删掉;容器异常自动重建,可能把数据弄丢。巡检该做的是三件事:报出异常、给出修复建议、留下基线。改不改、什么时间改、要不要停服,这些需要业务判断和变更窗口,是人的决定。工具把判断权留着,是对客户环境负责。
本文基于真实交付实践与自有测试实例实测撰写(2026-09,2026-11-16 重写)。文中数据均来自实测记录;NASA 一处引用止于公认记录。AI 参与创作。
这篇有用吗