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

Introducción

El conector 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 una solicitud a OpenAI a partir de datos de origen, enviarla a OpenAI usando la actividad Prompt V2, y luego dirigir la respuesta de IA hacia 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 la solicitud (por ejemplo, el resultado de una consulta de registros de Salesforce o una fila de base de datos). La transformación asigna esos datos a los campos de la solicitud de solicitud. La actividad Prompt V2 envía la solicitud a OpenAI y almacena la respuesta.

Una segunda operación, encadenada en el éxito de la primera, utiliza una transformación para leer la respuesta de IA y dirigir 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 OpenAI

1. En Studio, abre tu proyecto y haz clic en la pestaña Extremos 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 conexión.

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

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

   Consejo

   Almacena la clave de API como una variable del proyecto con su valor oculto, luego haz referencia a 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: Déjalo configurado al valor predeterminado V1, que es la única versión compatible. (Esta es la versión de la API de OpenAI de la conexión y no está relacionada con la actividad Prompt V2 que usarás más adelante en esta guía).

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

Parte 2: Configurar la actividad Prompt V2

La actividad Prompt V2 es un destino: consume datos asignados 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 extremo 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: Introduce un nombre y especifica la configuración

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

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

3. Texto de solicitud: Introduce el texto de solicitud base. Este campo acepta una cadena estática o una referencia de variable. Si la solicitud necesita incorporar dinámicamente campos de datos de origen (por ejemplo, incluir un ID de registro o valor de campo), déjalo como una instrucción general y reemplázalo con la solicitud completamente construida en la transformación (consulta Parte 3).

   Ejemplo de solicitud estática:

   Summarize the following support case in one sentence:
   

4. Modelo: Selecciona el modelo de OpenAI que deseas usar. El valor predeterminado es gpt-4. Para consultar la lista completa de modelos compatibles, consulta Conector OpenAI.

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

   • Rol: Selecciona User para un prompt de usuario estándar. Usa System para establecer el comportamiento del asistente, o Assistant para proporcionar respuestas de ejemplo.
   • Temperature: 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.
   • Max Tokens: Limita la longitud de la respuesta. Establece este valor para evitar completaciones inesperadamente largas.

6. Haz clic en Next.

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 array output de elementos; un elemento message tiene un array 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 a herramientas.

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

Parte 3: Asignar datos de origen al prompt en una transformación

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

El campo más importante para asignar es input. Usa un nodo de script para construir la cadena de prompt completa combinando la instrucción estática con los 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 Query 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: Acceder a la respuesta de la IA

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

Encadenar una operación descendente

Configura la acción On Success de la operación Prompt V2 para ejecutar una segunda operación que procese la respuesta de IA:

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

2. En la pestaña Actions, establece la acción On Success en Run Operation y selecciona la operación descendente.

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

Leer el texto generado

En la transformación de la operación descendente, el esquema de respuesta de la actividad Prompt 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 Enviar 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 a herramienta fallida). Añade 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ó exitosamente 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 API en la conexión OpenAI y confirma que no ha sido revocada en tu cuenta 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 usando llamadas de función, y Construir un chat LLM multiturno con historial de conversación.