Dify
简体中文
简体中文
  • 入门
    • 欢迎使用 Dify
      • 特性与技术规格
      • 模型供应商列表
    • 云服务
    • 社区版
      • Docker Compose 部署
      • 本地源码启动
      • 宝塔面板部署
      • 单独启动前端 Docker 容器
      • 环境变量说明
      • 常见问题
    • Dify Premium
    • Dify 教育版
  • 手册
    • 接入大模型
      • 增加新供应商
      • 预定义模型接入
      • 自定义模型接入
      • 接口方法
      • 配置规则
      • 负载均衡
    • 构建应用
      • 创建应用
      • 聊天助手
        • 多模型调试
      • Agent
      • 应用工具箱
        • 敏感内容审查
    • 工作流
      • 关键概念
      • 变量
      • 节点说明
        • 开始
        • LLM
        • 知识检索
        • 问题分类
        • 条件分支
        • 代码执行
        • 模板转换
        • 文档提取器
        • 列表操作
        • 变量聚合
        • 变量赋值
        • 迭代
        • 参数提取
        • HTTP 请求
        • Agent
        • 工具
        • 结束
        • 直接回复
        • 循环
      • 快捷键
      • 编排节点
      • 文件上传
      • 异常处理
        • 预定义异常处理逻辑
        • 错误类型
      • 附加功能
      • 预览与调试
        • 预览与运行
        • 单步调试
        • 对话/运行日志
        • 检查清单
        • 运行历史
      • 应用发布
      • 结构化输出
      • 变更公告:图片上传被替换为文件上传
    • 知识库
      • 创建知识库
        • 1. 导入文本数据
          • 1.1 从 Notion 导入数据
          • 1.2 从网页导入数据
        • 2. 指定分段模式
        • 3. 设定索引方法与检索设置
      • 管理知识库
        • 维护知识库内文档
        • 通过 API 维护知识库
      • 元数据
      • 在应用内集成知识库
      • 召回测试/引用归属
      • 知识库请求频率限制
      • 连接外部知识库
      • 外部知识库 API
    • 工具
      • 快速接入工具
      • 高级接入工具
      • 工具配置
        • Google
        • Bing
        • SearchApi
        • StableDiffusion
        • Dall-e
        • Perplexity Search
        • AlphaVantage 股票分析
        • Youtube
        • SearXNG
        • Serper
        • SiliconFlow (支持 Flux 绘图)
        • ComfyUI
    • 发布
      • 发布为公开 Web 站点
        • Web 应用的设置
        • 文本生成型应用
        • 对话型应用
      • 嵌入网站
      • 基于 APIs 开发
      • 基于前端组件再开发
    • 标注
      • 日志与标注
      • 标注回复
    • 监测
      • 集成外部 Ops 工具
        • 集成 LangSmith
        • 集成 Langfuse
        • 集成 Opik
      • 数据分析
    • 扩展
      • API 扩展
        • 使用 Cloudflare Workers 部署 API Tools
        • 敏感内容审查
      • 代码扩展
        • 外部数据工具
        • 敏感内容审查
    • 协同
      • 发现
      • 邀请与管理成员
    • 管理
      • 应用管理
      • 团队成员管理
      • 个人账号管理
      • 订阅管理
      • 版本管理
  • 动手实验室
    • 初级
      • 如何搭建 AI 图片生成应用
      • AI Agent 实战:搭建个人在线旅游助手
    • 中级
      • 使用文件上传搭建文章理解助手
      • 使用知识库搭建智能客服机器人
      • ChatFlow 实战:搭建 Twitter 账号分析助手
  • 社区
    • 寻求支持
    • 成为贡献者
    • 为 Dify 文档做出贡献
  • 插件
    • 功能简介
    • 快速开始
      • 安装与使用插件
      • 插件开发
        • 初始化开发工具
        • Tool 插件
        • Model 插件
          • 创建模型供应商
          • 接入预定义模型
          • 接入自定义模型
        • Agent 策略插件
        • Extension 插件
        • Bundle 插件包
      • 插件调试
    • 插件管理
    • 接口定义
      • Manifest
      • Endpoint
      • Tool
      • Agent
      • Model
        • 模型设计规则
        • 模型接口
      • 通用规范定义
      • 持久化存储
      • 反向调用 Dify 服务
        • App
        • Model
        • Tool
        • Node
    • 最佳实践
      • 开发 Slack Bot 插件
      • Dify MCP 插件指南:一键连接 Zapier 并自动发送邮件
    • 发布插件
      • 自动发布插件
      • 发布至 Dify Marketplace
        • 插件开发者准则
        • 插件隐私政策准则
      • 发布至个人 GitHub 仓库
      • 本地发布与分享
      • 第三方签名验证
    • 常见问题
  • 研发
    • 后端
      • DifySandbox
        • 贡献指南
    • 模型接入
      • 接入 Hugging Face 上的开源模型
      • 接入 Replicate 上的开源模型
      • 接入 Xinference 部署的本地模型
      • 接入 OpenLLM 部署的本地模型
      • 接入 LocalAI 部署的本地模型
      • 接入 Ollama 部署的本地模型
      • 接入 LiteLLM 代理的模型
      • 接入 GPUStack 进行本地模型部署
      • 接入 AWS Bedrock 上的模型(DeepSeek)
    • 迁移
      • 将社区版迁移至 v1.0.0
  • 阅读更多
    • 应用案例
      • DeepSeek 与 Dify 集成指南:打造具备多轮思考的 AI 应用
      • 本地私有化部署 DeepSeek + Dify,构建你的专属私人 AI 助手
      • 如何训练出专属于“你”的问答机器人?
      • 教你十几分钟不用代码创建 Midjourney 提示词机器人
      • 构建一个 Notion AI 助手
      • 如何在几分钟内创建一个带有业务数据的官网 AI 智能客服
      • 使用全套开源工具构建 LLM 应用实战:在 Dify 调用 Baichuan 开源模型能力
      • 手把手教你把 Dify 接入微信生态
      • 使用 Dify 和 Twilio 构建 WhatsApp 机器人
      • 将 Dify 应用与钉钉机器人集成
      • 使用 Dify 和 Azure Bot Framework 构建 Microsoft Teams 机器人
      • 如何让 LLM 应用提供循序渐进的聊天体验?
      • 如何将 Dify Chatbot 集成至 Wix 网站?
      • 如何连接 AWS Bedrock 知识库?
      • 构建 Dify 应用定时任务助手
      • 如何在 Dify 内体验大模型“竞技场”?以 DeepSeek R1 VS o1 为例
      • 在 Dify 云端构建 AI Thesis Slack Bot
      • 将 Dify 快速接入 QQ、微信、飞书、钉钉、Telegram、Discord 等平台
    • 扩展阅读
      • 什么是 LLMOps?
      • 什么是数组变量?
      • 检索增强生成(RAG)
        • 混合检索
        • 重排序
        • 召回模式
      • 提示词编排
      • 如何使用 JSON Schema 让 LLM 输出遵循结构化格式的内容?
    • 常见问题
      • 本地部署
      • LLM 配置与使用
      • 插件
  • 政策
    • 开源许可证
    • 用户协议
      • 服务条款
      • 隐私政策
      • 获取合规报告
Powered by GitBook
On this page
  • API 规范
  • 校验
  • 范例
  • 本地调试
  • 使用 Cloudflare Workers 部署 API 扩展
  1. 手册
  2. 扩展

API 扩展

Previous扩展Next使用 Cloudflare Workers 部署 API Tools

Last updated 6 months ago

开发者可通过 API 扩展模块能力,当前支持以下模块扩展:

  • moderation 敏感内容审计

  • external_data_tool 外部数据工具

在扩展模块能力之前,你需要准备一个 API 和用于鉴权的 API Key(也可由 Dify 自动生成,可选)。

除了需要开发对应的模块能力,还需要遵照以下规范,以便 Dify 正确调用 API。

API 规范

Dify 将会以以下规范调用你的接口:

POST {Your-API-Endpoint}

Header

Header
Value
Desc

Content-Type

application/json

请求内容为 JSON 格式。

Authorization

Bearer {api_key}

API Key 以 Token 令牌的方式传输,你需要解析该 api_key 并确认是否和提供的 API Key 一致,保证接口安全。

Request Body

{
    "point":  string, //  扩展点,不同模块可能包含多个扩展点
    "params": {
        ...  // 各模块扩展点传入参数
    }
}

API 返回

{
    ...  // API 返回的内容,不同扩展点返回见不同模块的规范设计
}

校验

在 Dify 配置 API-based Extension 时,Dify 将会发送一个请求至 API Endpoint,以检验 API 的可用性。

当 API Endpoint 接收到 point=ping 时,接口应返回 result=pong,具体如下:

Header

Content-Type: application/json
Authorization: Bearer {api_key}

Request Body

{
    "point": "ping"
}

API 期望返回

{
    "result": "pong"
}

范例

此处以外部数据工具为例,场景为根据地区获取外部天气信息作为上下文。

API 范例

POST https://fake-domain.com/api/dify/receive

Header

Content-Type: application/json
Authorization: Bearer 123456

Request Body

{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "How's the weather today?"
    }
}

API 返回

{
    "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
}

代码范例

代码基于 Python FastAPI 框架。

  1. 安装依赖

    pip install fastapi[all] uvicorn
  2. 按照接口规范编写代码

    from fastapi import FastAPI, Body, HTTPException, Header
    from pydantic import BaseModel
    
    app = FastAPI()
    
    
    class InputData(BaseModel):
        point: str
        params: dict = {}
    
    
    @app.post("/api/dify/receive")
    async def dify_receive(data: InputData = Body(...), authorization: str = Header(None)):
        """
        Receive API query data from Dify.
        """
        expected_api_key = "123456"  # TODO Your API key of this API
        auth_scheme, _, api_key = authorization.partition(' ')
    
        if auth_scheme.lower() != "bearer" or api_key != expected_api_key:
            raise HTTPException(status_code=401, detail="Unauthorized")
    
        point = data.point
    
        # for debug
        print(f"point: {point}")
    
        if point == "ping":
            return {
                "result": "pong"
            }
        if point == "app.external_data_tool.query":
            return handle_app_external_data_tool_query(params=data.params)
        # elif point == "{point name}":
            # TODO other point implementation here
    
        raise HTTPException(status_code=400, detail="Not implemented")
    
    
    def handle_app_external_data_tool_query(params: dict):
        app_id = params.get("app_id")
        tool_variable = params.get("tool_variable")
        inputs = params.get("inputs")
        query = params.get("query")
    
        # for debug
        print(f"app_id: {app_id}")
        print(f"tool_variable: {tool_variable}")
        print(f"inputs: {inputs}")
        print(f"query: {query}")
    
        # TODO your external data tool query implementation here, 
        #  return must be a dict with key "result", and the value is the query result
        if inputs.get("location") == "London":
            return {
                "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind "
                          "Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
            }
        else:
            return {"result": "Unknown city"}
  3. 启动 API 服务,默认端口为 8000,API 完整地址为:http://127.0.0.1:8000/api/dify/receive,配置的 API Key 为 123456。

    uvicorn main:app --reload --host 0.0.0.0
  4. 在 Dify 配置该 API。

  1. 在 App 中选择该 API 扩展。

App 调试时,Dify 将请求配置的 API,并发送以下内容(范例):

{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "How's the weather today?"
    }
}

API 返回为:

{
    "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
}

本地调试

  1. 下载完成后,进入下载目录,根据下方说明解压压缩包,并执行说明中的初始化脚本。

    • $ unzip /path/to/ngrok.zip
      $ ./ngrok config add-authtoken 你的Token
  2. 查看本地 API 服务的端口:

并运行以下命令启动:

  • $ ./ngrok http 端口号

    启动成功的样例如下:

  1. 我们找到 Forwarding 中,如上图:https://177e-159-223-41-52.ngrok-free.app(此为示例域名,请替换为自己的)即为公网域名。

  • 按照上述的范例,我们把本地已经启动的服务端点暴露出去,将代码范例接口:http://127.0.0.1:8000/api/dify/receive 替换为 https://177e-159-223-41-52.ngrok-free.app/api/dify/receive

此 API 端点即可公网访问。至此,我们即可在 Dify 配置该 API 端点进行本地调试代码,配置步骤请参考 https://github.com/langgenius/dify-docs/blob/main/zh_CN/guides/knowledge-base/external-data-tool.md。

使用 Cloudflare Workers 部署 API 扩展

我们推荐你使用 Cloudflare Workers 来部署你的 API 扩展,因为 Cloudflare Workers 可以方便的提供一个公网地址,而且可以免费使用。

使用 Cloudflare Workers 部署 API Tools。

配置 API
选择扩展

由于 Dify 云端版无法访问内网 API 服务,为了方便本地调试 API 服务,可以使用 将 API 服务的端点暴露到公网,实现云端调试本地代码。操作步骤:

进入 官网,注册并下载 Ngrok 文件。

Ngrok
https://ngrok.com
基于 API 扩展
Download
查看端口
Ngrok 启动