Chamada de função no Azure Databricks

Este artigo descreve a chamada de função e como usá-la como parte de seus fluxos de trabalho de aplicativos de IA generativos. O Databricks Function Calling é compatível com OpenAI e só está disponível durante a disponibilização do modelo como parte das APIs do Modelo de Fundação e dos endpoints de serviço que disponibilizam modelos externos .

O que é chamada de função?

O uso de chamadas de função permite que você controle a saída dos LLMs, garantindo que gerem respostas estruturadas de forma mais confiável. Ao usar uma chamada de função, você descreve funções na chamada de API descrevendo os argumentos de função usando 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 chamar as funções em seu código.

Para a chamada 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 seu esquema personalizado.
3. Analise as cadeias de caracteres em JSON em seu código e chame sua função com os argumentos fornecidos, se eles existirem.
4. Chame o modelo novamente anexando a resposta estruturada como uma nova mensagem. A estrutura da resposta é definida pelas funções fornecidas anteriormente em tools. A partir daqui, o modelo resume os resultados e envia esse resumo para o usuário.

Quando usar a chamada de função

A seguir estão exemplos de casos de uso para chamada de função:

• Crie assistentes que possam responder a perguntas chamando outras APIs. Por exemplo, você pode definir funções como send_email(to: string, body: string) ou current_weather(location: string, unit: 'celsius' | 'fahrenheit').
• Defina e use chamadas de API com base em linguagem natural. Como tomar a afirmação: "Quem são meus principais clientes?" e transformar isso em uma chamada de API com o nome 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 suportados

A tabela a seguir lista os modelos suportados e qual característica de serviço de modelo disponibiliza cada modelo. Consulte Licenças e termos aplicáveis para desenvolvedores de modelos para esses modelos.

• Para modelos disponibilizados por APIs de Modelo Fundamental, consulte Limites de APIs de Modelo Fundamental para disponibilidade por região.
• Para modelos disponibilizados por fontes externas, consulte Disponibilidade regional para verificar a disponibilidade por região.

Usar chamada de função

Para usar a chamada de função com o seu aplicativo de IA generativa, 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.

Você pode personalizar o comportamento padrão dependendo do seu caso de uso. As suas opções são as seguintes:

• Defina tool_choice: "required". Nesse cenário, o modelo sempre chama uma ou mais funções. O modelo seleciona a função ou funções a chamar.
• Defina tool_choice: {"type": "function", "function": {"name": "my_function"}}. Nesse cenário, o modelo chama apenas uma função específica.
• Defina tool_choice: "none" para desativar a chamada de função e fazer com que o modelo gere apenas uma mensagem voltada para o usuário.

A seguir está um exemplo de turno único usando o OpenAI SDK e seu tools parâmetro. Consulte a API Chat Completions para detalhes adicionais da 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))

Este parâmetro também suporta Uso do Computador (beta) para modelos Claude.

Esquema JSON

As APIs do Modelo de Base suportam amplamente as definições de função aceitas pela OpenAI. No entanto, o uso de um esquema JSON mais simples para definições de chamada de função resulta na geração JSON de chamada de função de maior qualidade. Para promover a geração de maior qualidade, as APIs do Foundation Model suportam apenas um subconjunto de especificações de esquema JSON.

As seguintes teclas de definição de chamada de função não são suportadas:

• Expressões regulares usando pattern.
• Composição e validação aninhadas complexas ou de esquema usando: anyOf, oneOf, allOf, prefixItems, ou $ref.
• Listas de tipos, exceto no 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 especificado 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, minPropertiese maxLength.
• Esquemas JSON fortemente aninhados resultam em geração de menor qualidade. Se possível, tente nivelar o esquema JSON para obter melhores resultados.

Uso de token

A injeção de prompt e outras técnicas são usadas para melhorar a qualidade das chamadas de ferramentas. Isso afeta o número de tokens de entrada e saída consumidos pelo modelo, o que, por sua vez, resulta em implicações de faturamento. Quanto mais ferramentas utilizares, mais aumentarão os teus tokens de entrada.

Limitações

A seguir estão as limitações para chamadas de função durante a Visualização Pública:

• Para chamadas de função multi-turno, a Databricks recomenda os modelos Claude suportados.
• Se estiver usando o Llama 4 Maverick, a solução atual de chamada de função é otimizada para chamadas de função de turno único. A chamada de função multiturno é suportada durante o teste, 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 funções.
• Para suporte de throughput provisionado, a chamada de função é suportada apenas em novos endpoints. Não é possível adicionar chamadas de funções a endpoints criados anteriormente.

Exemplo de bloco de notas

Consulte o bloco de anotações a seguir para obter exemplos detalhados de chamada de função

Exemplo de bloco de anotações de chamada de função

Obter portátil