输入处理族：参数提取 + 文档提取器——非结构化输入结构化的两种方式
基于 Dify 1.16.1 与 Hermes Agent 实战实测（2026-08/09）：E3 参数提取防幻觉实验 + E5 文档提取器实验 + 文件上传链实测
📖 摘要：非结构化输入结构化有两条路：参数提取（从文本提取语义字段）和文档提取器（从文件提取文本内容）。本文实测：PE 的防幻觉 instruction 怎么写才有效（格式判定 + 边界定义 + 禁止编造）、PE「空」的两种形态（防幻觉输出 "null"、宽松输出 ""——下游判空坑）、文件链路的可靠路径（workflow 模式，chatflow 的 sys.files 实测静默失败）、文件类型白名单的 API/UI 双路径陷阱。
📌 本文要解决的核心痛点
- 让参数提取从文本里抓姓名/电话/订单号，没提到它也编造一个？
- 参数提取返回的「空」到底是 null 还是空字符串？下游怎么判才稳？
- 上传文件给文档提取器，文件根本没进应用（不报错）——为什么？
- 文件类型白名单：API 能传、UI 不能传，到底谁说了算？
- 本文给 PE 的防幻觉写法 + 文件链路的可靠路径 + 双路径验证纪律。
一、两个节点是干什么的（先分场景）
| 节点 | 干什么 | 什么时候用 |
|---|---|---|
| 参数提取（PE） | 从非结构化文本提取结构化字段（姓名/电话/订单号/技能） | 用户输入一段话，你要抽出字段给下游（表单/建单/搜索） |
| 文档提取器（DE） | 提取上传文件（txt/pdf/docx）的文本内容 | 用户上传文件，你要读内容（解析/入库/处理） |
关键认知：PE 是 LLM 驱动的概率性节点（模型提取）；DE 是 确定性节点（平台解析文件）。所以 PE 的核心是「防幻觉」（概率性的通病），DE 的核心是「文件链路可靠」（确定性但要保证文件真的进来）。
二、设计模式
参数提取（PE）——防幻觉是设计的第一优先级
| 契约 | 要点 |
|---|---|
| 配置 | query（selector）+ reasoning_mode（function_call/prompt）+ instruction + parameters[{name,type,description,required}] + model |
| 防幻觉 instruction 三件套 | ① 格式判定（「电话必须是明确的 11 位手机号，以 1 开头」）② 边界定义（「什么算、什么不算」含正反例——岗位不算技能）③ 禁止编造（「没有明确出现的字段必须输出 null，禁止推测或编造」） |
| 判空 | PE 只负责从文本提取语义字段；判「用户有没有填」用 start 变量直给值 |
文档提取器（DE）——文件链路选可靠路径
| 契约 | 要点 |
|---|---|
| 配置 | type: document-extractor + variable_selector（文件变量引用） |
| ⚠️ 可靠链路 | workflow 模式：start
文件变量（allowed_file_extensions/types/upload_methods）→ DE
[start, 文件变量] → 下游 |
| Service API | /v1/files/upload（user 在 multipart form，与 run 同
user）→ /v1/workflows/run inputs 内嵌
{transfer_method, upload_file_id} |
| 输出 | text（提取的文本内容） |
三、实测踩坑（四个高频坑）
坑 1：PE 无防幻觉约束 → 编造填值
现象：用户输入里没有订单号，PE 还是提取了「订单号」填值 → 直接建单（脏数据入库）。
实测：dify104-02 无订单号也提取填值——instruction 无防幻觉约束。修复：显式「必须 null 禁止编造」+ 格式判定。
坑 2：PE「空」的形态不统一（"null" vs ""）——E3 实测
现象：输入「你好」（无姓名无电话），防幻觉
instruction 输出 "null"（字符串），宽松 instruction 输出
""（空字符串）——两种都是「无」，但形态不同。
实测（E3）：防幻觉版 name/phone =
"null"（__is_success=1，流程正常）；宽松版 =
""。deepseek
本次未编造（模型较保守），但形态差异是确定的。
根治：下游判空兼容两种形态（== "null" or == ""
都算空）；instruction 统一「无则输出 null」。
坑 3：chatflow 文件链路静默失败——E5 实测
现象：advanced-chat + files 参数（type:
document/custom 都试）+ features.file_upload → chat-messages 200，但
workflow_runs.inputs.sys.files = []——文件静默不进应用（DE
输出 text 空数组，不报错）。
根治：文件处理走 workflow 模式（start 文件变量）——E5 实测 txt 206 字符完整提取。chatflow 文件链路在本机 1.16.1 不可用。
坑 4：文件类型白名单双路径陷阱
现象：features.allowed_file_types 写 document，UI 上传 .yaml 报「文件类型错误」，但 Service API 冒烟全过。
根因：UI 前端按 allowed_file_types 白名单拦截（document 白名单不含 .yaml）；API 后端按 allowed_file_extensions 校验。API 全过 ≠ UI 可用。
纪律：配置类功能必须双路径验证（API 冒烟 + UI 导出回读比对）。
四、节点级验证清单
| 验证点 | 怎么验 | 取证 |
|---|---|---|
| PE 防幻觉 | 无信息输入 → 确认输出 "null"/""（不编造） | 同输入 5 次采样全过才算修好 |
| PE 正常提取 | 含信息输入 → 字段正确 | 提取结果断言 |
| PE 判空兼容 | 下游判空覆盖 "null" 和 "" 两种形态 | 边界用例 |
| DE 文件链路 | workflow 模式 + 文件上传 → 文本完整提取 | 提取长度/内容比对 |
| 文件白名单 | API + UI 双路径验证 | 两路径各跑一次 |
五、案例：客服工单信息提取 + 上传文件处理
| 环节 | 工具 | 做法 |
|---|---|---|
| 意图分类 | 问题分类 | 工单/咨询/投诉分流 |
| 信息提取 | 参数提取 | instruction 三件套（格式判定/边界/禁止编造）提取姓名/电话/订单号 |
| 空值处理 | 条件分支 | PE 输出 "null"/"" 都判空 → 走补料分支（人工输入） |
| 文件处理 | 文档提取器（workflow） | start 文件变量 → DE 提取 → 解析入库 |
| 建单 | HTTP/代码 | 校验通过 → 调工单系统 |
核心结论：输入处理族的本质是「把不确定的输入变成确定的契约」——PE 靠防幻觉 instruction（概率性节点要采样验证），DE 靠可靠的文件链路（workflow 模式 + 双路径验证）。判空兼容两种空形态，是 PE 下游最常见的隐藏 bug。
下一篇（终篇）预告：《节点级验证方法论》——全系列收束：每个节点的验证清单总表 + 三层根因排查全流程（导入/运行/逻辑）+ 取证命令（node-executions / DB 直查）+ 验收案例。
- Dify 节点全景图：20 个节点、7 个功能族、3 个通用设计问题
- 内容生成族：LLM 节点怎么设计才稳定——六类 17 条自查清单 + 4 条进阶经验
- 知识接入族：知识检索节点——RAG 质量的三道闸门（分段 / 检索配置 / 清洗）
- 决策路由族：问题分类 + 条件分支——工作流的骨架是分流，分流只能在分类节点出边完成
- 数据操作族：模板转换 / 代码执行 / 变量聚合 / 变量赋值 / 列表操作——数据五件套的选型与契约
- 外部交互族：HTTP / 工具 / Agent 节点 / 外部数据源——与外部世界打交道的四种方式
- 流程编排族：迭代 / 循环 / 定时触发 / 子工作流 / 人工输入——复杂流程组织五件套
- 输入处理族：参数提取 + 文档提取器——非结构化输入结构化的两种方式
- 节点级验证方法论：每个节点怎么验——三层排查 + 验证清单总表
