Dify集成

概述

Dify 是一款开源的大语言模型（LLM）应用开发平台。它融合了后端即服务（Backend as Service）和 LLMOps 的理念，使开发者可以快速搭建生产级的生成式 AI 应用。

SERVICEME 提供的 serviceme-rag-dify 插件，将 SERVICEME 强大的企业级检索增强生成（RAG）能力以工具形式提供给 Dify 工作流和应用，帮助用户在 Dify 中安全地访问企业知识库、执行上下文检索与问答。

主要能力涵盖：

• 针对 SERVICEME 工作区执行混合、向量或关键词检索。
• 返回结构化答案、元数据与工作区上下文，便于在后续节点中继续处理。
• 支持设置工作区范围、相似度阈值、混合权重与重排模型，匹配企业治理策略。
• 自动管理 OAuth 令牌状态，确保工具在令牌刷新后仍可调用。

最低版本与前置条件

• 最低支持版本：Dify ≥ 1.9.0。
• 可访问的 SERVICEME 环境，并已开启 OpenAPI 权限。
• 按 SERVICEME OpenAPI 认证指南 创建的 OAuth2 凭据（client_id、client_secret、用户账号）。
• 拥有导入并配置自定义插件的 Dify 工作区权限。

安装插件

通过 Marketplace 安装

1. 在 Dify 控制台右上角点击 Plugins > Install plugin > Marketplace。

2. 在搜索框输入 SERVICEME RAG 并回车。

   

3. 将鼠标悬停在第一个结果（SERVICEME RAG）上，点击 Install。

4. 安装完成后，会弹出成功提示，插件会自动出现在 Plugins 列表中。

   

通过 GitHub 安装

1. 在 Dify 控制台右上角点击 Plugins > Install plugin > GitHub。

   

2. 填写 serviceme-rag-dify仓库地址: https://github.com/medalsoftchina/serviceme-rag-dify 并点击 下一步。

3. 选择对应的版本和插件文件，点击 下一步。

   

4. 安装完成后，在 Plugins 列表中确认插件已显示。

   

通过本地 difypkg 安装

1. 访问 GitHub 仓库的 Release 页面，下载最新的 serviceme-rag-dify.difypkg。

2. 在 Dify 控制台选择 Plugins > Install plugin > Local Package Plugin，上传下载的安装包。

3. 完成成功后，确认弹出安装成功提示画面。

   

两种安装方式的功能完全一致，可根据部署环境的网络策略选择合适方式。

配置 OAuth2 认证

SERVICEME 插件使用 OAuth2 方式访问 SERVICEME OpenAPI 资源，请按以下步骤配置：

1. 在 SERVICEME 管理端进入超级管理员界面，系统管理员通过客户端管理界面 {domain}#/super-admin/client-management 创建凭据，生成 client_id 与 client_secret。

   

2. 在 Dify 控制台中点击插件，在侧边栏点击 Use OAuth Authorization。

   

3. 在 Vendor Configuration 中填写 SERVICEME 环境相关信息并点击 Save and Authorize：

   • Base URL：SERVICEME 域名（含协议），例如 https://example.serviceme.com。
   • Client Id / Client Secret：来自客户端管理界面的凭据。
   • Account：用于调用 OpenAPI 的 SERVICEME 用户名。

   

4. 保存后，如果一切正确，则显示绿色验证通过。插件会调用 /openapi/auth/client_with_account 获取访问令牌，并在令牌过期时自动刷新。

   

为简化授权控制，通过用户角色对SERVICEME的数据可见范围来控制OAuth的授权范围，可以参考OpenAPI章节。

在 Dify 中调用 SERVICEME RAG 工具

1. 前往 Dify 的 Studio，创建一个Chatflow工作流，命名为*Test SERVICEME。

   

2. 在画布点击Add Node > Tools > serviceme-rag。

   

3. 填写 Query String 和/或 Keywords后该节点即可执行。

   

4. 运行调试对话，验证工具返回结果是否符合预期。

参数说明

将 serviceme-rag 工具添加到节点后，可结合以下参数调整检索行为：

输入项	说明
query	可选，自然语言查询，未输入时可搭配 keywords 使用。
keywords	可选，关键词以 | 分隔。
workspaces	可选，限定搜索范围的 SERVICEME 工作区 ID 数组。
top_k	必填，返回结果数量。
rag_object	必填，检索对象：both、qna 或 doc。
rag_mode	必填，检索模式：hybrid、embedding 或 fulltext。
min_similarity	可选，相似度阈值，范围 0~1，默认 0.8。
metadata_filter	可选，元数据过滤，目前支持 default。
weights	可选，为混合检索配置 RRF 权重的 JSON。
reranker	可选，指定重排模型名称，留空即关闭重排。 注意：如果您的SERVICEME环境未开启重排模型，请务必留空

最佳实践

• 为不同业务场景创建独立的 OAuth2 客户端和 scope，降低越权风险。
• 使用 Dify 的版本管理功能，在生产环境发布前先在沙箱环境验证插件配置。
• 定期检查插件日志，及时发现调用异常。

常见问题排查

1. 认证失败
   • 确认 client_id 与 client_secret 是否正确。
   • 检查提供 scope 的账号是否在对应 SERVICEME 环境中设置了正确角色。
   • 确保 Dify 服务器能够访问 SERVICEME 地址。
2. 工具调用无数据返回
   • 检查绑定的数据源是否已完成同步。
   • 调整检索参数（如相似度阈值、召回数量）。
   • 验证调用账号是否被授权访问目标数据。
3. 插件安装异常
   • 查看 Dify 插件日志确认报错信息。
   • 若使用本地安装，确保 difypkg 文件完整且与 Dify 版本兼容。
   • 重新下载最新版本包并重试。
4. 第三方签名
   • 如Dify服务器采用自部署方式，并要求第三方插件签名，请联系Medalsoft对应的客户代表，获取签名的公钥文件

进一步阅读

• serviceme-rag-dify GitHub 仓库
• Dify Plugins 文档