Chamada de função no Azure Databricks

Este artigo descreve a chamada de função e como usá-la como parte de fluxos de trabalho de aplicativos de IA generativa. A Chamada de Função do Databricks é compatível com o OpenAI e só está disponível durante a disponibilização do modelo como parte das APIs do Modelo de Base e nos pontos de extremidade que atendem aos modelos externos.

O que é a chamada de função?

A chamada de função consiste em uma forma de controlar a saída dos LLMs, para que eles gerem respostas estruturadas de modo mais confiável. Ao usar uma chamada de função, você descreve funções na chamada de API descrevendo os argumentos da função com um esquema JSON. O LLM em si não chama essas funções, mas cria um objeto JSON que os usuários podem usar para chamá-las.

Para chamadas de função no Databricks, a sequência básica de etapas é a seguinte:

1. Chame o modelo usando a consulta enviada e um conjunto de funções definidas no parâmetro tools.
2. O modelo decide se deve ou não chamar as funções definidas. Quando a função é chamada, o conteúdo é um objeto JSON de cadeias de caracteres que adere ao esquema personalizado.
3. Analise as cadeias de caracteres em JSON no código e chame a função com os argumentos fornecidos, se houver.
4. Chame o modelo novamente anexando a resposta estruturada como uma nova mensagem. A estrutura da resposta é definida pelas funções que você forneceu anteriormente em tools. Aqui, o modelo resume os resultados e envia esse resumo ao usuário.

Quando usar a chamada de função

Veja alguns exemplos de casos de uso para a chamada de função:

• Crie assistentes que respondam perguntas chamando outras APIs. Por exemplo, é possível definir funções como send_email(to: string, body: string) ou current_weather(location: string, unit: 'celsius' | 'fahrenheit').
• Defina e use chamadas de API baseadas em linguagem natural. Por exemplo, usar a instrução “Quem são meus principais clientes?” e transformá-la em uma chamada à API chamada get_customers(min_revenue: int, created_before: string, limit: int) e chamar essa API.

Para inferência em lote ou tarefas de processamento de dados, como converter dados não estruturados em dados estruturados. O Databricks recomenda o uso de saídas estruturadas.

Modelos com suporte

A tabela a seguir lista os modelos com suporte e qual recurso do Serviço de Modelo disponibiliza cada modelo. Consulte as licenças e os termos do desenvolvedor de modelo aplicável para esses modelos.

• Para ver os modelos disponibilizados pelas APIs do Modelo de Base, veja Limites das APIs do Modelo de Base para saber a disponibilidade de região.
• Para modelos disponibilizados por modelos externos, veja Disponibilidade de região para saber a disponibilidade de região.

Usar a chamada de função

Para usar a chamada de função com seu aplicativo de IA generativa, você deve fornecer a função parameters e um description.

O comportamento padrão para tool_choice é "auto". Isso permite que o modelo decida quais funções chamar e se deve chamá-las.

É possível personalizar o comportamento padrão de acordo com o caso de uso. Estas são as opções:

• Defina tool_choice: "required". Neste cenário, o modelo sempre chama uma ou mais funções. O modelo seleciona as funções que serão chamadas.
• Defina tool_choice: {"type": "function", "function": {"name": "my_function"}}. Neste cenário, o modelo chama somente uma função específica.
• Configure tool_choice: "none" para desabilitar a chamada de função e fazer com que o modelo gere somente uma mensagem voltada ao usuário.

Confira a seguir um exemplo de turno único usando o SDK do OpenAI e o parâmetro tools. Consulte a API de Conclusões de Chat para obter detalhes adicionais de sintaxe.

import os
import json
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('YOUR_DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('YOUR_DATABRICKS_BASE_URL')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url=DATABRICKS_BASE_URL
  )

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_current_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": [
              "celsius",
              "fahrenheit"
            ]
          }
        }
      }
    }
  }
]

messages = [{"role": "user", "content": "What is the current temperature of Chicago?"}]

response = client.chat.completions.create(
    model="databricks-meta-llama-3-3-70b-instruct",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

print(json.dumps(response.choices[0].message.model_dump()['tool_calls'], indent=2))

Esse parâmetro também dá suporte ao Uso do Computador (beta) para modelos Claude.

Esquema JSON

As APIs do modelo de base oferecem amplo suporte às definições de funções aceitas pelo OpenAI. No entanto, usar um esquema JSON mais simples para definições de chamadas de função resulta na geração de JSON de chamadas de função de maior qualidade. Para promover uma geração de maior qualidade, as APIs do modelo de base só dão suporte a um subconjunto de especificações de esquema JSON.

As seguintes chaves de definição de chamada de função não têm suporte:

• Expressões regulares que usam pattern.
• Composição e validação de esquema complexo e aninhado que usam: anyOf, oneOf, allOf, prefixItems ou $ref.
• Listas de tipos, exceto para o caso especial de [type, “null”], em que um tipo na lista é um tipo JSON válido e o outro é "null"

Além disso, aplicam-se as seguintes limitações:

• O número máximo de chaves especificadas no esquema JSON é 16.
• As APIs do modelo de base não impõem restrições de comprimento ou tamanho para objetos e matrizes.
  • Isso inclui palavras-chave como maxProperties, minProperties e maxLength.
• Os esquemas JSON altamente aninhados resultam em geração de qualidade inferior. Se possível, tente simplificar o esquema JSON para obter melhores resultados.

Uso de token

A injeção de solicitação e outras técnicas são usadas para aprimorar a qualidade das chamadas de ferramenta. Isso afeta o número de tokens de entrada e saída consumidos pelo modelo, o que resulta em implicações na cobrança. Quanto mais ferramentas você usar, mais os tokens de entrada aumentarão.

Limitações

Confira a seguir as limitações para chamadas de funções durante a versão preliminar pública:

• Para chamadas de função de múltiplos turnos, a Databricks recomenda os modelos Claude compatíveis.
• Se estiver usando o Llama 4 Maverick, a solução de chamada de função atual está otimizada para chamadas de função de turno único. A chamada de função multivoltas é compatível durante a visualização, mas está em desenvolvimento.
• Não há suporte para chamadas de função paralela.
• O número máximo de funções que podem ser definidas em tools é 32.
• No caso do suporte à taxa de transferência provisionada, só há suporte para chamadas de função em novos pontos de extremidade. Não é possível adicionar chamadas de função a pontos de extremidade criados anteriormente.

Exemplo de notebook

Confira o seguinte notebook para analisar exemplos detalhados de chamadas de função

Exemplo de notebook de chamada de função

Obter notebook