基于 Dify Agent 的智能问答系统设计与实现
一、背景与目标
在日常工作中需要频繁查询各类统计数据,传统方式依赖登录后台系统逐级筛选,操作门槛高、响应慢。
为解决这一问题,我们基于 Dify Agent 平台构建了一套智能数字人问答系统,支持语音和文字两种交互模式,用户只需用自然语言提问,系统即可自动路由到正确的数据源,返回结构化的查询结果。
核心目标:
- 自然语言交互,零学习成本
- 严格的数据权限隔离(网格子树模型)
- 多源数据融合(事件、粉丝、成效指标、先行村、知识库、外网搜索)
- 流式输出,实时反馈工具调用进度
- 防幻觉、防越权、防数据泄露
二、整体架构
┌─────────────────────────────────────────────────────────────────┐
│ 前端 / 数字人终端 │
│ (语音识别 → 文字 → SSE 流式渲染 → TTS) │
└──────────────────────────┬──────────────────────────────────────┘
│ POST /aiChat/avatar/chat/stream
│ (Blade-Auth JWT)
▼
┌─────────────────────────────────────────────────────────────────┐
│ rjhj-business 服务 │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ AvatarChatController │ │
│ │ ├─ /chat (同步阻塞) │ │
│ │ └─ /chat/stream (SSE 流式) │ │
│ └───────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────┐ │
│ │ AvatarChatService │ │
│ │ ├─ 组装 inputs (userId, gridCode, inputType) │ │
│ │ ├─ 调用 Dify API (response_mode=streaming) │ │
│ │ ├─ 解析 SSE 事件流 → 转发给前端 │ │
│ │ └─ 落库 t_avatar_chat_record │ │
│ └───────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────┐ │
│ │ 内网工具 Controller 层(无登录态,Token 鉴权) │ │
│ │ ├─ InternalEventController /internal/event/query │ │
│ │ ├─ InternalUserStatisticController /internal/userStatistic/query │
│ │ ├─ InternalEffectDetectionController │ │
│ │ │ ├─ /internal/effectDetection/pilotVillage │ │
│ │ │ └─ /internal/effectDetection/indicator │ │
│ │ └─ 统一鉴权: X-Internal-Token / Authorization / query │ │
│ └───────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────┐ │
│ │ Service 层 + Redis 缓存 (@Cacheable ONE_HOUR_CACHE) │ │
│ │ ├─ IProvincialService / IEventService (事件三率) │ │
│ │ ├─ UserQueryStatisticService (关注数/粉丝量) │ │
│ │ └─ IInternalEffectDetectionService (成效指标/先行村) │ │
│ └───────────────────────┬───────────────────────────────────┘ │
│ │ │
└──────────────────────────┼──────────────────────────────────────┘
│ Feign
▼
┌─────────────────────────────────────────────────────────────────┐
│ rjhj-system (网格服务) │ rjhj-event (事件服务) │
│ IGridClient │ EventAiReportMapper │
│ ├─ getByCode │ t_event_new │
│ ├─ getChildrenByCode │ │
│ ├─ getAllByCode │ │
│ ├─ getParentByCode │ │
│ └─ getPathByCode │ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Dify Agent 平台 │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Agent (FunctionCalling 策略, qwen-max) │ │
│ │ ├─ 系统提示词 v2.7 (拒答门禁 + 分流规则 + 指标目录) │ │
│ │ ├─ 开始节点变量: userId, gridCode, inputType │ │
│ │ └─ 6 个工具: │ │
│ │ ① queryEventStats (事件统计) │ │
│ │ ② queryAttention (关注数/粉丝量) │ │
│ │ ③ queryPilotVillage (先行村建设) │ │
│ │ ④ queryIndicator (成效指标) │ │
│ │ ⑤ 数字人知识库工作流 (RAG 检索) │ │
│ │ ⑥ JINA 联网搜索 (外网补充) │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
三、Dify Agent 配置详解
3.1 应用类型与模型选择
| 配置项 | 值 | 说明 |
|---|---|---|
| 应用类型 | Agent | FunctionCalling 策略,模型自主决定调用哪个工具 |
| 模型 | qwen-max | 32K 上下文窗口,支持中文工具调用 |
| max_tokens | 8192 | 输出上限,需与提示词长度平衡 |
| 开始节点变量 | userId / gridCode / inputType | 由后端注入,作为权限边界和交互模式控制 |
3.2 工具注册方式
所有业务数据工具通过 OpenAPI 3.0.1 Schema 导入 Dify,而非手动配置参数。这样做的好处:
- 参数类型、枚举值、描述一次性定义,Dify 自动生成工具卡片
- 后端接口变更时只需更新 YAML 重新导入,无需逐个修改
- Schema 即文档,前后端、Dify 三方共用一份定义
每个工具的鉴权采用 Query 参数 internalToken 方式(后续计划迁移至 Header X-Internal-Token,避免 Token 出现在访问日志中)。
3.3 六大工具能力矩阵
| 工具 | 端点 | queryType 枚举 | 核心能力 |
|---|---|---|---|
| queryEventStats | /internal/event/query |
total / category / selfRate / nextGrid / nextTwoGrid | 事件总数、分类占比、三率(完结率/及时率/超时率)、下级排名、下两级排名 |
| queryAttention | /internal/userStatistic/query |
total / rank (selectType=1下辖/2同级) | 关注数(粉丝量)总数、下辖排名、同级排名 |
| queryPilotVillage | /internal/effectDetection/pilotVillage |
countyList / byTown / list / detail / sameTown | 区县分类、乡镇分布、先行村列表、村庄详情、同乡镇对比 |
| queryIndicator | /internal/effectDetection/indicator |
childData / childDataTwoLevel / siblingData / pathData / relationData / target / latest / history / caseList | 下级对比、下两级跨级排名、同级排名、层级链路、关联指标、目标对标、最新概览、历史趋势、绑定案例 |
| 知识库工作流 | Dify 内部 RAG | --- | 月报/年报/口径说明/FAQ/政策文件检索 |
| JINA 联网搜索 | Dify 内置 | --- | 外网公开政策、治理经验补充(严格白名单控制) |
四、系统提示词工程
系统提示词是 Agent 行为的"宪法",共 740+ 行,分为以下核心模块:
4.1 拒答门禁(最高优先级)
提示词开篇即定义了一张 13 类拒答主题表 ,涵盖农业产值、龙头企业、电商销售额、教共体/医共体等平台无权威数据源的领域。命中即触发标准拒答话术,禁止调用任何工具、禁止联网搜索、禁止输出任何数字。
这一设计源于实际测试中发现的严重问题:模型在拒答前会先调用 JINA 搜索,把外网数字念出来后再补一句"平台暂未接入"------数字已经出口,拒答形同虚设。通过将拒答门禁置于提示词最前端并标注"最高优先级",从根本上切断了这一路径。
4.2 四路分流规则
用户问题
│
├─ 命中拒答门禁? ──→ 标准话术,结束
│
├─ 实时业务数据? ──→ 调用对应工具(queryEventStats / queryAttention / queryIndicator / queryPilotVillage)
│
├─ 平台文档/口径? ──→ 调用知识库工作流
│
├─ 政策/经验做法? ──→ 平台数据 + JINA 联网搜索(仅 7 类白名单)
│
└─ 其他 ──→ 如实告知无法回答
4.3 成效监测指标目录(内联)
提示词中内联了一张 37 行指标目录表 ,包含指标编码(如 CS_TOILET_POPULARIZATION_RATE)、中文名称、单位。模型必须将用户口语(如"改厕率""厕所覆盖率")与目录整行比对后取出编码,严禁拼造、严禁凭 _NUM/_RATE 后缀推断含义。
之所以不挂知识库而是内联,是因为知识库检索存在"只命中部分行"的问题------模型看到 3 行就以为目录只有 3 行,导致编码匹配失败。内联确保模型每次都能看到完整目录。
4.4 防幻觉与防评价规则
- 禁止推测原因、预测趋势:工具没有返回"原因/因素/预测"类字段时,不得用"通常情况下""可能由......造成"等句式自行补充
- 禁止对数据做评价:不得使用"非常高""表现良好""接近满分"等主观评价,不得用"这说明""表明""反映了"做推论
- 禁止编造数字:工具返回无数据时如实说明"该区域暂未录入此指标数据",不得用邻近指标或邻近区域顶替
4.5 queryIndicator 调用规则(防崩溃)
针对省级大范围查询导致后端崩溃的问题,提示词中新增了 5 条硬性规则:
- 禁止在省、大市等大范围使用
deep=true - "全省各县排名"类问题优先用
childDataTwoLevel(省→县,跳过市级) - "本市在全省排第几"类问题用
siblingData(同级排名) deep=true被降级时 (fallback=true),回答中说明"范围过大,已按直接下级展示"- 除上述场景外,
childData默认deep=false
五、后端关键实现
5.1 SSE 流式输出
传统同步接口存在"等待时间长、无反馈、结果一次性输出"的问题。我们新增了 SSE(Server-Sent Events)流式接口:
java
@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter streamChat(@RequestBody AvatarChatParam param) {
MultiUserModel user = UserUtil.getMultiUser();
return avatarChatService.streamChat(user, param);
}
实现要点:
- 使用 Spring
SseEmitter(超时设为 0,即不超时) - 自建
ThreadPoolTaskExecutor(核心 4 线程,最大 8 线程),不依赖@EnableAsync(该服务无全局异步开关,裸@Async实为同步执行) - 后端以
response_mode=streaming调用 Dify API,逐行解析 SSE 事件流 - 解析 Dify 事件类型并映射为前端事件:
| Dify 事件 | 前端 SSE 事件 | 说明 |
|---|---|---|
agent_thought (tool_call) |
tool (status=running) |
工具开始调用,显示"正在查询XXX..." |
agent_thought (tool_response) |
tool (status=completed) |
工具调用完成 |
agent_message / message |
message |
文本片段,前端打字机效果追加 |
message_end |
done |
完整 AvatarChatVO(含 sessionId、suggestedQuestions) |
| 异常 | error |
错误信息 |
- 流结束后异步落库
t_avatar_chat_record(含原始回答、清洗后回答、Token 用量、耗时)
5.2 网格子树防越权模型
所有内网工具接口共享同一套权限校验逻辑:
用户身份网格码 userGridCode(Dify 开始节点注入)
│
▼
目标区域解析(gridCode 优先 → gridName 名称转码 → 默认身份网格)
│
▼
前缀校验:target.gridCode.startsWith(userGridCode)
│
┌────┴────┐
│ 通过 │ 拒绝
▼ ▼
查询数据 抛出 ServiceException("超出管辖范围")
名称转码 支持口语简称:用户说"九江",后端自动尝试"九江市"→"九江"→剥离后缀,通过 IGridClient.getByName 精确匹配。同时识别"各市""全县""所有区"等泛指词,避免误将其当作区域名查询。
5.3 Redis 缓存策略
对查询频率高、数据变化慢的接口添加 @Cacheable(1 小时 TTL):
| 方法 | 缓存 Key 组成 | 说明 |
|---|---|---|
queryIndicator |
queryType + userGridCode + gridCode + indicatorId + indicatorCode + dataDate + deep | 覆盖所有 9 种查询维度 |
getCountByGridCode |
gridCode | 区域关注数总数 |
queryNextGuanzhuCnt |
code + selectType | 关注数排名 |
缓存 Key 中不包含 internalToken,避免同一查询因 Token 轮换而缓存失效。
六、关键技术挑战与解决方案
6.1 模型幻觉与数据编造
挑战: qwen-max 在工具返回空数据或报错时,倾向于用外网搜索到的数字"补位",甚至自行编造统计数据。
解决:
- 拒答门禁前置(提示词最高优先级)
- JINA 联网搜索严格白名单(仅 7 类政策/经验问题允许调用)
- 禁止输出外网具体数字(只允许做法与机制描述)
- 工具失败时只说明"查询暂时不可用",不得改口用外网数字顶替
6.2 大范围查询导致后端崩溃
挑战: 省级 deep=true 查询返回数万个网格,触发 500 上限异常。
解决:
- 新增
childDataTwoLevel(下两级)和siblingData(同级)查询维度 deep=true超限自动降级 +fallback标志- 提示词硬性规则禁止大范围
deep=true
6.3 上下文窗口耗尽导致回答截断
挑战: 740 行系统提示词 + 6 个工具 Schema + 8192 max_tokens,频繁触发 qwen-max 的 32K 上下文窗口上限,回答被截断。
解决:
- 指标目录内联而非挂知识库(减少检索开销)
- 工具 Schema 精简描述(去掉冗余示例)
- 前端 SSE 流式输出(即使截断也能展示已生成部分)
- 后续计划:关闭 Dify 联网搜索(减少 Token 消耗)、调整 max_tokens
6.4 无登录态下的权限隔离
挑战: Dify 工具回调走内网,无用户登录态,无法使用框架自带的 UserUtil.getMultiUser()。
解决:
- 用户身份网格码
userGridCode由 Dify 开始节点变量注入(后端在调用 Dify 时传入) - 内网工具接口独立实现
resolveGrid()+ 前缀校验 - Token 鉴权支持三种传递方式(Header / Authorization / Query),兼容 Dify 不同版本的鉴权控件
6.5 口语区域名与库名不一致
挑战: 用户说"九江",库里存的是"九江市";用户说"南昌县",库里可能同时存在"南昌"和"南昌县"两条网格。
解决:
- 裸名优先补全行政区划后缀("九江"→"九江市"→"九江")
- 泛指词识别("各市""全县""所有区"不作为区域名查询)
- 多级兜底:精确匹配 → 补后缀 → 剥后缀
七、总结
本系统通过 Dify Agent + FunctionCalling + 内网工具回调 的架构,实现了自然语言到多源业务数据的精准路由。核心技术点包括:
- 提示词工程:拒答门禁前置、四路分流、指标目录内联、防幻觉规则,从源头控制模型行为
- 网格子树权限模型 :无登录态下通过
userGridCode前缀校验实现数据隔离 - SSE 流式输出:自建线程池 + Dify streaming API + 事件映射,解决等待体验问题
- 弹性查询设计:9 种 queryType + deep 降级 + fallback 标志,兼顾灵活性与稳定性
- Redis 缓存:1 小时 TTL 覆盖高频查询,降低数据库压力