技术文章-基于Dify-Agent的智能问答系统设计与实现

基于 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,而非手动配置参数。这样做的好处:

  1. 参数类型、枚举值、描述一次性定义,Dify 自动生成工具卡片
  2. 后端接口变更时只需更新 YAML 重新导入,无需逐个修改
  3. 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 条硬性规则:

  1. 禁止在省、大市等大范围使用 deep=true
  2. "全省各县排名"类问题优先用 childDataTwoLevel(省→县,跳过市级)
  3. "本市在全省排第几"类问题用 siblingData(同级排名)
  4. deep=true 被降级时 (fallback=true),回答中说明"范围过大,已按直接下级展示"
  5. 除上述场景外,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 + 内网工具回调 的架构,实现了自然语言到多源业务数据的精准路由。核心技术点包括:

  1. 提示词工程:拒答门禁前置、四路分流、指标目录内联、防幻觉规则,从源头控制模型行为
  2. 网格子树权限模型 :无登录态下通过 userGridCode 前缀校验实现数据隔离
  3. SSE 流式输出:自建线程池 + Dify streaming API + 事件映射,解决等待体验问题
  4. 弹性查询设计:9 种 queryType + deep 降级 + fallback 标志,兼顾灵活性与稳定性
  5. Redis 缓存:1 小时 TTL 覆盖高频查询,降低数据库压力
相关推荐
码事漫谈2 小时前
2027年火的很可能是AI工作台
后端
Flynn Liang2 小时前
I/O 密集型高并发实战:Java 服务 10 维优化,从线程打满到 10 万 QPS
java·spring boot·性能优化·高并发·系统设计·虚拟线程·io密集型
吃我一窝jio3 小时前
Python与Go线程模型深度对比
java·开发语言·python
这个昵称不容易3 小时前
SpringBoot 购物推荐网站的设计与实现:120 个 Java 文件、147 个接口、13 张表,附真实运行截图
java·springboot·毕设
文丑颜不良啊3 小时前
LeetCode3041~3060题目解析
java·leetcode
文丑颜不良啊4 小时前
LeetCode3101~3120题目解析
java·leetcode
stormzhangV4 小时前
Coding Agent,通往 AGI 的重要一环
人工智能·agent·ai编程
Resean02235 小时前
SpringMVC 6+源码分析(十一)视图渲染与异步请求(收尾篇)
java·spring·springmvc
花椒技术5 小时前
Genie 4 刷屏之后,AI 视频生成正在走向下一阶段
agent·ai编程·音视频开发