Usar Azure OpenAI en una operación de Studio en Jitterbit Studio

Introducción

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

A diferencia del conector OpenAI, el conector de Azure OpenAI se autentica usando una URL de punto de conexión de recursos de Azure y una clave API en lugar de una clave de cuenta de OpenAI, y los modelos se seleccionan de los despliegues en tu recurso de Azure OpenAI en lugar de una lista fija.

Patrón de diseño

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

La actividad de origen proporciona los datos que se utilizan para construir el mensaje (por ejemplo, un resultado de consulta de base de datos o un registro de Salesforce). La transformación asigna esos datos a los campos de solicitud del mensaje. La actividad Prompt envía la solicitud a Azure 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 destino (por ejemplo, escribirlo en un campo de base de datos o publicarlo en un canal de Slack).

Parte 1: Configurar la conexión de Azure OpenAI

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

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

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

4. Punto de conexión: Introduce la URL del punto de conexión para tu recurso de Azure OpenAI. Puedes encontrarla en Azure Portal en Gestión de recursos > Claves y punto de conexión en la barra lateral izquierda.

5. Clave API/Secreta: Introduce la clave API para tu recurso de Azure OpenAI. Puedes encontrarla en Azure Portal en la misma ubicación: utiliza el valor de CLAVE 1 o CLAVE 2.

   Consejo

   Almacena la clave API como una variable de 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 directa y facilita su rotación sin editar el proyecto.

6. Configuración opcional: Haz clic para expandir. Dos configuraciones son relevantes para casos de uso comunes:

   • Mantener contexto de chat entre operaciones: (Solo grupos de agentes en la nube.) Permite que el conector mantenga el historial de conversación entre operaciones en el mismo entorno que comparten el mismo chatId. Utilízalo cuando operaciones posteriores necesiten hacer referencia a turnos anteriores en una conversación.
   • Añadir una fuente de datos: Conecta una instancia de Azure AI Search o Azure Cosmos DB para MongoDB (vCore) para que las respuestas de Azure OpenAI se basen en tus propios datos.

7. Haz clic en Prueba para verificar la conexión, luego haz clic en Guardar cambios.

Parte 2: Configurar la actividad Prompt

La actividad Prompt es un destino: consume datos asignados desde una transformación y los envía a Azure OpenAI.

1. En la paleta de componentes de diseño, expande el punto de conexión de Azure OpenAI que creaste. Arrastra el tipo de actividad Prompt 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 Analizar sentimiento.

2. Texto del símbolo del sistema: Introduce el texto base del símbolo del sistema. Si el símbolo del sistema necesita incorporar campos de datos de origen de forma dinámica (por ejemplo, incluir el texto de una reseña de cliente o la descripción de un caso de soporte), introduce la instrucción estática aquí y construye el símbolo del sistema completo en la transformación (consulta Parte 3).

   Ejemplo de símbolo del sistema estático:

   Analyze the sentiment of the following customer review:
   

3. ID del modelo: Selecciona el modelo de Azure OpenAI que deseas utilizar. La lista muestra solo los modelos implementados en tu recurso de Azure OpenAI. Haz clic en Actualizar para actualizar la lista si has implementado nuevos modelos desde que abriste esta configuración. Para obtener información sobre la implementación de modelos, consulta la documentación de Microsoft.

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

   • Rol: Controla el tipo de símbolo del sistema que se envía a Azure OpenAI. El valor predeterminado es Sistema, que es apropiado para símbolos del sistema automatizados y no interactivos. Utiliza Usuario para simular un símbolo del sistema directo del usuario. Para obtener orientación sobre los roles Asistente y Herramienta, consulta Actividad Prompt de Azure OpenAI.
   • 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. No se recomienda utilizar esta configuración junto con Probabilidad superior.
   • Tokens máximos: Limita la longitud de la respuesta. El valor predeterminado es 16. Establece este valor para evitar finalizaciones inesperadamente largas.
   • Probabilidad superior: Una alternativa a Temperatura para controlar la diversidad de la salida. No se recomienda utilizar esta configuración junto con Temperatura.

5. Haz clic en Siguiente.

Paso 2: Revisar los esquemas de datos

Se muestran los esquemas de solicitud y respuesta. El esquema de solicitud incluye prompt, model, max_tokens, temperature y top_p. El esquema de respuesta incluye choices (una matriz que contiene el texto generado, index y finish_reason), usage (recuentos de tokens) y errors.

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

Parte 3: Asignar datos de origen al símbolo del sistema en una transformación

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

El campo más importante a asignar es prompt. Utiliza un nodo de script para construir la cadena de símbolo del sistema completa combinando la instrucción estática con valores de campo del origen:

<trans>
"Analyze the sentiment of the following customer review:\n\n" +
Source.ReviewText
</trans>

Donde Source.ReviewText es un campo del esquema de respuesta de la actividad de origen (por ejemplo, un campo devuelto por una actividad Consulta de base de datos).

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>
$azure_openai_model
</trans>

Parte 4: Acceder a la respuesta de IA

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

Encadenar una operación posterior

Configura la acción En caso de éxito de la operación Prompt para ejecutar una segunda operación que procese la respuesta de IA:

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

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

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

Leer el texto generado

El conector de Azure OpenAI utiliza la API Chat Completion, que devuelve el texto generado por IA en choices[0].message.content. En la transformación de la operación posterior, asigna este campo al destino:

<trans>
Source.choices[0].message.content
</trans>

Por ejemplo, asigna choices[0].message.content a un campo de base de datos para almacenar el resultado, o a un campo text de un mensaje de Slack para publicar la respuesta de IA en un canal (consulta Enviar una notificación de Slack desde una operación de Studio).

Verificar errores

El esquema de respuesta también incluye un array errors. Si Azure OpenAI devuelve un error (por ejemplo, debido a un nombre de implementación de modelo inválido o a un límite de tokens excedido), los detalles del error aparecen en errors[0].message. Para mostrar estos errores en el registro de operaciones, agrega un nodo de script a la transformación que llame a RaiseError cuando errors esté poblado:

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

Verificar la integración

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

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

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

4. Si la actividad Prompt falla con un error de autenticación, verifica la URL del punto de conexión y la clave de API en la conexión de Azure OpenAI y confirma que la clave no se haya rotado en Azure Portal.

Para patrones de IA más avanzados basados en esta base, consulta Procesar documentos con IA y Enrutar respuestas de LLM a operaciones de Studio mediante function calling.