mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-27 13:28:32 +07:00
429 lines
23 KiB
Plaintext
429 lines
23 KiB
Plaintext
---
|
||
title: ツールプラグイン
|
||
---
|
||
|
||
|
||
|
||
{/*
|
||
コントリビューター注:
|
||
----------------
|
||
これはレガシードキュメントであり、非推奨になります。
|
||
このバージョンに変更を加えないでください。
|
||
すべての更新は新しいバージョンに向けられるべきです：
|
||
/plugin_dev_ja/0222-tool-plugin.ja
|
||
*/}
|
||
|
||
<Card title="このドキュメントはまもなく非推奨になります" icon="circle-exclamation" href="/plugin_dev_ja/0222-tool-plugin.ja">
|
||
<p>ドキュメント再編の一環として、このページは段階的に廃止されます。</p>
|
||
|
||
<p><u><b>このカードをクリックして</b></u>、最新情報が含まれる更新版にリダイレクトしてください。</p>
|
||
|
||
<p>新しいドキュメントに不一致や改善が必要な箇所を見つけた場合は、ページ下部の「問題を報告」ボタンを使用してください。</p>
|
||
</Card>
|
||
|
||
Tool（ツール）プラグインは、チャットフロー、ワークフロー、エージェントといったアプリタイプから参照できる外部ツールであり、Difyアプリの機能を拡張するために使用されます。例えば、アプリにオンライン検索機能や画像生成機能を追加するといったことが可能です。ツールプラグインは、包括的なツールセットとAPI実装機能を提供します。
|
||
|
||
<img
|
||
src="https://assets-docs.dify.ai/2024/12/7e7bcf1f9e3acf72c6917ea9de4e4613.png"
|
||
className="mx-auto"
|
||
alt=""
|
||
/>
|
||
|
||
本篇では、「ツールプラグイン」とは、ツールプロバイダーファイル、機能コード、およびその他の関連コンポーネントを含む、一揃いのプロジェクトを指します。ツールプロバイダーは複数のツール（これは、単一のツールが提供する追加機能と解釈できます）を含むことがあり、以下の構造で構成されます。
|
||
|
||
```
|
||
- ツールプロバイダー
|
||
- Tool A
|
||
- Tool B
|
||
```
|
||
|
||
|
||
|
||
この記事では、`GoogleSearch`を例に、ツールプラグインを迅速に開発する方法をご紹介します。
|
||
|
||
### 事前準備
|
||
|
||
* Dify プラグインの Scaffolding（スキャフォールディング）ツール
|
||
* Python 環境 (バージョン 3.12 以上)
|
||
|
||
プラグイン開発用のScaffoldingツールの準備方法については、[初期化開発ツール](/ja-jp/plugins/quick-start/develop-plugins/initialize-development-tools)をご参照ください。
|
||
|
||
### 新規プロジェクトの作成
|
||
|
||
Scaffoldingのコマンドラインツールを実行し、新しいDifyプラグインプロジェクトを作成します。
|
||
|
||
```bash
|
||
./dify-plugin-darwin-arm64 plugin init
|
||
```
|
||
|
||
バイナリファイルの名前を `dify` に変更し、`/usr/local/bin` ディレクトリにコピーした場合は、次のコマンドを実行して新しいプラグインプロジェクトを作成できます。
|
||
|
||
```bash
|
||
dify plugin init
|
||
```
|
||
|
||
> 以下、コマンドラインツール `dify` を使用します。もし問題が発生した場合は、`dify` コマンドを、お使いのツールの実行パスに置き換えてください。
|
||
|
||
### プラグインの種類とテンプレートの選択
|
||
|
||
プラグインには、ツール、モデル、そしてエクステンションの3種類があります。SDK内のすべてのテンプレートには、完全なコードプロジェクトが付属しています。以下の部分では、**ツールプラグイン**テンプレートを例として使用します。
|
||
|
||
> プラグイン開発に精通されている方は、各種プラグインの実装にあたり、[スキーマ仕様](../../schema-definition/README)をご参照ください。
|
||
|
||
|
||
|
||
#### プラグイン権限の設定
|
||
|
||
プラグインを正常に接続するには、Difyプラットフォームの権限を読み取る必要があります。このサンプルツールプラグインには、以下の権限を付与する必要があります。
|
||
|
||
* ツール
|
||
* アプリ
|
||
* 永続的ストレージジストレージの有効化、デフォルトサイズのストレージの割り当て
|
||
* エンドポイントの登録許可
|
||
|
||
> ターミナルで方向キーを使って権限を選択し、"タグ"のブタンで権限を付与してください。
|
||
|
||
すべての権限項目にチェックを入れたら、Enterキーを押してプラグインの作成を完了させてください。システムが自動的にプラグインプロジェクトのコードを生成します。
|
||
|
||
|
||
|
||
### 開発ツールプラグイン
|
||
|
||
#### 1. ツールプロバイダーの yaml ファイルを作成する
|
||
|
||
ツールプロバイダーファイルは、ツールプラグインの基本的な設定ファイルとして機能し、ツールが利用するために必要な認証情報を提供します。このセクションでは、この `yaml` ファイルの記述方法について説明します。
|
||
|
||
`/provider` ディレクトリに移動し、その中にある yaml ファイルの名前を `google.yaml` に変更します。この `yaml` ファイルには、プロバイダー名、アイコン、作成者など、ツールプロバイダーに関する情報が含まれます。これらの情報は、プラグインのインストール時に表示されます。
|
||
|
||
**サンプルコード**
|
||
|
||
```yaml
|
||
identity: # ツールプロバイダーの基本情報
|
||
author: Your-name # 作成者
|
||
name: google # 名前。一意である必要があり、他のプロバイダーと重複できません
|
||
label: # ラベル。フロントエンドでの表示に使用
|
||
en_US: Google # 英語ラベル
|
||
zh_Hans: Google # 中国語ラベル
|
||
ja_JP: Google # 日本語ラベル
|
||
pt_BR: Google # プルトガル語ラベル
|
||
description: # 説明。フロントエンドでの表示に使用
|
||
en_US: Google # 英語説明
|
||
zh_Hans: Google # 中国語説明
|
||
ja_JP: : Google # 日本語説明
|
||
pt_BR: : Google # プルトガル語説明
|
||
icon: icon.svg # アイコン。_assets フォルダに配置する必要があります
|
||
tags: # タグ。フロントエンドでの表示に使用
|
||
- search
|
||
```
|
||
|
||
* `identity` には、作成者、名前、ラベル、説明、アイコンなど、ツールプロバイダーの基本的な情報が含まれます。
|
||
* アイコンは添付ファイルとして扱い、プロジェクトのルートディレクトリにある `_assets` フォルダに配置する必要があります。
|
||
* タグは、ユーザーがプラグインをカテゴリ別にすばやく検索するのに役立ちます。現在サポートされているすべてのタグは以下のとおりです。
|
||
* ```python
|
||
class ToolLabelEnum(Enum):
|
||
SEARCH = 'search'
|
||
IMAGE = 'image'
|
||
VIDEOS = 'videos'
|
||
WEATHER = 'weather'
|
||
FINANCE = 'finance'
|
||
DESIGN = 'design'
|
||
TRAVEL = 'travel'
|
||
SOCIAL = 'social'
|
||
NEWS = 'news'
|
||
MEDICAL = 'medical'
|
||
PRODUCTIVITY = 'productivity'
|
||
EDUCATION = 'education'
|
||
BUSINESS = 'business'
|
||
ENTERTAINMENT = 'entertainment'
|
||
UTILITIES = 'utilities'
|
||
OTHER = 'other'
|
||
```
|
||
|
||
ファイルパスが `/tools` ディレクトリにあることを確認してください。完全なパスは次のようになります。
|
||
|
||
```yaml
|
||
plugins:
|
||
tools:
|
||
- "google.yaml"
|
||
```
|
||
|
||
ここで、`google.yaml` ファイルのパスは、プラグインプロジェクト内の絶対パスで指定する必要があります。
|
||
|
||
* **サードパーティサービスの認証情報を設定する**
|
||
|
||
開発を容易にするため、サードパーティサービスである `SerpApi` が提供する Google Search API を利用することにしました。`SerpApi` を使用するには API キーが必要となるため、`yaml` ファイルに `credentials_for_provider` フィールドを追加する必要があります。
|
||
|
||
完全なコードは次のとおりです。
|
||
|
||
```yaml
|
||
identity:
|
||
author: Dify
|
||
name: google
|
||
label:
|
||
en_US: Google
|
||
zh_Hans: Google
|
||
ja_JP: Google
|
||
pt_BR: Google
|
||
description:
|
||
en_US: Google
|
||
zh_Hans: GoogleSearch
|
||
ja_JP: Google
|
||
pt_BR: Google
|
||
icon: icon.svg
|
||
tags:
|
||
- search
|
||
credentials_for_provider: # credentials_for_provider フィールドを追加
|
||
serpapi_api_key:
|
||
type: secret-input
|
||
required: true
|
||
label:
|
||
en_US: SerpApi API key
|
||
zh_Hans: SerpApi API key
|
||
ja_JP: SerpApi API key
|
||
pt_BR: chave de API SerpApi
|
||
placeholder:
|
||
en_US: Please input your SerpApi API key
|
||
zh_Hans: 请输入你的 SerpApi API key
|
||
ja_JP: SerpApi API keyを入力してください
|
||
pt_BR: Por favor, insira sua chave de API SerpApi
|
||
help:
|
||
en_US: Get your SerpApi API key from SerpApi
|
||
zh_Hans: 从 SerpApi 获取您的 SerpApi API key
|
||
ja_JP: SerpApiからSerpApi APIキーを取得する
|
||
pt_BR: Obtenha sua chave de API SerpApi da SerpApi
|
||
url: https://serpapi.com/manage-api-key
|
||
tools:
|
||
- tools/google_search.yaml
|
||
extra:
|
||
python:
|
||
source: google.py
|
||
```
|
||
|
||
* `credentials_for_provider` の子構造は、[ProviderConfig](/ja-jp/plugins/schema-definition/general-specifications) の仕様に準拠する必要があります。
|
||
* このプロバイダーに含まれるツールを指定する必要があります。この例では、`tools/google_search.yaml` ファイルが 1 つだけ含まれています。
|
||
* プロバイダーは、基本情報を定義するだけでなく、コードによるロジックの実装も必要です。そのため、実装ロジックを指定する必要があります。この例では、機能のコードファイルは `google.py` に配置されていますが、ここではまだ実装せず、先に `google_search` のコードを作成します。これは、`google_search` の機能が `google.py` の実装に依存するためです。
|
||
|
||
#### 2. ツールの YAML ファイルへの入力
|
||
|
||
1つのツールベンダーが複数のツールを提供することがあります。各ツールは、その基本的な情報、パラメータ、出力などを記述した `yaml` ファイルによって定義される必要があります。
|
||
|
||
ここでは、`GoogleSearch` ツールを例にとり、`/tools` フォルダに新しい `google_search.yaml` ファイルを作成する手順を見ていきましょう。
|
||
|
||
```yaml
|
||
identity:
|
||
name: google_search
|
||
author: Dify
|
||
label:
|
||
en_US: GoogleSearch
|
||
zh_Hans: 谷歌搜索
|
||
ja_JP: Google検索
|
||
pt_BR: Pesquisa Google
|
||
description:
|
||
human:
|
||
en_US: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query.
|
||
zh_Hans: 一个用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询。
|
||
ja_JP: Google SERP 検索を実行し、スニペットと Web ページを抽出するためのツール。入力は検索クエリである必要があります。
|
||
pt_BR: Uma ferramenta para realizar pesquisas no Google SERP e extrair snippets e páginas da web. A entrada deve ser uma consulta de pesquisa.
|
||
llm: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query.
|
||
parameters:
|
||
- name: query
|
||
type: string
|
||
required: true
|
||
label:
|
||
en_US: Query string
|
||
zh_Hans: 查询字符串
|
||
ja_JP: クエリ文字列
|
||
pt_BR: Cadeia de consulta
|
||
human_description:
|
||
en_US: used for searching
|
||
zh_Hans: 用于搜索网页内容
|
||
ja_JP: ネットの検索に使用する
|
||
pt_BR: usado para pesquisar
|
||
llm_description: key words for searching
|
||
form: llm
|
||
extra:
|
||
python:
|
||
source: tools/google_search.py
|
||
```
|
||
|
||
* `identity`: ツールの名前、作成者、ラベル、説明といった基本的な情報が含まれます。
|
||
* `parameters`: パラメータに関する設定項目です。各項目の詳細は以下の通りです。
|
||
* `name` (必須): パラメータ名。一意である必要があり、他のパラメータ名との重複は許容されません。
|
||
* `type` (必須): パラメータの型。`string` (文字列)、`number` (数値)、`boolean` (真偽値)、`select` (選択式ドロップダウン)、`secret-input` (暗号化入力フィールド)、`file` (ファイル)、`files` (ファイルセット)、`model-selector` (モデル選択)、`app-selector` (アプリケーション選択) の9種類がサポートされています。機密性の高い情報を取り扱う場合は、必ず `secret-input` 型を使用してください。
|
||
* `label` (必須): パラメータのラベル。フロントエンドに表示される際に用いられます。
|
||
* `form` (必須): フォームの種類。`llm` と `form` の2種類がサポートされています。
|
||
* Agentアプリケーションにおいて、`llm` はパラメータがLLMによって推論されることを意味し、`form` はツールを使用する前にユーザーが設定できるパラメータを意味します。
|
||
* ワークフローアプリケーションにおいては、`llm` と `form` の両方のパラメータに対してフロントエンドでの入力が求められます。ただし、`llm` パラメータはツールノードの入力変数として機能します。
|
||
* `required`: 必須項目であるかどうかを示すフラグです。
|
||
* `llm` モードの場合、`required` が `true` に設定されたパラメータは、Agentが推論によって値を決定する必要があります。
|
||
* `form` モードの場合、`required` が `true` に設定されたパラメータは、ユーザーが会話を開始する前にフロントエンドで値を入力する必要があります。
|
||
* `options`: パラメータの選択肢。
|
||
* `llm` モードでは、Dify はすべての選択肢をLLMに渡し、LLM はこれらの選択肢に基づいて推論を行います。
|
||
* `form` モードでは、`type` が `select` に設定されている場合、フロントエンドにこれらの選択肢が表示されます。
|
||
* `default`: デフォルト値。
|
||
* `min`: 最小値。パラメータの型が `number` の場合に設定可能です。
|
||
* `max`: 最大値。パラメータの型が `number` の場合に設定可能です。
|
||
* `human_description`: フロントエンドに表示されるパラメータの説明文です。多言語に対応しています。
|
||
* `placeholder`: 入力フィールドに表示されるプレースホルダーテキストです。`form` 形式で、パラメータの型が `string`、`number`、`secret-input` の場合に設定できます。多言語に対応しています。
|
||
* `llm_description`: LLMに渡されるパラメータの説明文です。LLMがパラメータの内容をより深く理解できるよう、できる限り詳細な情報を提供してください。
|
||
|
||
#### 3. ツールコードの準備
|
||
|
||
ツールの設定情報を入力したら、ツールの機能コードを記述し、ツールのロジックを実装します。 `/tools` ディレクトリに `google_search.py` を作成し、以下の内容を記述します。
|
||
|
||
```python
|
||
from collections.abc import Generator
|
||
from typing import Any
|
||
|
||
import requests
|
||
|
||
from dify_plugin import Tool
|
||
from dify_plugin.entities.tool import ToolInvokeMessage
|
||
|
||
SERP_API_URL = "https://serpapi.com/search"
|
||
|
||
class GoogleSearchTool(Tool):
|
||
def _parse_response(self, response: dict) -> dict:
|
||
result = {}
|
||
if "knowledge_graph" in response:
|
||
result["title"] = response["knowledge_graph"].get("title", "")
|
||
result["description"] = response["knowledge_graph"].get("description", "")
|
||
if "organic_results" in response:
|
||
result["organic_results"] = [
|
||
{
|
||
"title": item.get("title", ""),
|
||
"link": item.get("link", ""),
|
||
"snippet": item.get("snippet", ""),
|
||
}
|
||
for item in response["organic_results"]
|
||
]
|
||
return result
|
||
|
||
def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
|
||
params = {
|
||
"api_key": self.runtime.credentials["serpapi_api_key"],
|
||
"q": tool_parameters["query"],
|
||
"engine": "google",
|
||
"google_domain": "google.com",
|
||
"gl": "us",
|
||
"hl": "en",
|
||
}
|
||
|
||
response = requests.get(url=SERP_API_URL, params=params, timeout=5)
|
||
response.raise_for_status()
|
||
valuable_res = self._parse_response(response.json())
|
||
|
||
yield self.create_json_message(valuable_res)
|
||
```
|
||
|
||
この例では、`serpapi` にリクエストを送信し、`self.create_json_message` を使用して `json` 形式のデータを返しています。その他の戻り値の型については、[ツールインターフェースドキュメント](/ja-jp/plugins/schema-definition/tool)を参照してください。
|
||
|
||
#### 4. ツールプロバイダーコードの作成
|
||
|
||
最後に、プロバイダーのコードを実装します。これは、プロバイダーの認証情報を検証するために使用されます。認証情報の検証に失敗すると、`ToolProviderCredentialValidationError` 例外が発生します。検証に成功すると、`google_search` ツールサービスが正常にリクエストされます。
|
||
|
||
`/provider` ディレクトリに `google.py` ファイルを作成し、以下のコードを記述します。
|
||
|
||
```python
|
||
from typing import Any
|
||
|
||
from dify_plugin import ToolProvider
|
||
from dify_plugin.errors.tool import ToolProviderCredentialValidationError
|
||
from tools.google_search import GoogleSearchTool
|
||
|
||
class GoogleProvider(ToolProvider):
|
||
def _validate_credentials(self, credentials: dict[str, Any]) -> None:
|
||
try:
|
||
for _ in GoogleSearchTool.from_credentials(credentials).invoke(
|
||
tool_parameters={"query": "test", "result_type": "link"},
|
||
):
|
||
pass
|
||
except Exception as e:
|
||
raise ToolProviderCredentialValidationError(str(e))
|
||
```
|
||
|
||
### プラグインのデバッグ
|
||
|
||
プラグインが正常に動作するかテストします。Dify はリモートデバッグをサポートしています。「プラグイン管理」ページで、デバッグキーとリモートサーバーアドレスを取得してください。
|
||
|
||
<img
|
||
src="https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png"
|
||
className="mx-auto"
|
||
alt=""
|
||
/>
|
||
|
||
プラグインプロジェクトに戻り、`.env.example` ファイルをコピーして `.env` にリネームし、取得したリモートサーバーアドレスとデバッグキーを入力します。
|
||
|
||
`.env` ファイル
|
||
|
||
```bash
|
||
INSTALL_METHOD=remote
|
||
REMOTE_INSTALL_HOST=remote
|
||
REMOTE_INSTALL_PORT=5003
|
||
REMOTE_INSTALL_KEY=****-****-****-****-****
|
||
```
|
||
|
||
`python -m main` コマンドを実行してプラグインを起動します。プラグインページで、プラグインがワークスペースにインストールされていることを確認できます。これで、他のチームメンバーもこのプラグインを使用できます。
|
||
|
||
<img
|
||
src="https://assets-docs.dify.ai/2024/11/0fe19a8386b1234755395018bc2e0e35.png"
|
||
className="mx-auto"
|
||
alt=""
|
||
/>
|
||
|
||
### プラグインのパッケージ化
|
||
|
||
プラグインが正常に動作することを確認したら、以下のコマンドラインツールを使用してプラグインをパッケージ化し、名前を付けます。実行後、現在のフォルダに `google.difypkg` ファイルが作成されます。これがプラグインの最終的なパッケージです。
|
||
|
||
```bash
|
||
# Replace ./google with your actual plugin project path.
|
||
|
||
dify plugin package ./google
|
||
```
|
||
|
||
おめでとうございます。これで、ツールタイプのプラグインの開発、デバッグ、パッケージ化の全プロセスが完了しました。
|
||
|
||
### プラグインの公開
|
||
|
||
[Dify Plugins コードリポジトリ](https://github.com/langgenius/dify-plugins)にアップロードして、プラグインを公開しましょう。アップロードする前に、プラグインが[プラグイン公開仕様](/ja-jp/plugins/publish-plugins/publish-to-dify-marketplace/README)に準拠していることを確認してください。レビューに合格すると、コードはメインブランチにマージされ、[Dify Marketplace](https://marketplace.dify.ai/) に自動的に公開されます。
|
||
|
||
#### さらに詳しく
|
||
|
||
**クイックスタート:**
|
||
|
||
* [拡張タイププラグインの開発](/ja-jp/plugins/quick-start/develop-plugins/extension-plugin)
|
||
* [モデルタイププラグインの開発](/ja-jp/plugins/quick-start/develop-plugins/tool-plugin)
|
||
* [バンドルタイププラグイン：複数のプラグインをパッケージ化](/ja-jp/plugins/quick-start/develop-plugins/bundle)
|
||
|
||
**プラグインインターフェースドキュメント:**
|
||
|
||
* [マニフェスト](/ja-jp/plugins/schema-definition/manifest) 構造
|
||
* [エンドポイント](/ja-jp/plugins/schema-definition/endpoint) 詳細定義
|
||
* [Difyサービスの逆呼び出し](/ja-jp/plugins/schema-definition/reverse-invocation-of-the-dify-service/app)
|
||
* [ツール](/ja-jp/plugins/schema-definition/tool)
|
||
* [モデル](/ja-jp/plugins/schema-definition/reverse-invocation-of-the-dify-service/model)
|
||
* [拡張エージェント戦略](/ja-jp/plugins/schema-definition/agent)
|
||
|
||
{/*
|
||
Contributing Section
|
||
DO NOT edit this section!
|
||
It will be automatically generated by the script.
|
||
*/}
|
||
|
||
<CardGroup cols="2">
|
||
<Card
|
||
title="このページを編集する"
|
||
icon="pen-to-square"
|
||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/ja-jp/plugins/quick-start/develop-plugins/tool-plugin.mdx"
|
||
>
|
||
直接貢献することでドキュメントの改善にご協力ください
|
||
</Card>
|
||
<Card
|
||
title="問題を報告する"
|
||
icon="github"
|
||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=ドキュメントの問題%3A%20plu&body=%23%23%20問題の説明%0A%3C%21--%20発見した問題について簡単に説明してください%20--%3E%0A%0A%23%23%20ページリンク%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fja-jp/plugins/quick-start/develop-plugins%2Ftool-plugin.mdx%0A%0A%23%23%20提案される変更%0A%3C%21--%20特定の変更案がある場合は、ここで説明してください%20--%3E%0A%0A%3C%21--%20ドキュメントの品質向上にご協力いただきありがとうございます！%20--%3E"
|
||
>
|
||
エラーを見つけたり提案がありますか？お知らせください
|
||
</Card>
|
||
</CardGroup>
|