第七章：工具与插件系统

7.1 工具系统概述

7.1.1 什么是工具

工具（Tools）是 Dify 平台中用于扩展 LLM 能力的功能模块。通过工具，LLM 可以：

  • 联网搜索：获取实时信息
  • 科学计算：执行复杂计算
  • 绘制图片：生成图像内容
  • 访问 API：与外部系统交互

工具赋予并增强了 LLM 连接外部世界的能力，使 AI 应用能够执行真实世界的操作。

7.1.2 工具的作用

扩展应用能力： 为 Agent 和工作流提供更多功能，完成单纯 LLM 无法完成的任务。

系统集成： 将 AI 应用与其他系统或服务连接，实现数据交换和流程自动化。

环境交互： 让 AI 能够执行代码、访问数据库、控制外部设备等。

7.1.3 工具类型

Dify 提供两大类工具：

第一方工具（内置工具）：

  • Dify 官方提供和维护
  • 开箱即用
  • 定期更新和优化

自定义工具：

  • 用户自行创建
  • 基于 OpenAPI 规范
  • 支持任意 API 接入

7.2 内置工具详解

7.2.1 搜索类工具

Google 搜索：

功能: 执行 Google SERP 搜索，提取片段和网页
配置:
  - API Key: 需要 Google Custom Search API Key
  - Search Engine ID: 自定义搜索引擎 ID
使用场景:
  - 获取最新信息
  - 事实核查
  - 研究调研

Bing 搜索：

功能: 使用 Bing 搜索引擎搜索
配置:
  - API Key: Azure Cognitive Services Key
使用场景:
  - 替代 Google 搜索
  - 特定地区搜索优化

DuckDuckGo：

功能: 隐私友好的搜索
配置: 无需 API Key
使用场景:
  - 快速搜索
  - 无需配置的简单搜索

Wikipedia：

功能: 搜索维基百科内容
配置: 无需配置
使用场景:
  - 百科知识查询
  - 背景信息获取

7.2.2 计算类工具

WolframAlpha：

功能: 强大的计算知识引擎
配置:
  - App ID: WolframAlpha API Key
能力:
  - 数学计算
  - 科学问答
  - 数据分析
  - 单位换算
使用场景:
  - 复杂数学运算
  - 科学问题解答
  - 数据查询

代码执行器：

功能: 运行 Python/JavaScript 代码
配置: 无需配置
限制:
  - 执行时间限制
  - 内存限制
  - 无网络访问
  - 无文件系统访问
使用场景:
  - 数据处理
  - 计算分析
  - 格式转换

7.2.3 生成类工具

DALL-E：

功能: 通过自然语言生成图片
配置:
  - OpenAI API Key
参数:
  - 图片尺寸: 256x256, 512x512, 1024x1024
  - 图片数量: 1-10
使用场景:
  - 创意设计
  - 内容配图
  - 概念可视化

Stable Diffusion：

功能: 本地部署的图片生成
配置:
  - WebUI 地址
  - 可选：模型配置
使用场景:
  - 需要更多控制的图片生成
  - 隐私敏感场景
  - 自定义模型使用

图表生成：

功能: 生成数据可视化图表
支持图表类型:
  - 柱状图
  - 折线图
  - 饼图
  - 散点图
  - 面积图
使用场景:
  - 数据报告
  - 分析展示
  - 业务仪表板

7.2.4 数据类工具

网页抓取：

功能: 爬取网页内容
配置: 无需配置
能力:
  - 提取网页文本
  - 获取页面结构
  - 支持动态页面（部分）
使用场景:
  - 信息收集
  - 内容聚合
  - 数据提取

雅虎财经：

功能: 获取财经数据
配置: 无需配置
能力:
  - 股票报价
  - 新闻资讯
  - 市场数据
使用场景:
  - 投资分析
  - 财经报告
  - 市场监控

7.2.5 实用类工具

当前时间：

功能: 获取当前时间
配置: 无需配置
输出:
  - 当前日期
  - 当前时间
  - 时区信息

Vectorizer：

功能: 将 PNG/JPG 转换为 SVG
配置:
  - API Key（可选）
使用场景:
  - 图像矢量化
  - Logo 处理
  - 图标制作

YouTube：

功能: 获取 YouTube 视频信息
配置:
  - YouTube API Key
能力:
  - 搜索视频
  - 获取视频统计
  - 提取字幕

7.3 工具配置与授权

7.3.1 配置步骤

步骤一：进入工具设置

  1. 点击左下角”设置”
  2. 选择”工具”选项卡
  3. 找到需要配置的工具

步骤二：添加凭据

  1. 点击工具右侧的”配置”
  2. 填入所需的 API Key 或凭据
  3. 点击”保存”

步骤三：验证配置

  1. 保存后系统自动验证
  2. 显示”已授权”状态表示成功
  3. 工作区所有成员可使用该工具

7.3.2 凭据管理

安全存储：

  • 所有凭据加密存储
  • 使用 PKCS1_OAEP 加密
  • 每个租户独立密钥对

权限范围：

  • 凭据配置后对工作区所有成员生效
  • 管理员可以更新或撤销凭据
  • 凭据不会在日志中明文显示

7.3.3 获取 API Key 指南

Google 搜索：

  1. 访问 Google Cloud Console
  2. 创建项目并启用 Custom Search API
  3. 创建 API Key
  4. 创建自定义搜索引擎获取 Search Engine ID

OpenAI（DALL-E）：

  1. 访问 platform.openai.com
  2. 登录或注册账户
  3. 进入 API Keys 页面
  4. 创建新的 API Key

WolframAlpha：

  1. 访问 developer.wolframalpha.com
  2. 注册开发者账户
  3. 创建应用获取 App ID

7.4 自定义工具开发

7.4.1 OpenAPI 规范

自定义工具基于 OpenAPI（Swagger）规范定义，支持 3.0 版本。

基本结构：

openapi: 3.0.0
info:
  title: 工具名称
  description: 工具描述
  version: 1.0.0

servers:
  - url: https://api.example.com

paths:
  /endpoint:
    get:
      summary: 操作描述
      operationId: operation_name
      parameters:
        - name: param1
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: object

7.4.2 创建自定义工具

步骤一：准备 API 确保你的 API：

  • 可通过 HTTP 访问
  • 有清晰的接口文档
  • 支持 JSON 格式

步骤二：编写 Schema

示例 - 天气查询工具：

openapi: 3.0.0
info:
  title: 天气查询 API
  description: 查询城市天气信息
  version: 1.0.0
servers:
  - url: https://api.weather.example.com
paths:
  /weather:
    get:
      summary: 获取天气信息
      operationId: getWeather
      parameters:
        - name: city
          in: query
          description: 城市名称
          required: true
          schema:
            type: string
        - name: units
          in: query
          description: 温度单位
          required: false
          schema:
            type: string
            enum: [metric, imperial]
            default: metric
      responses:
        '200':
          description: 天气信息
          content:
            application/json:
              schema:
                type: object
                properties:
                  temperature:
                    type: number
                  humidity:
                    type: number
                  description:
                    type: string

步骤三：导入到 Dify

  1. 进入”工具” → “自定义工具”
  2. 点击”创建自定义工具”
  3. 填写工具名称
  4. 粘贴或导入 OpenAPI Schema
  5. 配置认证方式
  6. 保存

7.4.3 认证配置

无认证：

安全方案: 无
适用: 公开 API

API Key：

安全方案: API Key
认证头: Authorization
认证值: Bearer YOUR_API_KEY
# 或
认证头: X-API-Key
认证值: YOUR_API_KEY

Basic Auth：

安全方案: HTTP Basic
用户名: your_username
密码: your_password

7.4.4 测试自定义工具

测试步骤：

  1. 在工具配置页面点击”测试”
  2. 填入测试参数
  3. 执行测试
  4. 查看返回结果
  5. 确认无误后保存

7.4.5 工具描述最佳实践

清晰的描述：

# 好的描述
summary: 查询指定城市的实时天气信息，包括温度、湿度和天气状况

# 不好的描述
summary: 获取天气

参数说明：

parameters:
  - name: city
    description: 城市名称，支持中文和英文，例如：北京、Shanghai
    # 而不是
    description: 城市

7.5 插件生态系统

7.5.1 什么是插件

插件（Plugin）是 Dify 平台的新一代扩展模块，是工具系统的升级版本。插件系统提供：

  • 更丰富的类型：不仅是工具，还包括模型、策略等
  • 更好的封装：完整的功能包
  • 更便捷的分发：通过 Marketplace 发现和安装
  • 更灵活的开发：完善的 SDK 支持

7.5.2 插件类型

Models（模型）： 接入各类 AI 模型的插件，无需复杂配置即可使用新模型。

Tools（工具）： 被 Chatflow/Workflow/Agent 调用的第三方服务。

Agent 策略： 为 Agent 节点提供不同的推理和决策逻辑。

Extensions（扩展）： 通过 HTTP 服务调用的轻量级扩展功能。

Bundle（插件包）： 预组合的插件集合，一次安装多个相关插件。

7.5.3 Dify Marketplace

Dify Marketplace 是官方的插件市场：

访问地址：https://marketplace.dify.ai/

功能特性：

  • 浏览和搜索插件
  • 查看插件详情和评价
  • 一键安装到 Dify
  • 开发者发布插件

7.5.4 安装插件

从 Marketplace 安装：

  1. 访问 Dify Marketplace
  2. 找到需要的插件
  3. 点击”安装”
  4. 在 Dify 中配置插件

从 GitHub 安装：

  1. 获取插件 GitHub 仓库地址
  2. 在 Dify 中点击”从 GitHub 安装”
  3. 输入仓库地址
  4. 完成安装

本地文件安装：

  1. 下载插件文件（.difypkg）
  2. 在 Dify 中点击”上传插件”
  3. 选择文件完成安装

7.5.5 管理插件

查看已安装插件：

  1. 进入”设置” → “插件”
  2. 查看插件列表

插件操作：

  • 启用/禁用
  • 更新版本
  • 配置参数
  • 卸载移除

7.6 插件开发入门

7.6.1 开发环境准备

安装 Dify 插件 SDK：

pip install dify-plugin

创建插件项目：

dify plugin create my-plugin
cd my-plugin

7.6.2 插件项目结构

my-plugin/
├── manifest.yaml      # 插件清单
├── main.py           # 入口文件
├── requirements.txt  # 依赖
├── README.md         # 说明文档
└── icon.png          # 插件图标

7.6.3 插件清单（manifest.yaml）

name: my-plugin
version: 1.0.0
description: 我的第一个插件
author: Your Name
icon: icon.png

type: tool  # tool, model, agent_strategy, extension

entry: main:MyPlugin

permissions:
  - network  # 网络访问
  
settings:
  - name: api_key
    type: string
    required: true
    description: API 密钥

7.6.4 工具插件示例

# main.py
from dify_plugin import Plugin, ToolProvider

class MyPlugin(Plugin):
    """我的插件"""
    
    def __init__(self, settings):
        self.api_key = settings.get('api_key')
    
    def get_tools(self):
        return [MyTool(self.api_key)]


class MyTool(ToolProvider):
    """我的工具"""
    
    name = "my_tool"
    description = "工具描述"
    
    parameters = {
        "query": {
            "type": "string",
            "description": "查询内容",
            "required": True
        }
    }
    
    def __init__(self, api_key):
        self.api_key = api_key
    
    def execute(self, query: str) -> dict:
        # 实现工具逻辑
        result = self._call_api(query)
        return {"result": result}
    
    def _call_api(self, query):
        # 调用外部 API
        import requests
        response = requests.get(
            "https://api.example.com/search",
            params={"q": query},
            headers={"Authorization": f"Bearer {self.api_key}"}
        )
        return response.json()

7.6.5 测试和发布

本地测试：

dify plugin test

打包：

dify plugin build
# 生成 my-plugin.difypkg

发布到 Marketplace：

  1. 在 Marketplace 注册开发者账号
  2. 提交插件包和相关信息
  3. 等待审核
  4. 审核通过后上线

7.7 使用 Cloudflare Workers

7.7.1 简介

Cloudflare Workers 可以快速部署自定义工具，无需管理服务器。

7.7.2 使用 dify-tools-worker

项目地址： https://github.com/crazywoola/dify-tools-worker

特性：

  • 开箱即用的工具框架
  • 自动生成 OpenAPI 文档
  • 一键部署到 Cloudflare

7.7.3 部署步骤

# 克隆项目
git clone https://github.com/crazywoola/dify-tools-worker.git
cd dify-tools-worker

# 安装依赖
npm install

# 部署
npm run deploy

导入到 Dify： 部署后访问 https://your-worker.workers.dev/doc 获取 OpenAPI 文档，导入到 Dify 的自定义工具。

7.8 最佳实践

7.8.1 工具选择原则

按需选择：

  • 只添加必要的工具
  • 避免功能重复的工具
  • 工具过多会影响 Agent 决策

匹配场景：

  • 信息查询：搜索类工具
  • 数据处理：代码执行工具
  • 系统集成：HTTP 请求工具

7.8.2 性能优化

减少调用次数：

  • 合理设计工具功能
  • 避免不必要的工具调用
  • 使用缓存减少重复请求

控制响应时间：

  • 设置合理的超时时间
  • 异步处理长时间任务
  • 提供降级方案

7.8.3 安全考虑

凭据安全：

  • 不在代码中硬编码密钥
  • 定期轮换 API Key
  • 使用最小权限原则

数据保护：

  • 注意传输数据的敏感性
  • 遵循数据保护法规
  • 记录工具调用日志

7.8.4 工具文档

完善的文档：

  • 清晰的功能描述
  • 详细的参数说明
  • 使用示例
  • 常见问题解答

7.9 本章小结

通过本章的学习，你应该掌握：

  1. 工具系统：理解工具的作用和类型
  2. 内置工具：熟悉各类内置工具的功能和配置
  3. 自定义工具：掌握基于 OpenAPI 创建自定义工具的方法
  4. 插件生态：了解插件系统和 Marketplace
  5. 插件开发：初步了解插件开发流程
  6. 最佳实践：掌握工具使用的最佳实践

7.10 思考与练习

  1. 实践练习：
    • 配置 Google 搜索工具
    • 创建一个调用外部 API 的自定义工具
    • 从 Marketplace 安装一个插件
  2. 思考题：
    • 如何设计工具以提高 Agent 的工作效率？
    • 自定义工具和插件有什么区别？
    • 如何保证工具使用的安全性？

下一章预告：第八章将介绍模型接入与配置，包括各类模型供应商的接入方法和参数调优技巧。

← 上一章 目录 下一章 →