Tích hợp công cụ nâng cao

Trước khi bắt đầu với hướng dẫn nâng cao này, vui lòng đảm bảo rằng bạn đã có hiểu biết cơ bản về quy trình tích hợp công cụ trong Thổ Thần. Hãy xem qua phần Tích hợp nhanh công cụ để có cái nhìn tổng quan nhanh.

Giao diện công cụ

Chúng tôi đã định nghĩa một loạt các phương thức trợ giúp trongclass Tool để giúp các nhà phát triển nhanh chóng xây dựng các công cụ phức tạp hơn.

Phản hồi tin nhắn

Thổ Thần hỗ trợ các loại tin nhắn khác nhau như text, link, image, và file BLOB. Bạn có thể trả về các loại tin nhắn khác nhau cho LLM và người dùng thông qua các giao diện sau.

Lưu ý rằng một số tham số trong các giao diện sau sẽ được giới thiệu trong các phần sau.

URL ảnh

Bạn chỉ cần truyền URL của hình ảnh, và hệ thống sẽ tự động tải xuống hình ảnh và trả lại cho người dùng.

    def create_image_message(self, image: str, save_as: str = '') -> ToolInvokeMessage:
        """
            create an image message

            :param image: the url of the image
            :return: the image message
        """

Link

Nếu bạn cần trả về một liên kết, bạn có thể sử dụng giao diện sau đây..

    def create_link_message(self, link: str, save_as: str = '') -> ToolInvokeMessage:
        """
            create a link message

            :param link: the url of the link
            :return: the link message
        """

Text

Nếu bạn cần trả về một văn bản, bạn có thể sử dụng giao diện sau đây.

    def create_text_message(self, text: str, save_as: str = '') -> ToolInvokeMessage:
        """
            create a text message

            :param text: the text of the message
            :return: the text message
        """

File BLOB

Nếu bạn cần trả về dữ liệu thô của một tệp (raw data) , chẳng hạn như hình ảnh, âm thanh, video, PPT, Word, Excel, v.v., bạn có thể sử dụng giao diện sau.

blob Raw data, thuộc loại bytes
meta Thông tin metadata của tệp, nếu bạn biết loại tệp, tốt nhất nên truyền một mime_type, nếu không Thổ Thần sẽ sử dụng octet/stream làm loại mặc định.

    def create_blob_message(self, blob: bytes, meta: dict = None, save_as: str = '') -> ToolInvokeMessage:
        """
            create a blob message

            :param blob: the blob
            :return: the blob message
        """

Công cụ hỗ trợ

Chúng tôi có hai nhu cầu phổ biến:

Đầu tiên, tóm tắt một đoạn văn bản dài trước, sau đó chuyển nội dung tóm tắt cho LLM để tránh trường hợp văn bản gốc quá dài so với khả năng xử lý của LLM.
Nội dung là một liên kết, và thông tin trang web cần được lấy trước khi có thể trả lại cho LLM.

Để giúp các nhà phát triển nhanh chóng triển khai hai nhu cầu này, chúng tôi cung cấp hai công cụ rút gọn sau.

Công cụ tóm tắt văn bản

Công cụ này nhận vào một user_id và đoạn văn bản cần tóm tắt, sau đó trả về đoạn văn bản đã tóm tắt. Thổ Thần sẽ sử dụng mô hình mặc định của workspace hiện tại để tóm tắt đoạn văn bản dài.

    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
        """

Công cụ thu thập thông tin từ trang web

Công cụ này nhận vào một liên kết trang web để thu thập và một user_agent (có thể để trống), và trả về một chuỗi chứa thông tin của trang web đó. user_agent là một tham số tùy chọn có thể được sử dụng để nhận dạng công cụ. Nếu không được truyền vào, Thổ Thần sẽ sử dụng user_agent mặc định.

    def get_url(self, url: str, user_agent: str = None) -> str:
        """
            get url
        """ the crawled result

Biến

Chúng ta đã giới thiệu biến (variable pool) trong Tool để lưu trữ các biến, tệp,... được tạo ra trong quá trình vận hành công cụ. Những biến này có thể được sử dụng bởi các công cụ khác trong quá trình vận hành.

Tiếp theo, chúng ta sẽ sử dụng DallE3 và Vectorizer.AI làm ví dụ để giới thiệu cách sử dụng biến nhớ.

DallE3 là một công cụ tạo hình ảnh có thể tạo ra hình ảnh dựa trên văn bản. Ở đây, chúng ta sẽ sử dụng DallE3 để tạo ra logo cho cửa hàng cà phê.
Vectorizer.AI là một công cụ chuyển đổi hình ảnh vector, có thể chuyển đổi hình ảnh thành hình ảnh vector sao cho hình ảnh có thể được phóng to vô tận mà không bị biến dạng. Ở đây, chúng ta sẽ chuyển đổi biểu trưng PNG được tạo bởi DallE3 thành một hình ảnh vector, để nó có thể thực sự được sử dụng bởi các nhà thiết kế.

DallE3

Đầu tiên, dùng DallE3. Sau khi tạo ảnh, chúng ta lưu ảnh vào variable pool. Code như sau:

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_paramters: Dict[str, Any], 
        ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
        """
            invoke tools
        """
        client = OpenAI(
            api_key=self.runtime.credentials['openai_api_key'],
        )

        # prompt
        prompt = tool_paramters.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

Lưu ý rằng chúng tôi đã sử dụng self.VARIABLE_KEY.IMAGE.value như là tên biến của hình ảnh. Để các công cụ của nhà phát triển có thể hợp tác với nhau, chúng tôi đã định nghĩa KEY này. Bạn có thể sử dụng nó tự do, hoặc bạn có thể chọn không sử dụng KEY này. Việc truyền một KEY tùy chỉnh cũng được chấp nhận.

Vectorizer.AI

Tiếp theo, chúng ta sử dụng Vectorizer.AI để chuyển đổi biểu tượng PNG được tạo bởi DallE3 thành hình ảnh vector. Hãy cùng xem qua các hàm mà chúng ta đã định nghĩa ở đây. Code như sau:

from core.tools.tool.builtin_tool import BuiltinTool
from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParamter
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_paramters: 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[ToolParamter]:
        """
        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_avaliable(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
        """

Tiếp theo, hãy triển khai ba functions.

from core.tools.tool.builtin_tool import BuiltinTool
from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParamter
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_paramters: 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_paramters.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[ToolParamter]:
        """
        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 [
            ToolParamter.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=ToolParamter.ToolParameterType.SELECT,
                required=True,
                options=[i.name for i in self.list_default_image_variables()]
            )
        ]
    
    def is_tool_avaliable(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

Lưu ý rằng chúng ta thực tế không sử dụng image_id ở đây. Chúng ta giả định rằng phải có một hình ảnh trong variable pool mặc định khi gọi công cụ này, do đó chúng ta trực tiếp sử dụng image_binary = self.get_variable_file(self.VARIABLE_KEY.IMAGE) để lấy hình ảnh. Trong các trường hợp mà khả năng của mô hình yếu, chúng tôi khuyến nghị các nhà phát triển cũng làm như vậy, điều này có thể cải thiện đáng kể tính chịu lỗi và tránh việc mô hình truyền tham số sai.

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

Last updated 4 months ago