Analisar arquivos usando entradas de arquivo do OpenAI no Jitterbit Studio

Introdução

A API Chat Completions do OpenAI oferece suporte para enviar conteúdo de arquivo diretamente em uma mensagem usando entradas de arquivo: o arquivo é codificado em base64 e incorporado na mensagem como um item de conteúdo file com um URI de dados (data:<media-type>;base64,<content>). Nenhum upload separado para a Files API é necessário.

Para arquivos de texto simples, como CSV, uma alternativa mais simples é decodificar o conteúdo base64 em uma string legível e incorporá-lo diretamente no prompt. Quando combinado com o interpretador de código do OpenAI (disponível através da API de Respostas), isso permite que o modelo analise e consulte o conteúdo do arquivo de forma programática.

Ambos os padrões chamam a API OpenAI diretamente usando uma atividade HTTP v2, que fornece controle total sobre a estrutura do corpo da solicitação que cada abordagem requer.

Este guia cobre ambos os padrões, começando pela mesma etapa: fazer download de um arquivo de uma API externa cuja resposta contém o conteúdo do arquivo como dados codificados em base64.

Padrão de design

Cada abordagem segue o padrão de transformação:

A atividade GET faz download do arquivo e a primeira transformação extrai seu conteúdo codificado em base64 em uma variável. Um script então decodifica o conteúdo (para arquivos de texto) ou o prepara como um URI de dados (para arquivos binários). A segunda transformação constrói o corpo da solicitação OpenAI, a atividade POST a envia, e a transformação final extrai a resposta do modelo.

Parte 1: Fazer download do arquivo e extrair o conteúdo base64

Muitas APIs retornam o conteúdo do arquivo como uma string codificada em base64 no corpo da resposta JSON. Esta parte cobre a busca desse conteúdo e seu armazenamento para uso em etapas posteriores.

Configurar a conexão HTTP v2 e a atividade GET

Para configuração da conexão HTTP v2 e autenticação, consulte Chamar uma REST API usando o conector HTTP v2.

Configure uma atividade HTTP v2 GET que busque o arquivo da API de origem. Defina o caminho da URL para o endpoint de download do arquivo, usando uma variável de projeto para passar o ID do arquivo dinamicamente se necessário.

Extrair o conteúdo base64

Adicione uma transformação após a atividade GET. Mapeie o caminho JSON que contém a string base64 para um nó de script que o armazene em uma variável:

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

Substitua o caminho JSON acima pelo caminho real do esquema de resposta da sua API. O nome da variável core.base64fileContent é usado nas etapas que se seguem.

Parte 2: Analisar um arquivo de texto decodificando e incorporando seu conteúdo

Para arquivos CSV e outros arquivos de texto simples, decodifique o conteúdo base64 em uma string legível e incorpore-o na mensagem do usuário. O modelo vê o conteúdo do arquivo como parte do prompt.

Decodificar o conteúdo base64

Adicione uma etapa de script após a transformação de extração. Aplique Base64Decode, BinaryToHex e HexToString em sequência para converter a string base64 em texto legível:

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

A cadeia de três funções é necessária porque Base64Decode retorna dados binários, BinaryToHex os converte para uma string hexadecimal e HexToString converte a string hexadecimal para texto legível. Pular BinaryToHex produz uma string codificada em hex em vez do conteúdo de texto original.

Construir o prompt

Construa o prompt incorporando o conteúdo decodificado inline. Para análise CSV, instruir o modelo a tratar o conteúdo como RFC 4180 e especificar exatamente o que retornar:

$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";

Ajuste as instruções para sua própria estrutura de arquivo e objetivo de análise.

Configurar a transformação de solicitação da API de Respostas

Para análise de dados estruturados, use a API de Respostas (v1/responses) com a ferramenta de interpretador de código ativada. O interpretador de código fornece ao modelo um ambiente de execução Python para analisar o CSV programaticamente em vez de depender de correspondência de padrões.

Adicione uma transformação que mapeie o corpo da solicitação. O esquema de solicitação da API de Respostas difere do Chat Completions: o campo de mensagem é input, não messages.

Para ativar o interpretador de código, adicione [{"type":"code_interpreter"}] ao array tools no corpo da solicitação. Isso pode ser feito em um script antes da transformação ao construir o corpo completo da solicitação como uma string JSON, ou adicionando um mapeamento json/tools/item/type com o valor "code_interpreter".

Na etapa de script antes dessa transformação, defina o caminho da URL para o endpoint de Respostas:

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

Ler a resposta

Após a atividade POST, adicione uma transformação para extrair a resposta do modelo. Para a API de Respostas, o texto de saída está em json$output$item.content$item.text$:

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

Parte 3: Analisar um arquivo binário usando dados de arquivo inline

Para PDFs e outros arquivos binários, mantenha o conteúdo base64 como está e o incorpore no array de conteúdo da mensagem usando um URI de dados. O modelo recebe o arquivo completo junto com o prompt de texto.

Preparar o prompt e a variável de conteúdo

Adicione uma etapa de script para definir o prompt do usuário e atribuir o conteúdo base64 à variável que a transformação de solicitação usará:

$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;

Não decodifique o conteúdo base64 nesta etapa. A API Chat Completions espera a string base64 bruta como parte do URI de dados.

Configurar a transformação de solicitação do Chat Completions

Adicione uma transformação que mapeie o corpo da solicitação. O campo content é um array com dois itens: um item text para o prompt e um item file para o documento.

A notação item#1 cria um segundo elemento no array content. O valor file_data deve ser um URI de dados completo, não a string base64 bruta. Use application/pdf como o tipo MIME para arquivos PDF.

Na etapa de script antes dessa transformação, defina o caminho da URL para o endpoint Chat Completions:

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

Configurar a atividade HTTP v2 POST para OpenAI

Configure uma atividade HTTP v2 POST para a API OpenAI. Se você já tiver uma conexão OpenAI de outra operação, reutilize-a. Caso contrário, crie uma nova conexão:

1. Defina a Base URL como https://api.openai.com, ou faça referência a uma variável de projeto.

2. Adicione um header de autorização Bearer usando uma variável de projeto que contém sua chave de API OpenAI (com seu valor oculto):

   Authorization: Bearer [openai_api_key]
   

3. Defina o Path da URL como [openAi.url.path] para que a operação possa alternar entre endpoints usando a variável de script.

4. Defina Request Format e Response Format como JSON.

Para etapas detalhadas de conexão e autenticação, consulte Chamar uma API REST usando o conector HTTP v2.

Ler a resposta

Adicione uma transformação após a atividade POST para extrair a resposta do modelo. Para a API Chat Completions, o texto gerado está em json$choices$item.message$content$:

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

Verificar a integração

1. Implante e execute a operação manualmente.

2. Nos logs da operação, confirme que a atividade GET retornou uma resposta bem-sucedida e que a atividade POST para OpenAI também foi concluída sem erros.

3. Inspecione a saída do log para confirmar que a variável de resposta (llm_response para a abordagem de texto, offerSigned_cvSummary para a abordagem binária) contém um resumo válido gerado por IA.

4. Se a atividade POST falhar com um 400 Bad Request, verifique se o valor file_data começa com data:application/pdf;base64, e se a string base64 está completa e não foi truncada.

5. Se o conteúdo de texto decodificado parecer distorcido (para a abordagem de texto), confirme que a cadeia de funções completa está aplicada: HexToString(BinaryToHex(Base64Decode(...))). Aplicar apenas Base64Decode sem a cadeia de conversão retorna dados binários, não texto legível.