Analizar archivos usando entradas de archivos de OpenAI en Jitterbit Studio

Introducción

La API de Chat Completions de OpenAI admite enviar contenido de archivos directamente en un mensaje mediante entradas de archivos: el archivo se codifica en base64 y se incrusta en el mensaje como un elemento de contenido file con un URI de datos (data:<media-type>;base64,<content>). No se requiere una carga separada a la API de Files.

Para archivos de texto plano como CSV, existe una alternativa más simple: decodificar el contenido base64 a una cadena legible e incrustarlo directamente en el prompt. Cuando se combina con el intérprete de código de OpenAI (disponible a través de la API de Responses), esto permite que el modelo analice y consulte el contenido del archivo mediante programación.

Ambos patrones llaman a la API de OpenAI directamente usando una actividad HTTP v2, que proporciona control total sobre la estructura del cuerpo de la solicitud que cada enfoque requiere.

Esta guía cubre ambos patrones, comenzando desde el mismo paso: descargar un archivo de una API externa cuyo cuerpo de respuesta contiene el contenido del archivo como datos codificados en base64.

Patrón de diseño

Cada enfoque sigue el patrón de transformación:

La actividad GET descarga el archivo y la primera transformación extrae su contenido codificado en base64 en una variable. Un script luego decodifica el contenido (para archivos de texto) o lo prepara como un URI de datos (para archivos binarios). La segunda transformación construye el cuerpo de la solicitud de OpenAI, la actividad POST la envía, y la transformación final extrae la respuesta del modelo.

Parte 1: Descargar el archivo y extraer el contenido base64

Muchas API devuelven el contenido del archivo como una cadena codificada en base64 en el cuerpo de respuesta JSON. Esta parte cubre la obtención de ese contenido y su almacenamiento para usarlo en pasos posteriores.

Configurar la conexión HTTP v2 y la actividad GET

Para la configuración de conexión HTTP v2 y autenticación, consulta Llamar a una API REST usando el conector HTTP v2.

Configura una actividad HTTP v2 GET que descargue el archivo desde la API de origen. Establece la ruta URL al punto de conexión de descarga de archivo, usando una variable de proyecto para pasar el ID del archivo dinámicamente si es necesario.

Extraer el contenido base64

Agrega una transformación después de la actividad GET. Asigna la ruta JSON que contiene la cadena base64 a un nodo de script que la almacena en una variable:

<trans>
$core.base64fileContent = json$response$responseItem$responseContent$;
</trans>

Reemplaza la ruta JSON anterior con la ruta real del esquema de respuesta de tu API. El nombre de variable core.base64fileContent se usa en los pasos siguientes.

Parte 2: Analizar un archivo de texto decodificando e incrustando su contenido

Para archivos CSV y otros archivos de texto plano, decodifica el contenido base64 a una cadena legible e incrustalo en el mensaje del usuario. El modelo ve el contenido del archivo como parte del prompt.

Decodificar el contenido base64

Agrega un paso de script después de la transformación de extracción. Aplica Base64Decode, BinaryToHex y HexToString en secuencia para convertir la cadena base64 a texto legible:

$decodedFileContent = HexToString(BinaryToHex(Base64Decode($core.base64fileContent)));

La cadena de tres funciones es necesaria porque Base64Decode devuelve datos binarios, BinaryToHex los convierte a una cadena hexadecimal, y HexToString convierte la cadena hexadecimal a texto legible. Omitir BinaryToHex produce una cadena codificada en hexadecimal en lugar del contenido de texto original.

Construir el prompt

Construye el prompt incrustando el contenido decodificado en línea. Para el análisis de CSV, indica al modelo que trate el contenido como RFC 4180 y especifica exactamente qué devolver:

$gpt_userPrompt = "Role: " + $newHire_jobTitle + ".\n"
    + "Below is CSV text. Use Python to parse it as RFC 4180.\n"
    + "Rules:\n"
    + "- First row contains headers.\n"
    + "- Return ONLY rows where the target column value is exactly 'Yes'.\n"
    + "- Return the matching values as a single comma-separated line.\n\n"
    + "CSV START\n"
    + $decodedFileContent + "\n"
    + "CSV END";

Ajusta las instrucciones según la estructura de tu archivo y el objetivo del análisis.

Configurar la transformación de solicitud de la API de Respuestas

Para el análisis de datos estructurados, utiliza la API de Respuestas (v1/responses) con la herramienta de intérprete de código habilitada. El intérprete de código proporciona al modelo un entorno de ejecución de Python para analizar el CSV mediante programación en lugar de depender de coincidencias de patrones.

Añade una transformación que asigne el cuerpo de la solicitud. El esquema de solicitud de la API de Respuestas difiere de Completaciones de Chat: el campo de mensaje es input, no messages.

Para habilitar el intérprete de código, añade [{"type":"code_interpreter"}] al array tools en el cuerpo de la solicitud. Se puede hacer en un paso de script antes de la transformación al construir el cuerpo de la solicitud completo como una cadena JSON, o al añadir una asignación json/tools/item/type con el valor "code_interpreter".

En el paso de script antes de esta transformación, establece la ruta de URL para el endpoint de Respuestas:

$openAi.url.path = "v1/responses";

Leer la respuesta

Después de la actividad POST, añade una transformación para extraer la respuesta del modelo. Para la API de Respuestas, el texto de salida está en json$output$item.content$item.text$:

<trans>
$llm_response = json$output$item.content$item.text$;
</trans>

Parte 3: Analizar un archivo binario usando datos de archivo en línea

Para PDF y otros archivos binarios, mantén el contenido base64 tal como está e incrústalo en el array de contenido del mensaje usando un URI de datos. El modelo recibe el archivo completo junto con el prompt de texto.

Preparar el prompt y la variable de contenido

Añade un paso de script para establecer el prompt del usuario y asignar el contenido base64 a la variable que la transformación de solicitud utilizará:

$gpt_userPrompt_fileInputs = "Please analyze the attached document and provide a concise "
    + "summary of the candidate's professional background, key skills, and notable "
    + "achievements.";
$offerSigned_cv_base64 = $core.base64fileContent;

No decodifiques el contenido base64 en este paso. La API de Completaciones de Chat espera la cadena base64 sin procesar como parte del URI de datos.

Configurar la transformación de solicitud de Completaciones de Chat

Añade una transformación que asigne el cuerpo de la solicitud. El campo content es un array con dos elementos: un elemento text para el prompt y un elemento file para el documento.

La notación item#1 crea un segundo elemento en el array content. El valor file_data debe ser un URI de datos completo, no la cadena base64 sin procesar. Utiliza application/pdf como tipo MIME para archivos PDF.

En el paso de script antes de esta transformación, establece la ruta de URL al endpoint de Completaciones de Chat:

$openAi.url.path = "v1/chat/completions";

Configurar la actividad HTTP v2 POST a OpenAI

Configura una actividad HTTP v2 POST para la API de OpenAI. Si ya tienes una conexión de OpenAI desde otra operación, reutilízala. De lo contrario, crea una nueva conexión:

1. Establece la URL base en https://api.openai.com, o referencia una variable de proyecto.

2. Añade un encabezado de autorización Bearer usando una variable de proyecto que contenga tu clave de API de OpenAI (con su valor oculto):

   Authorization: Bearer [openai_api_key]
   

3. Establece la Ruta de URL en [openAi.url.path] para que la operación pueda cambiar entre puntos finales usando la variable de script.

4. Establece Formato de solicitud y Formato de respuesta en JSON.

Para pasos detallados de conexión y autenticación, consulta Llamar a una API REST usando el conector HTTP v2.

Lee la respuesta

Añade una transformación después de la actividad POST para extraer la respuesta del modelo. Para la API de Chat Completions, el texto generado se encuentra en json$choices$item.message$content$:

<trans>
$offerSigned_cvSummary = json$choices$item.message$content$;
</trans>

Verifica la integración

1. Despliega y ejecuta la operación manualmente.

2. En los registros de operación, confirma que la actividad GET devolvió una respuesta exitosa y que la actividad POST a OpenAI también se completó sin errores.

3. Inspecciona la salida del registro para confirmar que la variable de respuesta (llm_response para el enfoque de texto, offerSigned_cvSummary para el enfoque binario) contiene un resumen generado por IA válido.

4. Si la actividad POST falla con un error 400 Bad Request, verifica que el valor de file_data comience con data:application/pdf;base64, y que la cadena base64 esté completa y no truncada.

5. Si el contenido de texto decodificado se ve distorsionado (para el enfoque de texto), confirma que se aplique la cadena completa de tres funciones: HexToString(BinaryToHex(Base64Decode(...))). Aplicar solo Base64Decode sin la cadena de conversión devuelve datos binarios, no texto legible.