Recursos Avançados

Criando Ferramentas com Python

A Deepze permite a criação de ferramentas personalizadas em Python que podem ser utilizadas pelos modelos de IA para executar ações e obter informações adicionais em tempo real.

O que são Ferramentas?

Ferramentas são scripts Python fornecidos ao modelo de IA no momento da solicitação. Elas permitem que os modelos executem ações e recebam contexto adicional como resultado. Em geral, seu modelo de IA precisa suportar chamadas de função (function calling) para que as ferramentas sejam utilizadas de forma confiável.

As ferramentas habilitam diversos casos de uso, incluindo:

• Busca na web em tempo real
• Extração de dados de páginas web (web scraping)
• Interações com APIs externas
• Consultas a bancos de dados

Como usar Ferramentas

Para usar uma ferramenta, siga estes passos:

1. Navegue até Espaço de Trabalho => Modelos
2. Selecione o modelo de IA que deseja configurar (precisa suportar function calling)
3. Clique no ícone de lápis para editar as configurações do modelo
4. Role até a seção "Ferramentas" e marque as ferramentas que deseja habilitar
5. Clique em "Salvar" para aplicar as alterações

Uma vez habilitadas, você pode acessar as ferramentas clicando no ícone "+" durante uma conversa com o modelo. Importante notar que habilitar uma ferramenta não força seu uso - apenas disponibiliza essa opção para o modelo.

Interface de uso de ferramentas no chat

Instalação de Ferramentas

Existem duas maneiras de instalar ferramentas na plataforma:

Interface do editor de ferramentas Python

Escrevendo uma Ferramenta Personalizada

As ferramentas são definidas em um único arquivo Python, com uma docstring de nível superior contendo metadados e uma classe Tools.

"""
title: Inversor de String
author: Seu Nome
author_url: https://seusite.com
git_url: https://github.com/seunome/string-reverse.git
description: Esta ferramenta calcula o inverso de uma string
version: 1.0.0
licence: MIT
requirements: requests, pandas
"""

class Tools:
    def __init__(self):
        """Inicializa a Ferramenta."""
        self.valves = self.Valves()

    class Valves(BaseModel):
        api_key: str = Field("", description="Sua chave de API")

    def inverter_string(self, texto: str) -> str:
        """
        Inverte a string de entrada.
        :param texto: A string para inverter
        """
        # exemplo de uso de válvulas
        if self.valves.api_key != "42":
            return "Chave de API incorreta"
        return texto[::-1]

Componentes importantes de uma ferramenta personalizada:

• Docstring de nível superior: Contém metadados como título, autor, descrição e requisitos
• Classe Tools: Contém todos os métodos que serão expostos como ferramentas
• Type Hints: Cada método deve ter anotações de tipo para seus argumentos
• Valves: Subclasse opcional para configurações administradas apenas por administradores
• UserValves: Subclasse opcional para configurações que qualquer usuário pode modificar

Event Emitters

Os emissores de eventos (Event Emitters) permitem adicionar informações adicionais à interface de chat durante a execução da ferramenta:

• Status: Mostra mensagens de status durante o processamento da ferramenta
• Message: Adiciona mensagens ao chat a qualquer momento durante a execução
• Citation: Fornece citações ou referências no chat

Exemplo de ferramenta com API externa:

def buscar_cliente(id_cliente):
    """
    Busca informações de um cliente pelo ID
    
    Args:
        id_cliente (str): O identificador único do cliente
        
    Returns:
        dict: Dados do cliente ou mensagem de erro
    """
    import requests
    
    # Configuração da API interna (exemplo)
    API_URL = "https://api.interna.suaempresa.com/clientes"
    API_KEY = os.environ.get("API_KEY_INTERNA")
    
    try:
        # Fazendo a requisição à API interna
        response = requests.get(
            f"{API_URL}/{id_cliente}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 404:
            return {"erro": "Cliente não encontrado"}
        else:
            return {"erro": f"Erro na API: {response.status_code}"}
            
    except Exception as e:
        return {"erro": f"Exceção: {str(e)}"}
                    

Pacotes Externos

Você pode especificar dependências externas na seção de metadados da ferramenta. Quando você salva, a plataforma executará pip install para todas as dependências listadas:

"""
title: MinhaFerramenta
author: Meu Nome
version: 1.0.0
license: GPLv3
description: Uma descrição da minha ferramenta
requirements: requests>=2.28.0,pandas,beautifulsoup4
"""

Funções Pipe: Criando Modelos Personalizados

As Pipe Functions permitem criar modelos personalizados na plataforma Deepze, adicionando lógica customizada e processamento específico para suas necessidades.

Introdução às Pipe Functions

Imagine a Deepze como um sistema de encanamento onde os dados fluem através de tubos e válvulas. Nessa analogia:

• Pipes são como plugins que permitem introduzir novos caminhos para o fluxo de dados, permitindo injetar lógica e processamento personalizados.
• Valves (Válvulas) são as partes configuráveis do seu pipe que controlam como os dados fluem através dele.

Ao criar um Pipe, você está essencialmente construindo um modelo personalizado com o comportamento específico que deseja, tudo dentro do framework da Deepze.

Estrutura Básica de um Pipe

Vamos começar com uma versão básica de um Pipe para entender sua estrutura:

from pydantic import BaseModel, Field

class Pipe:
    class Valves(BaseModel):
        MODEL_ID: str = Field(default="")

    def __init__(self):
        self.valves = self.Valves()

    def pipe(self, body: dict):
        # Lógica vai aqui
        print(self.valves, body)  # Isso imprimirá as opções de configuração e o corpo de entrada
        return "Olá, Mundo!"

Componentes Principais

def __init__(self):
    self.valves = self.Valves()

def pipe(self, body: dict):
    # Lógica vai aqui
    print(self.valves, body)  # Isso imprimirá as opções de configuração e o corpo de entrada
    return "Olá, Mundo!"

Criando Múltiplos Modelos com Pipes

Se você quiser que seu Pipe crie múltiplos modelos dentro da Deepze, você pode fazer isso definindo uma função ou variável pipes dentro da sua classe Pipe:

from pydantic import BaseModel, Field

class Pipe:
    class Valves(BaseModel):
        MODEL_ID: str = Field(default="")

    def __init__(self):
        self.valves = self.Valves()

    def pipes(self):
        return [
            {"id": "model_id_1", "name": "modelo_1"},
            {"id": "model_id_2", "name": "modelo_2"},
            {"id": "model_id_3", "name": "modelo_3"},
        ]

    def pipe(self, body: dict):
        # Lógica vai aqui
        print(self.valves, body)  # Imprime as opções de configuração e o corpo de entrada
        model = body.get("model", "")
        return f"{model}: Olá, Mundo!"

A função pipes retorna uma lista de dicionários, onde cada dicionário representa um modelo com chaves id e name únicas. Esses modelos aparecerão individualmente no seletor de modelos da Deepze.

Exemplo: Pipe de Proxy para API Externa

Vamos ver um exemplo prático onde criaremos um Pipe que funciona como proxy para uma API externa. Este Pipe buscará modelos disponíveis da API e permitirá que os usuários interajam com eles através da Deepze.

from pydantic import BaseModel, Field
import requests

class Pipe:
    class Valves(BaseModel):
        NAME_PREFIX: str = Field(
            default="API_EXTERNA/",
            description="Prefixo a ser adicionado antes dos nomes dos modelos.",
        )
        API_BASE_URL: str = Field(
            default="https://api.exemplo.com/v1",
            description="URL base para acessar os endpoints da API externa.",
        )
        API_KEY: str = Field(
            default="",
            description="Chave de API para autenticar requisições à API externa.",
        )

    def __init__(self):
        self.valves = self.Valves()

    def pipes(self):
        if self.valves.API_KEY:
            try:
                headers = {
                    "Authorization": f"Bearer {self.valves.API_KEY}",
                    "Content-Type": "application/json",
                }

                r = requests.get(
                    f"{self.valves.API_BASE_URL}/models", headers=headers
                )
                models = r.json()
                return [
                    {
                        "id": model["id"],
                        "name": f'{self.valves.NAME_PREFIX}{model.get("name", model["id"])}',
                    }
                    for model in models["data"]
                    if "gpt" in model["id"]
                ]

            except Exception as e:
                return [
                    {
                        "id": "error",
                        "name": "Erro ao buscar modelos. Verifique sua chave de API.",
                    },
                ]
        else:
            return [
                {
                    "id": "error",
                    "name": "Chave de API não fornecida.",
                },
            ]

    def pipe(self, body: dict, __user__: dict):
        print(f"pipe:{__name__}")
        headers = {
            "Authorization": f"Bearer {self.valves.API_KEY}",
            "Content-Type": "application/json",
        }

        # Extrair ID do modelo a partir do nome do modelo
        model_id = body["model"][body["model"].find(".") + 1 :]

        # Atualizar o ID do modelo no corpo
        payload = {**body, "model": model_id}
        try:
            r = requests.post(
                url=f"{self.valves.API_BASE_URL}/chat/completions",
                json=payload,
                headers=headers,
                stream=True,
            )

            r.raise_for_status()

            if body.get("stream", False):
                return r.iter_lines()
            else:
                return r.json()
        except Exception as e:
            return f"Erro: {e}"

Frequently Asked Questions

Funções Filter: Modificando Entradas e Saídas

As Filter Functions são um sistema de plugins flexível e poderoso para modificar dados antes de serem enviados ao modelo de IA (entrada) ou após serem retornados pelo modelo (saída).

O que são Filters na Deepze?

Imagine a Deepze como um fluxo de água correndo através de tubulações:

• As entradas do usuário e saídas do modelo são a água.
• Os Filters são os estágios de tratamento de água que limpam, modificam e adaptam a água antes que ela chegue ao destino final.

Os Filters ficam no meio do fluxo — como pontos de verificação — onde você decide o que precisa ser ajustado.

Estrutura de uma Filter Function

Vamos começar com a representação mais simples de uma Filter Function:

from pydantic import BaseModel
from typing import Optional

class Filter:
    # Valves: Opções de configuração para o filtro
    class Valves(BaseModel):  
        pass

    def __init__(self):
        # Inicializa valves (configuração opcional para o Filter)
        self.valves = self.Valves()

    def inlet(self, body: dict) -> dict:
        # Aqui é onde você manipula as entradas do usuário.
        print(f"inlet chamado: {body}")
        return body  

    def stream(self, event: dict) -> dict:
        # Aqui é onde você modifica fragmentos transmitidos da saída do modelo.
        print(f"evento stream: {event}")
        return event

    def outlet(self, body: dict) -> None:
        # Aqui é onde você manipula as saídas do modelo.
        print(f"outlet chamado: {body}")
        return body

Componentes Principais

class Valves(BaseModel):
    NOME_OPCAO: str = "Valor Padrão"

def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
    # Adicionar mensagem de sistema para contexto na conversa
    mensagem_contexto = {
        "role": "system",
        "content": "Você está ajudando o usuário a resolver problemas de software."
    }
    # Inserir o contexto no início do histórico de chat
    body.setdefault("messages", []).insert(0, mensagem_contexto)
    return body

def stream(self, event: dict) -> dict:
    for choice in event.get("choices", []):
        delta = choice.get("delta", {})
        if "content" in delta:
            delta["content"] = delta["content"].replace("😊", "")  # Remove emojis
    return event

def outlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
    for message in body["messages"]:
        message["content"] = message["content"].replace("", "[REDACTED]")
    return body

Filters em Ação: Exemplos Práticos

class Filter:
    def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
        mensagem_contexto = {
            "role": "system", 
            "content": "Você é um assistente de solução de problemas de software."
        }
        body.setdefault("messages", []).insert(0, mensagem_contexto)
        return body

class Filter:
    def outlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
        # Adicionar markdown de "destaque" para cada resposta
        for message in body["messages"]:
            if message["role"] == "assistant":  # Alvo: resposta do modelo
                message["content"] = f"**{message['content']}**"  # Destacar com Markdown
        return body

Frequently Asked Questions

API

A API da Deepze permite integrar os recursos de IA diretamente em suas aplicações e sistemas, oferecendo total flexibilidade para automação e integração com seu ecossistema tecnológico.

Autenticação

Para garantir o acesso seguro à API, a autenticação é obrigatória. Você pode autenticar suas requisições API usando o mecanismo Bearer Token:

• Obtenha sua chave API em Configurações > Conta na plataforma Deepze
• Inclua essa chave no cabeçalho de autorização de todas as requisições

curl -H "Authorization: Bearer SUA_CHAVE_API" https://nome_cliente.chat.deepze.ai/api/v1/models

Endpoints Principais

curl -H "Authorization: Bearer SUA_CHAVE_API" https://nome_cliente.chat.deepze.ai/api/v1/models

curl -X POST https://nome_cliente.chat.deepze.ai/api/v1/chat/completions \
-H "Authorization: Bearer SUA_CHAVE_API" \
-H "Content-Type: application/json" \
-d '{
      "model": "llm-grande",
      "messages": [
        {
          "role": "user",
          "content": "Por que o céu é azul?"
        }
      ]
    }'

import requests

def chat_com_modelo(token):
    url = 'https://nome_cliente.chat.deepze.ai/api/v1/chat/completions'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    data = {
      "model": "llm-grande",
      "messages": [
        {
          "role": "user",
          "content": "Por que o céu é azul?"
        }
      ]
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

Retrieval Augmented Generation (RAG)

O recurso RAG permite enriquecer as respostas incorporando dados de fontes externas. Veja como gerenciar arquivos e coleções de conhecimento via API:

curl -X POST -H "Authorization: Bearer SUA_CHAVE_API" -H "Accept: application/json" \
-F "file=@/caminho/para/seu/arquivo" https://nome_cliente.chat.deepze.ai/api/v1/files/

curl -X POST https://nome_cliente.chat.deepze.ai/api/v1/knowledge/{knowledge_id}/file/add \
-H "Authorization: Bearer SUA_CHAVE_API" \
-H "Content-Type: application/json" \
-d '{"file_id": "seu-file-id-aqui"}'

curl -X POST https://nome_cliente.chat.deepze.ai/api/v1/chat/completions \
-H "Authorization: Bearer SUA_CHAVE_API" \
-H "Content-Type: application/json" \
-d '{
      "model": "llm-grande",
      "messages": [
        {"role": "user", "content": "Forneça insights sobre as perspectivas históricas abordadas na coleção."}
      ],
      "files": [
        {"type": "collection", "id": "seu-collection-id-aqui"}
      ]
    }'

Vantagens da API Deepze

A API Deepze oferece diversos benefícios:

• Interface unificada: Simplifique suas interações com diferentes modelos de IA
• Fácil implementação: Integração rápida com documentação abrangente
• Compatibilidade com padrões OpenAI: Facilita migração de código existente
• Controle de segurança: Gerenciamento granular de permissões e tokens