---
title: Ferramenta de Dados Externos
slug: inQs-ferramenta-de-dados-externos
createdAt: 2024-09-02T19:10:15.985Z
---

As ferramentas de dados externos são usadas para buscar dados adicionais de fontes externas após o usuário final enviar os dados e, em seguida, montar esses dados em prompts como informações contextuais adicionais para o LLM. O Paragraph fornece uma ferramenta padrão para chamadas de API externas, confira a Extensão Baseada em API para detalhes.

Para desenvolvedores que implantam o Paragraph localmente, para atender a necessidades mais personalizadas ou para evitar o desenvolvimento de um servidor de API adicional, você pode inserir diretamente a lógica personalizada da ferramenta de dados externos na forma de um plugin baseado no serviço do Paragraph. Após estender ferramentas personalizadas, suas opções de ferramentas personalizadas serão adicionadas à lista de tipos de ferramentas disponíveis, e os membros da equipe poderão usar essas ferramentas personalizadas para buscar dados externos.

**Início Rápido**
Aqui está um exemplo de como estender uma ferramenta de dados externos para Busca de Clima, com os seguintes passos:

**1.Inicializar o Diretório**
Para adicionar um tipo personalizado "Busca de Clima", você precisa criar o diretório e os arquivos relevantes em `api/core/external_data_tool`.

```text
.
└── api
    └── core
        └── external_data_tool
            └── weather_search
                ├── __init__.py
                ├── weather_search.py
                └── schema.json
```

2.**Adicionar Especificações de Componentes de Frontend**
O arquivo `schema.json` define as especificações dos componentes de frontend, detalhado em Extensão Baseada em Código.

```json
{
    "label": {
        "en-US": "Weather Search"
    },
    "form_schema": [
        {
            "type": "select",
            "label": {
                "en-US": "Temperature Unit"
            },
            "variable": "temperature_unit",
            "required": true,
            "options": [
                {
                    "label": {
                        "en-US": "Fahrenheit"
                    },
                    "value": "fahrenheit"
                },
                {
                    "label": {
                        "en-US": "Centigrade"
                    },
                    "value": "centigrade"
                }
            ],
            "default": "centigrade",
            "placeholder": "Please select temperature unit"
        }
    ]
}
```

**3.Adicionar Classe de Implementação**
Template de código `weather_search.py`, onde você pode implementar a lógica de negócios específica.

:::hint{type="warning"}
Nota: O nome da variável da classe deve ser o nome do tipo personalizado, consistente com o nome do diretório e do arquivo, e deve ser único.
:::

```python
from typing import Optional
from core.external_data_tool.base import ExternalDataTool

class WeatherSearch(ExternalDataTool):
    """
    O nome do tipo personalizado deve ser único, mantendo o mesmo nome do diretório e do arquivo.
    """
    name: str = "weather_search"

    @classmethod
    def validate_config(cls, tenant_id: str, config: dict) -> None:
        """
        Validação do schema.json. Será chamado quando o usuário salvar a configuração.

        Exemplo:
            config = {
                "temperature_unit": "centigrade"
            }

        :param tenant_id: id do workspace
        :param config: variáveis do formulário de configuração
        :return:
        """
        if não houver config.get('temperature_unit'):
            raise ValueError('temperature unit is required')

    def query(self, inputs: dict, query: Optional[str] = None) -> str:
        """
        Consulta a ferramenta de dados externos.

        :param inputs: entradas do usuário
        :param query: a consulta do aplicativo de chat
        :return: o resultado da consulta da ferramenta
        """
        city = inputs.get('city')
        temperature_unit = self.config.get('temperature_unit')

        if temperature_unit == 'fahrenheit':
            return f'Tempo em {city} é 32°F'
        else:
            return f'Tempo em {city} é 0°C'
```

**4.Depurar a Extensão**
Agora, você pode selecionar o tipo de extensão de ferramenta de dados externos "Busca de Clima" personalizado na interface de orquestração do aplicativo do Paragraph para depuração.

**Template de Classe de Implementação**

```python
from typing import Optional
from core.external_data_tool.base import ExternalDataTool

class WeatherSearch(ExternalDataTool):
    """
    O nome do tipo personalizado deve ser único, mantendo o mesmo nome do diretório e do arquivo.
    """
    name: str = "weather_search"

    @classmethod
    def validate_config(cls, tenant_id: str, config: dict) -> None:
        """
        Validação do schema.json. Será chamado quando o usuário salvar a configuração.

        :param tenant_id: id do workspace
        :param config: variáveis do formulário de configuração
        :return:
        """
        # implemente sua própria lógica aqui

    def query(self, inputs: dict, query: Optional[str] = None) -> str:
        """
        Consulta a ferramenta de dados externos.

        :param inputs: entradas do usuário
        :param query: a consulta do aplicativo de chat
        :return: o resultado da consulta da ferramenta
        """
        # implemente sua própria lógica aqui
        return "seus próprios dados."
```

**Introdução Detalhada ao Desenvolvimento de Classe de Implementação**

- `validate_config`: Método de validação do formulário `schema.json`, chamado quando o usuário clica em "Publicar" para salvar a configuração.
- Parâmetros de formulário `config`:
  - `{{variable}}`: Variáveis personalizadas do formulário.
- `query`: Implementação da consulta de dados definida pelo usuário, o resultado retornado será substituído na variável especificada.
  - `inputs`: Variáveis passadas pelo usuário final.
  - `query`: Conteúdo atual da conversa do usuário final, um parâmetro fixo para aplicações de conversação.