Dify 自定义工具从创建到部署全指南

扩展 AI 能力：Dify 自定义工具从创建到部署全指南

大型语言模型本身很强大，但它们的威力真正得以释放，是在与真实世界的数据和服务连接之后。无论是查询最新的物流信息、访问公司内部的知识库，还是调用一个特定的数据分析接口，这种连接能力都是构建实用 AI 应用的关键。这正是 Dify 平台中“自定义工具”功能的价值所在——它提供了一个清晰的路径，让开发者可以将任何外部 API 无缝集成，赋予 AI 解决特定领域问题的能力。

接下来，我们将一步步拆解如何在 Dify 中创建并上线一个自定义工具。

步骤 1：定义蓝图 – 撰写 API 接口描述

要让 Dify 理解你的工具，首先需要提供一份“说明书”，即 API 接口描述。这份描述文件告诉平台：你的工具能做什么、如何调用它以及需要哪些参数。

目前，Dify 支持两种业界主流的 API 描述规范：

• OpenAPI (Swagger): 一种被广泛采用的 API 描述语言，是现代 RESTful API 的事实标准。
• ChatGPT Plugin: 遵循 OpenAI 为其插件生态系统制定的规范。

你可以直接将 JSON 或 YAML 格式的描述内容粘贴到输入框，也可以提供一个 URL 地址，Dify 会自动获取并解析。

步骤 2：导入与验证

导入描述文件后，Dify 会自动解析其内容，识别出工具中包含的所有 API 端点。平台会清晰地列出每个接口的路径（如 /weather）、请求方法（GET / POST）以及必需的输入参数（如 city）。

这是一个关键的验证环节。你可以直接在界面上对识别出的工具进行测试，输入参数并查看返回结果，确保它在集成到 AI 应用前能够正常工作。

步骤 3：配置门禁 – 设置鉴权方式

定义好工具后，你需要决定谁可以使用它。这通过配置鉴权（Authentication）来实现，它就像为你的 API 服务设置门禁。

Dify 提供两种主要的鉴权方式：

• 无鉴权 (No Auth): 公开访问，任何人或应用都可以直接调用该工具，无需任何凭证。适合公开、免费的服务。
• API Key 鉴权: 调用方必须在请求中提供一个预设的密钥（API Key）。这是保护私有或付费 API 的标准做法，确保只有授权用户才能访问。

例如，一个天气查询工具，若选择“无鉴权”，则所有人都能用；若选择“API Key”，用户就必须先获取密钥，才能查询天气。

步骤 4：上线服务 – 让工具在云端运行

在 Dify 平台完成上述配置，只是完成了工具的“注册”。要让 AI 能够真正调用它，这个工具背后的 API 服务必须部署在互联网上，拥有一个可公开访问的 URL。

对于如何部署，你有两种主流选择，分别面向不同技术背景的用户。

方案一：零服务器的快速通道 – dify-tools-worker

对于不想管理服务器或不熟悉后端开发的开发者，Dify 官方提供了一个名为 dify-tools-worker 的开源项目。

它基于 Cloudflare Workers 平台，这是一个强大的无服务器（Serverless）计算环境，让你无需购买和配置服务器就能运行代码。

使用此方案的优势：

• 自动生成符合 OpenAPI 规范的接口文档。
• 快速部署，成本极低（Cloudflare Workers 提供免费额度）。
• 你会得到一个线上服务地址和一个文档地址，如 https://difytoolsworker.yourname.workers.dev/doc，后者可以直接用于在 Dify 中导入工具。

这个方案是快速验证想法和上线的最佳选择。

方案二：完全掌控的专业路径 – FastAPI

如果你是 Python 开发者或希望对服务有完全的控制权，使用 FastAPI 框架自行构建和部署是更专业的选择。

FastAPI 是一个现代、高性能的 Python Web 框架，其最大亮点之一就是自动生成交互式 API 文档。

它的工作流程很简单：

1. 用 Python 编写你的 API 逻辑。
2. FastAPI 会在你运行服务时，自动创建 OpenAPI 兼容的文档。

一个简单的 FastAPI 示例：

from fastapi import FastAPI
app = FastAPI()
@app.get("/hello")
def say_hello(name: str):
return {"message": f"Hello, {name}!"}

启动这个服务后，你可以通过以下地址访问其自动生成的文档：

• http://localhost:8000/docs: Swagger UI 格式的交互式文档，可直接测试。
• http://localhost:8000/openapi.json: 原始的 OpenAPI JSON 描述文件。

你只需将这个 FastAPI 应用部署到任何云服务器或 PaaS 平台，然后将线上生成的 /openapi.json 地址提供给 Dify，即可完成工具的导入。这个方案为你提供了最大的灵活性和扩展性。