Documentação Oficial da API de Function Calling

Este endpoint é usado para criar um Chat Completion (Preenchimento de Chat). Ao fornecer uma lista de mensagens e uma lista opcional de ferramentas (Functions), o modelo pode gerar uma resposta em texto ou gerar argumentos que correspondam a um esquema JSON específico para chamar uma função externa.

1. Informações da API

• URL do Endpoint: https://api.codingplanx.ai/v1/chat/completions
• Método HTTP: POST
• Content-Type: application/json
• Autenticação: Authorization: Bearer {{YOUR_API_KEY}}

2. Parâmetros da Requisição

2.1 Cabeçalhos (Headers)

2.2 Corpo da Requisição (Body)

---

3. Exemplo de Requisição

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "Como está o clima em Pequim hoje?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Obtém o clima atual de um local especificado",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "Nome da cidade, por exemplo: Pequim"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

---

4. Parâmetros de Resposta

4.1 Estrutura do Corpo da Resposta

4.2 Exemplo de Resposta (Texto Normal)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "O clima em Pequim está ensolarado hoje, com temperatura de 25 graus Celsius."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

5. FAQs (Perguntas Frequentes)

Q1: O que é Function Calling (Chamada de Função)? R: É uma maneira de dar ao modelo a capacidade de acessar recursos externos. O modelo não executa o código diretamente; em vez disso, com base na sua descrição, ele gera um objeto JSON contendo o nome da função e os argumentos necessários. Você precisa extrair este JSON, executar a função localmente ou no seu servidor e, em seguida, retornar o resultado para o modelo.

Q2: Por que configurei as ferramentas (tools), mas o modelo não retornou tool_calls? R: Pode haver os seguintes motivos:

1. O modelo considera que a pergunta do usuário não requer a chamada da função.
2. A descrição da sua função (description) não é clara o suficiente, fazendo com que o modelo não consiga corresponder à intenção.
3. O tool_choice foi definido explicitamente como none.
4. Limitações do modelo (recomenda-se priorizar modelos como gpt-4o ou gpt-3.5-turbo que suportam nativamente a chamada de funções).

Q3: Como forçar o modelo a chamar uma função específica? R: Você pode definir tool_choice para um objeto específico, por exemplo: "tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}. Dessa forma, mesmo que o modelo ache desnecessário, ele tentará gerar os argumentos para essa função.

Q4: O que devo fazer se o finish_reason for length? R: Isso significa que a resposta gerada excedeu o limite de max_tokens ou o limite da janela de contexto (context window) do modelo. Você pode tentar aumentar o parâmetro max_tokens ou reduzir o tamanho do histórico das messages.

Q5: Quais são os cuidados ao usar o Modo JSON (JSON Mode)? R: Ao definir response_format: { "type": "json_object" }, é obrigatório instruir explicitamente o modelo na mensagem do tipo System ou User para produzir conteúdo no formato JSON (por exemplo, incluindo "responda em formato JSON"). Caso contrário, o modelo pode entrar em um loop infinito produzindo espaços em branco.

Q6: Como lidar com múltiplas chamadas de ferramentas (Multiple Tool Calls)? R: Em uma única requisição, o modelo pode gerar várias chamadas de ferramentas simultaneamente (por exemplo, consultar o clima em Pequim e Xangai ao mesmo tempo). Você precisa iterar sobre o array choices[0].message.tool_calls e executar a lógica local correspondente para cada chamada.