Dify 使用方式与典型场景

四、使用方式与典型场景

示例一：用工作流搭「客服知识库问答」

目标：用户提问后，先在知识库检索，命中则基于资料回答并给出引用，未命中则转人工话术，整个应用可以被自有系统调用。

1. 建知识库：上传产品手册、售后政策、常见问题。分段按标题层级切，问答类内容按问答对切；索引方式选高质量并配置嵌入模型；开启混合检索，权重调到向量为主；Top K 先取 4 到 6，分数阈值从中位开始试。
2. 建 Workflow 应用，节点主线：开始，到知识检索，到条件分支，到 LLM，到结束。
3. 开始节点定义输入：query（字符串，必填）、user_id（字符串，可选，用于日志归因）。
4. 知识检索节点：挂上面建的知识库，查询变量引用开始节点的 query，输出为片段数组。
5. 条件分支节点：判断检索结果是否为空。条件可以写成「检索结果长度 > 0」这类可判定表达式；为空时走转人工分支，直接连到结束节点输出固定话术。
6. LLM 节点：模型选性价比高的对话模型，温度调低，事实型问答不需要发挥；上下文引用知识检索节点的输出。
7. 结束节点：输出 LLM 生成的文本，并额外输出命中片段的来源标题，供前端展示引用。

LLM 节点的提示词骨架：

你是客服知识库助手。只依据下面提供的资料回答问题。

资料：
{{知识检索结果}}

规则：
1. 资料中没有的信息，回答「资料中未提及，已为你转接人工」，不要编造。
2. 用中文回答，先给结论，再给必要步骤，控制在 200 字以内。
3. 涉及价格、时效、赔偿的条款，必须原文引用，不要改写数字。

用户问题：{{用户输入}}

调优顺序：先看运行历史里检索节点召回的内容对不对——召回错，就改分段与检索参数；召回对但答错，就改提示词与模型；都对但格式不对，再加模板转换或代码节点做后处理。不要一上来就换更大的模型，那是最后手段，也是最贵的手段。

示例二：用 API 把应用接进自有系统

在应用的访问 API 页面创建 API Key（形如 app-xxxxxxxx），Key 保存在服务端，不要下发到浏览器。下面是一次非流式调用：

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "退换货的时效是多久？",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-10086"
  }'

关键参数说明：query 是用户输入；inputs 对应应用里定义的输入变量；user 是你系统里的用户标识，务必传且保持稳定，它决定会话归属与日志归因；conversation_id 首轮留空，后续轮次把上一轮返回的值回传即可续上多轮上下文；response_mode 取 blocking 时等服务端算完一次性返回，取 streaming 时返回服务端推送的事件流。

流式模式下逐条返回 data: 开头的事件行，事件类型覆盖开始、节点执行、文本增量、结束与错误等（字段名以官方文档为准）。前端按行解析、把文本增量拼接起来，就能实现打字机效果。自托管环境把域名换成自己的地址，路径仍是 /v1/chat-messages。

API Key 管理要点：一个 Key 对应一个应用，按环境（测试、生产）分别建应用与 Key；Key 泄露时在页面直接删除重建，不要指望靠前端「隐藏」；对外限流放在自己的网关层做，因为 Dify 侧的并发能力同时受模型供应商配额与自身部署规格约束。除 /v1/chat-messages 之外，文本生成类应用用 /v1/completion-messages，工作流用 /v1/workflows/run，文件上传用 /v1/files/upload。

适合与不适合的场景