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 prompt a partir de datos de origen, enviarlo a Azure OpenAI utilizando la actividad de Prompt, y luego enrutar la respuesta de la IA a un destino posterior, como una base de datos, un archivo o un canal de notificación.

A diferencia del conector de OpenAI, el conector de Azure OpenAI se autentica utilizando una URL de endpoint de recurso de Azure y una clave de API en lugar de una clave de cuenta de OpenAI, y los modelos se seleccionan de los despliegues en su 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 utilizados para construir el prompt (por ejemplo, el resultado de una consulta a la base de datos o un registro de Salesforce). La transformación mapea esos datos en los campos de solicitud del prompt. La Actividad de 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 la IA y enrutar el texto generado a la actividad de destino (por ejemplo, escribiéndolo en un campo de base de datos o publicándolo 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 Endpoints y conectores del proyecto en la paleta de componentes de diseño.

2. Haz clic en el conector Azure 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 Azure OpenAI.

4. Endpoint: Ingresa la URL del endpoint para tu recurso de Azure OpenAI. Puedes encontrar esto en el Portal de Azure bajo Gestión de recursos > Claves y endpoint en la barra lateral izquierda.

5. API/Clave secreta: Ingresa la clave API para tu recurso de Azure OpenAI. Puedes encontrar esto en el Portal de Azure en la misma ubicación: usa el valor del campo CLAVE 1 o CLAVE 2.

   Consejo

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

6. Configuraciones opcionales: Haz clic para expandir. Dos configuraciones son relevantes para casos de uso comunes:

   • Almacenar el contexto del chat a través de operaciones: (Grupos de agentes en la nube solamente.) Permite que el conector mantenga el historial de la conversación entre operaciones en el mismo entorno que comparten el mismo chatId. Usa esto cuando las operaciones posteriores necesiten hacer referencia a turnos anteriores en una conversación.
   • Agregar 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 estén fundamentadas en tus propios datos.

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

Parte 2: Configurar la actividad de Prompt

La actividad Prompt es un objetivo: consume datos mapeados de una transformación y los envía a Azure OpenAI.

1. En la paleta de componentes de diseño, expande el endpoint 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: Ingresa un nombre y especifica configuraciones

1. Nombre: Ingresa un nombre para la actividad, por ejemplo Analizar Sentimiento.

2. Texto del aviso: Ingresa el texto base del aviso. Si el aviso necesita incorporar dinámicamente campos de datos de origen (por ejemplo, incluir el texto de una reseña de cliente o una descripción de caso de soporte), ingresa la instrucción estática aquí y construye el aviso completo en la transformación (ver Parte 3).

   Ejemplo de aviso estático:

   Analiza el sentimiento de la siguiente reseña de cliente:
   

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

4. Configuraciones opcionales: Haz clic para expandir:

   • Rol: Controla el tipo de aviso enviado a Azure OpenAI. El valor predeterminado es Sistema, que es apropiado para avisos automatizados y no interactivos. Usa Usuario para simular un aviso directo del usuario. Para orientación sobre los roles de Asistente y Herramienta, consulta la actividad de aviso de Azure OpenAI.
   • Temperatura: Controla la aleatoriedad de la respuesta. Los valores más cercanos a 0 producen una salida más determinista; los valores más cercanos a 2 producen una salida más variada. No se recomienda usar esta configuración junto con Probabilidad Superior.
   • Máx. Tokens: Limita la longitud de la respuesta. El valor predeterminado es 16. Establece esto para evitar completaciones inesperadamente largas.
   • Probabilidad Superior: Una alternativa a Temperatura para controlar la diversidad de la salida. No se recomienda usar esta configuración junto con Temperatura.

5. Haz clic en Siguiente.

Paso 2: Revisa 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 (un arreglo que contiene el texto generado, index y finish_reason), usage (conteos de tokens) y errors.

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

Parte 3: Mapea los datos de origen al aviso en una transformación

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

El campo más importante para mapear es prompt. Usa un nodo de script para construir la cadena completa del aviso combinando la instrucción estática con los 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, mapea el campo model a una cadena literal o a una variable de proyecto:

<trans>
$azure_openai_model
</trans>

Parte 4: Accede a la respuesta de la IA

El esquema de respuesta de la actividad Aviso 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 Al Éxito de la operación de Aviso para ejecutar una segunda operación que procese la respuesta de la IA:

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

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

Para más información sobre cómo encadenar operaciones, consulta Configurar el manejo de errores en operaciones.

Lee el texto generado

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

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

Por ejemplo, mapea 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 la IA en un canal (ver Enviar una notificación de Slack desde una operación de Studio).

Check for errors

El esquema de respuesta también incluye un arreglo errors. Si Azure OpenAI devuelve un error (por ejemplo, debido a un nombre de implementación de modelo inválido o un límite de tokens excedido), los detalles del error aparecen en errors[0].message. Para mostrar estos 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>

Verify the integration

1. Despliega y ejecuta la operación de Prompt manualmente.

2. En los registros de operaciones, confirma que la actividad Prompt se completó con éxito y que la operación descendente fue activada.

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

4. Si la actividad Prompt falla con un error de autenticación, verifica la URL del endpoint y la clave API en la conexión de Azure OpenAI y confirma que la clave no ha sido rotada en el Portal de Azure.

Para patrones de IA más avanzados construidos sobre esta base, consulta Procesar documentos con IA y Dirigir respuestas de LLM a operaciones de Studio utilizando llamadas a funciones.