Pular para o conteúdo principal

​
Cenários de uso

O recurso Function Calling permite que o modelo interaja com ferramentas externas para obter informações em tempo real ou executar operações específicas. Esse recurso aumenta a precisão dos dados e expande as capacidades do modelo, permitindo que ele deixe de ser apenas um gerador simples de texto e passe a oferecer suporte a cenários de aplicação mais dinâmicos e práticos. Exemplos de cenários de uso de Function Calling:
  • Consulta de informações dinâmicas: chame APIs para obter dados dinâmicos em tempo real de sistemas externos, como clima, notícias e cotações de ações. Por exemplo, ao chamar uma API de clima para obter informações meteorológicas em tempo real, quando o usuário pergunta sobre o clima atual, o modelo pode informar as condições climáticas do momento, em vez de fornecer uma previsão desatualizada.
  • Automação de tarefas e operações: execute operações específicas por meio de chamadas de função, permitindo que o usuário acione operações automatizadas no backend por meio da conversa. Por exemplo, ao chamar a API de um site de venda de ingressos para reservar entradas, quando o usuário pergunta como comprar ingressos para uma atração, o modelo não apenas explica como comprar, mas também pode ajudar o usuário a concluir diretamente a operação de reserva.

​
Modelos compatíveis

Os modelos abaixo são compatíveis com Function Calling:

​
Como usar

  1. Defina as funções de ferramenta que o modelo chamará.
  2. Adicione o parâmetro tools à requisição para definir as funções que o modelo usará.

​
Exemplo de uso

A seguir, fornecemos um exemplo completo de código Python usando a consulta do clima atual de um local como exemplo para demonstrar como usar Function Calling. Para o formato específico da API de Function Calling, consulte a API de criação de requisição de conversa por chat.

​
1. Inicializar o cliente

Você precisa inicializar o cliente usando sua chave de API da JieKou AI. 
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.highwayapi.ai/openai",
    api_key="<Your API Key>",
)

model = "deepseek/deepseek-v3"

​
2. Definir a função a ser chamada

Defina a função que o modelo chamará. O exemplo em Python abaixo demonstra uma função para obter informações meteorológicas. 
# Função de exemplo para simular a obtenção de dados meteorológicos.
def get_weather(location):
    """Obtém o clima atual do local especificado"""
    print("Chamando a função get_weather, local: ", location)
    # Em uma aplicação real, você precisará chamar uma API externa de clima aqui.
    # Este é um exemplo simplificado que retorna dados codificados.
    return json.dumps({"位置": location, "温度": "20 graus Celsius"})

​
3. Construir a requisição da API que inclui ferramentas e a mensagem do usuário

Crie uma requisição de chamada da API. Essa requisição inclui o parâmetro tools, que define as funções que o modelo usará, além da mensagem do usuário. 
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Obtém o clima de um local; o usuário deve primeiro fornecer o local",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Informações da cidade, por exemplo: Xangai",
                    }
                },
                "required": ["location"]
            },
        }
    },
]
messages = [
    {
        "role": "user",
        "content": "Como está o clima em Xangai?"
    }
]
# Envia a requisição e imprime a resposta
response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
)
# Em produção, verifique se a resposta contém uma chamada de ferramenta
tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.model_dump())
Saída: 
{'id': '0', 'function': {'arguments': '{"location": "Xangai"}', 'name': 'get_weather'}, 'type': 'function'}

​
4. Responder com base no resultado da chamada de função e obter a resposta final

Em seguida, processe a chamada de função, execute a função get_weather e envie o resultado de volta ao modelo para gerar a resposta final ao usuário. 
# Certifique-se de que a chamada de ferramenta foi definida na etapa anterior
if tool_call:
    # Estende o histórico da conversa adicionando a mensagem de chamada de ferramenta do assistente
    messages.append(response.choices[0].message)

    function_name = tool_call.function.name
    if function_name == "get_weather":
        function_args = json.loads(tool_call.function.arguments)
        # Executa a função e obtém a resposta
        function_response = get_weather(
            location=function_args.get("location"))
        # Adiciona a resposta da função às mensagens
        messages.append(
            {
                "tool_call_id": tool_call.id,
                "role": "tool",
                "content": function_response,
            }
        )

    # Obtém a resposta final do modelo, incluindo o resultado da função
    answer_response = client.chat.completions.create(
        model=model,
        messages=messages,
        # Observação: não inclua o parâmetro tools aqui
    )
    print(answer_response.choices[0].message)
Saída: 
ChatCompletionMessage(content="Atualmente, a temperatura em Xangai é de 20 graus Celsius. Observe que as condições climáticas podem mudar a qualquer momento; recomendamos consultar a previsão do tempo mais recente para obter informações mais precisas.", refusal=None, role='assistant', function_call=None, tool_calls=None)

​
Código completo

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.highwayapi.ai/openai",
    api_key="<Your API Key>",
)

model = "deepseek/deepseek-v3"

# Função de exemplo para simular a obtenção de dados meteorológicos.
def get_weather(location):
    """Obtém o clima atual do local especificado"""
    print("Chamando a função get_weather, local: ", location)
    # Em uma aplicação real, você precisará chamar uma API externa de clima aqui.
    # Este é um exemplo simplificado que retorna dados codificados.
    return json.dumps({"位置": location, "温度": "20 graus Celsius"})

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Obtém o clima de um local; o usuário deve primeiro fornecer o local",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Informações da cidade, por exemplo: Xangai",
                    }
                },
                "required": ["location"]
            },
        }
    },
]

messages = [
    {
        "role": "user",
        "content": "Como está o clima em Xangai?"
    }
]

# Envia a requisição e imprime a resposta
response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
)

# Em produção, verifique se a resposta contém uma chamada de ferramenta
tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.model_dump())

# Certifique-se de que a chamada de ferramenta foi definida na etapa anterior
if tool_call:
    # Estende o histórico da conversa adicionando a mensagem de chamada de ferramenta do assistente
    messages.append(response.choices[0].message)

    function_name = tool_call.function.name
    if function_name == "get_weather":
        function_args = json.loads(tool_call.function.arguments)
        # Executa a função e obtém a resposta
        function_response = get_weather(
            location=function_args.get("location"))
        # Adiciona a resposta da função às mensagens
        messages.append(
            {
                "tool_call_id": tool_call.id,
                "role": "tool",
                "content": function_response,
            }
        )

    # Obtém a resposta final do modelo, incluindo o resultado da função
    answer_response = client.chat.completions.create(
        model=model,
        messages=messages,
        # Observação: não inclua o parâmetro tools aqui
    )
    print(answer_response.choices[0].message)