Tutorial de la API de Asistentes de OpenAI

1. Presentación de la API de Asistentes de OpenAI

1.1 Definición y Propósito de la API de Asistentes

La API de Asistentes permite a los desarrolladores construir asistentes de inteligencia artificial dentro de sus propias aplicaciones. Al definir comandos personalizados y seleccionar modelos, los asistentes pueden utilizar herramientas, conocimientos y modelos para responder a consultas de los usuarios. Actualmente, la API de Asistentes es compatible con tres tipos de herramientas: Intérprete de Código, Recuperación y Llamada de Funciones.

1.2 Aplicaciones de la API de Asistentes

La API de Asistentes es ideal para varios escenarios que requieren soporte interactivo de inteligencia artificial. Por ejemplo:

• Atención al Cliente: Responder automáticamente a preguntas frecuentes para reducir la carga de trabajo del servicio al cliente humano.
• Educación en Línea: Responder preguntas de los estudiantes y proporcionar apoyo de aprendizaje personalizado.
• Análisis de Datos: Analizar archivos de datos subidos por los usuarios, generar informes y visualizar gráficos.
• Recomendaciones Personalizadas: Proporcionar sugerencias y servicios personalizados basados en las interacciones históricas de los usuarios.

1.3 Conceptos Principales de Asistentes

Los objetos principales de la API de Asistentes incluyen Asistente, Hilo y Mensaje. Aquí se presentan las introducciones detalladas sobre estos objetos y sus funciones:

Asistente

El objeto Asistente se basa en modelos de OpenAI y puede llamar a herramientas de asistentes de inteligencia artificial. Puedes personalizar las instrucciones del Asistente para adaptar su personalidad y funcionalidad. Por ejemplo, puedes crear un Asistente llamado "Analista de Datos" que analiza datos y genera gráficos utilizando la herramienta "code_interpreter".

Hilo

El objeto Hilo representa la sesión de conversación entre el usuario y el Asistente. Puedes crear un Hilo para cada usuario y agregar mensajes a él cuando el usuario interactúa con el Asistente. El objeto Hilo almacena efectivamente el historial de mensajes y truncarlos cuando sea necesario para cumplir con el límite de longitud del contexto del modelo.

Mensaje

El objeto Mensaje puede ser creado por el usuario o por el Asistente. Los mensajes pueden contener texto, imágenes y otros archivos. Los mensajes se almacenan como una lista en el Hilo. En el uso real de la API, los desarrolladores pueden agregar mensajes de usuario al Hilo y activar la respuesta del Asistente según sea necesario.

Ejecución

El objeto Ejecución representa la ejecución de una solicitud de asistente, llamando al asistente basándose en el contenido del mensaje en el Hilo. El asistente utiliza su configuración y los mensajes del Hilo para ejecutar tareas llamando a modelos y herramientas. Como parte de la ejecución, el asistente agrega mensajes al hilo.

2. Proceso de Desarrollo de la API de Asistentes

2.1 Crea tu Asistente

Para crear un Asistente, necesitas enviar una solicitud a la API con instrucciones, nombre del modelo y configuración de herramientas. Aquí tienes un ejemplo simple de cómo crear un asistente personal para tutoría de matemáticas:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_CLAVE_API_OPENAI" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Eres un tutor personal de matemáticas. Escribe y ejecuta código para responder preguntas de matemáticas.",
    "name": "Tutor de Matemáticas",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

Parámetros de la API:

• instructions: instrucciones del sistema que indican al asistente qué hacer.
• name: el nombre del asistente.
• tools: define qué herramientas puede usar el asistente. Cada asistente puede tener hasta 128 herramientas. Los tipos de herramientas actuales pueden ser code_interpreter, recuperación o función.
• model: ¿qué modelo debería usar el asistente?

Después de crear con éxito el Asistente, recibirás un ID de Asistente.

2.2 Crea un Hilo de Sesión

Un Hilo representa una conversación, y recomendamos crear un Hilo de sesión para cada usuario cuando inician una conversación. Puedes crear un Hilo de la siguiente manera:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TU_CLAVE_API_OPENAI" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

Después de crear el Hilo, recibirás un ID de Hilo.

2.3 Agregar mensajes al hilo

Puedes agregar mensajes a un hilo específico, los cuales contienen texto y opcionalmente permiten archivos subidos por el usuario. Por ejemplo:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_CLAVE_API_DE_OPENAI" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Necesito resolver esta ecuación `3x + 11 = 14`. ¿Me puedes ayudar?"
    }'

Parámetros de la API:

• thread_id - representa el ID del hilo de conversación, que puedes obtener al crear el hilo.

El cuerpo de la solicitud de la API es un mensaje de usuario, que generalmente representa la pregunta del usuario, similar a la estructura de mensaje del modelo de conversación.

2.4 Ejecutar al asistente para generar una respuesta

Para que el asistente responda a los mensajes del usuario, es necesario crear un Ejecución. Esto permite que el asistente lea el Hilo y decida si usar herramientas (si están habilitadas) o simplemente usar el modelo para responder mejor la consulta.

Nota: Hasta este punto, el asistente no ha respondido a la pregunta del usuario. Solo cuando llames a la API de Ejecución, el asistente de IA responderá a la pregunta del usuario.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer TU_CLAVE_API_DE_OPENAI" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "id_del_asistente",
    "instructions": "Dirígete al usuario como Jane Doe. El usuario tiene una cuenta premium."
  }'

Parámetros de la API:

• thread_id - representa el ID del hilo de conversación, que puedes obtener al crear el hilo.
• assistant_id - representa el ID del asistente, que puedes obtener al crear el asistente.
• instructions - instrucciones del asistente que pueden anular las instrucciones establecidas al crear el asistente.

Una solicitud exitosa a la API devolverá un ID de Ejecución.

2.5 Verificar el estado de ejecución del asistente

Después de iniciar una tarea (Ejecución) en el asistente, la ejecución de la tarea es asíncrona. Esto significa que necesitamos verificar regularmente el estado de la Ejecución para determinar si se ha completado. Para verificar el estado de la Ejecución, se puede hacer una solicitud HTTP usando CURL. A continuación se presenta una introducción específica a este proceso.

Ejemplo de solicitud CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Explicación de los parámetros de la API:

• https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: Esta es la URL de solicitud de la API, donde thread_abc123 es el identificador único del hilo (Thread), y run_abc123 es el identificador único de la Ejecución.

Ejemplo del cuerpo de la respuesta:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

Explicación de los parámetros de la respuesta de la API:

• id: El identificador único de la Ejecución.
• object: Indica el tipo del objeto devuelto, que es thread.run en este caso.
• status: El estado de la Ejecución, los valores posibles incluyen en cola, en progreso, completado, requiere acción, fallido, etc.
• created_at: La marca de tiempo en que se creó la Ejecución.

2.6 Obtener los resultados de la respuesta del asistente

Después de que la Ejecución del asistente se haya completado, podemos leer los resultados de la respuesta del asistente verificando los mensajes agregados al hilo (Thread). A continuación se muestra una demostración de cómo hacer la solicitud a través de CURL y una explicación detallada de los parámetros de la API.

Consejo: Similar a una conversación con un asistente, cuando el asistente termina de procesar la consulta del usuario, el asistente añadirá un mensaje al hilo de conversación (Thread). Por lo tanto, solo necesitamos consultar el último mensaje en el hilo de conversación (Thread) para obtener la respuesta del asistente.

Ejemplo de solicitud CURL:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Explicación de parámetros de la API:

• https://api.openai.com/v1/threads/thread_abc123/messages: La URL de solicitud de la API, donde thread_abc123 es el identificador único del hilo (Thread).
• Igual que los encabezados de solicitud utilizados para verificar el estado de ejecución anterior, incluida la información de autenticación y la información de la versión de la API.

Ejemplo de resultados de respuesta del asistente:

En este ejemplo, el usuario hizo una pregunta de matemáticas al Asistente, y el Asistente agregó un mensaje de respuesta al Hilo después de procesarlo.

Usuario: Necesito resolver la ecuación `3x + 11 = 14`. ¿Puedes ayudarme?
Asistente: Claro, Juanita. Para resolver la ecuación `(3x + 11 = 14)`, necesitas aislar `(x)` en un lado de la ecuación. Permíteme calcular el valor de `(x)` para ti.
Asistente: La solución de la ecuación `(3x + 11 = 14)` es `(x = 1)`.

Después de obtener los resultados de respuesta del Asistente, se pueden presentar al usuario para ayudarles a comprender y utilizar mejor los servicios proporcionados por el Asistente.

3. Herramientas: Herramientas Integradas Provistas por OpenAI

3.1 Herramienta de Interprete de Código

La herramienta de Intérprete de Código permite al API de Asistentes escribir y ejecutar código Python en un entorno de ejecución aislado. Esta herramienta puede manejar varios formatos de datos y archivos, y generar archivos con datos e imágenes gráficas. El Intérprete de Código permite que tu Asistente ejecute iterativamente código para resolver problemas de codificación y matemáticas complejos. Cuando el código escrito por el Asistente no se ejecuta correctamente, puede iterar este código intentando diferente código hasta que se ejecute con éxito.

Habilitar Intérprete de Código

Para habilitar el Intérprete de Código, pasa code_interpreter en el parámetro tools al crear el objeto del Asistente:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Eres un tutor personal de matemáticas. Cuando te hagan una pregunta de matemáticas, escribe y ejecuta código para responderla.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Luego, el modelo decidirá cuándo invocar el Intérprete de Código en tiempo de ejecución según la naturaleza de la solicitud del usuario. Puedes facilitar este comportamiento a través de las instrucciones del Asistente (por ejemplo, "Escribe código para resolver este problema").

Usar Intérprete de Código para Procesar Archivos

El Intérprete de Código puede analizar datos de archivos. Esto es útil cuando deseas proporcionar una gran cantidad de datos al Asistente o permitir que tus usuarios carguen sus propios archivos para análisis. Ten en cuenta que los archivos cargados para el Intérprete de Código no se indexarán para su recuperación. Para obtener información detallada sobre cómo indexar archivos para su recuperación, consulta la sección de Herramienta de Recuperación a continuación.

Los archivos pasados a nivel de Asistente pueden ser accedidos por todas las Ejecuciones asociadas con este Asistente:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/ruta/a/misdatos.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Eres un tutor personal de matemáticas. Cuando te hagan una pregunta de matemáticas, escribe y ejecuta código para responderla.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Lectura de imágenes y archivos generados por el intérprete de código

El intérprete de código también puede generar archivos en la API, como la generación de gráficos de imágenes, archivos CSV y PDF. Hay dos tipos de archivos generados: imágenes y archivos de datos (por ejemplo, un archivo CSV con datos generados por el Asistente).

Cuando el intérprete de código produce una imagen, puedes encontrar y descargar este archivo en el campo file_id de la respuesta del Mensaje del Asistente:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Herramienta de recuperación

La Herramienta de recuperación mejora las capacidades del Asistente agregando conocimientos desde fuera del modelo (como información de productos patentados o documentos proporcionados por el usuario). Una vez que el archivo se carga y se pasa al Asistente, OpenAI cortará automáticamente, indexará, almacenará incrustaciones de su documento e implementará búsqueda vectorial para recuperar contenido relevante para responder a las consultas de los usuarios.

Habilitar la recuperación

Para habilitar la recuperación en el parámetro tools del Asistente, pasa retrieval:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Eres un chatbot de soporte al cliente. Utiliza tu base de conocimientos para responder eficazmente a las consultas de los clientes.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Subir archivos para la recuperación

Similar al Intérprete de código, los archivos se pueden subir a nivel de Asistente o a nivel de Mensaje individual.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Eres un chatbot de soporte al cliente. Utiliza tu base de conocimientos para responder eficazmente a las consultas de los clientes.",
    "name": "Tutor de matemáticas",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Herramienta de llamada a funciones

Similar a la API de Completado de chat, la API de Asistentes admite la llamada a funciones. La llamada a funciones te permite describir funciones al Asistente y devolver de manera inteligente la función a llamar junto con sus parámetros. Cuando se ejecuta una llamada a función, la API de Asistentes pausará la ejecución, y puedes proporcionar el resultado de la llamada a función para continuar la ejecución.

Definir funciones

Al crear un asistente, puedes definir un conjunto de funciones para que el asistente las llame. Estas funciones deben especificarse explícitamente al crear el objeto del asistente. Cada función debe tener un nombre único, una descripción y una especificación de parámetros.

El siguiente código muestra cómo definir dos funciones usando el comando curl al crear un asistente:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Eres un bot de pronóstico del tiempo. Utiliza las funciones proporcionadas para responder preguntas.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Obtener las condiciones meteorológicas de una ubicación específica",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Ciudad y estado, por ejemplo, San Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Obtener el apodo de una ciudad",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Ciudad y estado, por ejemplo, San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Lectura de las funciones llamadas por el asistente

Cuando un usuario envía un mensaje al asistente y el contenido del mensaje activa una llamada a función, es necesario leer la información de esta llamada a función. Durante este proceso, el asistente generará un ejecución con estado requires_action. En este punto, puedes recuperar el objeto de ejecución para obtener información detallada sobre la llamada a función.

Aquí tienes un ejemplo de cómo recuperar el objeto de ejecución, que muestra cómo obtener la información de las llamadas a función:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

El parámetro tool_calls contiene la información de la llamada a función, y solo necesitas llamar la función correspondiente en tu programa local.

Envío de resultados de función

Después de ejecutar la llamada a función localmente y obtener los resultados, es necesario enviar estos resultados al asistente Assistants para que el asistente pueda continuar procesando la solicitud del usuario. Al enviar los resultados de función, debes asegurarte de que los resultados estén asociados con las llamadas a función originales.

Aquí tienes un ejemplo de código de cómo enviar los resultados de salida de función:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"LA\"}"
      }
    ]
  }'

Explicación de parámetros:

• thread_abc123 representa el ID del hilo de conversación
• run_123 representa el ID del objeto de ejecución
• tool_call_id representa el ID de una llamada a función específica, que se obtiene del parámetro tool_calls anterior.

Una vez que se hayan enviado con éxito todos los resultados de función, el estado del objeto de ejecución se actualizará nuevamente, y el asistente continuará procesando y devolverá la respuesta final al usuario.