Usar OpenAI para procesar datos en una operación de Studio en Jitterbit Studio

Introducción

El conector de OpenAI permite que las operaciones de Studio envíen datos a OpenAI y reciban texto generado por IA a cambio. Esta guía cubre el patrón común de construir un prompt de OpenAI a partir de datos de origen, enviarlo a OpenAI usando la actividad Prompt V2, y luego enrutar la respuesta de IA a un destino posterior como una base de datos, un archivo o un canal de notificación.

Patrón de diseño

La operación que envía datos a OpenAI sigue el patrón de transformación:

La actividad de origen proporciona los datos utilizados para construir el prompt (por ejemplo, el resultado de una consulta de registro de Salesforce o una fila de base de datos). La transformación mapea esos datos en los campos de solicitud del prompt. La actividad Prompt V2 envía la solicitud a OpenAI y almacena la respuesta.

Una segunda operación, encadenada al éxito de la primera, utiliza una transformación para leer la respuesta de IA y enrutar el texto generado a la actividad de destino (por ejemplo, publicarlo en un canal de Slack o escribirlo en un campo de base de datos).

Parte 1: Configurar la conexión de OpenAI

1. En Studio, abre tu proyecto y haz clic en la pestaña Puntos finales del proyecto y conectores en la paleta de componentes de diseño.

2. Haz clic en el conector OpenAI para abrir la configuración de la conexión.

3. Nombre de la conexión: Ingresa un nombre que identifique esta conexión, por ejemplo OpenAI.

4. Clave de API/Secreto: Ingresa tu clave de API de OpenAI.

   Consejo

   Almacena la clave de API como una variable de proyecto con su valor oculto, luego referencia la variable aquí usando el icono de variable o escribiendo [ para seleccionarla. Esto mantiene la clave fuera de la configuración de conexión directamente y facilita su rotación sin editar el proyecto.

5. Versión de API: Deja esto establecido en el valor predeterminado V1, que es la única versión compatible. (Esta es la versión de API de OpenAI de la conexión y no está relacionada con la actividad Prompt V2 utilizada más adelante en esta guía).

6. Haz clic en Probar para verificar la conexión, luego haz clic en Guardar cambios.

Parte 2: Configurar la actividad Prompt V2

La actividad Prompt V2 es un destino: consume datos mapeados desde una transformación y los envía a OpenAI usando la API de Respuestas de OpenAI.

1. En la paleta de componentes de diseño, expande el punto final de OpenAI que creaste. Arrastra el tipo de actividad Prompt V2 al lienzo de diseño para crear una instancia de actividad.

2. Haz doble clic en la actividad para abrir su configuración.

Paso 1: Ingresa un nombre y especifica la configuración

1. Nombre: Ingresa un nombre para la actividad, por ejemplo Resumir registro.

2. ID de chat: Déjalo en blanco para un prompt de una sola vuelta como el de esta guía; se genera automáticamente un chatId. Para continuar una conversación existente o llamar a herramientas registradas por una actividad anterior de Registrar herramientas V2 o Registrar herramientas del servidor MCP, ingresa el chatId de esa actividad aquí en su lugar.

3. Texto del prompt: Ingresa el texto del prompt base. Este campo acepta una cadena estática o una referencia de variable. Si el prompt necesita incorporar campos de datos de origen dinámicamente (por ejemplo, incluir un ID de registro o valor de campo), deja este campo como una instrucción general e anúlalo con el prompt completo construido en la transformación (consulta Parte 3).

Ejemplo de indicación estática:

Summarize the following support case in one sentence:

1. Modelo: Selecciona el modelo de OpenAI a utilizar. El predeterminado es gpt-4. Para ver la lista completa de modelos compatibles, consulta Conector de OpenAI.

2. Configuración opcional: Haz clic para expandir:

   • Rol: Selecciona Usuario para un indicación de usuario estándar. Usa Sistema para establecer el comportamiento del asistente, o Asistente para proporcionar respuestas de ejemplo.
   • Temperatura: Controla la aleatoriedad de la respuesta. Los valores más cercanos a 0 producen resultados más deterministas; los valores más cercanos a 2 producen resultados más variados.
   • Tokens máximos: Limita la longitud de la respuesta. Establece esto para evitar completaciones inesperadamente largas.

3. Haz clic en Siguiente.

Paso 2: Revisa los esquemas de datos

Se muestran los esquemas de solicitud y respuesta. Según la API de Respuestas de OpenAI, el esquema de solicitud incluye input, model, max_tokens, temperature y top_p. El esquema de respuesta incluye un arreglo output de elementos; un elemento message tiene un arreglo content, cada uno con un type (output_text para contenido generado) y el text generado, más su propio campo error por elemento para elementos como llamadas de herramientas.

Haz clic en Finalizado para guardar la configuración de la actividad.

Parte 3: Asigna datos de origen al indicación en una transformación

En la transformación que precede a la actividad Indicación V2, asigna los campos de origen al esquema de solicitud de la actividad Indicación V2.

El campo más importante a asignar es input. Usa un nodo de script para construir la cadena de indicación completa combinando la instrucción estática con valores de campo del origen:

<trans>
"Summarize the following support case in one sentence:\n\n" +
"Subject: " + Source.Subject + "\n" +
"Description: " + Source.Description
</trans>

Donde Source.Subject y Source.Description son campos del esquema de respuesta de la actividad de origen (por ejemplo, campos devueltos por una actividad Consulta de Salesforce).

Para anular el modelo establecido en la configuración de la actividad, asigna el campo model a una cadena literal o a una variable de proyecto:

<trans>
$openai_model
</trans>

Parte 4: Accede a la respuesta de IA

El esquema de respuesta de la actividad Indicación V2 está disponible en cualquier transformación dentro de la misma operación o en una operación posterior.

Encadena una operación posterior

Configura la acción Al tener éxito de la operación Indicación V2 para ejecutar una segunda operación que procese la respuesta de IA:

1. Abre la configuración de la operación Indicación V2.

2. En la pestaña Acciones, establece la acción Al tener éxito en Ejecutar operación y selecciona la operación posterior.

Para obtener más información sobre el encadenamiento de operaciones, consulta Configura el manejo de errores en operaciones.

Lee el texto generado

En la transformación de la operación posterior, el esquema de respuesta de la actividad Indicación V2 proporciona el texto generado por IA anidado bajo output. Según la API de Respuestas de OpenAI, asigna el campo de destino al texto del primer elemento de salida:

<trans>
Source.output[0].content[0].text
</trans>

Por ejemplo, asigna este campo a un campo text de mensaje de Slack para publicar el resumen de IA en un canal (consulta Envía una notificación de Slack desde una operación de Studio), o asígnalo a un campo de base de datos para almacenar el resultado.

Verificar errores

Cada elemento en el array output tiene su propio campo error, que se completa cuando ese elemento específico falla (por ejemplo, una llamada de herramienta fallida). Agrega un nodo de script a la transformación que verifique output[0].error y llame a RaiseError si está completo:

<trans>
if(Length(Source.output[0].error) > 0,
  RaiseError(Source.output[0].error)
);
</trans>

Verificar la integración

1. Implementa y ejecuta la operación Prompt V2 manualmente.

2. En los registros de operación, confirma que la actividad Prompt V2 se completó correctamente y que se activó la operación descendente.

3. Inspecciona el registro de la operación descendente para verificar que output[0].content[0].text contiene una respuesta válida generada por IA.

4. Si la actividad Prompt V2 falla con un error de autenticación, verifica la clave de API en la conexión de OpenAI y confirma que no ha sido revocada en tu cuenta de OpenAI.

Para patrones de IA más avanzados basados en esta base, consulta Procesar documentos con IA, Enrutar respuestas de LLM a operaciones de Studio mediante llamadas de función, y Crear un chat LLM multiturno con historial de conversación.