mirror of
https://github.com/langgenius/dify.git
synced 2024-11-16 03:32:23 +08:00
docs: Add Japanese documentation for tools (#8469)
This commit is contained in:
Shota Totsuka
GitHub
parent
8c51d06222
commit
a587f0d3f1
|
|
@ -9,10 +9,10 @@ The tools provided for Agents and Workflows are currently divided into two categ
|
|||
- `Api-Based Tools` leverage third-party APIs for implementation. You don't need to code to integrate these -- simply provide interface definitions in formats like `OpenAPI` , `Swagger`, or the `OpenAI-plugin` on the front-end.
|
||||
|
||||
### Built-in Tool Providers
|
||||
|
||||
|
||||
|
||||
### API Tool Providers
|
||||
|
||||
|
||||
|
||||
## Tool Integration
|
||||
|
||||
|
|
|
|||
|
|
@ -12,10 +12,10 @@
|
|||
- `Api-Based Tools` 基于API的工具，即通过调用第三方API实现的工具，`Api-Based Tool`不需要再额外定义，只需提供`OpenAPI` `Swagger` `OpenAI plugin`等接口文档即可。
|
||||
|
||||
### 内置工具供应商
|
||||
|
||||
|
||||
|
||||
### API工具供应商
|
||||
|
||||
|
||||
|
||||
## 工具接入
|
||||
为了实现更灵活更强大的功能，Tools提供了一系列的接口，帮助开发者快速构建想要的工具，本文作为开发者的入门指南，将会以[快速接入](./docs/zh_Hans/tool_scale_out.md)和[高级接入](./docs/zh_Hans/advanced_scale_out.md)两部分介绍如何接入工具。
|
||||
|
|
|
|||
31
api/core/tools/README_JP.md
Normal file
31
api/core/tools/README_JP.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# Tools
|
||||
|
||||
このモジュールは、Difyのエージェントアシスタントやワークフローで使用される組み込みツールを実装しています。このモジュールでは、フロントエンドのロジックを変更することなく、独自のツールを定義し表示することができます。この分離により、Difyの機能を容易に水平方向にスケールアウトできます。
|
||||
|
||||
## 機能紹介
|
||||
|
||||
エージェントとワークフロー向けに提供されるツールは、現在2つのカテゴリーに分類されています。
|
||||
|
||||
- `Built-in Tools`はDify内部で実装され、エージェントとワークフローで使用するためにハードコードされています。
|
||||
- `Api-Based Tools`はサードパーティのAPIを利用して実装されています。これらを統合するためのコーディングは不要で、フロントエンドで
|
||||
`OpenAPI`, `Swagger`または`OpenAI-plugin`などの形式でインターフェース定義を提供するだけです。
|
||||
|
||||
### 組み込みツールプロバイダー
|
||||
|
||||
|
||||
|
||||
### APIツールプロバイダー
|
||||
|
||||
|
||||
|
||||
## ツールの統合
|
||||
|
||||
開発者が柔軟で強力なツールを構築できるよう、2つのガイドを提供しています。
|
||||
|
||||
### [クイック統合 👈🏻](./docs/ja_JP/tool_scale_out.md)
|
||||
|
||||
クイック統合は、Google検索ツールの例を通じて、ツール統合の基本をすばやく理解できるようにすることを目的としています。
|
||||
|
||||
### [高度な統合 👈🏻](./docs/ja_JP/advanced_scale_out.md)
|
||||
|
||||
高度な統合では、モジュールインターフェースについてより深く掘り下げ、画像生成、複数ツールの組み合わせ、異なるツール間でのパラメーター、画像、ファイルのフロー管理など、より複雑な機能の実装方法を説明します。
|
||||
|
|
@ -245,4 +245,4 @@ After the above steps are completed, we can see this tool on the frontend, and i
|
|||
|
||||
Of course, because google_search needs a credential, before using it, you also need to input your credentials on the frontend.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 242 KiB After Width: | Height: | Size: 242 KiB |
|
Before Width: | Height: | Size: 407 KiB After Width: | Height: | Size: 407 KiB |
|
Before Width: | Height: | Size: 266 KiB After Width: | Height: | Size: 266 KiB |
283
api/core/tools/docs/ja_JP/advanced_scale_out.md
Normal file
283
api/core/tools/docs/ja_JP/advanced_scale_out.md
Normal file
|
|
@ -0,0 +1,283 @@
|
|||
# 高度なツール統合
|
||||
|
||||
このガイドを始める前に、Difyのツール統合プロセスの基本を理解していることを確認してください。簡単な概要については[クイック統合](./tool_scale_out.md)をご覧ください。
|
||||
|
||||
## ツールインターフェース
|
||||
|
||||
より複雑なツールを迅速に構築するのを支援するため、`Tool`クラスに一連のヘルパーメソッドを定義しています。
|
||||
|
||||
### メッセージの返却
|
||||
|
||||
Difyは`テキスト`、`リンク`、`画像`、`ファイルBLOB`、`JSON`などの様々なメッセージタイプをサポートしています。以下のインターフェースを通じて、異なるタイプのメッセージをLLMとユーザーに返すことができます。
|
||||
|
||||
注意：以下のインターフェースの一部のパラメータについては、後のセクションで説明します。
|
||||
|
||||
#### 画像URL
|
||||
画像のURLを渡すだけで、Difyが自動的に画像をダウンロードしてユーザーに返します。
|
||||
|
||||
```python
|
||||
def create_image_message(self, image: str, save_as: str = '') -> ToolInvokeMessage:
|
||||
"""
|
||||
create an image message
|
||||
|
||||
:param image: the url of the image
|
||||
:param save_as: save as
|
||||
:return: the image message
|
||||
"""
|
||||
```
|
||||
|
||||
#### リンク
|
||||
リンクを返す必要がある場合は、以下のインターフェースを使用できます。
|
||||
|
||||
```python
|
||||
def create_link_message(self, link: str, save_as: str = '') -> ToolInvokeMessage:
|
||||
"""
|
||||
create a link message
|
||||
|
||||
:param link: the url of the link
|
||||
:param save_as: save as
|
||||
:return: the link message
|
||||
"""
|
||||
```
|
||||
|
||||
#### テキスト
|
||||
テキストメッセージを返す必要がある場合は、以下のインターフェースを使用できます。
|
||||
|
||||
```python
|
||||
def create_text_message(self, text: str, save_as: str = '') -> ToolInvokeMessage:
|
||||
"""
|
||||
create a text message
|
||||
|
||||
:param text: the text of the message
|
||||
:param save_as: save as
|
||||
:return: the text message
|
||||
"""
|
||||
```
|
||||
|
||||
#### ファイルBLOB
|
||||
画像、音声、動画、PPT、Word、Excelなどのファイルの生データを返す必要がある場合は、以下のインターフェースを使用できます。
|
||||
|
||||
- `blob` ファイルの生データ（bytes型）
|
||||
- `meta` ファイルのメタデータ。ファイルの種類が分かっている場合は、`mime_type`を渡すことをお勧めします。そうでない場合、Difyはデフォルトタイプとして`octet/stream`を使用します。
|
||||
|
||||
```python
|
||||
def create_blob_message(self, blob: bytes, meta: dict = None, save_as: str = '') -> ToolInvokeMessage:
|
||||
"""
|
||||
create a blob message
|
||||
|
||||
:param blob: the blob
|
||||
:param meta: meta
|
||||
:param save_as: save as
|
||||
:return: the blob message
|
||||
"""
|
||||
```
|
||||
|
||||
#### JSON
|
||||
フォーマットされたJSONを返す必要がある場合は、以下のインターフェースを使用できます。これは通常、ワークフロー内のノード間のデータ伝送に使用されますが、エージェントモードでは、ほとんどの大規模言語モデルもJSONを読み取り、理解することができます。
|
||||
|
||||
- `object` Pythonの辞書オブジェクトで、自動的にJSONにシリアライズされます。
|
||||
|
||||
```python
|
||||
def create_json_message(self, object: dict) -> ToolInvokeMessage:
|
||||
"""
|
||||
create a json message
|
||||
"""
|
||||
```
|
||||
|
||||
### ショートカットツール
|
||||
|
||||
大規模モデルアプリケーションでは、以下の2つの一般的なニーズがあります：
|
||||
- まず長いテキストを事前に要約し、その要約内容をLLMに渡すことで、元のテキストが長すぎてLLMが処理できない問題を防ぐ
|
||||
- ツールが取得したコンテンツがリンクである場合、Webページ情報をクロールしてからLLMに返す必要がある
|
||||
|
||||
開発者がこれら2つのニーズを迅速に実装できるよう、以下の2つのショートカットツールを提供しています。
|
||||
|
||||
#### テキスト要約ツール
|
||||
|
||||
このツールはuser_idと要約するテキストを入力として受け取り、要約されたテキストを返します。Difyは現在のワークスペースのデフォルトモデルを使用して長文を要約します。
|
||||
|
||||
```python
|
||||
def summary(self, user_id: str, content: str) -> str:
|
||||
"""
|
||||
summary the content
|
||||
|
||||
:param user_id: the user id
|
||||
:param content: the content
|
||||
:return: the summary
|
||||
"""
|
||||
```
|
||||
|
||||
#### Webページクローリングツール
|
||||
|
||||
このツールはクロールするWebページのリンクとユーザーエージェント（空でも可）を入力として受け取り、そのWebページの情報を含む文字列を返します。`user_agent`はオプションのパラメータで、ツールを識別するために使用できます。渡さない場合、Difyはデフォルトの`user_agent`を使用します。
|
||||
|
||||
```python
|
||||
def get_url(self, url: str, user_agent: str = None) -> str:
|
||||
"""
|
||||
get url from the crawled result
|
||||
"""
|
||||
```
|
||||
|
||||
### 変数プール
|
||||
|
||||
`Tool`内に変数プールを導入し、ツールの実行中に生成された変数やファイルなどを保存します。これらの変数は、ツールの実行中に他のツールが使用することができます。
|
||||
|
||||
次に、`DallE3`と`Vectorizer.AI`を例に、変数プールの使用方法を紹介します。
|
||||
|
||||
- `DallE3`は画像生成ツールで、テキストに基づいて画像を生成できます。ここでは、`DallE3`にカフェのロゴを生成させます。
|
||||
- `Vectorizer.AI`はベクター画像変換ツールで、画像をベクター画像に変換できるため、画像を無限に拡大しても品質が損なわれません。ここでは、`DallE3`が生成したPNGアイコンをベクター画像に変換し、デザイナーが実際に使用できるようにします。
|
||||
|
||||
#### DallE3
|
||||
まず、DallE3を使用します。画像を作成した後、その画像を変数プールに保存します。コードは以下の通りです：
|
||||
|
||||
```python
|
||||
from typing import Any, Dict, List, Union
|
||||
from core.tools.entities.tool_entities import ToolInvokeMessage
|
||||
from core.tools.tool.builtin_tool import BuiltinTool
|
||||
|
||||
from base64 import b64decode
|
||||
|
||||
from openai import OpenAI
|
||||
|
||||
class DallE3Tool(BuiltinTool):
|
||||
def _invoke(self,
|
||||
user_id: str,
|
||||
tool_parameters: Dict[str, Any],
|
||||
) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
|
||||
"""
|
||||
invoke tools
|
||||
"""
|
||||
client = OpenAI(
|
||||
api_key=self.runtime.credentials['openai_api_key'],
|
||||
)
|
||||
|
||||
# prompt
|
||||
prompt = tool_parameters.get('prompt', '')
|
||||
if not prompt:
|
||||
return self.create_text_message('Please input prompt')
|
||||
|
||||
# call openapi dalle3
|
||||
response = client.images.generate(
|
||||
prompt=prompt, model='dall-e-3',
|
||||
size='1024x1024', n=1, style='vivid', quality='standard',
|
||||
response_format='b64_json'
|
||||
)
|
||||
|
||||
result = []
|
||||
for image in response.data:
|
||||
# Save all images to the variable pool through the save_as parameter. The variable name is self.VARIABLE_KEY.IMAGE.value. If new images are generated later, they will overwrite the previous images.
|
||||
result.append(self.create_blob_message(blob=b64decode(image.b64_json),
|
||||
meta={ 'mime_type': 'image/png' },
|
||||
save_as=self.VARIABLE_KEY.IMAGE.value))
|
||||
|
||||
return result
|
||||
```
|
||||
|
||||
ここでは画像の変数名として`self.VARIABLE_KEY.IMAGE.value`を使用していることに注意してください。開発者のツールが互いに連携できるよう、この`KEY`を定義しました。自由に使用することも、この`KEY`を使用しないこともできます。カスタムのKEYを渡すこともできます。
|
||||
|
||||
#### Vectorizer.AI
|
||||
次に、Vectorizer.AIを使用して、DallE3が生成したPNGアイコンをベクター画像に変換します。ここで定義した関数を見てみましょう。コードは以下の通りです：
|
||||
|
||||
```python
|
||||
from core.tools.tool.builtin_tool import BuiltinTool
|
||||
from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParameter
|
||||
from core.tools.errors import ToolProviderCredentialValidationError
|
||||
|
||||
from typing import Any, Dict, List, Union
|
||||
from httpx import post
|
||||
from base64 import b64decode
|
||||
|
||||
class VectorizerTool(BuiltinTool):
|
||||
def _invoke(self, user_id: str, tool_parameters: Dict[str, Any])
|
||||
-> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
|
||||
"""
|
||||
Tool invocation, the image variable name needs to be passed in from here, so that we can get the image from the variable pool
|
||||
"""
|
||||
|
||||
|
||||
def get_runtime_parameters(self) -> List[ToolParameter]:
|
||||
"""
|
||||
Override the tool parameter list, we can dynamically generate the parameter list based on the actual situation in the current variable pool, so that the LLM can generate the form based on the parameter list
|
||||
"""
|
||||
|
||||
|
||||
def is_tool_available(self) -> bool:
|
||||
"""
|
||||
Whether the current tool is available, if there is no image in the current variable pool, then we don't need to display this tool, just return False here
|
||||
"""
|
||||
```
|
||||
|
||||
次に、これら3つの関数を実装します：
|
||||
|
||||
```python
|
||||
from core.tools.tool.builtin_tool import BuiltinTool
|
||||
from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParameter
|
||||
from core.tools.errors import ToolProviderCredentialValidationError
|
||||
|
||||
from typing import Any, Dict, List, Union
|
||||
from httpx import post
|
||||
from base64 import b64decode
|
||||
|
||||
class VectorizerTool(BuiltinTool):
|
||||
def _invoke(self, user_id: str, tool_parameters: Dict[str, Any])
|
||||
-> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
|
||||
"""
|
||||
invoke tools
|
||||
"""
|
||||
api_key_name = self.runtime.credentials.get('api_key_name', None)
|
||||
api_key_value = self.runtime.credentials.get('api_key_value', None)
|
||||
|
||||
if not api_key_name or not api_key_value:
|
||||
raise ToolProviderCredentialValidationError('Please input api key name and value')
|
||||
|
||||
# Get image_id, the definition of image_id can be found in get_runtime_parameters
|
||||
image_id = tool_parameters.get('image_id', '')
|
||||
if not image_id:
|
||||
return self.create_text_message('Please input image id')
|
||||
|
||||
# Get the image generated by DallE from the variable pool
|
||||
image_binary = self.get_variable_file(self.VARIABLE_KEY.IMAGE)
|
||||
if not image_binary:
|
||||
return self.create_text_message('Image not found, please request user to generate image firstly.')
|
||||
|
||||
# Generate vector image
|
||||
response = post(
|
||||
'https://vectorizer.ai/api/v1/vectorize',
|
||||
files={ 'image': image_binary },
|
||||
data={ 'mode': 'test' },
|
||||
auth=(api_key_name, api_key_value),
|
||||
timeout=30
|
||||
)
|
||||
|
||||
if response.status_code != 200:
|
||||
raise Exception(response.text)
|
||||
|
||||
return [
|
||||
self.create_text_message('the vectorized svg is saved as an image.'),
|
||||
self.create_blob_message(blob=response.content,
|
||||
meta={'mime_type': 'image/svg+xml'})
|
||||
]
|
||||
|
||||
def get_runtime_parameters(self) -> List[ToolParameter]:
|
||||
"""
|
||||
override the runtime parameters
|
||||
"""
|
||||
# Here, we override the tool parameter list, define the image_id, and set its option list to all images in the current variable pool. The configuration here is consistent with the configuration in yaml.
|
||||
return [
|
||||
ToolParameter.get_simple_instance(
|
||||
name='image_id',
|
||||
llm_description=f'the image id that you want to vectorize, \
|
||||
and the image id should be specified in \
|
||||
{[i.name for i in self.list_default_image_variables()]}',
|
||||
type=ToolParameter.ToolParameterType.SELECT,
|
||||
required=True,
|
||||
options=[i.name for i in self.list_default_image_variables()]
|
||||
)
|
||||
]
|
||||
|
||||
def is_tool_available(self) -> bool:
|
||||
# Only when there are images in the variable pool, the LLM needs to use this tool
|
||||
return len(self.list_default_image_variables()) > 0
|
||||
```
|
||||
|
||||
ここで注目すべきは、実際には`image_id`を使用していないことです。このツールを呼び出す際には、デフォルトの変数プールに必ず画像があると仮定し、直接`image_binary = self.get_variable_file(self.VARIABLE_KEY.IMAGE)`を使用して画像を取得しています。モデルの能力が弱い場合、開発者にもこの方法を推奨します。これにより、エラー許容度を効果的に向上させ、モデルが誤ったパラメータを渡すのを防ぐことができます。
|
||||
240
api/core/tools/docs/ja_JP/tool_scale_out.md
Normal file
240
api/core/tools/docs/ja_JP/tool_scale_out.md
Normal file
|
|
@ -0,0 +1,240 @@
|
|||
# ツールの迅速な統合
|
||||
|
||||
ここでは、GoogleSearchを例にツールを迅速に統合する方法を紹介します。
|
||||
|
||||
## 1. ツールプロバイダーのyamlを準備する
|
||||
|
||||
### 概要
|
||||
|
||||
このyamlファイルには、プロバイダー名、アイコン、作者などの詳細情報が含まれ、フロントエンドでの柔軟な表示を可能にします。
|
||||
|
||||
### 例
|
||||
|
||||
`core/tools/provider/builtin`の下に`google`モジュール（フォルダ）を作成し、`google.yaml`を作成します。名前はモジュール名と一致している必要があります。
|
||||
|
||||
以降、このツールに関するすべての操作はこのモジュール内で行います。
|
||||
|
||||
```yaml
|
||||
identity: # ツールプロバイダーの基本情報
|
||||
author: Dify # 作者
|
||||
name: google # 名前（一意、他のプロバイダーと重複不可）
|
||||
label: # フロントエンド表示用のラベル
|
||||
en_US: Google # 英語ラベル
|
||||
zh_Hans: Google # 中国語ラベル
|
||||
description: # フロントエンド表示用の説明
|
||||
en_US: Google # 英語説明
|
||||
zh_Hans: Google # 中国語説明
|
||||
icon: icon.svg # アイコン（現在のモジュールの_assetsフォルダに配置）
|
||||
tags: # タグ（フロントエンド表示用）
|
||||
- search
|
||||
```
|
||||
|
||||
- `identity`フィールドは必須で、ツールプロバイダーの基本情報（作者、名前、ラベル、説明、アイコンなど）が含まれます。
|
||||
- アイコンは現在のモジュールの`_assets`フォルダに配置する必要があります。[こちら](../../provider/builtin/google/_assets/icon.svg)を参照してください。
|
||||
- タグはフロントエンドでの表示に使用され、ユーザーがこのツールプロバイダーを素早く見つけるのに役立ちます。現在サポートされているすべてのタグは以下の通りです：
|
||||
```python
|
||||
class ToolLabelEnum(Enum):
|
||||
SEARCH = 'search'
|
||||
IMAGE = 'image'
|
||||
VIDEOS = 'videos'
|
||||
WEATHER = 'weather'
|
||||
FINANCE = 'finance'
|
||||
DESIGN = 'design'
|
||||
TRAVEL = 'travel'
|
||||
SOCIAL = 'social'
|
||||
NEWS = 'news'
|
||||
MEDICAL = 'medical'
|
||||
PRODUCTIVITY = 'productivity'
|
||||
EDUCATION = 'education'
|
||||
BUSINESS = 'business'
|
||||
ENTERTAINMENT = 'entertainment'
|
||||
UTILITIES = 'utilities'
|
||||
OTHER = 'other'
|
||||
```
|
||||
|
||||
## 2. プロバイダーの認証情報を準備する
|
||||
|
||||
GoogleはSerpApiが提供するAPIを使用するサードパーティツールであり、SerpApiを使用するにはAPI Keyが必要です。つまり、このツールを使用するには認証情報が必要です。一方、`wikipedia`のようなツールでは認証情報フィールドを記入する必要はありません。[こちら](../../provider/builtin/wikipedia/wikipedia.yaml)を参照してください。
|
||||
|
||||
認証情報フィールドを設定すると、以下のようになります：
|
||||
|
||||
```yaml
|
||||
identity:
|
||||
author: Dify
|
||||
name: google
|
||||
label:
|
||||
en_US: Google
|
||||
zh_Hans: Google
|
||||
description:
|
||||
en_US: Google
|
||||
zh_Hans: Google
|
||||
icon: icon.svg
|
||||
credentials_for_provider: # 認証情報フィールド
|
||||
serpapi_api_key: # 認証情報フィールド名
|
||||
type: secret-input # 認証情報フィールドタイプ
|
||||
required: true # 必須かどうか
|
||||
label: # 認証情報フィールドラベル
|
||||
en_US: SerpApi API key # 英語ラベル
|
||||
zh_Hans: SerpApi API key # 中国語ラベル
|
||||
placeholder: # 認証情報フィールドプレースホルダー
|
||||
en_US: Please input your SerpApi API key # 英語プレースホルダー
|
||||
zh_Hans: 请输入你的 SerpApi API key # 中国語プレースホルダー
|
||||
help: # 認証情報フィールドヘルプテキスト
|
||||
en_US: Get your SerpApi API key from SerpApi # 英語ヘルプテキスト
|
||||
zh_Hans: 从 SerpApi 获取您的 SerpApi API key # 中国語ヘルプテキスト
|
||||
url: https://serpapi.com/manage-api-key # 認証情報フィールドヘルプリンク
|
||||
```
|
||||
|
||||
- `type`：認証情報フィールドタイプ。現在、`secret-input`、`text-input`、`select`の3種類をサポートしており、それぞれパスワード入力ボックス、テキスト入力ボックス、ドロップダウンボックスに対応します。`secret-input`の場合、フロントエンドで入力内容が隠され、バックエンドで入力内容が暗号化されます。
|
||||
|
||||
## 3. ツールのyamlを準備する
|
||||
|
||||
1つのプロバイダーの下に複数のツールを持つことができ、各ツールにはyamlファイルが必要です。このファイルにはツールの基本情報、パラメータ、出力などが含まれます。
|
||||
|
||||
引き続きGoogleSearchを例に、`google`モジュールの下に`tools`モジュールを作成し、`tools/google_search.yaml`を作成します。内容は以下の通りです：
|
||||
|
||||
```yaml
|
||||
identity: # ツールの基本情報
|
||||
name: google_search # ツール名（一意、他のツールと重複不可）
|
||||
author: Dify # 作者
|
||||
label: # フロントエンド表示用のラベル
|
||||
en_US: GoogleSearch # 英語ラベル
|
||||
zh_Hans: 谷歌搜索 # 中国語ラベル
|
||||
description: # フロントエンド表示用の説明
|
||||
human: # フロントエンド表示用の紹介（多言語対応）
|
||||
en_US: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query.
|
||||
zh_Hans: 一个用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询。
|
||||
llm: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query. # LLMに渡す紹介文。LLMがこのツールをより理解できるよう、できるだけ詳細な情報を記述することをお勧めします。
|
||||
parameters: # パラメータリスト
|
||||
- name: query # パラメータ名
|
||||
type: string # パラメータタイプ
|
||||
required: true # 必須かどうか
|
||||
label: # パラメータラベル
|
||||
en_US: Query string # 英語ラベル
|
||||
zh_Hans: 查询语句 # 中国語ラベル
|
||||
human_description: # フロントエンド表示用の紹介（多言語対応）
|
||||
en_US: used for searching
|
||||
zh_Hans: 用于搜索网页内容
|
||||
llm_description: key words for searching # LLMに渡す紹介文。LLMがこのパラメータをより理解できるよう、できるだけ詳細な情報を記述することをお勧めします。
|
||||
form: llm # フォームタイプ。llmはこのパラメータがAgentによって推論される必要があることを意味し、フロントエンドではこのパラメータは表示されません。
|
||||
- name: result_type
|
||||
type: select # パラメータタイプ
|
||||
required: true
|
||||
options: # ドロップダウンボックスのオプション
|
||||
- value: text
|
||||
label:
|
||||
en_US: text
|
||||
zh_Hans: 文本
|
||||
- value: link
|
||||
label:
|
||||
en_US: link
|
||||
zh_Hans: 链接
|
||||
default: link
|
||||
label:
|
||||
en_US: Result type
|
||||
zh_Hans: 结果类型
|
||||
human_description:
|
||||
en_US: used for selecting the result type, text or link
|
||||
zh_Hans: 用于选择结果类型，使用文本还是链接进行展示
|
||||
form: form # フォームタイプ。formはこのパラメータが対話開始前にフロントエンドでユーザーによって入力される必要があることを意味します。
|
||||
```
|
||||
|
||||
- `identity`フィールドは必須で、ツールの基本情報（名前、作者、ラベル、説明など）が含まれます。
|
||||
- `parameters` パラメータリスト
|
||||
- `name`（必須）パラメータ名。一意で、他のパラメータと重複しないようにしてください。
|
||||
- `type`（必須）パラメータタイプ。現在、`string`、`number`、`boolean`、`select`、`secret-input`の5種類をサポートしており、それぞれ文字列、数値、ブール値、ドロップダウンボックス、暗号化入力ボックスに対応します。機密情報には`secret-input`タイプの使用をお勧めします。
|
||||
- `label`（必須）パラメータラベル。フロントエンド表示用です。
|
||||
- `form`（必須）フォームタイプ。現在、`llm`と`form`の2種類をサポートしています。
|
||||
- エージェントアプリケーションでは、`llm`はこのパラメータがLLM自身によって推論されることを示し、`form`はこのツールを使用するために事前に設定できるパラメータであることを示します。
|
||||
- ワークフローアプリケーションでは、`llm`と`form`の両方がフロントエンドで入力する必要がありますが、`llm`のパラメータはツールノードの入力変数として使用されます。
|
||||
- `required` パラメータが必須かどうかを示します。
|
||||
- `llm`モードでは、パラメータが必須の場合、Agentはこのパラメータを推論する必要があります。
|
||||
- `form`モードでは、パラメータが必須の場合、ユーザーは対話開始前にフロントエンドでこのパラメータを入力する必要があります。
|
||||
- `options` パラメータオプション
|
||||
- `llm`モードでは、DifyはすべてのオプションをLLMに渡し、LLMはこれらのオプションに基づいて推論できます。
|
||||
- `form`モードで、`type`が`select`の場合、フロントエンドはこれらのオプションを表示します。
|
||||
- `default` デフォルト値
|
||||
- `min` 最小値。パラメータタイプが`number`の場合に設定できます。
|
||||
- `max` 最大値。パラメータタイプが`number`の場合に設定できます。
|
||||
- `human_description` フロントエンド表示用の紹介。多言語対応です。
|
||||
- `placeholder` 入力ボックスのプロンプトテキスト。フォームタイプが`form`で、パラメータタイプが`string`、`number`、`secret-input`の場合に設定できます。多言語対応です。
|
||||
- `llm_description` LLMに渡す紹介文。LLMがこのパラメータをより理解できるよう、できるだけ詳細な情報を記述することをお勧めします。
|
||||
|
||||
## 4. ツールコードを準備する
|
||||
|
||||
ツールの設定が完了したら、ツールのロジックを実装するコードを作成します。
|
||||
|
||||
`google/tools`モジュールの下に`google_search.py`を作成し、内容は以下の通りです：
|
||||
|
||||
```python
|
||||
from core.tools.tool.builtin_tool import BuiltinTool
|
||||
from core.tools.entities.tool_entities import ToolInvokeMessage
|
||||
|
||||
from typing import Any, Dict, List, Union
|
||||
|
||||
class GoogleSearchTool(BuiltinTool):
|
||||
def _invoke(self,
|
||||
user_id: str,
|
||||
tool_parameters: Dict[str, Any],
|
||||
) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
|
||||
"""
|
||||
ツールを呼び出す
|
||||
"""
|
||||
query = tool_parameters['query']
|
||||
result_type = tool_parameters['result_type']
|
||||
api_key = self.runtime.credentials['serpapi_api_key']
|
||||
result = SerpAPI(api_key).run(query, result_type=result_type)
|
||||
|
||||
if result_type == 'text':
|
||||
return self.create_text_message(text=result)
|
||||
return self.create_link_message(link=result)
|
||||
```
|
||||
|
||||
### パラメータ
|
||||
ツールの全体的なロジックは`_invoke`メソッドにあります。このメソッドは2つのパラメータ（`user_id`とtool_parameters`）を受け取り、それぞれユーザーIDとツールパラメータを表します。
|
||||
|
||||
### 戻り値
|
||||
ツールの戻り値として、1つのメッセージまたは複数のメッセージを選択できます。ここでは1つのメッセージを返しています。`create_text_message`と`create_link_message`を使用して、テキストメッセージまたはリンクメッセージを作成できます。複数のメッセージを返す場合は、リストを構築できます（例：`[self.create_text_message('msg1'), self.create_text_message('msg2')]`）。
|
||||
|
||||
## 5. プロバイダーコードを準備する
|
||||
|
||||
最後に、プロバイダーモジュールの下にプロバイダークラスを作成し、プロバイダーの認証情報検証ロジックを実装する必要があります。認証情報の検証が失敗した場合、`ToolProviderCredentialValidationError`例外が発生します。
|
||||
|
||||
`google`モジュールの下に`google.py`を作成し、内容は以下の通りです：
|
||||
|
||||
```python
|
||||
from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController
|
||||
from core.tools.errors import ToolProviderCredentialValidationError
|
||||
|
||||
from core.tools.provider.builtin.google.tools.google_search import GoogleSearchTool
|
||||
|
||||
from typing import Any, Dict
|
||||
|
||||
class GoogleProvider(BuiltinToolProviderController):
|
||||
def _validate_credentials(self, credentials: Dict[str, Any]) -> None:
|
||||
try:
|
||||
# 1. ここでGoogleSearchTool()を使ってGoogleSearchToolをインスタンス化する必要があります。これによりGoogleSearchToolのyaml設定が自動的に読み込まれますが、この時点では認証情報は含まれていません
|
||||
# 2. 次に、fork_tool_runtimeメソッドを使用して、現在の認証情報をGoogleSearchToolに渡す必要があります
|
||||
# 3. 最後に、invokeを呼び出します。パラメータはGoogleSearchToolのyamlで設定されたパラメータルールに従って渡す必要があります
|
||||
GoogleSearchTool().fork_tool_runtime(
|
||||
meta={
|
||||
"credentials": credentials,
|
||||
}
|
||||
).invoke(
|
||||
user_id='',
|
||||
tool_parameters={
|
||||
"query": "test",
|
||||
"result_type": "link"
|
||||
},
|
||||
)
|
||||
except Exception as e:
|
||||
raise ToolProviderCredentialValidationError(str(e))
|
||||
```
|
||||
|
||||
## 完了
|
||||
|
||||
以上のステップが完了すると、このツールをフロントエンドで確認し、Agentで使用することができるようになります。
|
||||
|
||||
もちろん、google_searchには認証情報が必要なため、使用する前にフロントエンドで認証情報を入力する必要があります。
|
||||
|
||||
|
||||
|
|
@ -234,4 +234,4 @@ class GoogleProvider(BuiltinToolProviderController):
|
|||
|
||||
当然，因为google_search需要一个凭据，在使用之前，还需要在前端配置它的凭据。
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user