Dify 集成

通过 Orchestrator 的 External 类型集成 Dify AI 应用,实现企业知识库问答、工作流自动化等功能。

什么是 Dify

Dify 是一个开源的 LLM 应用开发平台,支持:

🤖 AI 对话应用: 基于知识库的智能问答
⚙️ Workflow 工作流: 复杂的 AI 任务编排
📚 知识库管理: 企业文档向量化和检索
🔧 工具调用: AI Agent 使用外部工具

集成架构

用户消息
  ↓
Application (企业微信/Web)
  ↓
Orchestrator (External 类型)
  ↓
Dify Adapter
  ↓
Dify API (4种应用类型)
  ↓
响应返回

Dify 应用类型

Sira AI 支持 Dify 的 4 种应用类型:

类型	说明	适用场景	API 端点
CHAT	对话型应用	多轮对话,知识库问答	`/v1/chat-messages`
COMPLETION	文本生成型	单次文本生成,不保留上下文	`/v1/completion-messages`
WORKFLOW	工作流应用	复杂任务编排,多步骤处理	`/v1/workflows/run`
ADVANCED_CHAT	工作流编排对话型	对话 + 工作流混合	`/v1/chat-messages`

推荐类型

多轮对话 → CHAT 或 ADVANCED_CHAT
单次生成 → COMPLETION
复杂流程 → WORKFLOW

配置步骤

1. 在 Dify 中准备应用

创建 Dify 应用:

登录 Dify 管理后台
创建应用并选择类型
配置知识库、提示词、工具等
发布应用

获取 API 信息:

进入应用详情页
找到 API 访问 部分
复制 API 密钥 (api-xxx 格式)
记录 API 端点地址

2. 创建 Orchestrator

进入 Orchestrator 管理:

导航到 Agent System → 编排器 → 创建编排器
填写基础信息:
- 名称: dify_knowledge_base
- 显示名称: Dify 知识库问答
- 描述: 功能说明

选择编排类型:

类型: External
外部系统: Dify

3. 配置 Dify 参数

必填参数

字段	说明	示例
API Base URL	Dify API 地址	`https://api.dify.ai/v1`
API Key	Dify 应用密钥	`app-xxxxxxxxxxxxx`
应用类型	选择 Dify 应用类型	`chat` / `completion` / `workflow` / `advanced_chat`

API Base URL 格式:

bash

# 完整格式（推荐）
https://api.dify.ai/v1

# 也支持不带 /v1（系统自动添加）
https://api.dify.ai

# 自建 Dify
https://your-dify.example.com/v1

可选参数

会话管理:

会话持久化 (conversation_persistence):
- 默认: true
- 启用后保留 24 小时对话上下文
- 支持多轮对话记忆

显示选项:

显示 Agent 思考过程 (show_agent_thoughts):
- 显示 Dify Agent 的推理步骤
- 示例: 💭 正在思考...
显示工作流进度 (show_workflow_progress):
- 显示 Workflow 执行节点
- 示例: 🔄 正在执行节点: 数据提取

自定义输入 (custom_inputs): 传递额外变量给 Dify 工作流,支持占位符:

json

{
  "user_input": "{{message}}",
  "user_id": "{{user_id}}",
  "department": "销售部",
  "priority": "high"
}

支持的占位符:

{{message}} - 用户消息
{{user_id}} - 用户ID
{{session_id}} - 会话ID

4. 保存并测试

点击创建保存 Orchestrator
创建 Agent (可使用任意 LLM 模型,不会被实际调用)
创建 Application 绑定该 Orchestrator
发送测试消息验证集成

应用示例

示例 1: 知识库问答 (CHAT)

Dify 配置:

应用类型: 对话型应用
绑定企业知识库
配置检索策略和重排序

Orchestrator 配置:

json

{
  "type": "external",
  "external_config": {
    "system_type": "dify",
    "api_base_url": "https://api.dify.ai/v1",
    "api_key": "app-knowledge-base-key",
    "app_type": "chat",
    "conversation_persistence": true,
    "show_agent_thoughts": true
  }
}

效果:

用户提问自动检索知识库
多轮对话保持上下文
显示检索和推理过程

示例 2: 工作流自动化 (WORKFLOW)

Dify 配置:

应用类型: Workflow
设计多步骤流程:
1. 意图识别
2. 数据提取
3. API 调用
4. 结果整合

Orchestrator 配置:

json

{
  "type": "external",
  "external_config": {
    "system_type": "dify",
    "api_base_url": "https://api.dify.ai/v1",
    "api_key": "app-workflow-key",
    "app_type": "workflow",
    "show_workflow_progress": true,
    "custom_inputs": {
      "user_message": "{{message}}",
      "source": "wechat_work"
    }
  }
}

效果:

自动执行多步骤流程
显示每个节点执行进度
传递自定义参数给工作流

示例 3: 文本生成 (COMPLETION)

Dify 配置:

应用类型: 文本生成型
配置生成提示词模板
不需要知识库

Orchestrator 配置:

json

{
  "type": "external",
  "external_config": {
    "system_type": "dify",
    "api_base_url": "https://api.dify.ai/v1",
    "api_key": "app-completion-key",
    "app_type": "completion",
    "custom_inputs": {
      "query": "{{message}}",
      "style": "professional"
    }
  }
}

效果:

单次文本生成
不保留对话历史
适合摘要、翻译等任务

流式响应

Dify 集成支持完整的流式响应:

流式输出格式

文本流式:

正在思考... (如果启用 show_agent_thoughts)
这是第一部分回答
这是第二部分回答
完成

Agent Thoughts:

💭 思考: 用户询问产品价格
🔧 工具: 调用价格查询API
📊 结果: 获取到价格信息
✅ 生成回答...

Workflow Progress:

🔄 正在执行: 意图识别
✅ 完成: 意图识别
🔄 正在执行: 数据提取
✅ 完成: 数据提取
...

强制流式

Dify 的 blocking 模式存在返回内容不完整的 bug,系统会自动强制使用 streaming 模式。

对话记忆

Conversation ID 管理

Dify 通过 conversation_id 维护对话上下文:

首次对话:

用户: "我叫张三"
→ Dify 返回 conversation_id: "abc-123"
→ 系统保存到 Redis: external:dify:conversation:{session_id}

后续对话:

用户: "我叫什么名字?"
→ 系统从 Redis 读取 conversation_id: "abc-123"
→ 传递给 Dify API
→ Dify 识别对话并回答: "你叫张三"

配置说明

启用对话记忆:

json

{
  "conversation_persistence": true
}

禁用对话记忆 (每次都是新对话):

json

{
  "conversation_persistence": false
}

记忆有效期: 24 小时 (Redis TTL)

常见问题

配置相关

Q: API Base URL 应该填什么?

Dify 云服务: https://api.dify.ai/v1
自建 Dify: https://your-dify.example.com/v1
支持不带 /v1,系统会自动添加

Q: 如何获取 API Key?

登录 Dify 管理后台
进入应用详情页
找到 "API 访问" 部分
复制 API 密钥 (格式: app-xxxxx)

Q: 应用类型如何选择?

多轮对话 → chat 或 advanced_chat
单次生成 → completion
复杂流程 → workflow

功能相关

Q: 对话记忆不生效?

A: 检查:

conversation_persistence 是否为 true
Redis 是否正常运行
session_id 是否一致

Q: 如何传递自定义变量给 Dify?

A: 使用 custom_inputs 配置:

json

{
  "custom_inputs": {
    "my_var": "{{message}}",
    "department": "销售部"
  }
}

Q: Workflow 类型需要 conversation_id 吗?

A: Workflow 通常不需要对话上下文,可以禁用:

json

{
  "app_type": "workflow",
  "conversation_persistence": false
}

错误处理

Q: 返回 401 Unauthorized

A: API Key 错误或已失效,重新从 Dify 获取

Q: 返回 404 Not Found

检查 API Base URL 是否正确
检查应用类型与实际 Dify 应用是否匹配

Q: 响应内容不完整

A: 这是 Dify blocking 模式的 bug,系统已自动启用 streaming 模式解决

最佳实践

知识库应用

检索优化:
- 在 Dify 中配置合适的检索策略
- 启用重排序提升精准度
- 设置合理的召回数量
显示优化:
- 启用 show_agent_thoughts 显示检索过程
- 用户能看到 AI 的思考和数据来源

工作流应用

进度反馈:
- 启用 show_workflow_progress
- 用户能看到执行到哪一步
参数传递:
- 使用 custom_inputs 传递必要参数
- 使用占位符动态替换值

性能优化

缓存策略:
- 启用 conversation_persistence 减少重复检索
- 相同问题直接从对话历史获取
超时设置:
- Workflow 可能较慢,设置合理超时 (60s+)
- 简单对话设置 30s 即可

下一步

N8N 集成 - 集成 N8N 工作流
创建 Orchestrator - Orchestrator 完整教程
创建 Application - 创建应用绑定 Orchestrator

Dify 集成 ​

什么是 Dify ​

集成架构 ​

Dify 应用类型 ​

配置步骤 ​

1. 在 Dify 中准备应用 ​

2. 创建 Orchestrator ​

3. 配置 Dify 参数 ​

必填参数 ​

可选参数 ​

4. 保存并测试 ​

应用示例 ​

示例 1: 知识库问答 (CHAT) ​

示例 2: 工作流自动化 (WORKFLOW) ​

示例 3: 文本生成 (COMPLETION) ​

流式响应 ​

流式输出格式 ​

对话记忆 ​

Conversation ID 管理 ​

配置说明 ​

常见问题 ​

配置相关 ​

功能相关 ​

错误处理 ​

最佳实践 ​

知识库应用 ​

工作流应用 ​

性能优化 ​

下一步 ​

Dify 集成

什么是 Dify

集成架构

Dify 应用类型

配置步骤

1. 在 Dify 中准备应用

2. 创建 Orchestrator

3. 配置 Dify 参数

必填参数

可选参数

4. 保存并测试

应用示例

示例 1: 知识库问答 (CHAT)

示例 2: 工作流自动化 (WORKFLOW)

示例 3: 文本生成 (COMPLETION)

流式响应

流式输出格式

对话记忆

Conversation ID 管理

配置说明

常见问题

配置相关

功能相关

错误处理

最佳实践

知识库应用

工作流应用

性能优化

下一步