Tích hợp nhanh công cụ

Chúng ta sẽ sử dụng GoogleSearch làm ví dụ để minh họa cách tích hợp một công cụ một cách nhanh chóng.

1. Chuẩn bị tệp yaml nhà cung cấp tool

Giới thiệu

Tệp yaml này khai báo một nhà cung cấp công cụ mới, và bao gồm các thông tin như tên nhà cung cấp, icon, tác giả, và các chi tiết khác được giao diện người dùng lấy để hiển thị.

Ví dụ

Chúng ta cần tạo một module (thư mục) google dưới core/tools/provider/builtin, và tạo tệp google.yaml. Tên phải nhất quán với tên module.

Sau đó, tất cả các hoạt động liên quan đến công cụ này sẽ được thực hiện dưới module này.

identity: # Basic information of the tool provider
  author: Dify # Author
  name: google # Name, unique, no duplication with other providers
  label: # Label for frontend display
    en_US: Google # English label
    zh_Hans: Google # Chinese label
  description: # Description for frontend display
    en_US: Google # English description
    zh_Hans: Google # Chinese description
  icon: icon.svg # Icon, needs to be placed in the _assets folder of the current module

• Trường identity là bắt buộc, nó chứa thông tin cơ bản của nhà cung cấp công cụ, bao gồm tác giả, tên, nhãn, mô tả, biểu tượng, v.v.

  • Icon cần được đặt trong thư mục _assets của module hiện tại, bạn có thể tham khảo: api/core/tools/provider/builtin/google/_assets/icon.svg

    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="25" viewBox="0 0 24 25" fill="none">
      <path d="M22.501 12.7332C22.501 11.8699 22.4296 11.2399 22.2748 10.5865H12.2153V14.4832H18.12C18.001 15.4515 17.3582 16.9099 15.9296 17.8898L15.9096 18.0203L19.0902 20.435L19.3106 20.4565C21.3343 18.6249 22.501 15.9298 22.501 12.7332Z" fill="#4285F4"/>
      <path d="M12.214 23C15.1068 23 17.5353 22.0666 19.3092 20.4567L15.9282 17.8899C15.0235 18.5083 13.8092 18.9399 12.214 18.9399C9.38069 18.9399 6.97596 17.1083 6.11874 14.5766L5.99309 14.5871L2.68583 17.0954L2.64258 17.2132C4.40446 20.6433 8.0235 23 12.214 23Z" fill="#34A853"/>
      <path d="M6.12046 14.5766C5.89428 13.9233 5.76337 13.2233 5.76337 12.5C5.76337 11.7766 5.89428 11.0766 6.10856 10.4233L6.10257 10.2841L2.75386 7.7355L2.64429 7.78658C1.91814 9.20993 1.50146 10.8083 1.50146 12.5C1.50146 14.1916 1.91814 15.7899 2.64429 17.2132L6.12046 14.5766Z" fill="#FBBC05"/>
      <path d="M12.2141 6.05997C14.2259 6.05997 15.583 6.91163 16.3569 7.62335L19.3807 4.73C17.5236 3.03834 15.1069 2 12.2141 2C8.02353 2 4.40447 4.35665 2.64258 7.78662L6.10686 10.4233C6.97598 7.89166 9.38073 6.05997 12.2141 6.05997Z" fill="#EB4335"/>
    </svg>

2. Chuẩn bị các thông tin xác thực của nhà cung cấp

Google, là một công cụ bên thứ ba, sử dụng API được cung cấp bởi SerpApi, yêu cầu một API Key để sử dụng. Điều này có nghĩa là công cụ này cần thông tin xác thực để sử dụng. Đối với các công cụ như wikipedia, không cần điền vào trường thông tin xác thực, bạn có thể tham khảo: api/core/tools/provider/builtin/wikipedia/wikipedia.yaml.

identity:
  author: Dify
  name: wikipedia
  label:
    en_US: Wikipedia
    zh_Hans: 维基百科
    pt_BR: Wikipedia
  description:
    en_US: Wikipedia is a free online encyclopedia, created and edited by volunteers around the world.
    zh_Hans: 维基百科是一个由全世界的志愿者创建和编辑的免费在线百科全书。
    pt_BR: Wikipedia is a free online encyclopedia, created and edited by volunteers around the world.
  icon: icon.svg
credentials_for_provider:

Sau khi cấu hình trường thông tin xác thực, kết quả sẽ như sau:

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: # Credential field
  serpapi_api_key: # Credential field name
    type: secret-input # Credential field type
    required: true # Required or not
    label: # Credential field label
      en_US: SerpApi API key # English label
      zh_Hans: SerpApi API key # Chinese label
    placeholder: # Credential field placeholder
      en_US: Please input your SerpApi API key # English placeholder
      zh_Hans: 请输入你的 SerpApi API key # Chinese placeholder
    help: # Credential field help text
      en_US: Get your SerpApi API key from SerpApi # English help text
      zh_Hans: 从 SerpApi 获取您的 SerpApi API key # Chinese help text
    url: https://serpapi.com/manage-api-key # Credential field help link

• type: Kiểu trường thông tin xác thực, hiện có thể là secret-input, text-input, hoặc select, tương ứng với box nhập mật khẩu, box nhập văn bản và box drop-down tương ứng. Nếu được đặt là secret-input, nó sẽ che giấu nội dung đầu vào trên giao diện người dùng và backend sẽ mã hóa nội dung đầu vào đó.

3. Chuẩn bị tool yaml

Một nhà cung cấp có thể có nhiều công cụ, mỗi công cụ cần một tệp yaml để mô tả, tệp này chứa thông tin cơ bản, tham số, đầu ra của công cụ.

Lấy GoogleSearch làm ví dụ, chúng ta cần tạo một mô-đun công cụ dưới mô-đun google và tạo tệp tools/google_search.yaml với nội dung như sau:

identity: # Basic information of the tool
  name: google_search # Tool name, unique, no duplication with other tools
  author: Dify # Author
  label: # Label for frontend display
    en_US: GoogleSearch # English label
    zh_Hans: 谷歌搜索 # Chinese label
description: # Description for frontend display
  human: # Introduction for frontend display, supports multiple languages
    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. # Introduction passed to LLM, in order to make LLM better understand this tool, we suggest to write as detailed information about this tool as possible here, so that LLM can understand and use this tool
parameters: # Parameter list
  - name: query # Parameter name
    type: string # Parameter type
    required: true # Required or not
    label: # Parameter label
      en_US: Query string # English label
      zh_Hans: 查询语句 # Chinese label
    human_description: # Introduction for frontend display, supports multiple languages
      en_US: used for searching
      zh_Hans: 用于搜索网页内容
    llm_description: key words for searching # Introduction passed to LLM, similarly, in order to make LLM better understand this parameter, we suggest to write as detailed information about this parameter as possible here, so that LLM can understand this parameter
    form: llm # Form type, llm means this parameter needs to be inferred by Agent, the frontend will not display this parameter
  - name: result_type
    type: select # Parameter type
    required: true
    options: # Drop-down box 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 type, form means this parameter needs to be filled in by the user on the frontend before the conversation starts

• Trường identity là bắt buộc, nó chứa thông tin cơ bản của công cụ, bao gồm tên, tác giả, nhãn, mô tả, v.v.

• parameters Danh sách tham số

  • name Tên tham số, duy nhất, không trùng lặp với các tham số khác

  • type Loại tham số, hiện hỗ trợ bốn loại: string, number, boolean, select, tương ứng với chuỗi ký tự, số, boolean, và drop-down box

  • required Có bắt buộc hay không

    • Trong chế độ llm, nếu tham số là bắt buộc, Agent sẽ phải suy diễn tham số này

    • Trong chế độ form, nếu tham số là bắt buộc, người dùng phải điền tham số này trên giao diện trước khi cuộc trò chuyện bắt đầu

  • options Các tùy chọn của tham số

    • Trong chế độ llm, Thổ Thần sẽ chuyển tất cả các tùy chọn cho LLM, LLM có thể suy diễn dựa trên các tùy chọn này

    • Trong chế độ form, khi type là select, giao diện sẽ hiển thị các tùy chọn này

  • default Giá trị mặc định

  • label Nhãn của tham số, hiển thị cho giao diện

  • human_description Giới thiệu cho giao diện, hỗ trợ nhiều ngôn ngữ

  • llm_description Giới thiệu để cho LLM hiểu rõ hơn về tham số này, viết thông tin chi tiết nhất có thể về tham số này, để LLM có thể hiểu được tham số

  • form Loại biểu mẫu, hiện hỗ trợ hai loại: llm và form, tương ứng với suy diễn tự động của Agent và điền thông tin trên giao diện

4. Thêm logic công cụ

Sau khi hoàn tất cấu hình công cụ, chúng ta có thể bắt đầu viết mã công cụ để định nghĩa cách nó được triệu hồi.

Tạo tệp google_search.py dưới mô-đun google/tools với nội dung như sau.

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]]:
        """
            invoke tools
        """
        query = tool_parameters['query']
        result_type = tool_parameters['result_type']
        api_key = self.runtime.credentials['serpapi_api_key']
        # TODO: search with serpapi
        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)

Tham số

Logic tổng quát của công cụ nằm trong phương thức _invoke, phương thức này chấp nhận hai tham số: user_id và tool_parameters, lần lượt đại diện cho ID người dùng và các tham số của công cụ.

Return Data

Khi công cụ trả về, bạn có thể chọn trả về một hoặc nhiều message, ở đây chúng ta trả về mộtmessage, sử dụng create_text_message và create_link_message để tạo ra một văn bản hoặc một liên kết.

5. Thêm code cung cấp

Cuối cùng, chúng ta cần tạo một lớp nhà cung cấp (provider) dưới mô-đun provider để thực hiện logic xác thực thông tin. Nếu việc xác thực thông tin thất bại, nó sẽ ném ra một ngoại lệ ToolProviderCredentialValidationError.

Tạo tệp google.py dưới mô-đun google với nội dung như sau.

from core.tools.entities.tool_entities import ToolInvokeMessage, ToolProviderType
from core.tools.tool.tool import Tool
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. Here you need to instantiate a GoogleSearchTool with GoogleSearchTool(), it will automatically load the yaml configuration of GoogleSearchTool, but at this time it does not have credential information inside
            # 2. Then you need to use the fork_tool_runtime method to pass the current credential information to GoogleSearchTool
            # 3. Finally, invoke it, the parameters need to be passed according to the parameter rules configured in the yaml of GoogleSearchTool
            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))

Hoàn thành

Sau khi các bước trên hoàn thành, chúng ta có thể thấy công cụ này trên giao diện và có thể sử dụng nó trong Agent.

Dĩ nhiên, vì google_search cần thông tin xác thực, trước khi sử dụng, bạn cũng cần nhập thông tin xác thực của mình trên giao diện.