diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx index e24de2e7a..cb0909941 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx @@ -5,20 +5,20 @@ description: Function Callingエージェント戦略をゼロから構築する ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin) を参照してください。 -**エージェント戦略プラグイン**は、LLMが推論や意思決定などのタスクを実行する際に役立ちます。これには、ツールの選択と呼び出し、および結果の処理が含まれます。これにより、システムはより自律的に問題に対処できるようになります。 +**エージェント戦略プラグイン**は、LLMにツールを選択・呼び出し、その結果を処理するための推論と意思決定ロジックを提供し、自律的に問題を解決できるようにします。 -以下では、現在時刻を自動的に取得するための**Function Calling**をサポートするプラグインの開発方法を説明します。 +このガイドでは、モデルが自律的に現在時刻を取得できる**Function Calling**戦略の構築方法を説明します。 ## 前提条件 - Difyプラグインスキャフォールディングツール - Python環境（バージョン 3.12） -プラグイン開発ツールの準備の詳細については、[開発ツールの初期化](/ja/develop-plugin/getting-started/cli)を参照してください。 +プラグイン開発ツールの準備の詳細については、[CLI](/ja/develop-plugin/getting-started/cli)を参照してください。 - -**ヒント**： ターミナルで`dify version`を実行して、スキャフォールディングツールがインストールされていることを確認してください。 - + +ターミナルで`dify version`を実行して、スキャフォールディングツールがインストールされていることを確認してください。 + --- @@ -26,11 +26,11 @@ description: Function Callingエージェント戦略をゼロから構築する 以下のコマンドを実行して、エージェントプラグインの開発テンプレートを作成します： -``` +```bash dify plugin init ``` -画面上のプロンプトに従い、サンプルコメントをガイダンスとして参照してください。 +画面上のプロンプトに従い、以下のコメントが各選択肢を説明します。 ```bash ➜ Dify Plugins Developing dify plugin init @@ -69,7 +69,7 @@ Models: ... ``` -初期化後、プラグイン開発に必要なすべてのリソースを含むフォルダが作成されます。エージェント戦略プラグインの全体的な構造を理解することで、開発プロセスがスムーズになります： +初期化により、プラグイン開発に必要なすべてを含むフォルダが作成されます： ```text ├── GUIDE.md # ユーザーガイドとドキュメント @@ -100,25 +100,25 @@ Models: ### 2.1 パラメータの定義 -エージェントプラグインを構築するには、まず`strategies/basic_agent.yaml`で必要なパラメータを指定します。これらのパラメータは、LLMの呼び出しやツールの使用など、プラグインのコア機能を定義します。 +まず、`strategies/basic_agent.yaml`でプラグインのパラメータを宣言します。これらのパラメータは、LLMの呼び出しやツールの使用など、プラグインのコア機能を提供します。 -最初に以下の4つのパラメータを含めることをお勧めします： +最初に以下の4つのパラメータから始めることをお勧めします： -1. **model**： 呼び出す大規模言語モデル（例：GPT-4、GPT-4o-mini）。 -2. **tools**： プラグインの機能を拡張するツールのリスト。 -3. **query**： モデルに送信されるユーザー入力またはプロンプトの内容。 -4. **maximum_iterations**： 過度な計算を防ぐための最大イテレーション数。 +- **`model`**： 呼び出す大規模言語モデル（例：GPT-4、GPT-4o-mini）。 +- **`tools`**： プラグインの機能を拡張するツールのリスト。 +- **`query`**： モデルに送信されるユーザー入力またはプロンプトの内容。 +- **`maximum_iterations`**： 過度な計算を防ぐための最大イテレーション数。 -サンプルコード： +例： ```yaml identity: name: basic_agent # the name of the agent_strategy author: novice # the author of the agent_strategy label: - en_US: BasicAgent # the engilish label of the agent_strategy + en_US: BasicAgent # the English label of the agent_strategy description: - en_US: BasicAgent # the english description of the agent_strategy + en_US: BasicAgent # the English description of the agent_strategy parameters: - name: model # the name of the model parameter type: model-selector # model-type @@ -157,7 +157,7 @@ extra: source: strategies/basic_agent.py ``` -これらのパラメータを設定すると、プラグインは自動的にユーザーフレンドリーなインターフェースを生成し、簡単に管理できるようになります： +Difyはこれらのパラメータ宣言から自動的に設定インターフェースをレンダリングします： ![エージェント戦略プラグインの UI](https://assets-docs.dify.ai/2025/01/d011e2eba4c37f07a9564067ba787df8.png) @@ -165,9 +165,7 @@ extra: ### 2.2 パラメータの取得と実行 -ユーザーがこれらの基本フィールドを入力した後、プラグインは送信されたパラメータを処理する必要があります。`strategies/basic_agent.py`で、エージェント用のパラメータクラスを定義し、ロジック内でこれらのパラメータを取得して適用します。 - -受信パラメータを検証： +ユーザーがこれらのフィールドを入力すると、プラグインは送信された値を受け取ります。`strategies/basic_agent.py`で、受信パラメータを検証するPydanticモデルを定義します： ```python from dify_plugin.entities.agent import AgentInvokeMessage @@ -181,7 +179,7 @@ class BasicParams(BaseModel): query: str ``` -パラメータを取得した後、具体的なビジネスロジックが実行されます： +次に、`_invoke`でパラメータを解析し、戦略ロジックを実行します： ```python class BasicAgentAgentStrategy(AgentStrategy): @@ -191,19 +189,19 @@ class BasicAgentAgentStrategy(AgentStrategy): ## 3. モデルの呼び出し -エージェント戦略プラグインでは、**モデルの呼び出し**がワークフローの中心です。SDKの`session.model.llm.invoke()`を使用して、テキスト生成、対話などを処理し、LLMを効率的に呼び出すことができます。 +モデルの呼び出しはエージェント戦略の中心です。SDKの`session.model.llm.invoke()`を使用して、テキスト生成、対話などのタスクでLLMを呼び出すことができます。 -LLMに**ツールを処理**させたい場合は、ツールのインターフェースに一致する構造化されたパラメータを出力するようにします。つまり、LLMはユーザーの指示に基づいて、ツールが受け入れられる入力引数を生成する必要があります。 +LLMにツール呼び出しを駆動させるには、各ツールのインターフェースに一致する構造化された引数を出力する必要があります—ユーザーの指示から導出された、ツールが受け入れられる入力です。 -以下のパラメータを構築します： +このメソッドは以下のパラメータを取ります： -* model -* prompt\_messages -* tools -* stop -* stream +- `model` +- `prompt_messages` +- `tools` +- `stop` +- `stream` -メソッド定義のサンプルコード： +メソッドシグネチャ： ```python def invoke( @@ -216,25 +214,25 @@ def invoke( ) -> Generator[LLMResultChunk, None, None] | LLMResult:... ``` -完全な機能実装を確認するには、モデル呼び出しのサンプルコードを参照してください。 +完全な実装については、以下の[サンプルコード](#sample-code)の**モデルの呼び出し**タブを参照してください。 -このコードは以下の機能を実現します：ユーザーがコマンドを入力すると、エージェント戦略プラグインは自動的にLLMを呼び出し、生成された結果に基づいてツール呼び出しに必要なパラメータを構築し、モデルが統合されたツールを柔軟にディスパッチして複雑なタスクを効率的に完了できるようにします。 +これにより、ユーザーがコマンドを入力するたびにプラグインはLLMを呼び出し、モデルの出力からツール呼び出しパラメータを構築し、モデルが設定されたツールをディスパッチして複雑なタスクを完了できるようにします。 ![ツール生成のためのリクエストパラメータ](https://assets-docs.dify.ai/2025/01/01e32c2d77150213c7c929b3cceb4dae.png) -## 4. ツールの処理 +## 4. ツールの呼び出し -ツールパラメータを指定した後、エージェント戦略プラグインは実際にこれらのツールを呼び出す必要があります。`session.tool.invoke()`を使用してこれらのリクエストを行います。 +モデルがツールパラメータを生成したら、プラグインは実際にツールを呼び出す必要があります。`session.tool.invoke()`を使用してこれらのリクエストを行います。 -以下のパラメータを構築します： +このメソッドは以下のパラメータを取ります： -- provider -- tool\_name -- parameters +- `provider` +- `tool_name` +- `parameters` -メソッド定義のサンプルコード： +メソッドシグネチャ： ```python def invoke( @@ -246,7 +244,7 @@ def invoke( ) -> Generator[ToolInvokeMessage, None, None]:... ``` -LLM自体にツール呼び出しに必要なパラメータを生成させたい場合は、モデルの出力とツール呼び出しコードを組み合わせることで実現できます。 +LLM自体にツール呼び出しパラメータを生成させるには、モデルから抽出されたツール呼び出しを呼び出しコードに渡します： ```python tool_instances = ( @@ -262,7 +260,7 @@ for tool_call_id, tool_call_name, tool_call_args in tool_calls: ) ``` -これにより、エージェント戦略プラグインは自動的に**Function Calling**を実行できるようになります。例えば、現在時刻を取得することができます。 +これにより、プラグインは自動的にFunction Callingを実行できるようになります—例えば、現在時刻を取得することができます。 ![ツール呼び出し](https://assets-docs.dify.ai/2025/01/80e5de8acc2b0ed00524e490fd611ff5.png) @@ -270,12 +268,12 @@ for tool_call_id, tool_call_name, tool_call_args in tool_calls: ## 5. ログの作成 -**エージェント戦略プラグイン**で複雑なタスクを完了するには、複数のステップが必要になることがよくあります。開発者が各ステップの結果を追跡し、意思決定プロセスを分析し、戦略を最適化することは非常に重要です。SDKの`create_log_message`と`finish_log_message`を使用することで、呼び出しの前後のリアルタイムの状態をログに記録し、迅速な問題診断に役立てることができます。 +複雑なタスクは通常複数のステップを必要とし、意思決定を分析し戦略を改善するために各ステップの結果を追跡する必要があります。SDKの`create_log_message`と`finish_log_message`により、各呼び出しの前後の状態を記録でき、問題診断を迅速化します。 例えば： -- モデルを呼び出す前に「モデル呼び出しを開始」というメッセージをログに記録し、タスクの実行進捗を明確にします。 -- モデルが応答したら「呼び出し成功」というメッセージをログに記録し、モデルの出力をエンドツーエンドで追跡できるようにします。 +- モデルを呼び出す前に「モデル呼び出しを開始」というメッセージをログに記録し、実行の進捗を表示します。 +- モデルが応答したら「呼び出し成功」というメッセージをログに記録し、出力をエンドツーエンドで追跡できるようにします。 ```python model_log = self.create_log_message( @@ -302,15 +300,13 @@ yield self.finish_log_message( ) ``` -セットアップが完了すると、ワークフローログに実行結果が出力されます： +セットアップが完了すると、ワークフローログに実行結果が表示されます： ![エージェント出力の実行結果](https://assets-docs.dify.ai/2025/01/96516388a4fb1da9cea85fc1804ff377.png) -複数ラウンドのログが発生する場合は、ログ呼び出しで`parent`パラメータを設定することで階層構造にし、追跡しやすくすることができます。 - -参照メソッド： +タスクが複数ラウンドにまたがる場合、ログ呼び出しで`parent`パラメータを設定してログを階層的にネストし、追跡しやすくします： ```python function_call_round_log = self.create_log_message( @@ -331,13 +327,11 @@ model_log = self.create_log_message( yield model_log ``` -### エージェントプラグイン機能のサンプルコード +### サンプルコード - #### モデルの呼び出し - -以下のコードは、エージェント戦略プラグインにモデルを呼び出す機能を付与する方法を示しています： + 以下のコードは、エージェント戦略プラグインにモデルを呼び出す機能を付与します： ```python import json @@ -561,9 +555,7 @@ class BasicAgentAgentStrategy(AgentStrategy): ``` - #### ツールの処理 - -以下のコードは、エージェント戦略プラグインにモデル呼び出しを実装し、ツールに正規化されたリクエストを送信する方法を示しています。 + 以下のコードは、モデルを呼び出し、選択したツールに正しい形式のリクエストを送信します： ```python import json @@ -786,10 +778,8 @@ class BasicAgentAgentStrategy(AgentStrategy): return tool_calls ``` - - #### 完全な機能コードの例 - -**モデルの呼び出し、ツールの処理**、および**複数ラウンドのログを出力する機能**を含む完全なサンプルプラグインコード： + + モデルの呼び出し、ツールの処理、複数ラウンドのログ記録をカバーする完全なサンプル： ```python import json @@ -1047,13 +1037,13 @@ class BasicAgentAgentStrategy(AgentStrategy): ## 6. プラグインのデバッグ -プラグインの宣言ファイルと実装コードを完成させた後、プラグインディレクトリで`python -m main`を実行して再起動します。次に、プラグインが正しく動作することを確認します。Difyはリモートデバッグを提供しています。**プラグイン管理**に移動して、デバッグキーとリモートサーバーアドレスを取得してください。 +宣言ファイルと実装コードが完成したら、プラグインが正しく動作することを確認します。Difyはリモートデバッグをサポートしています：**プラグイン管理**に移動して、デバッグキーとリモートサーバーアドレスを取得してください。 - ![プラグインの宣言ファイルと実装コードを完成させた後、python -m mainを実行](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png) + ![プラグイン管理でのデバッグキーとリモートサーバーアドレス](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png) -プラグインプロジェクトに戻り、`.env.example`を`.env`にコピーし、関連するリモートサーバーとデバッグキー情報を挿入します。 +プラグインプロジェクトで、`.env.example`を`.env`にコピーし、リモートサーバーアドレスとデバッグキーを入力します。 ```bash INSTALL_METHOD=remote @@ -1067,7 +1057,7 @@ REMOTE_INSTALL_KEY=********-****-****-****-************ python -m main ``` -ワークスペースにプラグインがインストールされ、チームメンバーもアクセスできるようになります。 +プラグインがワークスペースに表示され、チームメンバーもアクセスできるようになります。 ![プラグインのブラウズ](https://assets-docs.dify.ai/2025/01/c82ec0202e5bf914b36e06c796398dd6.png) @@ -1085,17 +1075,17 @@ dify plugin package ./basic_agent/ 現在のフォルダに`basic_agent.difypkg`（プラグイン名と一致）という名前のファイルが表示されます。これが最終的なプラグインパッケージです。 -**おめでとうございます！** エージェント戦略プラグインの開発、テスト、パッケージングが完了しました。 +おめでとうございます！エージェント戦略プラグインの開発、テスト、パッケージングが完了しました。 ## プラグインの公開（オプション） -[Difyプラグインリポジトリ](https://github.com/langgenius/dify-plugins)にアップロードできます。その前に、[プラグイン公開ガイドライン](/ja/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace)を満たしていることを確認してください。承認されると、コードがメインブランチにマージされ、プラグインは自動的に[Dify Marketplace](https://marketplace.dify.ai/)で公開されます。 +[Difyプラグインリポジトリ](https://github.com/langgenius/dify-plugins)にパッケージをアップロードできます。その前に、[プラグイン公開ガイドライン](/ja/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace)を満たしていることを確認してください。承認されると、コードがメインブランチにマージされ、プラグインは自動的に[Dify Marketplace](https://marketplace.dify.ai/)で公開されます。 --- ## さらなる探求 -複雑なタスクには、複数ラウンドの思考とツール呼び出しが必要になることが多く、通常は**モデル呼び出し → ツール使用**をタスクが終了するか最大イテレーション数に達するまで繰り返します。このプロセスでは、プロンプトを効果的に管理することが重要です。[完全なFunction Calling実装](https://github.com/langgenius/dify-official-plugins/blob/main/agent-strategies/cot_agent/strategies/function_calling.py)を参照して、モデルが外部ツールを呼び出し、その出力を処理するための標準化されたアプローチを確認してください。 +複雑なタスクには、複数ラウンドの思考とツール呼び出しが必要になることが多く、タスクが終了するか最大イテレーション数に達するまでモデル呼び出し → ツール使用のサイクルを繰り返します。このプロセスではプロンプトを効果的に管理することが重要です。[完全なFunction Calling実装](https://github.com/langgenius/dify-official-plugins/blob/main/agent-strategies/cot_agent/strategies/function_calling.py)を参照して、モデルが外部ツールを呼び出し、その出力を処理するための標準化されたアプローチを確認してください。 {/* Contributing Section diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx index 04aca84bc..44400e230 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx @@ -7,21 +7,21 @@ dimensions: standard_title: Cheatsheet language: ja title: チートシート -description: 環境要件、インストール方法、開発プロセス、プラグインのカテゴリとタイプ、一般的なコードスニペット、よくある問題の解決策を含む、Dify プラグイン開発の包括的なリファレンスガイドです。開発者が素早く参照できるように設計されています。 +description: 環境セットアップ、インストール、開発プロセス、プラグインタイプを含む、Dify プラグイン開発のクイックリファレンス --- ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet) を参照してください。 ## 環境要件 -- Python バージョン 3.12 -- Dify プラグインスキャフォールドツール (dify-plugin-daemon) +- Python バージョン 3.12 +- Dify プラグインスキャフォールドツール (`dify-plugin-daemon`) -> 詳細： [開発ツールの初期化](/ja/develop-plugin/getting-started/cli) +セットアップ手順については、[開発ツールの初期化](/ja/develop-plugin/getting-started/cli)を参照してください。 ## Dify プラグイン開発パッケージの取得 -[Dify Plugin CLI](https://github.com/langgenius/dify-plugin-daemon/releases) +GitHub リリースページから [Dify Plugin CLI](https://github.com/langgenius/dify-plugin-daemon/releases) をダウンロードしてください。 ### 各プラットフォームのインストール方法 @@ -70,7 +70,7 @@ dify version ## 開発パッケージの実行 -ここでは `dify` を例として使用します。ローカルインストール方法を使用している場合は、コマンドを適宜置き換えてください。例： `./dify-plugin-darwin-arm64 plugin init` +以下の例では `dify` をコマンドとして使用しています。ローカルインストールの場合は、コマンドを適宜置き換えてください。例：`./dify-plugin-darwin-arm64 plugin init` ## プラグイン開発プロセス @@ -80,9 +80,9 @@ dify version ./dify plugin init ``` -プロンプトに従って、基本的なプラグイン情報の設定を完了してください +プロンプトに従って、基本的なプラグイン情報を設定してください。 -> 詳細： [Dify プラグイン開発： Hello World ガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) +詳細なウォークスルーについては、[Dify プラグイン開発： Hello World ガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)を参照してください。 ### 2. 開発モードで実行 @@ -92,7 +92,7 @@ dify version python -m main ``` -> 詳細： [プラグインのリモートデバッグ](/ja/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) +デバッグの詳細については、[プラグインのリモートデバッグ](/ja/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin)を参照してください。 ### 3. パッケージングとデプロイ @@ -103,13 +103,13 @@ cd .. dify plugin package ./yourapp ``` -> 詳細： [公開の概要](/ja/develop-plugin/publishing/marketplace-listing/release-overview) +公開の詳細については、[公開の概要](/ja/develop-plugin/publishing/marketplace-listing/release-overview)を参照してください。 ## プラグインカテゴリ ### ツールラベル -カテゴリ `tag` [class ToolLabelEnum(Enum)](https://github.com/langgenius/dify-plugin-sdks/blob/main/python/dify_plugin/entities/tool.py) +カテゴリタグは [`ToolLabelEnum`](https://github.com/langgenius/dify-plugin-sdks/blob/main/python/dify_plugin/entities/tool.py) で定義されています： ```python class ToolLabelEnum(Enum): @@ -133,25 +133,14 @@ class ToolLabelEnum(Enum): ## プラグインタイプリファレンス -Dify は様々なタイプのプラグイン開発をサポートしています： +Dify は複数のプラグインタイプをサポートしています： -- **ツールプラグイン**： サードパーティの API とサービスを統合 - > 詳細： [Dify プラグイン開発： Hello World ガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - -- **モデルプラグイン**： AI モデルを統合 - > 詳細： [モデルプラグイン](/ja/develop-plugin/features-and-specs/plugin-types/model-designing-rules)、[新しいモデルのクイック統合](/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - -- **エージェント戦略プラグイン**： Agent の思考と意思決定戦略をカスタマイズ - > 詳細： [エージェント戦略プラグイン](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation) - -- **拡張プラグイン**： Endpoints や WebApp など、Dify プラットフォームの機能を拡張 - > 詳細： [拡張プラグイン](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint) - -- **データソースプラグイン**： ナレッジベースパイプラインのドキュメントデータソースおよび開始点として機能 - > 詳細： [データソースプラグイン](/ja/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin) - -- **トリガープラグイン**： サードパーティのイベントに基づいてワークフローの実行を自動的にトリガー - > 詳細： [トリガープラグイン](/ja/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin) +- **ツールプラグイン**：サードパーティの API とサービスを統合します。[Dify プラグイン開発： Hello World ガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)を参照してください。 +- **モデルプラグイン**：AI モデルを統合します。[モデルプラグイン](/ja/develop-plugin/features-and-specs/plugin-types/model-designing-rules)および[新しいモデルのクイック統合](/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider)を参照してください。 +- **Agent 戦略プラグイン**：Agent の思考と意思決定戦略をカスタマイズします。[Agent 戦略プラグイン](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation)を参照してください。 +- **拡張プラグイン**：Endpoints や WebApp など、Dify プラットフォームの機能を拡張します。[拡張プラグイン](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint)を参照してください。 +- **データソースプラグイン**：ナレッジパイプラインのドキュメントデータソースおよび開始点として機能します。[データソースプラグイン](/ja/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin)を参照してください。 +- **トリガープラグイン**：サードパーティのイベントに基づいてワークフローの実行を自動的にトリガーします。[トリガープラグイン](/ja/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin)を参照してください。 {/* Contributing Section diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx index fa90ae0e7..3c2361e26 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx @@ -7,16 +7,16 @@ dimensions: standard_title: Model Provider Plugin language: ja title: モデルプロバイダープラグイン -description: この包括的なガイドでは、モデルプロバイダープラグインの作成について詳細な手順を提供し、プロジェクトの初期化、ディレクトリ構造の編成、モデル構成方法、プロバイダーコードの記述、およびコア API 実装の詳細な例を含むモデル統合の実装について説明します。 +description: プロジェクトのセットアップ、プロバイダー設定からモデル実装、デバッグ、公開までのモデルプロバイダープラグインの構築 --- ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) を参照してください。 ## 前提条件 -* [Dify CLI](/ja/develop-plugin/getting-started/cli) -* 基本的な Python プログラミングスキルとオブジェクト指向プログラミングの理解 -* 統合したいモデルプロバイダーの API ドキュメントへの精通 +- [Dify CLI](/ja/develop-plugin/getting-started/cli) +- 基本的な Python プログラミングスキルとオブジェクト指向プログラミングの理解 +- 統合したいモデルプロバイダーの API ドキュメントへの精通 ## ステップ 1: 新しいプラグインプロジェクトの作成と設定 @@ -38,9 +38,9 @@ dify plugin init モデルプロバイダープラグインには、以下の必須権限を設定します： -* **Models** - モデル操作の基本権限 -* **LLM** - 大規模言語モデル機能の権限 -* **Storage** - ファイル操作の権限（必要な場合） +- **Models**: モデル操作の基本権限。 +- **LLM**: 大規模言語モデル機能の権限。 +- **Storage**: ファイル操作の権限（必要な場合）。 ![モデルプラグインの権限](https://assets-docs.dify.ai/2024/12/10f3b3ee6c03a1215309f13d712455d4.png) @@ -72,28 +72,28 @@ Dify は、ユーザーがプロバイダーのモデルとどのようにやり ### 事前定義モデル（`predefined-model`） -これらは、統一されたプロバイダー認証情報のみで使用できるモデルです。ユーザーがプロバイダーの API キーやその他の認証詳細を設定すると、すべての事前定義モデルにすぐにアクセスできます。 +事前定義モデルは、統一されたプロバイダー認証情報のみを必要とします。ユーザーがプロバイダーの API キーやその他の認証詳細を設定すると、すべての事前定義モデルにすぐにアクセスできます。 -**例**： `OpenAI` プロバイダーは、`gpt-3.5-turbo-0125` や `gpt-4o-2024-05-13` などの事前定義モデルを提供しています。ユーザーは OpenAI API キーを一度設定するだけで、これらすべてのモデルにアクセスできます。 +**例**：OpenAI プロバイダーは、`gpt-3.5-turbo-0125` や `gpt-4o-2024-05-13` などの事前定義モデルを提供しています。ユーザーは OpenAI API キーを一度設定するだけで、これらすべてのモデルにアクセスできます。 ### カスタムモデル（`customizable-model`） -これらは、各特定のモデルインスタンスに追加の設定が必要です。このアプローチは、モデルがプロバイダーレベルの認証情報以外の個別パラメータを必要とする場合に便利です。 +カスタムモデルは、各モデルインスタンスに追加の設定が必要です。このアプローチは、モデルがプロバイダーレベルの認証情報以外の個別パラメータを必要とする場合に便利です。 -**例**： `Xinference` は LLM と Text Embedding の両方をサポートしていますが、各モデルには固有の **model_uid** があります。ユーザーは使用したい各モデルごとにこの model_uid を個別に設定する必要があります。 +**例**：Xinference は LLM と Text Embedding の両方をサポートしていますが、各モデルには固有の `model_uid` があります。ユーザーは使用したい各モデルごとにこの `model_uid` を個別に設定する必要があります。 -これらの設定方法は、単一のプロバイダー内で**共存できます**。たとえば、プロバイダーがいくつかの事前定義モデルを提供しながら、ユーザーが特定の設定でカスタムモデルを追加できるようにすることができます。 +これら 2 つの設定方法は、単一のプロバイダー内で共存できます。たとえば、プロバイダーがいくつかの事前定義モデルを提供しながら、ユーザーが特定の設定でカスタムモデルを追加できるようにすることができます。 ## ステップ 3: モデルプロバイダーファイルの作成 新しいモデルプロバイダーの作成には、2 つの主要なコンポーネントが含まれます： -1. **プロバイダー設定 YAML ファイル** - プロバイダーの基本情報、サポートされるモデルタイプ、認証情報要件を定義 -2. **プロバイダークラスの実装** - 認証検証やその他のプロバイダーレベルの機能を実装 +- **プロバイダー設定 YAML ファイル**: プロバイダーの基本情報、サポートされるモデルタイプ、認証情報要件を定義します。 +- **プロバイダークラスの実装**: 認証検証やその他のプロバイダーレベルの機能を実装します。 ### 3.1 モデルプロバイダー設定ファイルの作成 -プロバイダー設定は、プロバイダーの基本情報、サポートされるモデルタイプ、設定方法、認証情報ルールを宣言する YAML ファイルで定義されます。このファイルは、プラグインプロジェクトのルートディレクトリに配置されます。 +プロバイダー設定は、プロバイダーの基本情報、サポートされるモデルタイプ、設定方法、認証情報ルールを宣言する YAML ファイルです。プラグインプロジェクトのルートディレクトリに配置してください。 以下は、`anthropic.yaml` 設定ファイルの注釈付き例です： @@ -162,7 +162,7 @@ extra: ### カスタムモデル設定 -プロバイダーがカスタムモデルをサポートする場合、各個別モデルに対してユーザーが設定する必要がある追加フィールドを定義する `model_credential_schema` セクションを追加する必要があります。これは、ファインチューニングされたモデルをサポートするプロバイダーや、モデル固有のパラメータが必要な場合に一般的です。 +プロバイダーがカスタムモデルをサポートする場合、各モデルに対してユーザーが設定する必要がある追加フィールドを定義する `model_credential_schema` セクションを追加します。これは、ファインチューニングされたモデルをサポートするプロバイダーや、モデル固有のパラメータが必要な場合に一般的です。 以下は OpenAI プロバイダーの例です： @@ -196,11 +196,11 @@ model_credential_schema: # 必要に応じて追加フィールド... ``` -完全なモデルプロバイダー YAML 仕様については、[モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema)ドキュメントを参照してください。 +完全なモデルプロバイダー YAML 仕様については、[モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema)を参照してください。 ### 3.2 モデルプロバイダーコードの記述 -次に、プロバイダークラス実装用の Python ファイルを作成します。このファイルは、プロバイダー名に一致する名前で `/provider` ディレクトリに配置する必要があります（例：`anthropic.py`）。 +次に、プロバイダークラス用の Python ファイルを `/provider` ディレクトリに作成します。ファイル名はプロバイダー名にちなんで付けます（例：`anthropic.py`）。 プロバイダークラスは `ModelProvider` を継承し、少なくとも `validate_provider_credentials` メソッドを実装する必要があります： @@ -240,15 +240,15 @@ class AnthropicProvider(ModelProvider): raise ex ``` -`validate_provider_credentials` メソッドは、ユーザーが Dify でプロバイダー認証情報を保存しようとするたびに呼び出されるため、非常に重要です。このメソッドは： +Dify は、ユーザーがプロバイダー認証情報を保存するたびに `validate_provider_credentials` を呼び出すため、このメソッドは： -1. 簡単な API 呼び出しを行って認証情報を検証しようとする -2. 検証が成功した場合は静かに戻る -3. 検証が失敗した場合は、役立つメッセージとともに `CredentialsValidateFailedError` をスロー +1. 簡単な API 呼び出しを行って認証情報を検証しようとする必要があります。 +2. 検証が成功した場合は静かに戻る必要があります。 +3. 検証が失敗した場合は、役立つメッセージとともに `CredentialsValidateFailedError` をスローする必要があります。 #### カスタムモデルプロバイダーの場合 -カスタムモデルのみを使用するプロバイダー（各モデルに独自の設定が必要な場合）には、より単純なプロバイダークラスを実装できます。たとえば、`Xinference` の場合： +カスタムモデルのみを使用するプロバイダー（各モデルに独自の設定が必要な場合）には、より単純なプロバイダークラスを実装できます。たとえば、Xinference の場合： ```python from dify_plugin import ModelProvider @@ -264,15 +264,15 @@ class XinferenceProvider(ModelProvider): ## ステップ 4: モデル固有のコードの実装 -プロバイダーの設定後、サポートする各モデルタイプの API 呼び出しを処理するモデル固有のコードを実装する必要があります。これには以下が含まれます： +プロバイダーの設定後、サポートする各モデルタイプの API 呼び出しを処理するモデル固有のコードを実装します。これには以下が含まれます： -1. 各特定モデルのモデル設定 YAML ファイルの作成 -2. API 通信を処理するモデルタイプクラスの実装 +1. 各特定モデルのモデル設定 YAML ファイルの作成。 +2. API 通信を処理するモデルタイプクラスの実装。 -これらのステップの詳細な手順については、以下を参照してください： +詳細な手順については、以下を参照してください： -* [モデル設計ルール](/ja/develop-plugin/features-and-specs/plugin-types/model-designing-rules) - 事前定義モデルを統合するための標準 -* [モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema) - モデル設定ファイルの標準 +- [モデル設計ルール](/ja/develop-plugin/features-and-specs/plugin-types/model-designing-rules): 事前定義モデルを統合するための標準。 +- [モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema): モデル設定ファイルの標準。 ### 4.1 モデル設定の定義（YAML） @@ -409,48 +409,49 @@ class MyProviderLargeLanguageModel(LargeLanguageModel): 実装する最も重要なメソッドは `_invoke` で、コア API 通信を処理します。このメソッドは： -1. Dify の標準化された入力をプロバイダーの API が必要とする形式に変換 -2. 適切なエラー処理で API 呼び出しを実行 -3. API レスポンスを Dify の標準化された出力形式に変換 -4. ストリーミングモードと非ストリーミングモードの両方を処理 +1. Dify の標準化された入力をプロバイダーの API が必要とする形式に変換する必要があります。 +2. 適切なエラー処理で API 呼び出しを実行する必要があります。 +3. API レスポンスを Dify の標準化された出力形式に変換する必要があります。 +4. ストリーミングモードと非ストリーミングモードの両方を処理する必要があります。 ## ステップ 5: プラグインのデバッグとテスト -Dify は、開発中にプラグインをテストできるリモートデバッグ機能を提供しています： +Dify はリモートデバッグをサポートしているため、開発中にプラグインをテストできます： -1. Dify インスタンスで「プラグイン管理」に移動し、「プラグインをデバッグ」をクリックしてデバッグキーとサーバーアドレスを取得 -2. `.env` ファイルでこれらの値をローカル環境に設定： +1. Dify インスタンスで **プラグイン管理** に移動し、**プラグインをデバッグ** をクリックしてデバッグキーとサーバーアドレスを取得します。 +2. `.env` ファイルでこれらの値をローカル環境に設定します： -```dotenv -INSTALL_METHOD=remote -REMOTE_INSTALL_URL=:5003 -REMOTE_INSTALL_KEY=****-****-****-****-**** -``` + ```dotenv + INSTALL_METHOD=remote + REMOTE_INSTALL_URL=:5003 + REMOTE_INSTALL_KEY=****-****-****-****-**** + ``` -3. `python -m main` でプラグインをローカルで実行し、Dify でテスト +3. `python -m main` でプラグインをローカルで実行し、Dify でテストします。 ## ステップ 6: パッケージ化と公開 プラグインの準備ができたら： -1. スキャフォールディングツールを使用してパッケージ化： +1. スキャフォールディングツールを使用してパッケージ化します： + ```bash dify plugin package models/ ``` -2. 提出前にパッケージ化されたプラグインをローカルでテスト +2. 提出前にパッケージ化されたプラグインをローカルでテストします。 -3. [Dify 公式プラグインリポジトリ](https://github.com/langgenius/dify-official-plugins)にプルリクエストを提出 +3. [Dify 公式プラグインリポジトリ](https://github.com/langgenius/dify-official-plugins)にプルリクエストを提出します。 公開プロセスの詳細については、[公開の概要](/ja/develop-plugin/publishing/marketplace-listing/release-overview)を参照してください。 ## 参考リソース -- [新しいモデルのクイック統合](/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - 既存のプロバイダーに新しいモデルを追加する方法 -- [プラグイン開発の基本概念](/ja/develop-plugin/getting-started/getting-started-dify-plugin) - プラグイン開発入門ガイドに戻る -- [モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema) - 詳細なモデル設定仕様を学ぶ -- [一般仕様](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications) - プラグインマニフェストファイルの設定を学ぶ -- [Dify プラグイン SDK リファレンス](https://github.com/langgenius/dify-plugin-sdks) - 基底クラス、データ構造、エラータイプを参照 +- [新しいモデルのクイック統合](/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider): 既存のプロバイダーに新しいモデルを追加する方法。 +- [プラグイン開発の基本概念](/ja/develop-plugin/getting-started/getting-started-dify-plugin): プラグイン開発入門ガイドに戻る。 +- [モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema): 詳細なモデル設定仕様。 +- [一般仕様](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications): プラグインマニフェストファイルの設定。 +- [Dify プラグイン SDK リファレンス](https://github.com/langgenius/dify-plugin-sdks): 基底クラス、データ構造、エラータイプ。 {/* Contributing Section diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx index e04685acb..c3d4d54a1 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx @@ -1,27 +1,27 @@ --- title: データソースプラグイン -description: Dify 1.9.0以降のデータソースプラグインを構築し、ナレッジパイプラインにドキュメントを供給—アーキテクチャ、コードサンプル、デバッグ手順 +description: Dify 1.9.0以降のデータソースプラグインを構築し、ナレッジパイプラインにドキュメントを供給 --- ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin) を参照してください。 -データソースプラグインは、Dify 1.9.0で導入された新しいタイプのプラグインです。ナレッジパイプラインにおいて、ドキュメントデータソースとして機能し、パイプライン全体の起点となります。 +データソースプラグインは、Dify 1.9.0で導入され、ナレッジパイプラインにドキュメントを供給し、パイプライン全体の起点として機能します。 -この記事では、データソースプラグインの開発方法について、プラグインアーキテクチャ、コード例、デバッグ方法を網羅し、データソースプラグインの迅速な開発とリリースを支援します。 +このガイドでは、データソースプラグインの構築とリリースに必要なプラグインアーキテクチャ、コード例、デバッグ方法について説明します。 ## 前提条件 -読み進める前に、ナレッジパイプラインの基本的な理解とプラグイン開発に関する知識があることを確認してください。関連情報はこちらで確認できます： +ナレッジパイプラインとプラグイン開発の基本的な理解が必要です： - [ステップ2：ナレッジパイプラインオーケストレーション](/ja/use-dify/knowledge/knowledge-pipeline/knowledge-pipeline-orchestration) - [Difyプラグイン開発：Hello Worldガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) -## **データソースプラグインの種類** +## データソースプラグインの種類 -Difyは3種類のデータソースプラグインをサポートしています：Webクローラー、オンラインドキュメント、オンラインドライブ。プラグインコードを実装する際、プラグインの機能を提供するクラスは特定のデータソースクラスを継承する必要があります。3種類のプラグインタイプはそれぞれ異なる親クラスに対応しています。 +Difyは3種類のデータソースプラグインをサポートしています：Webクローラー、オンラインドキュメント、オンラインドライブ。各タイプは異なる親クラスに対応しており、プラグインの機能を実装するクラスはそれを継承する必要があります。 - 親クラスを継承してプラグイン機能を実装する方法については、[ツールプラグイン：ツールコードの準備](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin#4-ツールコードの準備)を参照してください。 + 親クラスを継承してプラグイン機能を実装する方法については、[ツールプラグイン：ツールコードの準備](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin#4-prepare-tool-code)を参照してください。 各データソースプラグインタイプは複数のデータソースをサポートしています。例えば： @@ -40,9 +40,9 @@ Difyは3種類のデータソースプラグインをサポートしています ### データソースプラグインの作成 -スキャフォールディングコマンドラインツールを使用して、`datasource`タイプを選択することでデータソースプラグインを作成できます。セットアップが完了すると、コマンドラインツールが自動的にプラグインプロジェクトコードを生成します。 +スキャフォールディングコマンドラインツールで`datasource`タイプを選択してデータソースプラグインを作成します。セットアップが完了すると、ツールがプラグインプロジェクトコードを生成します。 -```powershell +```bash dify plugin init ``` @@ -62,7 +62,7 @@ dify plugin init - `provider`ディレクトリ：プラグインプロバイダーの説明と認証実装コードを含みます。 - `datasources`ディレクトリ：データソースからデータを取得するための説明とコアロジックを含みます。 -``` +```text ├── _assets │ └── icon.svg ├── datasources @@ -80,20 +80,22 @@ dify plugin init #### 正しいバージョンとタグの設定 -- `manifest.yaml`ファイルで、最小サポートDifyバージョンを以下のように設定します： +- `manifest.yaml`ファイルで、最小サポートDifyバージョンを設定します： ```yaml minimum_dify_version: 1.9.0 ``` -- `manifest.yaml`ファイルで、Dify Marketplaceのデータソースカテゴリにプラグインを表示するために以下のタグを追加します： + +- 同じファイルで、Dify Marketplaceのデータソースカテゴリにプラグインを表示するために以下のタグを追加します： ```yaml tags: - rag ``` -- `requirements.txt`ファイルで、データソースプラグイン開発に使用するプラグインSDKバージョンを以下のように設定します： - ```yaml +- `requirements.txt`ファイルで、プラグインSDKバージョンを設定します： + + ```text dify-plugin>=0.5.0,<0.6.0 ``` @@ -113,7 +115,7 @@ datasources: ``` - プロバイダーYAMLファイルの作成について詳しくは、[ツールプラグイン：サードパーティサービス認証情報の完成](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin#2-サードパーティサービス認証情報の完成)を参照してください。 + プロバイダーYAMLファイルの作成について詳しくは、[ツールプラグイン：サードパーティサービス認証情報の完成](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin#2-complete-third-party-service-credentials)を参照してください。 @@ -124,7 +126,7 @@ datasources: #### プロバイダーコードファイルの作成 -- APIキー認証モードを使用する場合、データソースプラグインのプロバイダーコードファイルはツールプラグインと同一です。プロバイダークラスが継承する親クラスを`DatasourceProvider`に変更するだけです。 +- APIキー認証の場合、プロバイダーコードファイルはツールプラグインと同一です。プロバイダークラスの親クラスを`DatasourceProvider`に変更するだけです。 ```python class YourDatasourceProvider(DatasourceProvider): @@ -137,9 +139,10 @@ datasources: except Exception as e: raise ToolProviderCredentialValidationError(str(e)) ``` -- OAuth認証モードを使用する場合、データソースプラグインはツールプラグインとわずかに異なります。OAuthでアクセス権限を取得する際、データソースプラグインはフロントエンドに表示するユーザー名とアバターを同時に返すことができます。そのため、`_oauth_get_credentials`と`_oauth_refresh_credentials`は`name`、`avatar_url`、`expires_at`、`credentials`を含む`DatasourceOAuthCredentials`型を返す必要があります。 - `DatasourceOAuthCredentials`クラスは以下のように定義されており、返す際に対応する型を設定する必要があります： +- OAuth認証の場合、データソースプラグインはツールプラグインとわずかに異なります：OAuthでアクセスを取得する際、フロントエンドに表示するユーザー名とアバターも返すことができます。そのため、`_oauth_get_credentials`と`_oauth_refresh_credentials`は`name`、`avatar_url`、`expires_at`、`credentials`を含む`DatasourceOAuthCredentials`オブジェクトを返す必要があります。 + + `DatasourceOAuthCredentials`クラスは以下のように定義されています： ```python class DatasourceOAuthCredentials(BaseModel): @@ -237,9 +240,9 @@ output_schema: description: the description of the website ``` -Webクローラープラグインのメインロジックコードでは、クラスは`WebsiteCrawlDatasource`を継承し、`_get_website_crawl`メソッドを実装する必要があります。次に、`create_crawl_message`メソッドを使用してWebクロールメッセージを返します。 +Webクローラープラグインのメインロジックコードでは、クラスは`WebsiteCrawlDatasource`を継承し、`_get_website_crawl`メソッドを実装する必要があります。`create_crawl_message`メソッドを使用してクロール結果を返します。 -複数のWebページをクロールしてバッチで返すには、`WebSiteInfo.status`を`processing`に設定し、`create_crawl_message`メソッドを使用して各バッチのクロールされたページを返します。すべてのページがクロールされた後、`WebSiteInfo.status`を`completed`に設定します。 +複数のWebページをクロールしてバッチで返すには、`WebSiteInfo.status`を`processing`に設定し、各バッチのクロールされたページに対して`create_crawl_message`を呼び出します。すべてのページがクロールされた後、`WebSiteInfo.status`を`completed`に設定します。 ```python class YourDataSource(WebsiteCrawlDatasource): @@ -346,11 +349,11 @@ output_schema: オンラインドライブプラグインのメインロジックコードでは、クラスは`OnlineDriveDatasource`を継承し、2つのメソッドを実装する必要があります：`_browse_files`と`_download_file`。 -ユーザーがプラグインを実行すると、まず`_browse_files`を呼び出してファイルリストを取得します。この時点で、`prefix`は空であり、ルートディレクトリのファイルリストを要求していることを示します。ファイルリストにはフォルダとファイルタイプの変数が含まれています。ユーザーがフォルダを開くと、`_browse_files`メソッドが再度呼び出されます。この時点で、`OnlineDriveBrowseFilesRequest`の`prefix`はそのフォルダ内のファイルリストを取得するために使用されるフォルダIDになります。 +ユーザーがプラグインを実行すると、まず`_browse_files`を呼び出してファイルリストを取得します。この時点で、`prefix`は空であり、ルートディレクトリのファイルリストを要求していることを示します。リストにはフォルダとファイルの両方のエントリが含まれています。ユーザーがフォルダを開くと、`_browse_files`が再度呼び出され、`OnlineDriveBrowseFilesRequest`の`prefix`はそのフォルダ内のファイルリストを取得するために使用されるフォルダIDになります。 ユーザーがファイルを選択した後、プラグインは`_download_file`メソッドとファイルIDを使用してファイルのコンテンツを取得します。`_get_mime_type_from_filename`メソッドを使用してファイルのMIMEタイプを取得でき、パイプラインが異なるファイルタイプを適切に処理できるようになります。 -ファイルリストに複数のファイルが含まれている場合、`OnlineDriveFileBucket.is_truncated`を`True`に設定し、`OnlineDriveFileBucket.next_page_parameters`をファイルリストの次のページを取得するために必要なパラメータ（サービスプロバイダーに応じて次のページのリクエストIDやURLなど）に設定できます。 +ファイルリストに複数のファイルが含まれている場合、`OnlineDriveFileBucket.is_truncated`を`True`に設定し、`OnlineDriveFileBucket.next_page_parameters`を次のページを取得するために必要なパラメータ（サービスプロバイダーに応じて次のページのリクエストIDやURLなど）に設定できます。 @@ -415,12 +418,12 @@ AWS S3のようなストレージサービスでは、`prefix`、`bucket`、`id` - `id`：`_download_file`メソッドは`prefix`変数を使用しないため、完全なファイルパスを`id`に含める必要があります。例えば、`id=container1/folder1/file1.txt`は`container1`バケット内の`folder1`フォルダから`file1.txt`ファイルを取得することを示します。 - [公式Google Driveプラグイン](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/google_cloud_storage/datasources/google_cloud_storage.py)と[公式AWS S3プラグイン](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/aws_s3_storage/datasources/aws_s3_storage.py)の具体的な実装を参照できます。 + リファレンス実装については、[公式Google Driveプラグイン](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/google_cloud_storage/datasources/google_cloud_storage.py)と[公式AWS S3プラグイン](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/aws_s3_storage/datasources/aws_s3_storage.py)を参照してください。 ## プラグインのデバッグ -データソースプラグインは、リモートデバッグまたはローカルプラグインとしてインストールしてデバッグする2つのデバッグ方法をサポートしています。以下の点に注意してください： +データソースプラグインは、リモートデバッグとローカルでのプラグインインストールの2つのデバッグ方法をサポートしています。以下の点に注意してください： - プラグインがOAuth認証を使用している場合、リモートデバッグの`redirect_uri`はローカルプラグインのものとは異なります。サービスプロバイダーのOAuth Appの関連設定を適宜更新してください。 - データソースプラグインはシングルステップデバッグをサポートしていますが、完全な機能を確保するために、完全なナレッジパイプラインでテストすることをお勧めします。 @@ -439,7 +442,7 @@ AWS S3のようなストレージサービスでは、`prefix`、`bucket`、`id` プラグインディレクトリで以下のコマンドを実行して`.difypkg`プラグインパッケージを生成します： -``` +```bash dify plugin package . -o your_datasource.difypkg ``` diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx index 28bafd250..d480c405c 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx @@ -7,69 +7,69 @@ dimensions: standard_title: Slack Bot language: ja title: Slack Bot -description: このガイドでは、Slack Botプラグインの開発について、プロジェクトの初期化、設定フォームの編集、機能の実装、デバッグ、エンドポイントのセットアップ、検証、パッケージングまで完全なウォークスルーを提供します。Slack上でAIを活用したチャットボットを構築するために、Difyプラグインスキャフォールディングツールと事前に作成したSlack Appが必要です。 +description: Slack Botプラグインの構築方法を学びます。Difyアプリとslackを接続し、プロジェクトのセットアップからデバッグ、パッケージングまでを解説します。 --- ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin) を参照してください。 -**学習内容**： - -AIを活用したSlack Botの構築方法をしっかりと理解できます。このBotはSlack内でユーザーの質問に直接回答できます。プラグインを初めて開発する場合は、まず[プラグイン開発クイックスタートガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)を読むことをお勧めします。 +このガイドでは、Slack内でユーザーの質問に直接回答できるAIを活用したSlack Botを構築します。プラグインを初めて開発する場合は、まず[プラグイン開発クイックスタートガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)を読んでください。 ## プロジェクトの背景 -Difyプラグインエコシステムは、統合をよりシンプルでアクセスしやすくすることに焦点を当てています。このガイドでは、Slackを例として、Slack Botプラグインの開発プロセスを順を追って説明します。これにより、チームはSlack内でLLMと直接チャットでき、AIの活用効率が大幅に向上します。 +Slack Botプラグインを使用すると、チームはSlack内でLLMと直接チャットでき、会話がすでに行われている場所にAIを配置できます。 -Slackは、堅牢なAPIを備えたオープンなリアルタイムコミュニケーションプラットフォームです。その機能の中には、webhookベースのイベントシステムがあり、開発が非常に簡単です。このシステムを活用してSlack Botプラグインを作成します。以下の図に示されています： +Slackは、堅牢なAPIを備えたオープンなリアルタイムコミュニケーションプラットフォームです。webhookベースのイベントシステムがあり、開発が非常に簡単です。このガイドでは、そのシステムを使用してSlack Botプラグインを作成します。以下の図に示されています： ![Slack Bot の図](https://assets-docs.dify.ai/2025/01/a0865d18f1ca4051601ca53fa6f92db2.png) -> 混乱を避けるため、以下の概念を説明します： -> -> * **Slack Bot** Slackプラットフォーム上のチャットボットで、リアルタイムでやり取りできる仮想ユーザーとして機能します。 -> * **Slack Botプラグイン** DifyアプリケーションとSlackを接続するDifyマーケットプレイス内のプラグインです。このガイドでは、そのプラグインの開発方法に焦点を当てています。 + +このガイドでは、2つの類似した用語が登場します： + +- **Slack Bot**：Slackプラットフォーム上のチャットボットで、リアルタイムでやり取りできる仮想ユーザーです。 +- **Slack Botプラグイン**：DifyアプリケーションとSlackを接続するDifyマーケットプレイス内のプラグインです。このガイドでは、その構築方法を説明します。 + -**動作の仕組み（簡単な概要）**： +### 動作の仕組み -1. **Slack Botにメッセージを送信する** +1. **ユーザーがSlack Botにメッセージを送信する** - Slack内のユーザーがBotにメッセージを送信すると、Slack Botは即座にDifyプラットフォームにwebhookリクエストを発行します。 + Slack内のユーザーがBotにメッセージを送信すると、Slack Botは即座にDifyプラットフォームにwebhookリクエストを発行します。 -2. **メッセージをSlack Botプラグインに転送する** +2. **SlackがメッセージをSlack Botプラグインに転送する** - Difyプラットフォームは、Slack Botプラグインをトリガーし、詳細をDifyアプリケーションに中継します。これは、メールシステムで受信者のアドレスを入力するのと似ています。SlackのAPIを通じてSlack webhookアドレスを設定し、Slack Botプラグインに入力することで、この接続が確立されます。プラグインはSlackリクエストを処理し、Difyアプリケーションに送信します。そこでLLMがユーザーの入力を分析し、応答を生成します。 + Difyプラットフォームは、Slack Botプラグインをトリガーし、メッセージをDifyアプリケーションに中継します。これは、メールシステムが受信者のアドレスに配信するのと似ています。SlackのAPIを通じてSlack webhookアドレスを設定し、プラグインに入力することで、この接続を確立します。プラグインはSlackリクエストを処理し、Difyアプリケーションに転送します。そこでLLMが入力を分析し、応答を生成します。 -3. **Slackに応答を返す** +3. **プラグインがSlackに応答を返す** - Slack BotプラグインがDifyアプリケーションから応答を受け取ると、同じルートを通じてLLMの回答をSlack Botに送り返します。Slack内のユーザーは、チャットしている場所で、よりインテリジェントでインタラクティブな体験を得られます。 + プラグインがDifyアプリケーションから応答を受け取ると、同じルートを通じてLLMの回答をSlack Botに送り返し、ユーザーはチャットしている場所で応答を受け取ります。 ## 前提条件 -- **Difyプラグイン開発ツール**：詳細については、[開発ツールの初期化](/ja/develop-plugin/getting-started/cli)を参照してください。 -- **Python環境（バージョン 3.12）**：[Python公式ダウンロードページ](https://www.python.org/downloads/)を参照するか、LLMに完全なセットアップガイドを尋ねてください。 -- Slack Appを作成してOAuthトークンを取得する +- **Difyプラグイン開発ツール**：[開発ツールの初期化](/ja/develop-plugin/getting-started/cli)を参照してください。 +- **Python環境（バージョン 3.12）**：[Python公式ダウンロードページ](https://www.python.org/downloads/)を参照してください。 +- **OAuthトークンを持つSlack App**：以下の手順を参照してください。 -[Slack APIプラットフォーム](https://api.slack.com/apps)にアクセスし、Slack appをゼロから作成し、デプロイするワークスペースを選択します。 +Slack Appを作成するには、[Slack APIプラットフォーム](https://api.slack.com/apps)にアクセスし、ゼロからアプリを作成し、デプロイするワークスペースを選択します。 - ![](https://assets-docs.dify.ai/2025/01/c1fd0ac1467faf5a3ebf3818bb234aa8.png) + ![Slack Appを作成する](https://assets-docs.dify.ai/2025/01/c1fd0ac1467faf5a3ebf3818bb234aa8.png) -1. **Webhooksを有効にする**： +1. **Webhooksを有効にする**： ![Webhooksを有効にする](https://assets-docs.dify.ai/2025/01/7112e0710300f1db16827e17f3deac00.png) -2. **Slackワークスペースにアプリをインストールする**： +2. **Slackワークスペースにアプリをインストールする**： ![Slackワークスペースにアプリをインストールする](https://assets-docs.dify.ai/2025/01/88c360ff4f7b04fea52174ce330522fa.png) -3. 将来のプラグイン開発のために**OAuthトークンを取得する**： +3. プラグイン開発のために**OAuthトークンを取得する**： ![将来のプラグイン開発のためにOAuthトークンを取得する](https://assets-docs.dify.ai/2025/01/dcd8ec947253f2ef9ae121ed77ec9f26.png) @@ -77,7 +77,7 @@ Slackは、堅牢なAPIを備えたオープンなリアルタイムコミュニ ## 1. プラグインの開発 -ここから実際のコーディングに入ります。開始する前に、[クイックスタート：拡張プラグインの開発](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint)を読んでいるか、すでにDifyプラグインを構築した経験があることを確認してください。 +コーディングを開始する前に、[クイックスタート：拡張プラグインの開発](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint)を読んでいるか、すでにDifyプラグインを構築した経験があることを確認してください。 ### 1.1 プロジェクトの初期化 @@ -97,9 +97,9 @@ dify plugin init ### 1.2 設定フォームの編集 -このプラグインは、どのDifyアプリが応答を処理するか、およびBotの応答を認証するためのSlack Appトークンを知る必要があります。そのため、プラグインのフォームにこれら2つのフィールドを追加します。 +プラグインは2つの情報を必要とします：どのDifyアプリが応答を処理するか、およびBotの応答を認証するためのSlack Appトークンです。プラグインのフォームに両方のフィールドを追加します。 -groupディレクトリ内のYAMLファイル（例：`group/slack.yaml`）を修正します。フォームのファイル名は、プラグイン作成時に入力した情報によって決まるので、適宜調整してください。 +`group`ディレクトリ内のYAMLファイル（例：`group/slack.yaml`）を修正します。フォームのファイル名は、プラグイン作成時に入力した情報によって決まるので、適宜パスを調整してください。 **サンプルコード**： @@ -146,19 +146,18 @@ endpoints: - endpoints/slack.yaml ``` -設定フィールドの説明： +2つの設定フィールドについて詳しく説明します： -``` +```yaml - name: app type: app-selector scope: chat ``` -* **type**： app-selectorに設定すると、ユーザーはこのプラグインを使用する際にメッセージを特定のDifyアプリに転送できます。 +- **`type`**：`app-selector`に設定すると、ユーザーはこのプラグインを使用する際にメッセージを特定のDifyアプリに転送できます。 +- **`scope`**：`chat`に設定すると、プラグインはAgent、チャットボット、またはチャットフローなどのアプリタイプとのみやり取りできます。 -* **scope**： chatに設定すると、プラグインはAgent、チャットボット、またはチャットフローなどのアプリタイプとのみやり取りできます。 - -最後に、`endpoints/slack.yaml`ファイルで、受信するSlackメッセージを適切に処理するためにリクエストメソッドをPOSTに変更します。 +最後に、`endpoints/slack.yaml`ファイルで、受信するSlackメッセージを処理できるようにリクエストメソッドを`POST`に変更します。 **サンプルコード**： @@ -256,10 +255,10 @@ class SlackEndpoint(Endpoint): Difyプラットフォームに移動し、プラグインのリモートデバッグアドレスとキーを取得します。 - ![](https://assets-docs.dify.ai/2025/01/8d24006f0cabf5bf61640a9023c45db8.png) + ![リモートデバッグアドレスとキーを取得する](https://assets-docs.dify.ai/2025/01/8d24006f0cabf5bf61640a9023c45db8.png) -プラグインプロジェクトに戻り、`.env.example`ファイルをコピーして`.env`にリネームします。 +プラグインプロジェクトに戻り、`.env.example`ファイルをコピーして`.env`にリネームし、デバッグ詳細を入力します： ```bash INSTALL_METHOD=remote @@ -267,15 +266,17 @@ REMOTE_INSTALL_URL=debug.dify.ai:5003 REMOTE_INSTALL_KEY=********-****-****-****-************ ``` -`python -m main`を実行してプラグインを起動します。Difyのプラグイン管理ページで、ワークスペースにプラグインがインストールされているのが確認できるはずです。他のチームメンバーもアクセスできるようになります。 +プラグインを起動します： ```bash python -m main ``` +Difyのプラグイン管理ページで、ワークスペースにプラグインがインストールされているのが確認できるはずです。他のチームメンバーもアクセスできます。 + ### プラグインエンドポイントの設定 -Difyのプラグイン管理ページから、新しくインストールされたテストプラグインを見つけ、新しいエンドポイントを作成します。名前、Botトークンを入力し、接続するアプリを選択します。 +Difyのプラグイン管理ページから、新しくインストールされたテストプラグインを見つけ、新しいエンドポイントを作成します。名前と**Botトークン**を入力し、接続するアプリを選択します。 ![プラグインをテスト](https://assets-docs.dify.ai/2025/01/07f87e8a2786d6f5f05195961c5630c3.png) @@ -311,17 +312,17 @@ Difyのプラグイン管理ページから、新しくインストールされ ## 4. プラグインの検証 -コード内で、`self.session.app.chat.invoke`がDifyアプリケーションを呼び出すために使用され、`app_id`や`query`などのパラメータを渡します。応答はSlack Botに返されます。`python -m main`を再度実行してプラグインをデバッグ用に再起動し、SlackがDify Appの応答を正しく表示するかどうかを確認します： +プラグインは`self.session.app.chat.invoke`を通じてDifyアプリケーションを呼び出し、`app_id`や`query`などのパラメータを渡し、応答をSlack Botに返します。`python -m main`を再度実行してプラグインを再起動し、SlackがDifyアプリの応答を表示するか確認します： - ![コード内で、self](https://assets-docs.dify.ai/2025/01/6fc872d1343ce8503d63c5222f7f26f9.png) + ![SlackがDifyアプリの応答を表示](https://assets-docs.dify.ai/2025/01/6fc872d1343ce8503d63c5222f7f26f9.png) --- ## 5. プラグインのパッケージ化（オプション） -プラグインが正しく動作することを確認したら、以下のコマンドでパッケージ化して名前を付けることができます。実行後、現在のディレクトリに`slack_bot.difypkg`ファイルが作成されます：これが最終的なプラグインパッケージです。詳細なパッケージ化手順については、[ローカルファイルとしてパッケージ化して共有](/ja/develop-plugin/publishing/marketplace-listing/release-by-file)を参照してください。 +プラグインが正しく動作することを確認したら、以下のコマンドでパッケージ化します。コマンドは現在のディレクトリに`slack_bot.difypkg`ファイルを生成します。これが最終的なプラグインパッケージです。詳細なパッケージ化手順については、[ローカルファイルとしてパッケージ化して共有](/ja/develop-plugin/publishing/marketplace-listing/release-by-file)を参照してください。 ```bash # ./slack_botを実際のプラグインプロジェクトパスに置き換えてください。 @@ -329,7 +330,7 @@ Difyのプラグイン管理ページから、新しくインストールされ dify plugin package ./slack_bot ``` -おめでとうございます！プラグインの開発、テスト、パッケージ化が正常に完了しました！ +おめでとうございます！プラグインの開発、テスト、パッケージ化が完了しました！ --- @@ -341,32 +342,34 @@ dify plugin package ./slack_bot ## 関連リソース -- [プラグイン開発の基礎](/ja/develop-plugin/getting-started/getting-started-dify-plugin) - Difyプラグイン開発の包括的な概要 -- [プラグイン開発クイックスタートガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - ゼロからプラグイン開発を始める -- [拡張プラグインの開発](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 拡張プラグイン開発について学ぶ -- [Difyサービスの逆呼び出し](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation) - Difyプラットフォームの機能を呼び出す方法を理解する -- [逆呼び出し：App](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app) - プラットフォーム内でアプリを呼び出す方法を学ぶ -- [プラグインの公開](/ja/develop-plugin/publishing/marketplace-listing/release-overview) - 公開プロセスを学ぶ -- [Difyマーケットプレイスへの公開](/ja/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace) - マーケットプレイス公開ガイド -- [エンドポイントの詳細定義](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 詳細なエンドポイント定義 +- [プラグイン開発の基礎](/ja/develop-plugin/getting-started/getting-started-dify-plugin)：Difyプラグイン開発の包括的な概要 +- [プラグイン開発クイックスタートガイド](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)：ゼロからプラグイン開発を始める +- [拡張プラグインの開発](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint)：拡張プラグイン開発 +- [Difyサービスの逆呼び出し](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation)：Difyプラットフォームの機能を呼び出す方法 +- [逆呼び出し：App](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app)：プラットフォーム内でアプリを呼び出す方法 +- [プラグインの公開](/ja/develop-plugin/publishing/marketplace-listing/release-overview)：公開プロセス +- [Difyマーケットプレイスへの公開](/ja/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace)：マーケットプレイス公開ガイド +- [エンドポイントの詳細定義](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint)：エンドポイントリファレンス ## さらに読む 完全なDifyプラグインプロジェクトの例については、[GitHubリポジトリ](https://github.com/langgenius/dify-plugins)をご覧ください。完全なソースコードと実装の詳細を含む追加のプラグインも見つかります。 -プラグイン開発についてさらに探求したい場合は、以下を確認してください： +プラグイン開発についてさらに探求するには、以下を参照してください： **クイックスタート**： + - [拡張プラグインの開発](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint) - [モデルプラグインの開発](/ja/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - [バンドルプラグイン：複数のプラグインのパッケージング](/ja/develop-plugin/features-and-specs/advanced-development/bundle) **プラグインインターフェースドキュメント**： -- [Manifestファイルによるプラグイン情報の定義](/ja/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest) - Manifest構造 -- [エンドポイント](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint) - エンドポイントの詳細定義 -- [逆呼び出し](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation) - Dify機能の逆呼び出し -- [一般仕様](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications) - ツール仕様 -- [モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema) - モデル + +- [Manifestファイルによるプラグイン情報の定義](/ja/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest)：Manifest構造 +- [エンドポイント](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint)：エンドポイントリファレンス +- [逆呼び出し](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation)：プラグインからDify機能を呼び出す +- [一般仕様](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications)：ツール仕様 +- [モデルスキーマ](/ja/develop-plugin/features-and-specs/plugin-types/model-schema)：モデルスキーマリファレンス {/* Contributing Section diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx index 2305dc74e..99e0ac69a 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx @@ -14,7 +14,7 @@ standard_title: Flomo Tool (10-min) - Flomoメモ取りAPIへの接続 - AIとの会話から直接Flomoにメモを保存する機能 - 認証とエラー状態の適切な処理 -- Dify Marketplaceでの配布準備完了 +- Difyマーケットプレイスでの配布準備完了 @@ -47,6 +47,7 @@ standard_title: Flomo Tool (10-min) インストールを確認： + ```bash dify version ``` @@ -60,8 +61,9 @@ standard_title: Flomo Tool (10-min) ``` プロンプトに従ってプラグインをセットアップします： - - 名前を「flomo」にする - - プラグインタイプとして「tool」を選択 + + - 名前を`flomo`にする + - プラグインタイプとして`tool`を選択 - その他の必須フィールドを入力 @@ -70,14 +72,14 @@ standard_title: Flomo Tool (10-min) cd flomo ``` - これにより、必要なすべてのファイルを含むプラグインの基本構造が作成されます。 + プロジェクトには、必要なすべてのファイルを含むプラグインの基本構造が含まれています。 ## ステップ2：プラグインマニフェストの定義 -manifest.yamlファイルはプラグインのメタデータ、権限、機能を定義します。 +`manifest.yaml`ファイルはプラグインのメタデータ、権限、機能を定義します。 `manifest.yaml`ファイルを作成します： @@ -286,12 +288,14 @@ class FlomoTool(Tool): サンプル環境ファイルをコピーします： + ```bash cp .env.example .env ``` `.env`ファイルをDify環境の詳細で編集します： - ``` + + ```bash INSTALL_METHOD=remote REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003 REMOTE_INSTALL_KEY=your_debug_key @@ -310,8 +314,7 @@ class FlomoTool(Tool): - Difyインスタンスでプラグインに移動し、デバッグ中のプラグイン（「debugging」とマークされています）を見つけます。 - Flomo APIの認証情報を追加し、メモの送信をテストします。 + Difyインスタンスで**プラグイン**ページを開き、プラグイン（**debugging**とマークされています）を見つけます。Flomo APIの認証情報を追加し、メモの送信をテストします。 @@ -323,7 +326,7 @@ class FlomoTool(Tool): dify plugin package ./ ``` -これにより、Dify Marketplaceにアップロードできる`plugin.difypkg`ファイルが作成されます。 +これにより、Difyマーケットプレイスにアップロードできる`plugin.difypkg`ファイルが作成されます。 ## FAQとトラブルシューティング @@ -337,17 +340,17 @@ dify plugin package ./ - 必要なすべてのファイルが存在し、manifest.yamlの構造が有効であることを確認してください。 + 必要なすべてのファイルが存在し、`manifest.yaml`の構造が有効であることを確認してください。 ## まとめ -外部APIサービスと連携する機能的なDifyプラグインを構築しました！この同じパターンは、データベースや検索エンジンから生産性ツールやカスタムAPIまで、何千ものサービスとの統合に使用できます。 +外部APIサービスと連携する機能的なDifyプラグインを構築しました。この同じパターンは、データベースや検索エンジンから生産性ツールやカスタムAPIまで、何千ものサービスとの統合に使用できます。 - 機能、セットアップ、使用例を説明するREADME.mdを英語（en_US）で作成してください + 機能、セットアップ、使用例を説明する`README.md`を英語（en_US）で作成してください 他の言語用に`readme/README_zh_Hans.md`のような追加のREADMEファイルを作成してください diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx index 0a2ddf6e9..6ba9a3d39 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx @@ -1,6 +1,6 @@ --- title: Markdownエクスポーター -description: '会話をさまざまなドキュメント形式にエクスポートするプラグインの作成方法を学ぶ' +description: 会話をさまざまなドキュメント形式にエクスポートするプラグインの作成方法を学ぶ language: en standard_title: Building a Markdown Exporter Plugin --- @@ -9,7 +9,7 @@ standard_title: Building a Markdown Exporter Plugin ## 構築するもの -このガイドでは、会話を一般的なドキュメント形式にエクスポートする実用的なDifyプラグインの構築方法を学びます。最終的に、プラグインは以下の機能を持ちます： +会話を一般的なドキュメント形式にエクスポートする実用的なDifyプラグインを構築します。最終的に、プラグインは以下の機能を持ちます： - MarkdownテキストをWord文書（.docx）に変換 - 会話をPDFファイルとしてエクスポート @@ -37,7 +37,7 @@ standard_title: Building a Markdown Exporter Plugin ``` - [Dify GitHubリリースページ](https://github.com/langgenius/dify-plugin-daemon/releases)から最新のDify CLIを取得します + [Dify GitHubリリースページ](https://github.com/langgenius/dify-plugin-daemon/releases)から最新のDify CLIを取得します。 ```bash # Download appropriate version @@ -49,6 +49,7 @@ standard_title: Building a Markdown Exporter Plugin インストールの確認： + ```bash dify version ``` @@ -62,9 +63,10 @@ standard_title: Building a Markdown Exporter Plugin ``` プロンプトに従って入力してください： - - Name: "md_exporter" - - Type: "tool" - - その他の詳細は指示に従って完了してください + + - **Name**: `md_exporter` + - **Type**: `tool` + - その他の詳細は指示に従って完了してください。 @@ -449,12 +451,14 @@ plugin = PluginRunner( まず、テンプレートから`.env`ファイルを作成します： + ```bash cp .env.example .env ``` Dify環境の詳細を設定します： - ``` + + ```dotenv INSTALL_METHOD=remote REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003 REMOTE_INSTALL_KEY=your_debug_key @@ -499,23 +503,23 @@ dify plugin package ./ このプラグインを拡張するための興味深い方法をいくつか紹介します： -- **カスタムテンプレート**：企業ブランディングやパーソナライズされたスタイルを追加 -- **マルチフォーマットサポート**：HTML、Markdown、その他のフォーマットへのエクスポートを拡張 -- **画像処理**：会話からの画像を処理して含める -- **テーブルサポート**：データテーブルの適切なフォーマットを実装 -- **コラボレーティブ編集**：Google Docsや類似のプラットフォームとの統合を追加 +- **カスタムテンプレート**：企業ブランディングやパーソナライズされたスタイルを追加。 +- **マルチフォーマットサポート**：HTML、Markdown、その他のフォーマットへのエクスポートを拡張。 +- **画像処理**：会話からの画像を処理して含める。 +- **テーブルサポート**：データテーブルの適切なフォーマットを実装。 +- **コラボレーティブ編集**：Google Docsや類似のプラットフォームとの統合を追加。 -ドキュメント変換の核心的な課題は、フォーマットと構造を維持することです。このプラグインで使用されているアプローチは、まずMarkdownをHTML（中間形式）に変換し、その後そのHTMLをターゲット形式に処理します。 +ドキュメント変換の核心的な課題は、フォーマットと構造を維持することです。このプラグインはまずMarkdownをHTML（中間形式）に変換し、その後そのHTMLをターゲット形式に処理します。 -この2段階のプロセスは柔軟性を提供します：HTML表現で動作する新しい出力モジュールを追加するだけで、追加のフォーマットをサポートするように拡張できます。 +この2段階のプロセスは柔軟性を提供します：HTML表現で動作する新しい出力モジュールを追加することで、追加のフォーマットをサポートできます。 -PDF生成には、CSSサポート付きの高品質なPDFレンダリングを提供するWeasyPrintが選択されました。Word文書には、python-docxがドキュメント構造に対する詳細な制御を提供します。 +PDF生成には、CSSサポート付きの高品質なPDFレンダリングを提供するWeasyPrintを使用しています。Word文書には、python-docxがドキュメント構造に対する詳細な制御を提供します。 ## まとめ -会話をプロフェッショナルなドキュメント形式でエクスポートできるようにすることで、Difyプラットフォームに実際の価値を追加する実用的なプラグインを構築しました。この機能は、AI会話と従来のドキュメントワークフローの間のギャップを埋めます。 +会話をプロフェッショナルなドキュメント形式でエクスポートできる実用的なプラグインを構築しました。これにより、AI会話と従来のドキュメントワークフローの間のギャップを埋めることができます。 diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx index 0fb628653..dc187776a 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx @@ -7,17 +7,16 @@ description: ナレッジベースノードがマルチモーダル出力をテ ナレッジパイプラインでは、ナレッジベースノードは2種類のマルチモーダルデータ形式の入力をサポートしています：`multimodal-Parent-Child` と `multimodal-General`。 -マルチモーダルデータ処理用のツールプラグインを開発する際、プラグインの出力するマルチモーダルデータ（テキスト、画像、音声、動画など）がナレッジベースノードで正しく認識・埋め込みされるためには、以下の設定が必要です： +ナレッジベースノードがツールプラグインのマルチモーダル出力（テキスト、画像、音声、動画など）を認識し埋め込むためには、以下の2つの設定を完了する必要があります： -- **ツールコードファイル内で**、ツールセッションインターフェースを呼び出してファイルをアップロードし、`files` オブジェクトを構築します。 - -- **ツールプロバイダーのYAMLファイル**で、`output_schema` を `multimodal-Parent-Child` または `multimodal-General` として宣言します。 +- **ツールコードファイル内**：ツールセッションインターフェースを呼び出してファイルをアップロードし、`files` オブジェクトを構築します。 +- **ツールプロバイダーのYAMLファイル内**：`output_schema` を `multimodal-Parent-Child` または `multimodal-General` として宣言します。 ## ファイルのアップロードとファイルオブジェクトの構築 -マルチモーダルデータ（画像など）を処理する際は、まずDifyのツールセッションツールを使用してファイルをアップロードし、ファイルのメタデータを取得する必要があります。 +マルチモーダルデータ（画像など）を処理する際は、まずDifyのツールセッションを通じてファイルをアップロードし、ファイルのメタデータを取得します。 -以下の例では、Dify公式プラグイン **Dify Extractor** を使用して、ファイルのアップロードと `files` オブジェクトの構築方法を示します。 +以下の例は、Dify公式プラグイン **Dify Extractor** から抜粋したもので、ファイルのアップロードと `files` オブジェクトの構築方法を示しています。 ```python # Upload the file using the tool session @@ -30,41 +29,42 @@ file_res = self._tool.session.file.upload( # Generate a Markdown image reference using the file preview URL image_url = f"![image]({file_res.preview_url})" ``` -アップロードインターフェースは、ファイル情報を含む `UploadFileResponse` オブジェクトを返します。その構造は以下の通りです： -```python - from enum import Enum - from pydantic import BaseModel +アップロードインターフェースは、ファイル情報を含む `UploadFileResponse` オブジェクトを返します： + +```python +from enum import Enum +from pydantic import BaseModel - class UploadFileResponse(BaseModel): - class Type(str, Enum): - DOCUMENT = "document" - IMAGE = "image" - VIDEO = "video" - AUDIO = "audio" +class UploadFileResponse(BaseModel): + class Type(str, Enum): + DOCUMENT = "document" + IMAGE = "image" + VIDEO = "video" + AUDIO = "audio" - @classmethod - def from_mime_type(cls, mime_type: str): - if mime_type.startswith("image/"): - return cls.IMAGE - if mime_type.startswith("video/"): - return cls.VIDEO - if mime_type.startswith("audio/"): - return cls.AUDIO - return cls.DOCUMENT - id: str - name: str - size: int - extension: str - mime_type: str - type: Type | None = None - preview_url: str | None = None + @classmethod + def from_mime_type(cls, mime_type: str): + if mime_type.startswith("image/"): + return cls.IMAGE + if mime_type.startswith("video/"): + return cls.VIDEO + if mime_type.startswith("audio/"): + return cls.AUDIO + return cls.DOCUMENT + id: str + name: str + size: int + extension: str + mime_type: str + type: Type | None = None + preview_url: str | None = None ``` -ファイル情報（`name`、`size`、`extension`、`mime_type` など）をマルチモーダル出力構造の `files` フィールドにマッピングできます。 +ファイル情報（`name`、`size`、`extension`、`mime_type` など）をマルチモーダル出力構造の `files` フィールドにマッピングします。 - ```yaml multimodal_parent_child_structure highlight={22-62} expandable + ```json multimodal_parent_child_structure highlight={22-62} expandable { "$id": "https://dify.ai/schemas/v1/multimodal_parent_child_structure.json", "$schema": "http://json-schema.org/draft-07/schema#", @@ -145,7 +145,7 @@ image_url = f"![image]({file_res.preview_url})" } ``` - ```yaml multimodal_general_structure highlight={18-56} expandable + ```json multimodal_general_structure highlight={18-56} expandable { "$id": "https://dify.ai/schemas/v1/multimodal_general_structure.json", "$schema": "http://json-schema.org/draft-07/schema#", @@ -216,9 +216,9 @@ image_url = f"![image]({file_res.preview_url})" ## マルチモーダル出力構造の宣言 -マルチモーダルデータの構造は、Dify公式が提供するJSON Schemaによって定義されています。 +マルチモーダルデータの構造は、Dify公式のJSON Schemaによって定義されています。 -ナレッジベースノードがプラグインのマルチモーダル出力タイプを認識できるようにするためには、プラグインプロバイダーのYAMLファイルで `output_schema` の `result` フィールドを対応する公式Schema URLに指定する必要があります。 +ナレッジベースノードがプラグインのマルチモーダル出力タイプを認識できるようにするには、プラグインプロバイダーのYAMLファイルで `output_schema` の `result` フィールドを対応する公式Schema URLに指定します。 ```yaml output_schema: @@ -232,7 +232,7 @@ output_schema: # $ref: "https://dify.ai/schemas/v1/multimodal_general_structure.json" ``` -`multimodal-Parent-Child` の例として、完全なYAML設定は以下の通りです： +例えば、`multimodal-Parent-Child` を使用した完全なYAML設定は以下の通りです： ```yaml expandable identity: diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx index 3eec8eb98..d3adce2c5 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx @@ -7,31 +7,31 @@ dimensions: standard_title: Endpoint language: ja title: Endpoint プラグイン -description: 著者 Yeuoly、Allen。このドキュメントでは、Neko Cat プロジェクトを例として、Dify プラグインにおける Endpoint の構造と実装について詳しく説明します。Endpoint グループの定義、インターフェースの設定、_invoke メソッドの実装、リクエストとレスポンスの処理について説明します。また、各種 YAML 設定フィールドの意味と使用方法についても解説します。 +description: Neko Cat プロジェクトを例として、Dify プラグインにおける HTTP Endpoint の定義、設定、実装について説明します --- ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint) を参照してください。 -このドキュメントでは、[Neko Cat](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko) プロジェクトを例として、プラグイン内の Endpoint の構造について説明します。Endpoint はプラグインが公開する HTTP インターフェースで、外部システムとの統合に使用できます。完全なプラグインコードについては、[GitHub リポジトリ](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko)を参照してください。 +Endpoint はプラグインが外部システムとの統合のために公開する HTTP インターフェースです。このガイドでは、[Neko Cat](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko) プロジェクトを例として、その構造について説明します。完全なプラグインコードについては、[GitHub リポジトリ](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko)を参照してください。 ## グループ定義 -`Endpoint` グループは、複数の `Endpoint` の集合です。Dify プラグイン内で新しい `Endpoint` を作成する際、以下の設定を入力する必要がある場合があります。 +Endpoint グループは、複数の Endpoint の集合です。Dify プラグイン内で新しい Endpoint を作成する際、以下の設定を入力する必要がある場合があります。 - ![](https://assets-docs.dify.ai/2024/11/763dbf86e4319591415dc5a1b6948ccb.png) + ![Endpoint グループ設定フォーム](https://assets-docs.dify.ai/2024/11/763dbf86e4319591415dc5a1b6948ccb.png) -`Endpoint Name` の他に、グループの設定情報を記述することで新しいフォーム項目を追加できます。保存をクリックすると、含まれる複数のインターフェースが表示され、それらは同じ設定情報を使用します。 +**Endpoint Name** の他に、グループの設定を記述することでフォーム項目を追加できます。保存後、グループに含まれる複数のインターフェースが表示され、それらはすべて同じ設定を共有します。 - ![Besides the Endpoint Name, You Can Add New Form Items by Writing the Group's](https://assets-docs.dify.ai/2024/11/b778b7093b7df0dc80a476c65ddcbe58.png) + ![Endpoint グループインターフェース一覧](https://assets-docs.dify.ai/2024/11/b778b7093b7df0dc80a476c65ddcbe58.png) -### **構造** +### 構造 -* `settings` (map[string] [ProviderConfig](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications#providerconfig)): Endpoint 設定の定義。 -* `endpoints` （list[string]、必須）: 具体的な `endpoint` インターフェース定義を指します。 +- **`settings`** (map[string] [ProviderConfig](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications#providerconfig)): Endpoint 設定の定義。 +- **`endpoints`** (list[string]、必須): 具体的な `endpoint` インターフェース定義を指します。 ```yaml settings: @@ -55,11 +55,11 @@ endpoints: ## インターフェース定義 -* `path` (string): Werkzeug インターフェース標準に従います。 -* `method` (string): インターフェースメソッド、`HEAD`、`GET`、`POST`、`PUT`、`DELETE`、`OPTIONS` のみサポートします。 -* `extra` (object): 基本情報以外の設定情報。 - * `python` (object) - * `source` (string): このインターフェースを実装するソースコード。 +- **`path`** (string): Werkzeug インターフェース標準に従います。 +- **`method`** (string): インターフェースメソッド、`HEAD`、`GET`、`POST`、`PUT`、`DELETE`、`OPTIONS` のみサポートします。 +- **`extra`** (object): 基本情報以外の設定情報。 + - **`python`** (object) + - **`source`** (string): このインターフェースを実装するソースコード。 ```yaml path: "/duck/" @@ -71,15 +71,15 @@ extra: ## インターフェース実装 -`dify_plugin.Endpoint` を継承するサブクラスを実装し、`_invoke` メソッドを実装する必要があります。 +`dify_plugin.Endpoint` のサブクラスを実装し、その `_invoke` メソッドを実装します。 -* **入力パラメータ** - * `r` (Request): `werkzeug` の `Request` オブジェクト。 - * `values` (Mapping): パスから解析されたパスパラメータ。 - * `settings` (Mapping): この `Endpoint` の設定情報。 -* **戻り値** - * `werkzeug` の `Response` オブジェクト、ストリーミングレスポンスをサポートします。 - * 文字列を直接返すことはサポートされていません。 +- **入力パラメータ** + - **`r`** (Request): `werkzeug` の `Request` オブジェクト。 + - **`values`** (Mapping): パスから解析されたパスパラメータ。 + - **`settings`** (Mapping): この Endpoint の設定情報。 +- **戻り値** + - `werkzeug` の `Response` オブジェクト、ストリーミングレスポンスをサポートします。 + - 文字列を直接返すことはサポートされていません。 サンプルコード： @@ -104,20 +104,20 @@ class Duck(Endpoint): ## 注意事項 -* Endpoint はプラグインが呼び出されたときにのみインスタンス化されます。常時稼働するサービスではありません。 -* Endpoint を開発する際はセキュリティに注意し、危険な操作の実行を避けてください。 -* Endpoint は Webhook コールバックの処理や、他のシステムが接続するためのインターフェースの提供に使用できます。 +- Endpoint はプラグインが呼び出されたときにのみインスタンス化されます。常時稼働するサービスではありません。 +- Endpoint を開発する際はセキュリティに注意し、危険な操作の実行を避けてください。 +- Endpoint は Webhook コールバックの処理や、他のシステムが接続するためのインターフェースの提供に使用できます。 プラグイン開発を学習中の場合は、まず[プラグイン開発入門](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)と[開発者チートシート](/ja/develop-plugin/dev-guides-and-walkthroughs/cheatsheet)を読むことをお勧めします。 ## 関連リソース -* [プラグイン開発の基本概念](/ja/develop-plugin/getting-started/getting-started-dify-plugin) - プラグイン開発の全体的なアーキテクチャを理解する。 -* [Neko Cat サンプル](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 拡張プラグイン開発のサンプル。 -* [汎用仕様定義](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications) - ProviderConfig などの共通構造を理解する。 -* [Slack Bot プラグイン開発サンプル](/ja/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin) - 別のプラグイン開発サンプル。 -* [プラグイン開発入門](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - ゼロからプラグインを開発する。 -* [Dify サービスの逆呼び出し](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app) - 逆呼び出し機能の使用方法を学ぶ。 +- [プラグイン開発の基本概念](/ja/develop-plugin/getting-started/getting-started-dify-plugin): プラグイン開発の全体的なアーキテクチャ。 +- [Neko Cat サンプル](/ja/develop-plugin/dev-guides-and-walkthroughs/endpoint): 拡張プラグイン開発のサンプル。 +- [汎用仕様定義](/ja/develop-plugin/features-and-specs/plugin-types/general-specifications): ProviderConfig などの共通構造。 +- [Slack Bot プラグイン開発サンプル](/ja/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin): 別のプラグイン開発サンプル。 +- [プラグイン開発入門](/ja/develop-plugin/dev-guides-and-walkthroughs/tool-plugin): ゼロからプラグインを開発する。 +- [Dify サービスの逆呼び出し](/ja/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app): 逆呼び出し機能の使用方法。 {/* Contributing Section diff --git a/ja/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx b/ja/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx index 4c8da32da..2521340bc 100644 --- a/ja/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx +++ b/ja/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx @@ -47,35 +47,35 @@ sequenceDiagram ### フロー1: OAuthクライアントセットアップ（管理者/開発者フロー） - Dify Cloudでは、Difyチームが人気のあるツールプラグイン用のOAuthアプリを作成し、OAuthクライアントをセットアップするため、ユーザーは自分で設定する手間が省けます。 + Dify Cloudでは、Difyチームが人気のあるツールプラグイン用のOAuthアプリを作成し、OAuthクライアントをセットアップするため、ユーザーは自分で設定する必要がありません。 セルフホストDifyインスタンスの管理者は、このセットアップフローを実行する必要があります。 -Difyインスタンスの管理者または開発者は、まずサードパーティサービスに信頼できるアプリケーションとしてOAuthアプリを登録する必要があります。これにより、DifyツールプロバイダーをOAuthクライアントとして設定するために必要な資格情報を取得できます。 +Difyインスタンスの管理者または開発者は、まずサードパーティサービスに信頼できるアプリケーションとしてOAuthアプリを登録します。これにより、DifyツールプロバイダーをOAuthクライアントとして設定するために必要な資格情報が提供されます。 例として、DifyのGmailツールプロバイダー用のOAuthクライアントをセットアップする手順を示します： - 1. [Google Cloud Console](https://console.cloud.google.com)にアクセスし、新しいプロジェクトを作成するか、既存のプロジェクトを選択します - 2. 必要なAPI（例：Gmail API）を有効にします + 1. [Google Cloud Console](https://console.cloud.google.com)にアクセスし、新しいプロジェクトを作成するか、既存のプロジェクトを選択します。 + 2. 必要なAPI（例：Gmail API）を有効にします。 - - 1. **APIs & Services** \> **OAuth consent screen**に移動します - 2. 公開プラグインの場合は**External**ユーザータイプを選択します - 3. アプリケーション名、ユーザーサポートメール、開発者連絡先を入力します - 4. 必要に応じて承認済みドメインを追加します - 5. テストの場合：**Test users**セクションでテストユーザーを追加します + + 1. **APIs & Services** \> **OAuth consent screen**に移動します。 + 2. 公開プラグインの場合は**External**ユーザータイプを選択します。 + 3. アプリケーション名、ユーザーサポートメール、開発者連絡先を入力します。 + 4. 必要に応じて承認済みドメインを追加します。 + 5. テストの場合、**Test users**セクションでテストユーザーを追加します。 - 1. **APIs & Services** \> **Credentials**に移動します - 2. **Create Credentials** \> **OAuth 2.0 Client IDs**をクリックします - 3. **Web application**タイプを選択します + 1. **APIs & Services** \> **Credentials**に移動します。 + 2. **Create Credentials** \> **OAuth 2.0 Client IDs**をクリックします。 + 3. **Web application**タイプを選択します。 4. `client_id`と`client_secret`が生成されます。これらを資格情報として保存します。 - OAuthクライアント設定ポップアップにclient_idとclient_secretを入力して、ツールプロバイダーをクライアントとしてセットアップします。 + OAuthクライアント設定ポップアップに`client_id`と`client_secret`を入力して、ツールプロバイダーをクライアントとしてセットアップします。 ![OAuth クライアント設定ダイアログ](/images/develop-plugin/dev-guide/oauth-client-settings-dialog.png) @@ -117,7 +117,7 @@ OAuthクライアントを設定した後、個々のDifyユーザーは、プ ### 1. プロバイダーマニフェストでOAuthスキーマを定義する -プロバイダーマニフェストの`oauth_schema`セクションは、プラグインのOAuthに必要な資格情報と、OAuthフローが生成するものをDifyに伝えます。OAuthをセットアップするには、2つのスキーマが必要です： +プロバイダーマニフェストの`oauth_schema`セクションは、プラグインのOAuthセットアップに必要な資格情報と、OAuthフローが生成するものをDifyに伝えます。OAuthをセットアップするには、2つのスキーマが必要です： #### client_schema @@ -136,7 +136,7 @@ oauth_schema: ``` - `url`フィールドはサードパーティサービスのヘルプドキュメントに直接リンクします。これは困っている管理者/開発者の助けになります。 + `url`フィールドはサードパーティサービスのヘルプドキュメントにリンクし、セットアップ時に管理者や開発者に参考情報を提供します。 #### credentials_schema @@ -155,7 +155,7 @@ oauth_schema: ``` - OAuth \+ APIキー認証オプションを提供するには、`oauth_schema`と`credentials_for_provider`の両方を含めてください。 + OAuthとAPIキー認証オプションの両方を提供するには、`oauth_schema`と`credentials_for_provider`を一緒に含めてください。 ### 2. ツールプロバイダーで必要なOAuthメソッドを完成させる @@ -170,7 +170,7 @@ from dify_plugin.errors.tool import ToolProviderCredentialValidationError, ToolP `ToolProvider`クラスは、これら3つのOAuthメソッドを実装する必要があります（例として`GmailProvider`を使用）： - いかなる場合でも、`ToolOAuthCredentials`の資格情報に`client_secret`を返してはなりません。これはセキュリティ上の問題につながる可能性があります。 + `ToolOAuthCredentials`の資格情報に`client_secret`を返してはなりません。これはセキュリティ上の問題につながる可能性があります。 @@ -207,7 +207,7 @@ def _oauth_get_credentials( ) -> ToolOAuthCredentials: """ Exchange authorization code for access token and refresh token. This is called - to creates ONE credential set for one account connection + to create ONE credential set for one account connection. """ # Extract authorization code from OAuth callback code = request.args.get("code") @@ -281,8 +281,8 @@ def _oauth_refresh_credentials( self, redirect_uri: str, system_credentials: Mapping[str, Any], credentials: Mapping[str, Any] ) -> ToolOAuthCredentials: """ - Refresh the credentials using refresh token. - Dify calls this automatically when tokens expire + Refresh the credentials using the refresh token. + Dify calls this automatically when tokens expire. """ refresh_token = credentials.get("refresh_token") if not refresh_token: @@ -348,7 +348,7 @@ def _oauth_refresh_credentials( ### 3. ツールでトークンにアクセスする -`Tool`実装でOAuth資格情報を使用して認証済みAPI呼び出しを行うことができます： +`Tool`実装でOAuth資格情報を使用して認証済みAPI呼び出しを行います： ```python class YourTool(BuiltinTool): @@ -363,13 +363,13 @@ class YourTool(BuiltinTool): `self.runtime.credentials`は現在のユーザーのトークンを自動的に提供します。Difyはリフレッシュを自動的に処理します。 -OAuthとAPI_KEY認証の両方をサポートするプラグインの場合、`self.runtime.credential_type`を使用して2つの認証タイプを区別できます。 +OAuthと`API_KEY`認証の両方をサポートするプラグインの場合、`self.runtime.credential_type`を使用して2つの認証タイプを区別します。 ### 4. 正しいバージョンを指定する OAuthには最新のSDKとDifyバージョンが必要です。`requirements.txt`でプラグインSDKを固定します： -``` +```text dify_plugin>=0.5.0 ``` diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx index 423c25426..4f831d601 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx @@ -5,9 +5,9 @@ description: 从零开始构建一个 Function Calling Agent 策略——一个 ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin)。 -**Agent 策略插件**帮助 LLM 执行推理或决策等任务，包括选择和调用工具以及处理结果。这使系统能够更自主地解决问题。 +**Agent 策略插件**为 LLM 提供推理和决策逻辑，使其能够选择工具、调用工具并处理结果，从而自主解决问题。 -下面，你将看到如何开发一个支持 **Function Calling** 来自动获取当前时间的插件。 +本指南将引导你构建一个 **Function Calling** 策略，让模型能够自主获取当前时间。 ## 前置条件 @@ -16,9 +16,9 @@ description: 从零开始构建一个 Function Calling Agent 策略——一个 有关准备插件开发工具的详细信息，请参阅[初始化开发工具](/zh/develop-plugin/getting-started/cli)。 - -**提示**：在终端中运行 `dify version` 以确认脚手架工具已安装。 - + +在终端中运行 `dify version` 以确认脚手架工具已安装。 + --- @@ -26,11 +26,11 @@ description: 从零开始构建一个 Function Calling Agent 策略——一个 运行以下命令为你的 Agent 插件创建开发模板： -``` +```bash dify plugin init ``` -按照屏幕提示操作，并参考示例注释获取指导。 +按照屏幕提示操作；下面的注释解释了每个选择。 ```bash ➜ Dify Plugins Developing dify plugin init @@ -69,7 +69,7 @@ Models: ... ``` -初始化完成后，你将获得一个包含插件开发所需全部资源的文件夹。熟悉 Agent 策略插件的整体结构将简化开发过程： +初始化完成后，你将获得一个包含插件开发所需全部资源的文件夹： ```text ├── GUIDE.md # User guide and documentation @@ -100,25 +100,25 @@ Agent 策略插件的开发围绕两个文件展开： ### 2.1 定义参数 -要构建 Agent 插件，首先在 `strategies/basic_agent.yaml` 中指定必要的参数。这些参数定义了插件的核心功能，例如调用 LLM 或使用工具。 +首先在 `strategies/basic_agent.yaml` 中声明插件的参数。这些参数支持插件的核心功能，例如调用 LLM 或使用工具。 我们建议首先包含以下四个参数： -1. **model**：要调用的大语言模型（例如 GPT-4、GPT-4o-mini）。 -2. **tools**：增强插件功能的工具列表。 -3. **query**：发送给模型的用户输入或提示词内容。 -4. **maximum_iterations**：防止过度计算的最大迭代次数。 +- **`model`**：要调用的大语言模型（例如 GPT-4、GPT-4o-mini）。 +- **`tools`**：增强插件功能的工具列表。 +- **`query`**：发送给模型的用户输入或提示词内容。 +- **`maximum_iterations`**：最大迭代次数，用于防止过度计算。 -示例代码： +示例： ```yaml identity: name: basic_agent # the name of the agent_strategy author: novice # the author of the agent_strategy label: - en_US: BasicAgent # the engilish label of the agent_strategy + en_US: BasicAgent # the English label of the agent_strategy description: - en_US: BasicAgent # the english description of the agent_strategy + en_US: BasicAgent # the English description of the agent_strategy parameters: - name: model # the name of the model parameter type: model-selector # model-type @@ -157,7 +157,7 @@ extra: source: strategies/basic_agent.py ``` -配置好这些参数后，插件将自动生成用户友好的界面，以便你轻松管理它们： +Dify 会根据这些参数声明自动渲染配置界面： ![Agent 策略插件界面](https://assets-docs.dify.ai/2025/01/d011e2eba4c37f07a9564067ba787df8.png) @@ -165,9 +165,7 @@ extra: ### 2.2 获取参数并执行 -用户填写这些基本字段后，你的插件需要处理提交的参数。在 `strategies/basic_agent.py` 中，为 Agent 定义一个参数类，然后在你的逻辑中获取并应用这些参数。 - -验证传入参数： +用户填写这些字段后，你的插件会接收提交的值。在 `strategies/basic_agent.py` 中，定义一个 Pydantic 模型来验证传入的参数： ```python from dify_plugin.entities.agent import AgentInvokeMessage @@ -181,7 +179,7 @@ class BasicParams(BaseModel): query: str ``` -获取参数后，执行具体的业务逻辑： +然后在 `_invoke` 中解析参数并运行你的策略逻辑： ```python class BasicAgentAgentStrategy(AgentStrategy): @@ -191,19 +189,19 @@ class BasicAgentAgentStrategy(AgentStrategy): ## 3. 调用模型 -在 Agent 策略插件中，**调用模型**是工作流的核心。你可以使用 SDK 中的 `session.model.llm.invoke()` 高效地调用 LLM，处理文本生成、对话等任务。 +调用模型是 Agent 策略的核心。使用 SDK 中的 `session.model.llm.invoke()` 来调用 LLM 进行文本生成、对话等任务。 -如果你希望 LLM **处理工具**，请确保它输出结构化参数以匹配工具的接口。换句话说，LLM 必须根据用户的指令生成工具可以接受的输入参数。 +如果你希望 LLM 驱动工具调用，它必须输出与每个工具接口匹配的结构化参数——即工具可以接受的输入，这些输入源自用户的指令。 -构造以下参数： +该方法接受以下参数： -* model -* prompt\_messages -* tools -* stop -* stream +- `model` +- `prompt_messages` +- `tools` +- `stop` +- `stream` -方法定义示例代码： +方法签名： ```python def invoke( @@ -216,25 +214,25 @@ def invoke( ) -> Generator[LLMResultChunk, None, None] | LLMResult:... ``` -要查看完整的功能实现，请参阅模型调用的示例代码。 +要查看完整实现，请参阅下方[示例代码](#示例代码)中的**调用模型**标签页。 -此代码实现以下功能：用户输入命令后，Agent 策略插件自动调用 LLM，根据生成的结果构造工具调用所需的参数，并使模型能够灵活调度集成的工具以高效完成复杂任务。 +完成此设置后，用户输入命令时插件会调用 LLM，根据模型输出构建工具调用参数，并让模型调度配置的工具来完成复杂任务。 ![生成工具的请求参数](https://assets-docs.dify.ai/2025/01/01e32c2d77150213c7c929b3cceb4dae.png) -## 4. 处理工具 +## 4. 调用工具 -指定工具参数后，Agent 策略插件必须实际调用这些工具。使用 `session.tool.invoke()` 来发起这些请求。 +当模型生成工具参数后，插件必须实际调用这些工具。使用 `session.tool.invoke()` 来发起这些请求。 -构造以下参数： +该方法接受以下参数： -- provider -- tool\_name -- parameters +- `provider` +- `tool_name` +- `parameters` -方法定义示例代码： +方法签名： ```python def invoke( @@ -246,7 +244,7 @@ def invoke( ) -> Generator[ToolInvokeMessage, None, None]:... ``` -如果你希望 LLM 自己生成工具调用所需的参数，可以将模型的输出与工具调用代码结合起来实现。 +如果你希望 LLM 自己生成工具调用参数，可以将模型提取的工具调用传入你的调用代码： ```python tool_instances = ( @@ -262,7 +260,7 @@ for tool_call_id, tool_call_name, tool_call_args in tool_calls: ) ``` -完成这些设置后，你的 Agent 策略插件可以自动执行 **Function Calling**，例如获取当前时间。 +你的插件现在可以自动执行 Function Calling——例如获取当前时间。 ![工具调用](https://assets-docs.dify.ai/2025/01/80e5de8acc2b0ed00524e490fd611ff5.png) @@ -270,12 +268,12 @@ for tool_call_id, tool_call_name, tool_call_args in tool_calls: ## 5. 创建日志 -在 **Agent 策略插件**中，通常需要多个步骤才能完成复杂任务。对于开发者来说，跟踪每个步骤的结果、分析决策过程和优化策略至关重要。使用 SDK 中的 `create_log_message` 和 `finish_log_message`，你可以在调用前后记录实时状态，有助于快速诊断问题。 +复杂任务通常需要多个步骤，你需要跟踪每个步骤的结果来分析决策和优化策略。SDK 的 `create_log_message` 和 `finish_log_message` 让你能够记录每次调用前后的状态，从而加速问题诊断。 例如： -- 在调用模型之前记录"开始模型调用"消息，明确任务的执行进度。 -- 模型响应后记录"调用成功"消息，确保模型的输出可以端到端追踪。 +- 在调用模型之前记录"开始模型调用"消息，以显示执行进度。 +- 模型响应后记录"调用成功"消息，以便端到端追踪其输出。 ```python model_log = self.create_log_message( @@ -302,15 +300,13 @@ yield self.finish_log_message( ) ``` -设置完成后，工作流日志将输出执行结果： +设置完成后，工作流日志将显示执行结果： ![Agent 输出执行结果](https://assets-docs.dify.ai/2025/01/96516388a4fb1da9cea85fc1804ff377.png) -如果出现多轮日志，你可以通过在日志调用中设置 `parent` 参数来分层组织它们，使其更易于跟踪。 - -参考方法： +当任务跨越多轮时，在日志调用中设置 `parent` 参数来分层嵌套日志，使其更易于跟踪： ```python function_call_round_log = self.create_log_message( @@ -331,13 +327,11 @@ model_log = self.create_log_message( yield model_log ``` -### Agent 插件功能示例代码 +### 示例代码 - #### 调用模型 - -以下代码演示了如何为 Agent 策略插件赋予调用模型的能力： + 以下代码为 Agent 策略插件提供调用模型的能力： ```python import json @@ -561,9 +555,7 @@ class BasicAgentAgentStrategy(AgentStrategy): ``` - #### 处理工具 - -以下代码展示了如何为 Agent 策略插件实现模型调用并向工具发送规范化请求。 + 以下代码调用模型并向其选择的工具发送格式正确的请求： ```python import json @@ -786,10 +778,8 @@ class BasicAgentAgentStrategy(AgentStrategy): return tool_calls ``` - - #### 完整功能代码示例 - -一个完整的示例插件代码，包含**调用模型、处理工具**和**输出多轮日志的功能**： + + 一个涵盖模型调用、工具处理和多轮日志记录的完整示例： ```python import json @@ -1047,13 +1037,13 @@ class BasicAgentAgentStrategy(AgentStrategy): ## 6. 调试插件 -完成插件的声明文件和实现代码后，在插件目录中运行 `python -m main` 以重新启动它。接下来，确认插件运行正常。Dify 提供远程调试功能。前往**插件管理**获取你的调试密钥和远程服务器地址。 +完成声明文件和实现代码后，验证插件是否正常运行。Dify 支持远程调试：前往**插件管理**获取你的调试密钥和远程服务器地址。 - ![完成插件的声明文件和实现代码后，运行 Python -M](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png) + ![插件管理中的调试密钥和远程服务器地址](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png) -返回你的插件项目，将 `.env.example` 复制为 `.env` 并填入相关的远程服务器和调试密钥信息。 +在你的插件项目中，将 `.env.example` 复制为 `.env` 并填入远程服务器地址和调试密钥。 ```bash INSTALL_METHOD=remote @@ -1067,7 +1057,7 @@ REMOTE_INSTALL_KEY=********-****-****-****-************ python -m main ``` -你将看到插件已安装到你的工作区中，团队成员也可以访问它。 +插件会出现在你的工作区中，团队成员也可以访问它。 ![浏览插件](https://assets-docs.dify.ai/2025/01/c82ec0202e5bf914b36e06c796398dd6.png) @@ -1075,7 +1065,7 @@ python -m main ## 打包插件（可选） -一切正常后，你可以通过运行以下命令打包你的插件： +一切正常后，通过运行以下命令打包你的插件： ```bash # Replace ./basic_agent/ with your actual plugin project path. @@ -1085,7 +1075,7 @@ dify plugin package ./basic_agent/ 当前文件夹中会出现一个名为 `basic_agent.difypkg`（与你的插件名称匹配）的文件。这就是你的最终插件包。 -**恭喜！** 你已经完整地开发、测试和打包了你的 Agent 策略插件。 +恭喜！你已经完成了 Agent 策略插件的开发、测试和打包。 ## 发布插件（可选） @@ -1095,7 +1085,7 @@ dify plugin package ./basic_agent/ ## 进一步探索 -复杂任务通常需要多轮思考和工具调用，通常重复**模型调用 → 工具使用**直到任务结束或达到最大迭代限制。在此过程中，有效管理提示词至关重要。查看[完整的 Function Calling 实现](https://github.com/langgenius/dify-official-plugins/blob/main/agent-strategies/cot_agent/strategies/function_calling.py)，了解让模型调用外部工具并处理其输出的标准化方法。 +复杂任务通常需要多轮思考和工具调用，重复模型调用 → 工具使用的循环，直到任务结束或达到最大迭代次数限制。在此过程中，良好的提示词管理至关重要。查看[完整的 Function Calling 实现](https://github.com/langgenius/dify-official-plugins/blob/main/agent-strategies/cot_agent/strategies/function_calling.py)，了解让模型调用外部工具并处理其输出的标准化方法。 {/* Contributing Section diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx index 8d478cea1..8580795d2 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx @@ -7,21 +7,21 @@ dimensions: standard_title: Cheatsheet language: zh title: 速查表 -description: Dify 插件开发的综合参考指南，包括环境要求、安装方法、开发流程、插件类别和类型、常用代码片段以及常见问题解决方案。适合开发者快速查阅和参考。 +description: Dify 插件开发的快速参考，涵盖环境设置、安装、开发流程和插件类型 --- ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet)。 ## 环境要求 -- Python 版本 3.12 -- Dify 插件脚手架工具 (dify-plugin-daemon) +- Python 版本 3.12 +- Dify 插件脚手架工具 (`dify-plugin-daemon`) -> 了解更多：[初始化开发工具](/zh/develop-plugin/getting-started/cli) +有关设置说明，请参阅[初始化开发工具](/zh/develop-plugin/getting-started/cli)。 ## 获取 Dify 插件开发包 -[Dify Plugin CLI](https://github.com/langgenius/dify-plugin-daemon/releases) +从 GitHub releases 页面下载 [Dify Plugin CLI](https://github.com/langgenius/dify-plugin-daemon/releases)。 ### 不同平台的安装方法 @@ -70,7 +70,7 @@ dify version ## 运行开发包 -这里我们以 `dify` 为例。如果你使用的是本地安装方式，请相应地替换命令，例如 `./dify-plugin-darwin-arm64 plugin init`。 +以下示例使用 `dify` 作为命令。如果你使用的是本地安装方式，请相应地替换命令，例如 `./dify-plugin-darwin-arm64 plugin init`。 ## 插件开发流程 @@ -80,9 +80,9 @@ dify version ./dify plugin init ``` -按照提示完成基本的插件信息配置 +按照提示配置基本的插件信息。 -> 了解更多：[Dify 插件开发：Hello World 指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) +有关完整演练，请参阅 [Dify 插件开发：Hello World 指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)。 ### 2. 以开发模式运行 @@ -92,7 +92,7 @@ dify version python -m main ``` -> 了解更多：[远程调试插件](/zh/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) +有关调试详情，请参阅[远程调试插件](/zh/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin)。 ### 3. 打包和部署 @@ -103,13 +103,13 @@ cd .. dify plugin package ./yourapp ``` -> 了解更多：[发布概览](/zh/develop-plugin/publishing/marketplace-listing/release-overview) +有关发布详情，请参阅[发布概览](/zh/develop-plugin/publishing/marketplace-listing/release-overview)。 ## 插件类别 ### 工具标签 -类别 `tag` [class ToolLabelEnum(Enum)](https://github.com/langgenius/dify-plugin-sdks/blob/main/python/dify_plugin/entities/tool.py) +类别标签在 [`ToolLabelEnum`](https://github.com/langgenius/dify-plugin-sdks/blob/main/python/dify_plugin/entities/tool.py) 中定义： ```python class ToolLabelEnum(Enum): @@ -133,25 +133,14 @@ class ToolLabelEnum(Enum): ## 插件类型参考 -Dify 支持开发多种类型的插件： +Dify 支持多种插件类型： -- **工具插件**：集成第三方 API 和服务 - > 了解更多：[Dify 插件开发：Hello World 指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - -- **模型插件**：集成 AI 模型 - > 了解更多：[模型插件](/zh/develop-plugin/features-and-specs/plugin-types/model-designing-rules)，[快速集成新模型](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - -- **Agent 策略插件**：自定义 Agent 思考和决策策略 - > 了解更多：[Agent 策略插件](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation) - -- **扩展插件**：扩展 Dify 平台功能，如 Endpoints 和 WebAPP - > 了解更多：[扩展插件](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) - -- **数据源插件**：作为知识库管道的文档数据源和起点 - > 了解更多：[数据源插件](/zh/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin) - -- **触发器插件**：在第三方事件发生时自动触发工作流执行 - > 了解更多：[触发器插件](/zh/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin) +- **工具插件**：集成第三方 API 和服务。请参阅 [Dify 插件开发：Hello World 指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)。 +- **模型插件**：集成 AI 模型。请参阅[模型插件](/zh/develop-plugin/features-and-specs/plugin-types/model-designing-rules)和[快速集成新模型](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider)。 +- **Agent 策略插件**：自定义 Agent 思考和决策策略。请参阅 [Agent 策略插件](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation)。 +- **扩展插件**：扩展 Dify 平台功能，如 Endpoints 和 WebApp。请参阅[扩展插件](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint)。 +- **数据源插件**：作为知识库管道的文档数据源和起点。请参阅[数据源插件](/zh/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin)。 +- **触发器插件**：在第三方事件发生时自动触发工作流执行。请参阅[触发器插件](/zh/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin)。 {/* Contributing Section diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx index ae74d6d0f..ad88ed860 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx @@ -7,16 +7,16 @@ dimensions: standard_title: Model Provider Plugin language: en title: 模型供应商插件 -description: 本综合指南提供了创建模型供应商插件的详细说明，涵盖项目初始化、目录结构组织、模型配置方法、编写供应商代码以及实现模型集成，并附有核心 API 实现的详细示例。 +description: 构建模型供应商插件，从项目设置和供应商配置到模型实现、调试和发布 --- ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider)。 ## 前提条件 -* [Dify CLI](/zh/develop-plugin/getting-started/cli) -* 基本的 Python 编程技能和面向对象编程的理解 -* 熟悉您想要集成的模型供应商的 API 文档 +- [Dify CLI](/zh/develop-plugin/getting-started/cli) +- 基本的 Python 编程技能和面向对象编程的理解 +- 熟悉您想要集成的模型供应商的 API 文档 ## 步骤 1：创建和配置新插件项目 @@ -38,9 +38,9 @@ dify plugin init 对于模型供应商插件，配置以下基本权限： -* **Models** - 模型操作的基础权限 -* **LLM** - 大语言模型功能的权限 -* **Storage** - 文件操作的权限（如果需要） +- **Models**：模型操作的基础权限。 +- **LLM**：大语言模型功能的权限。 +- **Storage**：文件操作的权限（如果需要）。 ![模型插件权限](https://assets-docs.dify.ai/2024/12/10f3b3ee6c03a1215309f13d712455d4.png) @@ -72,28 +72,28 @@ Dify 支持两种模型配置方法，决定用户如何与您供应商的模型 ### 预定义模型（`predefined-model`） -这些模型只需要统一的供应商凭证即可使用。一旦用户为供应商配置了 API 密钥或其他身份验证详情，他们就可以立即访问所有预定义模型。 +预定义模型只需要统一的供应商凭证。一旦用户为供应商配置了 API 密钥或其他身份验证详情，他们就可以立即访问所有预定义模型。 -**示例**： `OpenAI` 供应商提供预定义模型，如 `gpt-3.5-turbo-0125` 和 `gpt-4o-2024-05-13`。用户只需配置一次 OpenAI API 密钥即可访问所有这些模型。 +**示例**：OpenAI 供应商提供预定义模型，如 `gpt-3.5-turbo-0125` 和 `gpt-4o-2024-05-13`。用户只需配置一次 OpenAI API 密钥即可访问所有这些模型。 ### 自定义模型（`customizable-model`） -这些模型需要为每个特定模型实例进行额外配置。当模型需要供应商级凭证之外的单独参数时，这种方法很有用。 +自定义模型需要为每个模型实例进行额外配置。当模型需要供应商级凭证之外的单独参数时，这种方法很有用。 -**示例**： `Xinference` 同时支持 LLM 和 Text Embedding，但每个模型都有唯一的 **model_uid**。用户必须为他们想要使用的每个模型单独配置此 model_uid。 +**示例**：Xinference 同时支持 LLM 和 Text Embedding，但每个模型都有唯一的 `model_uid`。用户必须为他们想要使用的每个模型单独配置此 `model_uid`。 -这些配置方法**可以在单个供应商中共存**。例如，供应商可能提供一些预定义模型，同时也允许用户添加具有特定配置的自定义模型。 +这两种配置方法可以在单个供应商中共存。例如，供应商可能提供一些预定义模型，同时也允许用户添加具有特定配置的自定义模型。 ## 步骤 3：创建模型供应商文件 创建新的模型供应商涉及两个主要组件： -1. **供应商配置 YAML 文件** - 定义供应商的基本信息、支持的模型类型和凭证要求 -2. **供应商类实现** - 实现身份验证验证和其他供应商级功能 +- **供应商配置 YAML 文件**：定义供应商的基本信息、支持的模型类型和凭证要求。 +- **供应商类实现**：实现身份验证验证和其他供应商级功能。 ### 3.1 创建模型供应商配置文件 -供应商配置在 YAML 文件中定义，声明供应商的基本信息、支持的模型类型、配置方法和凭证规则。此文件将放置在插件项目的根目录中。 +供应商配置是一个 YAML 文件，声明供应商的基本信息、支持的模型类型、配置方法和凭证规则。将其放置在插件项目的根目录中。 以下是带注释的 `anthropic.yaml` 配置文件示例： @@ -162,7 +162,7 @@ extra: ### 自定义模型配置 -如果您的供应商支持自定义模型，您需要添加 `model_credential_schema` 部分来定义用户需要为每个单独模型配置的额外字段。这对于支持微调模型或需要模型特定参数的供应商很常见。 +如果您的供应商支持自定义模型，添加 `model_credential_schema` 部分来定义用户必须为每个模型配置的额外字段。这对于支持微调模型或需要模型特定参数的供应商很常见。 以下是来自 OpenAI 供应商的示例： @@ -196,11 +196,11 @@ model_credential_schema: # 根据需要添加其他字段... ``` -有关完整的模型供应商 YAML 规范，请参阅[模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema) 文档。 +有关完整的模型供应商 YAML 规范，请参阅[模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema)。 ### 3.2 编写模型供应商代码 -接下来，为您的供应商类实现创建一个 Python 文件。此文件应放置在 `/provider` 目录中，名称与您的供应商匹配（例如 `anthropic.py`）。 +接下来，在 `/provider` 目录中为您的供应商类创建一个 Python 文件，以您的供应商命名（例如 `anthropic.py`）。 供应商类必须继承自 `ModelProvider` 并至少实现 `validate_provider_credentials` 方法： @@ -240,15 +240,15 @@ class AnthropicProvider(ModelProvider): raise ex ``` -`validate_provider_credentials` 方法非常重要，因为每当用户尝试在 Dify 中保存其供应商凭证时都会调用它。它应该： +每当用户保存供应商凭证时，Dify 都会调用 `validate_provider_credentials`，因此它应该： -1. 尝试通过进行简单的 API 调用来验证凭证 -2. 如果验证成功则静默返回 -3. 如果验证失败则抛出带有有用消息的 `CredentialsValidateFailedError` +1. 尝试通过进行简单的 API 调用来验证凭证。 +2. 如果验证成功则静默返回。 +3. 如果验证失败则抛出带有有用消息的 `CredentialsValidateFailedError`。 #### 对于自定义模型供应商 -对于专门使用自定义模型的供应商（每个模型都需要自己的配置），您可以实现一个更简单的供应商类。例如，对于 `Xinference`： +对于专门使用自定义模型的供应商（每个模型都需要自己的配置），您可以实现一个更简单的供应商类。例如，对于 Xinference： ```python from dify_plugin import ModelProvider @@ -264,15 +264,15 @@ class XinferenceProvider(ModelProvider): ## 步骤 4：实现模型特定代码 -设置好供应商后，您需要实现模型特定代码来处理您支持的每种模型类型的 API 调用。这涉及： +设置好供应商后，实现模型特定代码来处理您支持的每种模型类型的 API 调用。这涉及： -1. 为每个特定模型创建模型配置 YAML 文件 -2. 实现处理 API 通信的模型类型类 +1. 为每个特定模型创建模型配置 YAML 文件。 +2. 实现处理 API 通信的模型类型类。 -有关这些步骤的详细说明，请参阅： +有关详细说明，请参阅： -* [模型设计规则](/zh/develop-plugin/features-and-specs/plugin-types/model-designing-rules) - 集成预定义模型的标准 -* [模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema) - 模型配置文件的标准 +- [模型设计规则](/zh/develop-plugin/features-and-specs/plugin-types/model-designing-rules)：集成预定义模型的标准。 +- [模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema)：模型配置文件的标准。 ### 4.1 定义模型配置（YAML） @@ -314,7 +314,7 @@ pricing: # 可选的定价信息 ### 4.2 实现模型调用代码（Python） -为您支持的每种模型类型创建一个 Python 文件（例如 `models/llm/` 目录中的 `llm.py`）。此类将处理 API 通信、参数转换和结果格式化。 +为您支持的每种模型类型创建一个 Python 文件（例如 `models/llm/` 目录中的 `llm.py`）。此类处理 API 通信、参数转换和结果格式化。 以下是 LLM 的实现结构示例： @@ -409,48 +409,49 @@ class MyProviderLargeLanguageModel(LargeLanguageModel): 要实现的最重要方法是 `_invoke`，它处理核心 API 通信。此方法应该： -1. 将 Dify 的标准化输入转换为供应商 API 所需的格式 -2. 使用适当的错误处理进行 API 调用 -3. 将 API 响应转换为 Dify 的标准化输出格式 -4. 处理流式和非流式模式 +1. 将 Dify 的标准化输入转换为供应商 API 所需的格式。 +2. 使用适当的错误处理进行 API 调用。 +3. 将 API 响应转换为 Dify 的标准化输出格式。 +4. 处理流式和非流式模式。 ## 步骤 5：调试和测试您的插件 -Dify 提供远程调试功能，允许您在开发期间测试插件： +Dify 支持远程调试，因此您可以在开发期间测试插件： -1. 在您的 Dify 实例中，转到"插件管理"并点击"调试插件"以获取您的调试密钥和服务器地址 +1. 在您的 Dify 实例中，转到**插件管理**并点击**调试插件**以获取您的调试密钥和服务器地址。 2. 在 `.env` 文件中使用这些值配置您的本地环境： -```dotenv -INSTALL_METHOD=remote -REMOTE_INSTALL_URL=:5003 -REMOTE_INSTALL_KEY=****-****-****-****-**** -``` + ```dotenv + INSTALL_METHOD=remote + REMOTE_INSTALL_URL=:5003 + REMOTE_INSTALL_KEY=****-****-****-****-**** + ``` -3. 使用 `python -m main` 在本地运行您的插件并在 Dify 中测试它 +3. 使用 `python -m main` 在本地运行您的插件并在 Dify 中测试它。 ## 步骤 6：打包和发布 当您的插件准备就绪时： 1. 使用脚手架工具打包： + ```bash dify plugin package models/ ``` -2. 在提交之前在本地测试打包的插件 +2. 在提交之前在本地测试打包的插件。 -3. 向 [Dify 官方插件仓库](https://github.com/langgenius/dify-official-plugins) 提交拉取请求 +3. 向 [Dify 官方插件仓库](https://github.com/langgenius/dify-official-plugins) 提交拉取请求。 有关发布流程的更多详情，请参阅[发布概述](/zh/develop-plugin/publishing/marketplace-listing/release-overview)。 ## 参考资源 -- [快速集成新模型](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - 如何向现有供应商添加新模型 -- [插件开发基本概念](/zh/develop-plugin/getting-started/getting-started-dify-plugin) - 返回插件开发入门指南 -- [模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema) - 了解详细的模型配置规范 -- [通用规范](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications) - 了解插件清单文件配置 -- [Dify 插件 SDK 参考](https://github.com/langgenius/dify-plugin-sdks) - 查找基类、数据结构和错误类型 +- [快速集成新模型](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider)：如何向现有供应商添加新模型。 +- [插件开发基本概念](/zh/develop-plugin/getting-started/getting-started-dify-plugin)：返回插件开发入门指南。 +- [模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema)：详细的模型配置规范。 +- [通用规范](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications)：插件清单文件配置。 +- [Dify 插件 SDK 参考](https://github.com/langgenius/dify-plugin-sdks)：基类、数据结构和错误类型。 {/* Contributing Section diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx index 2743705c2..297213e93 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx @@ -1,24 +1,24 @@ --- title: "数据源插件" -description: 构建 Dify 1.9.0+ 数据源插件，将文档输入知识库管道——架构、代码示例和调试步骤 +description: 构建 Dify 1.9.0+ 数据源插件，将文档输入知识库管道 --- ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin)。 -数据源插件是 Dify 1.9.0 中引入的一种新型插件。在知识库管道中，它们作为文档数据源和整个管道的起点。 +数据源插件是 Dify 1.9.0 中引入的一种插件类型，它为知识库管道提供文档，并作为整个管道的起点。 -本文介绍如何开发数据源插件，涵盖插件架构、代码示例和调试方法，帮助你快速开发和发布数据源插件。 +本指南介绍了构建和发布数据源插件所需的插件架构、代码示例和调试方法。 ## 前置条件 -在继续阅读之前，请确保你对知识库管道有基本了解，并具备一些插件开发知识。你可以在这里找到相关信息： +你应该对知识库管道和插件开发有基本了解： - [步骤 2：知识库管道编排](/zh/use-dify/knowledge/knowledge-pipeline/knowledge-pipeline-orchestration) - [Dify 插件开发：Hello World 指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) -## **数据源插件类型** +## 数据源插件类型 -Dify 支持三种类型的数据源插件：网页爬虫、在线文档和在线云盘。在实现插件代码时，提供插件功能的类必须继承自特定的数据源类。三种插件类型分别对应不同的父类。 +Dify 支持三种类型的数据源插件：网页爬虫、在线文档和在线云盘。每种类型对应不同的父类，实现插件功能的类必须继承自相应的父类。 要了解如何通过继承父类来实现插件功能，请参阅[工具插件：准备工具代码](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin#4-准备工具代码)。 @@ -40,9 +40,9 @@ Dify 支持三种类型的数据源插件：网页爬虫、在线文档和在线 ### 创建数据源插件 -你可以使用脚手架命令行工具，通过选择 `datasource` 类型来创建数据源插件。完成设置后，命令行工具将自动生成插件项目代码。 +通过选择 `datasource` 类型，使用脚手架命令行工具创建数据源插件。完成设置后，该工具会生成插件项目代码。 -```powershell +```bash dify plugin init ``` @@ -62,7 +62,7 @@ dify plugin init - `provider` 目录：包含插件提供者的描述和认证实现代码。 - `datasources` 目录：包含从数据源获取数据的描述和核心逻辑。 -``` +```text ├── _assets │ └── icon.svg ├── datasources @@ -80,20 +80,22 @@ dify plugin init #### 设置正确的版本和标签 -- 在 `manifest.yaml` 文件中，按如下方式设置最低支持的 Dify 版本： +- 在 `manifest.yaml` 文件中，设置最低支持的 Dify 版本： ```yaml minimum_dify_version: 1.9.0 ``` -- 在 `manifest.yaml` 文件中，添加以下标签以在 Dify Marketplace 的数据源类别下显示插件： + +- 在同一文件中，添加以下标签以在 Dify 市场的数据源类别下显示插件： ```yaml tags: - rag ``` -- 在 `requirements.txt` 文件中，按如下方式设置数据源插件开发所使用的插件 SDK 版本： - ```yaml +- 在 `requirements.txt` 文件中，设置插件 SDK 版本： + + ```text dify-plugin>=0.5.0,<0.6.0 ``` @@ -124,7 +126,7 @@ datasources: #### 创建提供者代码文件 -- 使用 API Key 认证模式时，数据源插件的提供者代码文件与工具插件相同。你只需要将提供者类继承的父类更改为 `DatasourceProvider`。 +- 使用 API Key 认证时，提供者代码文件与工具插件相同。你只需要将提供者类的父类更改为 `DatasourceProvider`。 ```python class YourDatasourceProvider(DatasourceProvider): @@ -137,9 +139,10 @@ datasources: except Exception as e: raise ToolProviderCredentialValidationError(str(e)) ``` -- 使用 OAuth 认证模式时，数据源插件与工具插件略有不同。通过 OAuth 获取访问权限时，数据源插件可以同时返回要在前端显示的用户名和头像。因此，`_oauth_get_credentials` 和 `_oauth_refresh_credentials` 需要返回包含 `name`、`avatar_url`、`expires_at` 和 `credentials` 的 `DatasourceOAuthCredentials` 类型。 - `DatasourceOAuthCredentials` 类定义如下，返回时必须设置为相应的类型： +- 使用 OAuth 认证时，数据源插件与工具插件略有不同：通过 OAuth 获取访问权限时，它们还可以返回要在前端显示的用户名和头像。因此，`_oauth_get_credentials` 和 `_oauth_refresh_credentials` 必须返回包含 `name`、`avatar_url`、`expires_at` 和 `credentials` 的 `DatasourceOAuthCredentials` 对象。 + + `DatasourceOAuthCredentials` 类定义如下： ```python class DatasourceOAuthCredentials(BaseModel): @@ -237,9 +240,9 @@ output_schema: description: the description of the website ``` -在网页爬虫插件的主要逻辑代码中，类必须继承自 `WebsiteCrawlDatasource` 并实现 `_get_website_crawl` 方法。然后你需要使用 `create_crawl_message` 方法返回网页爬取消息。 +在网页爬虫插件的主要逻辑代码中，类必须继承自 `WebsiteCrawlDatasource` 并实现 `_get_website_crawl` 方法，使用 `create_crawl_message` 方法返回爬取结果。 -要爬取多个网页并分批返回，你可以将 `WebSiteInfo.status` 设置为 `processing`，并使用 `create_crawl_message` 方法返回每批爬取的页面。所有页面爬取完成后，将 `WebSiteInfo.status` 设置为 `completed`。 +要爬取多个网页并分批返回，将 `WebSiteInfo.status` 设置为 `processing`，并为每批爬取的页面调用 `create_crawl_message`。所有页面爬取完成后，将 `WebSiteInfo.status` 设置为 `completed`。 ```python class YourDataSource(WebsiteCrawlDatasource): @@ -346,11 +349,11 @@ output_schema: 在在线云盘插件的主要逻辑代码中，类必须继承自 `OnlineDriveDatasource` 并实现两个方法：`_browse_files` 和 `_download_file`。 -当用户运行插件时，它首先调用 `_browse_files` 获取文件列表。此时，`prefix` 为空，表示请求根目录的文件列表。文件列表包含文件夹和文件两种类型的变量。如果用户打开文件夹，会再次调用 `_browse_files` 方法。此时，`OnlineDriveBrowseFilesRequest` 中的 `prefix` 将是用于检索该文件夹内文件列表的文件夹 ID。 +当用户运行插件时，它首先调用 `_browse_files` 获取文件列表。此时，`prefix` 为空，表示请求根目录的文件列表。列表包含文件夹和文件两种条目。如果用户打开文件夹，会再次调用 `_browse_files`，`OnlineDriveBrowseFilesRequest` 中的 `prefix` 将是用于检索该文件夹内文件列表的文件夹 ID。 用户选择文件后，插件使用 `_download_file` 方法和文件 ID 获取文件内容。你可以使用 `_get_mime_type_from_filename` 方法获取文件的 MIME 类型，使管道能够适当处理不同的文件类型。 -当文件列表包含多个文件时，你可以将 `OnlineDriveFileBucket.is_truncated` 设置为 `True`，并将 `OnlineDriveFileBucket.next_page_parameters` 设置为获取下一页文件列表所需的参数，例如下一页的请求 ID 或 URL，具体取决于服务提供商。 +当文件列表包含多个文件时，你可以将 `OnlineDriveFileBucket.is_truncated` 设置为 `True`，并将 `OnlineDriveFileBucket.next_page_parameters` 设置为获取下一页所需的参数，例如下一页的请求 ID 或 URL，具体取决于服务提供商。 @@ -415,12 +418,12 @@ output_schema: - `id`：由于 `_download_file` 方法不使用 `prefix` 变量，因此完整文件路径必须包含在 `id` 中。例如，`id=container1/folder1/file1.txt` 表示从 `container1` 存储桶的 `folder1` 文件夹中检索 `file1.txt` 文件。 - 你可以参考[官方 Google Drive 插件](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/google_cloud_storage/datasources/google_cloud_storage.py)和[官方 AWS S3 插件](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/aws_s3_storage/datasources/aws_s3_storage.py)的具体实现。 + 有关参考实现，请参阅[官方 Google Drive 插件](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/google_cloud_storage/datasources/google_cloud_storage.py)和[官方 AWS S3 插件](https://github.com/langgenius/dify-official-plugins/blob/main/datasources/aws_s3_storage/datasources/aws_s3_storage.py)。 ## 调试插件 -数据源插件支持两种调试方法：远程调试或作为本地插件安装进行调试。请注意以下事项： +数据源插件支持两种调试方法：远程调试和本地安装插件。请注意以下事项： - 如果插件使用 OAuth 认证，远程调试的 `redirect_uri` 与本地插件不同。请在服务提供商的 OAuth App 中相应更新相关配置。 - 虽然数据源插件支持单步调试，但我们仍建议在完整的知识库管道中测试它们，以确保完整功能。 @@ -439,14 +442,14 @@ output_schema: 在插件目录中，运行以下命令生成 `.difypkg` 插件包： -``` +```bash dify plugin package . -o your_datasource.difypkg ``` 接下来，你可以： - 在你的 Dify 环境中导入和使用插件。 -- 通过提交 pull request 将插件发布到 Dify Marketplace。 +- 通过提交 pull request 将插件发布到 Dify 市场。 有关插件发布流程，请参阅[发布插件](/zh/develop-plugin/publishing/marketplace-listing/release-overview)。 diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx index ac9efc679..2c24fdc36 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx @@ -5,71 +5,71 @@ dimensions: detail: examples level: intermediate standard_title: Slack Bot -language: en +language: zh title: Slack Bot -description: 本指南提供了开发 Slack Bot 插件的完整演练，涵盖项目初始化、配置表单编辑、功能实现、调试、端点设置、验证和打包。你需要 Dify 插件脚手架工具和预先创建的 Slack App 来在 Slack 上构建 AI 驱动的聊天机器人。 +description: 构建一个 Slack Bot 插件，将 Dify 应用连接到 Slack，涵盖项目初始化到调试和打包的完整流程 --- ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin)。 -**你将学到**： - -深入了解如何构建一个由 AI 驱动的 Slack Bot——它可以直接在 Slack 中回答用户问题。如果你之前没有开发过插件，我们建议先阅读[插件开发快速入门指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)。 +本指南将带你构建一个由 AI 驱动的 Slack Bot，它可以直接在 Slack 中回答用户问题。如果你之前没有开发过插件，请先阅读[插件开发快速入门指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)。 ## 项目背景 -Dify 插件生态系统致力于使集成更简单、更易于访问。在本指南中，我们将以 Slack 为例，带你完成开发 Slack Bot 插件的过程。这允许你的团队直接在 Slack 中与 LLM 聊天，显著提高他们使用 AI 的效率。 +Slack Bot 插件让你的团队能够直接在 Slack 中与 LLM 聊天，将 AI 带到对话已经发生的地方。 -Slack 是一个开放的实时通信平台，拥有强大的 API。其功能之一是基于 webhook 的事件系统，开发起来非常简单。我们将利用这个系统创建一个 Slack Bot 插件，如下图所示： +Slack 是一个开放的实时通信平台，拥有强大的 API，包括一个易于构建的基于 webhook 的事件系统。本指南使用该系统创建 Slack Bot 插件，如下图所示： ![Slack 机器人示意图](https://assets-docs.dify.ai/2025/01/a0865d18f1ca4051601ca53fa6f92db2.png) -> 为避免混淆，以下概念作说明： -> -> * **Slack Bot** Slack 平台上的聊天机器人，作为一个虚拟用户，你可以与其实时交互。 -> * **Slack Bot 插件** Dify 市场中的一个插件，用于连接 Dify 应用程序与 Slack。本指南重点介绍如何开发该插件。 + +本指南中出现两个相似的术语： + +- **Slack Bot**：Slack 平台上的聊天机器人——一个可以实时交互的虚拟用户。 +- **Slack Bot 插件**：Dify 市场中的一个插件，用于连接 Dify 应用与 Slack。本指南将展示如何构建它。 + -**工作原理（简要概述）**： +### 工作原理 -1. **向 Slack Bot 发送消息** +1. **用户向 Slack Bot 发送消息** - 当 Slack 中的用户向 Bot 发送消息时，Slack Bot 会立即向 Dify 平台发出 webhook 请求。 + 当 Slack 中的用户向 Bot 发送消息时，Slack Bot 会立即向 Dify 平台发出 webhook 请求。 -2. **将消息转发给 Slack Bot 插件** +2. **Slack 将消息转发给 Slack Bot 插件** - Dify 平台触发 Slack Bot 插件，该插件将详细信息转发给 Dify 应用程序——类似于在电子邮件系统中输入收件人地址。通过 Slack 的 API 设置 Slack webhook 地址并在 Slack Bot 插件中输入，即可建立此连接。然后插件处理 Slack 请求并将其发送到 Dify 应用程序，LLM 分析用户的输入并生成响应。 + Dify 平台触发 Slack Bot 插件，该插件将消息转发给 Dify 应用——类似于邮件系统将邮件投递到收件人地址。你通过 Slack 的 API 设置 Slack webhook 地址并在插件中输入来建立此连接。插件处理 Slack 请求并将其转发到 Dify 应用，LLM 分析输入并生成响应。 -3. **将响应返回给 Slack** +3. **插件将响应返回给 Slack** - 一旦 Slack Bot 插件收到 Dify 应用程序的回复，它就会通过相同的路径将 LLM 的答案发送回 Slack Bot。Slack 中的用户就可以在他们聊天的地方看到更智能、更互动的体验。 + 一旦插件收到 Dify 应用的回复，它就会通过相同的路径将 LLM 的答案发送回 Slack Bot，用户就能在聊天的地方获得响应。 ## 前提条件 -- **Dify 插件开发工具**：更多信息，请参阅[初始化开发工具](/zh/develop-plugin/getting-started/cli)。 -- **Python 环境（版本 3.12）**：参考 [Python 官方下载页面](https://www.python.org/downloads/)或向 LLM 询问完整的设置指南。 -- 创建 Slack App 并获取 OAuth 令牌 +- **Dify 插件开发工具**：参阅[初始化开发工具](/zh/develop-plugin/getting-started/cli)。 +- **Python 环境（版本 3.12）**：参阅 [Python 官方下载页面](https://www.python.org/downloads/)。 +- **带有 OAuth 令牌的 Slack App**：参阅以下步骤。 -前往 [Slack API 平台](https://api.slack.com/apps)，从头创建一个 Slack 应用，并选择将其部署到的工作区。 +要创建 Slack App，请前往 [Slack API 平台](https://api.slack.com/apps)，从头创建一个应用，并选择将其部署到的工作区。 - ![](https://assets-docs.dify.ai/2025/01/c1fd0ac1467faf5a3ebf3818bb234aa8.png) + ![创建 Slack App](https://assets-docs.dify.ai/2025/01/c1fd0ac1467faf5a3ebf3818bb234aa8.png) -1. **启用 Webhooks**： +1. **启用 Webhooks**： ![启用 Webhooks](https://assets-docs.dify.ai/2025/01/7112e0710300f1db16827e17f3deac00.png) -2. **在你的 Slack 工作区安装应用**： +2. **在你的 Slack 工作区安装应用**： ![在你的 Slack 工作区安装应用](https://assets-docs.dify.ai/2025/01/88c360ff4f7b04fea52174ce330522fa.png) -3. **获取 OAuth 令牌**以供后续插件开发使用： +3. **获取 OAuth 令牌**以供插件开发使用： ![获取 OAuth 令牌以供后续插件开发使用](https://assets-docs.dify.ai/2025/01/dcd8ec947253f2ef9ae121ed77ec9f26.png) @@ -77,7 +77,7 @@ Slack 是一个开放的实时通信平台，拥有强大的 API。其功能之 ## 1. 开发插件 -现在我们将深入实际编码。在开始之前，请确保你已阅读[快速入门：开发扩展插件](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint)或已经构建过 Dify 插件。 +在开始编码之前，请确保你已阅读[快速入门：开发扩展插件](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint)或已经构建过 Dify 插件。 ### 1.1 初始化项目 @@ -97,9 +97,9 @@ dify plugin init ### 1.2 编辑配置表单 -此插件需要知道哪个 Dify 应用应处理回复，以及用于验证机器人响应的 Slack App 令牌。因此，你需要在插件的表单中添加这两个字段。 +插件需要两条信息：哪个 Dify 应用处理回复，以及用于验证机器人响应的 Slack App 令牌。将这两个字段添加到插件的表单中。 -修改 group 目录中的 YAML 文件（例如 `group/slack.yaml`）。表单的文件名由你创建插件时提供的信息决定，请相应调整。 +修改 `group` 目录中的 YAML 文件（例如 `group/slack.yaml`）。表单的文件名来自你创建插件时提供的信息，请相应调整路径。 **示例代码**： @@ -146,19 +146,18 @@ endpoints: - endpoints/slack.yaml ``` -配置字段说明： +有两个配置字段值得仔细了解： -``` +```yaml - name: app type: app-selector scope: chat ``` -* **type**：设置为 app-selector，允许用户在使用此插件时将消息转发到特定的 Dify 应用。 +- **`type`**：设置为 `app-selector`，允许用户在使用此插件时将消息转发到特定的 Dify 应用。 +- **`scope`**：设置为 `chat`，意味着该插件只能与 Agent、chatbot 或 chatflow 等应用类型交互。 -* **scope**：设置为 chat，意味着该插件只能与 Agent、chatbot 或 chatflow 等应用类型交互。 - -最后，在 `endpoints/slack.yaml` 文件中，将请求方法更改为 POST 以正确处理传入的 Slack 消息。 +最后，在 `endpoints/slack.yaml` 文件中，将请求方法更改为 `POST`，以便端点能够处理传入的 Slack 消息。 **示例代码**： @@ -256,10 +255,10 @@ class SlackEndpoint(Endpoint): 前往 Dify 平台并获取插件的远程调试地址和密钥。 - ![](https://assets-docs.dify.ai/2025/01/8d24006f0cabf5bf61640a9023c45db8.png) + ![获取远程调试地址和密钥](https://assets-docs.dify.ai/2025/01/8d24006f0cabf5bf61640a9023c45db8.png) -回到你的插件项目，复制 `.env.example` 文件并将其重命名为 `.env`。 +回到你的插件项目，复制 `.env.example` 文件并将其重命名为 `.env`，然后填入调试详情： ```bash INSTALL_METHOD=remote @@ -267,15 +266,17 @@ REMOTE_INSTALL_URL=debug.dify.ai:5003 REMOTE_INSTALL_KEY=********-****-****-****-************ ``` -运行 `python -m main` 启动插件。你现在应该可以在 Dify 插件管理页面的工作区中看到你的插件已安装。其他团队成员也可以访问它。 +启动插件： ```bash python -m main ``` +你现在应该可以在 Dify 插件管理页面的工作区中看到你的插件已安装，其他团队成员也可以访问它。 + ### 配置插件端点 -从 Dify 的插件管理页面，找到新安装的测试插件并创建一个新端点。提供名称、Bot 令牌，并选择你想要连接的应用。 +在 Dify 的插件管理页面，找到新安装的测试插件并创建一个新端点。输入名称和你的 **Bot Token**，然后选择你想要连接的应用。 ![测试插件](https://assets-docs.dify.ai/2025/01/07f87e8a2786d6f5f05195961c5630c3.png) @@ -311,17 +312,17 @@ python -m main ## 4. 验证插件 -在你的代码中，`self.session.app.chat.invoke` 用于调用 Dify 应用程序，传入 `app_id` 和 `query` 等参数。然后将响应返回给 Slack Bot。再次运行 `python -m main` 重启插件进行调试，并检查 Slack 是否正确显示 Dify App 的回复： +插件通过 `self.session.app.chat.invoke` 调用 Dify 应用，传入 `app_id` 和 `query` 等参数，并将响应返回给 Slack Bot。再次运行 `python -m main` 重启插件，然后检查 Slack 是否正确显示 Dify 应用的回复： - ![在你的代码中，self](https://assets-docs.dify.ai/2025/01/6fc872d1343ce8503d63c5222f7f26f9.png) + ![Slack 显示 Dify 应用回复](https://assets-docs.dify.ai/2025/01/6fc872d1343ce8503d63c5222f7f26f9.png) --- ## 5. 打包插件（可选） -确认插件工作正常后，你可以通过以下命令打包并命名它。运行后，你会在当前目录中找到一个 `slack_bot.difypkg` 文件——这就是你的最终插件包。有关详细的打包步骤，请参阅[打包为本地文件并分享](/zh/develop-plugin/publishing/marketplace-listing/release-by-file)。 +确认插件工作正常后，使用以下命令打包。该命令会在当前目录中生成一个 `slack_bot.difypkg` 文件——这就是你的最终插件包。有关详细的打包步骤，请参阅[打包为本地文件并分享](/zh/develop-plugin/publishing/marketplace-listing/release-by-file)。 ```bash # 将 ./slack_bot 替换为你实际的插件项目路径。 @@ -329,7 +330,7 @@ python -m main dify plugin package ./slack_bot ``` -恭喜！你已成功开发、测试和打包了一个插件！ +恭喜——你已成功开发、测试和打包了一个插件！ --- @@ -341,14 +342,14 @@ dify plugin package ./slack_bot ## 相关资源 -- [插件开发基础](/zh/develop-plugin/getting-started/getting-started-dify-plugin) - Dify 插件开发的全面概述 -- [插件开发快速入门指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - 从零开始开发插件 -- [开发扩展插件](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 了解扩展插件开发 -- [反向调用 Dify 服务](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation) - 了解如何调用 Dify 平台功能 -- [反向调用：App](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app) - 了解如何调用平台内的应用 -- [发布插件](/zh/develop-plugin/publishing/marketplace-listing/release-overview) - 了解发布流程 -- [发布到 Dify 市场](/zh/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace) - 市场发布指南 -- [端点详细定义](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 端点详细定义 +- [插件开发基础](/zh/develop-plugin/getting-started/getting-started-dify-plugin)：Dify 插件开发的全面概述 +- [插件开发快速入门指南](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)：从零开始开发插件 +- [开发扩展插件](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint)：扩展插件开发 +- [反向调用 Dify 服务](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation)：如何调用 Dify 平台功能 +- [反向调用：App](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app)：如何调用平台内的应用 +- [发布插件](/zh/develop-plugin/publishing/marketplace-listing/release-overview)：发布流程 +- [发布到 Dify 市场](/zh/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace)：市场发布指南 +- [端点详细定义](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint)：端点参考 ## 延伸阅读 @@ -357,16 +358,18 @@ dify plugin package ./slack_bot 如果你想了解更多关于插件开发的内容，请查看以下资源： **快速入门**： + - [开发扩展插件](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) - [开发模型插件](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - [Bundle 插件：打包多个插件](/zh/develop-plugin/features-and-specs/advanced-development/bundle) **插件接口文档**： -- [通过 Manifest 文件定义插件信息](/zh/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest) - Manifest 结构 -- [端点](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 端点详细定义 -- [反向调用](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation) - 反向调用 Dify 功能 -- [通用规范](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications) - 工具规范 -- [模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema) - 模型 + +- [通过 Manifest 文件定义插件信息](/zh/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest)：Manifest 结构 +- [端点](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint)：端点参考 +- [反向调用](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation)：从插件调用 Dify 功能 +- [通用规范](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications)：工具规范 +- [模型 Schema](/zh/develop-plugin/features-and-specs/plugin-types/model-schema)：模型 Schema 参考 {/* Contributing Section diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx index 6af169590..b3f139da1 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx @@ -47,6 +47,7 @@ standard_title: Flomo Tool (10-min) 验证安装： + ```bash dify version ``` @@ -60,8 +61,9 @@ standard_title: Flomo Tool (10-min) ``` 按照提示设置你的插件： - - 将其命名为 "flomo" - - 选择 "tool" 作为插件类型 + + - 将其命名为 `flomo` + - 选择 `tool` 作为插件类型 - 完成其他必填字段 @@ -70,14 +72,14 @@ standard_title: Flomo Tool (10-min) cd flomo ``` - 这将为你的插件创建基本结构，包含所有必要的文件。 + 该项目包含插件的基本结构以及所有必要的文件。 ## 步骤 2：定义插件清单 -manifest.yaml 文件定义了插件的元数据、权限和功能。 +`manifest.yaml` 文件定义了插件的元数据、权限和功能。 创建 `manifest.yaml` 文件： @@ -286,12 +288,14 @@ class FlomoTool(Tool): 复制示例环境文件： + ```bash cp .env.example .env ``` 使用你的 Dify 环境详情编辑 `.env` 文件： - ``` + + ```bash INSTALL_METHOD=remote REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003 REMOTE_INSTALL_KEY=your_debug_key @@ -310,8 +314,7 @@ class FlomoTool(Tool): - 在你的 Dify 实例中，导航到插件并找到你的调试插件（标记为"debugging"）。 - 添加你的 Flomo API 凭证并测试发送笔记。 + 在你的 Dify 实例中，打开**插件**页面并找到你的插件（标记为 **debugging**）。添加你的 Flomo API 凭证并测试发送笔记。 @@ -337,17 +340,17 @@ dify plugin package ./ - 确保所有必需的文件都存在，并且 manifest.yaml 结构有效。 + 确保所有必需的文件都存在，并且 `manifest.yaml` 结构有效。 ## 总结 -你已经构建了一个连接外部 API 服务的功能性 Dify 插件！这种相同的模式适用于与数千种服务的集成——从数据库和搜索引擎到生产力工具和自定义 API。 +你已经构建了一个连接外部 API 服务的功能性 Dify 插件。这种相同的模式适用于与数千种服务的集成——从数据库和搜索引擎到生产力工具和自定义 API。 - 用英文（en_US）编写你的 README.md，描述功能、设置和使用示例 + 用英文（en_US）编写你的 `README.md`，描述功能、设置和使用示例 为其他语言创建额外的 README 文件，如 `readme/README_zh_Hans.md` diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx index 91a76bb1e..fee489dcd 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx @@ -9,7 +9,7 @@ standard_title: Building a Markdown Exporter Plugin ## 你将构建什么 -在本指南中，你将学习如何构建一个实用的 Dify 插件，将对话导出为流行的文档格式。完成后，你的插件将能够： +你将构建一个实用的 Dify 插件，将对话导出为流行的文档格式。完成后，你的插件将能够： - 将 markdown 文本转换为 Word 文档 (.docx) - 将对话导出为 PDF 文件 @@ -37,7 +37,7 @@ standard_title: Building a Markdown Exporter Plugin ``` - 从 [Dify GitHub releases 页面](https://github.com/langgenius/dify-plugin-daemon/releases)获取最新的 Dify CLI + 从 [Dify GitHub releases 页面](https://github.com/langgenius/dify-plugin-daemon/releases)获取最新的 Dify CLI。 ```bash # Download appropriate version @@ -49,6 +49,7 @@ standard_title: Building a Markdown Exporter Plugin 验证安装： + ```bash dify version ``` @@ -62,9 +63,10 @@ standard_title: Building a Markdown Exporter Plugin ``` 按照提示操作： - - 名称："md_exporter" - - 类型："tool" - - 按提示完成其他详细信息 + + - **名称**：`md_exporter` + - **类型**：`tool` + - 按提示完成其余详细信息。 @@ -449,12 +451,14 @@ plugin = PluginRunner( 首先，从模板创建你的 `.env` 文件： + ```bash cp .env.example .env ``` 使用你的 Dify 环境详细信息进行配置： - ``` + + ```dotenv INSTALL_METHOD=remote REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003 REMOTE_INSTALL_KEY=your_debug_key @@ -499,23 +503,23 @@ dify plugin package ./ 以下是一些扩展此插件的有趣方式： -- **自定义模板**：添加公司品牌或个性化样式 -- **多格式支持**：扩展导出为 HTML、Markdown 或其他格式 -- **图像处理**：处理并包含对话中的图像 -- **表格支持**：为数据表格实现正确的格式化 -- **协作编辑**：添加与 Google Docs 或类似平台的集成 +- **自定义模板**：添加公司品牌或个性化样式。 +- **多格式支持**：扩展导出为 HTML、Markdown 或其他格式。 +- **图像处理**：处理并包含对话中的图像。 +- **表格支持**：为数据表格实现正确的格式化。 +- **协作编辑**：添加与 Google Docs 或类似平台的集成。 -文档转换的核心挑战是保持格式和结构。此插件使用的方法首先将 markdown 转换为 HTML（一种中间格式），然后将该 HTML 处理为目标格式。 +文档转换的核心挑战是保持格式和结构。此插件首先将 markdown 转换为 HTML 作为中间格式，然后将该 HTML 处理为目标格式。 -这个两步过程提供了灵活性：你可以通过简单地添加与 HTML 表示配合工作的新输出模块来扩展它以支持其他格式。 +这个两步过程提供了灵活性：你可以通过添加与 HTML 表示配合工作的新输出模块来支持其他格式。 -对于 PDF 生成，选择 WeasyPrint 是因为它提供具有 CSS 支持的高质量 PDF 渲染。对于 Word 文档，python-docx 提供对文档结构的精细控制。 +对于 PDF 生成，此插件使用 WeasyPrint，因为它提供具有 CSS 支持的高质量 PDF 渲染。对于 Word 文档，python-docx 提供对文档结构的精细控制。 ## 总结 -你已经构建了一个实用的插件，通过使用户能够以专业文档格式导出对话，为 Dify 平台增添了真正的价值。此功能弥合了 AI 对话与传统文档工作流之间的差距。 +你已经构建了一个实用的插件，让用户能够以专业文档格式导出对话，弥合了 AI 对话与传统文档工作流之间的差距。 diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx index ea9e3e147..64ccdfe6e 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx @@ -7,15 +7,14 @@ description: 配置工具插件以输出图片、音频或视频，使知识库 在知识流水线中，知识库节点支持两种多模态数据格式的入参：`multimodal-Parent-Child` 和 `multimodal-General`。 -开发用于多模态数据处理的工具插件时，若希望插件输出的多模态数据（如文字、图片、音视频等）能够被知识库节点正确识别并向量化，需要完成以下配置： +若希望知识库节点能够识别并向量化工具插件的多模态输出（如文字、图片、音频或视频），需要完成以下配置： -- **在工具代码文件中**，调用工具会话接口上传文件并构造 `files` 对象。 - -- **在工具提供者 YAML 文件中**，将 `output_schema` 声明为 `multimodal-Parent-Child` 或 `multimodal-General`。 +- **在工具代码文件中**：调用工具会话接口上传文件并构造 `files` 对象。 +- **在工具提供者 YAML 文件中**：将 `output_schema` 声明为 `multimodal-Parent-Child` 或 `multimodal-General`。 ## 上传并构造文件对象 -在处理多模态数据（如图片）时，需要先通过 Dify 的工具会话工具上传文件，以获取文件元数据。 +在处理多模态数据（如图片）时，需要先通过 Dify 的工具会话上传文件，以获取文件元数据。 下面以 Dify 官方插件 **Dify Extractor** 为例，展示如何上传文件并构造 `files` 对象。 @@ -30,41 +29,42 @@ file_res = self._tool.session.file.upload( # Generate a Markdown image reference using the file preview URL image_url = f"![image]({file_res.preview_url})" ``` -上传接口会返回一个 `UploadFileResponse` 对象，包含文件的基本信息。其结构如下： -```python - from enum import Enum - from pydantic import BaseModel +上传接口会返回一个 `UploadFileResponse` 对象，包含文件的基本信息： + +```python +from enum import Enum +from pydantic import BaseModel - class UploadFileResponse(BaseModel): - class Type(str, Enum): - DOCUMENT = "document" - IMAGE = "image" - VIDEO = "video" - AUDIO = "audio" +class UploadFileResponse(BaseModel): + class Type(str, Enum): + DOCUMENT = "document" + IMAGE = "image" + VIDEO = "video" + AUDIO = "audio" - @classmethod - def from_mime_type(cls, mime_type: str): - if mime_type.startswith("image/"): - return cls.IMAGE - if mime_type.startswith("video/"): - return cls.VIDEO - if mime_type.startswith("audio/"): - return cls.AUDIO - return cls.DOCUMENT - id: str - name: str - size: int - extension: str - mime_type: str - type: Type | None = None - preview_url: str | None = None + @classmethod + def from_mime_type(cls, mime_type: str): + if mime_type.startswith("image/"): + return cls.IMAGE + if mime_type.startswith("video/"): + return cls.VIDEO + if mime_type.startswith("audio/"): + return cls.AUDIO + return cls.DOCUMENT + id: str + name: str + size: int + extension: str + mime_type: str + type: Type | None = None + preview_url: str | None = None ``` 可将文件信息（如 `name`、`size`、`extension`、`mime_type` 等）映射到多模态输出结构中的 `files` 字段。 - ```yaml multimodal_parent_child_structure highlight={22-62} expandable + ```json multimodal_parent_child_structure highlight={22-62} expandable { "$id": "https://dify.ai/schemas/v1/multimodal_parent_child_structure.json", "$schema": "http://json-schema.org/draft-07/schema#", @@ -145,7 +145,7 @@ image_url = f"![image]({file_res.preview_url})" } ``` - ```yaml multimodal_general_structure highlight={18-56} expandable + ```json multimodal_general_structure highlight={18-56} expandable { "$id": "https://dify.ai/schemas/v1/multimodal_general_structure.json", "$schema": "http://json-schema.org/draft-07/schema#", diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx index d96009bcf..7b21c8aea 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx @@ -7,35 +7,31 @@ dimensions: standard_title: Endpoint language: zh title: Endpoint 插件 -description: Authors Yeuoly, Allen. This document details the structure and implementation - of Endpoints in Dify plugins, using the Neko Cat project as an example. It covers - defining Endpoint groups, configuring interfaces, implementing the _invoke method, - and handling requests and responses. The document explains the meaning and usage - of various YAML configuration fields. +description: 以 Neko Cat 项目为例，介绍如何在 Dify 插件中定义、配置和实现 HTTP Endpoint --- ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint)。 -本文档以 [Neko Cat](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko) 项目为例，介绍插件中 Endpoint 的结构。Endpoint 是插件暴露的 HTTP 接口，可用于与外部系统集成。完整的插件代码请参考 [GitHub 仓库](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko)。 +Endpoint 是插件暴露的 HTTP 接口，可用于与外部系统集成。本指南以 [Neko Cat](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko) 项目为例，介绍其结构。完整的插件代码请参考 [GitHub 仓库](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko)。 ## 分组定义 -`Endpoint` 分组是多个 `Endpoint` 的集合。在 Dify 插件中创建新的 `Endpoint` 时，你可能需要填写以下配置。 +Endpoint 分组是多个 Endpoint 的集合。在 Dify 插件中创建新的 Endpoint 时，你可能需要填写以下配置。 - ![](https://assets-docs.dify.ai/2024/11/763dbf86e4319591415dc5a1b6948ccb.png) + ![Endpoint 分组配置表单](https://assets-docs.dify.ai/2024/11/763dbf86e4319591415dc5a1b6948ccb.png) -除了 `Endpoint Name` 之外，你可以通过编写分组的配置信息来添加新的表单项。点击保存后，你可以看到它包含的多个接口，这些接口将使用相同的配置信息。 +除了 **Endpoint Name** 之外，你可以通过编写分组的配置信息来添加新的表单项。点击保存后，你可以看到该分组包含的多个接口，这些接口将使用相同的配置信息。 - ![除了 Endpoint Name 之外，你可以通过编写分组的配置信息来添加新的表单项](https://assets-docs.dify.ai/2024/11/b778b7093b7df0dc80a476c65ddcbe58.png) + ![Endpoint 分组接口列表](https://assets-docs.dify.ai/2024/11/b778b7093b7df0dc80a476c65ddcbe58.png) -### **结构** +### 结构 -* `settings` (map[string] [ProviderConfig](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications#providerconfig))：Endpoint 配置定义。 -* `endpoints` （list[string]，必填）：指向具体的 `endpoint` 接口定义。 +- **`settings`** (map[string] [ProviderConfig](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications#providerconfig))：Endpoint 配置定义。 +- **`endpoints`** （list[string]，必填）：指向具体的 `endpoint` 接口定义。 ```yaml settings: @@ -59,11 +55,11 @@ endpoints: ## 接口定义 -* `path` (string)：遵循 Werkzeug 接口标准。 -* `method` (string)：接口方法，仅支持 `HEAD`、`GET`、`POST`、`PUT`、`DELETE`、`OPTIONS`。 -* `extra` (object)：基本详情之外的配置信息。 - * `python` (object) - * `source` (string)：实现此接口的源代码。 +- **`path`** (string)：遵循 Werkzeug 接口标准。 +- **`method`** (string)：接口方法，仅支持 `HEAD`、`GET`、`POST`、`PUT`、`DELETE`、`OPTIONS`。 +- **`extra`** (object)：基本详情之外的配置信息。 + - **`python`** (object) + - **`source`** (string)：实现此接口的源代码。 ```yaml path: "/duck/" @@ -77,13 +73,13 @@ extra: 你需要实现一个继承自 `dify_plugin.Endpoint` 的子类，并实现 `_invoke` 方法。 -* **输入参数** - * `r` (Request)：来自 `werkzeug` 的 `Request` 对象。 - * `values` (Mapping)：从路径解析的路径参数。 - * `settings` (Mapping)：此 `Endpoint` 的配置信息。 -* **返回** - * 来自 `werkzeug` 的 `Response` 对象，支持流式响应。 - * 不支持直接返回字符串。 +- **输入参数** + - **`r`** (Request)：来自 `werkzeug` 的 `Request` 对象。 + - **`values`** (Mapping)：从路径解析的路径参数。 + - **`settings`** (Mapping)：此 Endpoint 的配置信息。 +- **返回** + - 来自 `werkzeug` 的 `Response` 对象，支持流式响应。 + - 不支持直接返回字符串。 示例代码： @@ -108,20 +104,20 @@ class Duck(Endpoint): ## 注意事项 -* Endpoint 仅在插件被调用时实例化；它们不是长期运行的服务。 -* 开发 Endpoint 时请注意安全性，避免执行危险操作。 -* Endpoint 可用于处理 Webhook 回调或为其他系统提供连接接口。 +- Endpoint 仅在插件被调用时实例化；它们不是长期运行的服务。 +- 开发 Endpoint 时请注意安全性，避免执行危险操作。 +- Endpoint 可用于处理 Webhook 回调或为其他系统提供连接接口。 如果你正在学习插件开发，建议先阅读[插件开发入门](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)和[开发者速查表](/zh/develop-plugin/dev-guides-and-walkthroughs/cheatsheet)。 ## 相关资源 -* [插件开发基本概念](/zh/develop-plugin/getting-started/getting-started-dify-plugin) - 了解插件开发的整体架构。 -* [Neko Cat 示例](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 扩展插件开发示例。 -* [通用规范定义](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications) - 了解 ProviderConfig 等通用结构。 -* [开发 Slack Bot 插件示例](/zh/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin) - 另一个插件开发示例。 -* [插件开发入门](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - 从零开始开发插件。 -* [反向调用 Dify 服务](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app) - 了解如何使用反向调用功能。 +- [插件开发基本概念](/zh/develop-plugin/getting-started/getting-started-dify-plugin)：了解插件开发的整体架构。 +- [Neko Cat 示例](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint)：扩展插件开发示例。 +- [通用规范定义](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications)：了解 ProviderConfig 等通用结构。 +- [开发 Slack Bot 插件示例](/zh/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin)：另一个插件开发示例。 +- [插件开发入门](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)：从零开始开发插件。 +- [反向调用 Dify 服务](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app)：了解如何使用反向调用功能。 {/* Contributing Section diff --git a/zh/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx b/zh/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx index 10c3582c9..d6acf7124 100644 --- a/zh/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx +++ b/zh/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx @@ -47,35 +47,35 @@ sequenceDiagram ### 流程 1：OAuth 客户端设置（管理员/开发者流程） - 在 Dify Cloud 上，Dify 团队会为热门工具插件创建 OAuth 应用并设置 OAuth 客户端，省去用户自行配置的麻烦。 + 在 Dify Cloud 上，Dify 团队会为热门工具插件创建 OAuth 应用并设置 OAuth 客户端，用户无需自行配置。 自托管 Dify 实例的管理员必须完成此设置流程。 -Dify 实例的管理员或开发者首先需要在第三方服务上将 OAuth 应用注册为受信任的应用程序。由此，他们将能够获取必要的凭证，以将 Dify 工具提供者配置为 OAuth 客户端。 +Dify 实例的管理员或开发者首先需要在第三方服务上将 OAuth 应用注册为受信任的应用程序。这将提供配置 Dify 工具提供者作为 OAuth 客户端所需的凭证。 以下是为 Dify 的 Gmail 工具提供者设置 OAuth 客户端的步骤示例： - 1. 前往 [Google Cloud Console](https://console.cloud.google.com) 创建新项目，或选择现有项目 - 2. 启用所需的 API（例如 Gmail API） + 1. 前往 [Google Cloud Console](https://console.cloud.google.com) 创建新项目，或选择现有项目。 + 2. 启用所需的 API（例如 Gmail API）。 - - 1. 导航至 **APIs & Services** \> **OAuth consent screen** - 2. 为公共插件选择 **External** 用户类型 - 3. 填写应用名称、用户支持邮箱和开发者联系方式 - 4. 如需要，添加授权域名 - 5. 测试阶段：在 **Test users** 部分添加测试用户 + + 1. 导航至 **APIs & Services** \> **OAuth consent screen**。 + 2. 为公共插件选择 **External** 用户类型。 + 3. 填写应用名称、用户支持邮箱和开发者联系方式。 + 4. 如需要，添加授权域名。 + 5. 测试阶段，在 **Test users** 部分添加测试用户。 - 1. 前往 **APIs & Services** \> **Credentials** - 2. 点击 **Create Credentials** \> **OAuth 2.0 Client IDs** - 3. 选择 **Web application** 类型 + 1. 前往 **APIs & Services** \> **Credentials**。 + 2. 点击 **Create Credentials** \> **OAuth 2.0 Client IDs**。 + 3. 选择 **Web application** 类型。 4. 将生成 `client_id` 和 `client_secret`。保存这些凭证。 - 在 OAuth 客户端配置弹窗中输入 client_id 和 client_secret，以将工具提供者设置为客户端。 + 在 OAuth 客户端配置弹窗中输入 `client_id` 和 `client_secret`，以将工具提供者设置为客户端。 ![OAuth 客户端设置对话框](/images/develop-plugin/dev-guide/oauth-client-settings-dialog.png) @@ -117,7 +117,7 @@ Dify 实例的管理员或开发者首先需要在第三方服务上将 OAuth ### 1. 在提供者清单中定义 OAuth Schema -提供者清单中的 `oauth_schema` 部分告诉 Dify 你的插件 OAuth 需要哪些凭证以及 OAuth 流程将产生什么。设置 OAuth 需要两个 schema： +提供者清单中的 `oauth_schema` 部分告诉 Dify 你的插件 OAuth 设置需要哪些凭证以及 OAuth 流程将产生什么。设置 OAuth 需要两个 schema： #### client_schema @@ -136,7 +136,7 @@ oauth_schema: ``` - `url` 字段直接链接到第三方服务的帮助文档。这有助于遇到困惑的管理员/开发者。 + `url` 字段链接到第三方服务的帮助文档，为管理员和开发者在设置过程中提供参考。 #### credentials_schema @@ -155,7 +155,7 @@ oauth_schema: ``` - 同时包含 `oauth_schema` 和 `credentials_for_provider` 可提供 OAuth \+ API 密钥认证选项。 + 同时包含 `oauth_schema` 和 `credentials_for_provider` 可提供 OAuth 和 API 密钥两种认证选项。 ### 2. 在工具提供者中完成必需的 OAuth 方法 @@ -170,7 +170,7 @@ from dify_plugin.errors.tool import ToolProviderCredentialValidationError, ToolP 你的 `ToolProvider` 类必须实现以下三个 OAuth 方法（以 `GmailProvider` 为例）： - 在任何情况下都不应在 `ToolOAuthCredentials` 的凭证中返回 `client_secret`，因为这可能导致安全问题。 + 永远不要在 `ToolOAuthCredentials` 的凭证中返回 `client_secret`；这样做可能导致安全问题。 @@ -207,7 +207,7 @@ def _oauth_get_credentials( ) -> ToolOAuthCredentials: """ Exchange authorization code for access token and refresh token. This is called - to creates ONE credential set for one account connection + to create ONE credential set for one account connection. """ # Extract authorization code from OAuth callback code = request.args.get("code") @@ -281,8 +281,8 @@ def _oauth_refresh_credentials( self, redirect_uri: str, system_credentials: Mapping[str, Any], credentials: Mapping[str, Any] ) -> ToolOAuthCredentials: """ - Refresh the credentials using refresh token. - Dify calls this automatically when tokens expire + Refresh the credentials using the refresh token. + Dify calls this automatically when tokens expire. """ refresh_token = credentials.get("refresh_token") if not refresh_token: @@ -348,7 +348,7 @@ def _oauth_refresh_credentials( ### 3. 在工具中访问令牌 -你可以在 `Tool` 实现中使用 OAuth 凭证进行经过身份验证的 API 调用，如下所示： +在 `Tool` 实现中使用 OAuth 凭证进行经过身份验证的 API 调用： ```python class YourTool(BuiltinTool): @@ -363,13 +363,13 @@ class YourTool(BuiltinTool): `self.runtime.credentials` 自动提供当前用户的令牌。Dify 自动处理刷新。 -对于同时支持 OAuth 和 API_KEY 认证的插件，你可以使用 `self.runtime.credential_type` 来区分这两种认证类型。 +对于同时支持 OAuth 和 `API_KEY` 认证的插件，使用 `self.runtime.credential_type` 来区分这两种认证类型。 ### 4. 指定正确的版本 OAuth 需要较新版本的 SDK 和 Dify。在 `requirements.txt` 中固定插件 SDK 版本： -``` +```text dify_plugin>=0.5.0 ```