Documentación Oficial de la API de Function Calling

Este endpoint se utiliza para crear un completado de chat (Chat Completion). Al proporcionar una lista de mensajes y una lista opcional de herramientas (Functions), el modelo puede generar una respuesta de texto o generar parámetros que cumplan con un esquema JSON específico para llamar a funciones externas.

1. Información del Endpoint

• URL de la API: https://api.codingplanx.ai/v1/chat/completions
• Método HTTP: POST
• Content-Type: application/json
• Método de Autenticación: Authorization: Bearer {{YOUR_API_KEY}}

2. Parámetros de la Solicitud

2.1 Encabezados (Headers)

2.2 Cuerpo de la Solicitud (Body)

---

3. Ejemplo de Solicitud

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "¿Cómo está el clima hoy en Pekín?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Obtiene el clima actual de una ubicación especificada",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "Nombre de la ciudad, por ejemplo: Pekín"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

---

4. Parámetros de Respuesta

4.1 Estructura del Cuerpo de Respuesta

4.2 Ejemplo de Respuesta (Texto Normal)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "El clima hoy en Pekín está soleado, con una temperatura de 25 grados Celsius."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

5. FAQs (Preguntas Frecuentes)

Q1: ¿Qué es Function Calling (Llamada a Funciones)? R: Es un mecanismo que permite al modelo interactuar con herramientas externas. El modelo no ejecuta código directamente; en su lugar, basándose en la descripción que le proporcionas, genera un objeto JSON que contiene el nombre de la función y los parámetros requeridos. Tú debes extraer este JSON, ejecutar la función localmente o en tu servidor, y luego devolver los resultados al modelo.

Q2: ¿Por qué configuré tools, pero el modelo no devuelve tool_calls? R: Puede deberse a las siguientes razones:

1. El modelo considera que la pregunta del usuario no requiere llamar a esa función.
2. La descripción de tu función (description) no es lo suficientemente clara, lo que impide al modelo identificar la intención.
3. El parámetro tool_choice se estableció explícitamente en none.
4. Limitaciones en la capacidad del modelo (se recomienda priorizar modelos como gpt-4o o gpt-3.5-turbo que tienen soporte nativo optimizado para llamadas a herramientas).

Q3: ¿Cómo puedo obligar al modelo a llamar a una función específica? R: Puedes configurar tool_choice con un objeto específico, por ejemplo: "tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}. De esta manera, incluso si el modelo considera que no es necesario, intentará generar los parámetros para dicha función.

Q4: ¿Qué debo hacer si el finish_reason es length? R: Esto significa que la respuesta generada superó el límite establecido en max_tokens o alcanzó el límite de la ventana de contexto del modelo. Puedes intentar aumentar el valor del parámetro max_tokens o acortar la longitud del historial en el array messages.

Q5: ¿Qué precauciones debo tomar al usar el Modo JSON (JSON Mode)? R: Al configurar response_format: { "type": "json_object" }, debes solicitar explícitamente al modelo en el mensaje de System o User que genere la salida en formato JSON (por ejemplo, incluyendo la instrucción "responde en formato JSON"). De lo contrario, el modelo podría entrar en un bucle infinito generando espacios en blanco.

Q6: ¿Cómo manejo múltiples llamadas a herramientas (Multiple Tool Calls)? R: En una sola solicitud, el modelo podría generar varias llamadas a herramientas simultáneamente (por ejemplo, consultar el clima de Pekín y Shanghái al mismo tiempo). Debes iterar sobre el array choices[0].message.tool_calls y ejecutar la lógica local correspondiente para cada una de las llamadas.