Usar OpenAI para processar dados em uma operação do Studio no Jitterbit Studio

Introdução

O conector OpenAI permite que operações do Studio enviem dados para OpenAI e recebam texto gerado por IA em retorno. Este guia aborda o padrão comum de construir um prompt OpenAI a partir de dados de origem, enviá-lo para OpenAI usando a atividade Prompt V2 e, em seguida, rotear a resposta de IA para um destino downstream, como um banco de dados, um arquivo ou um canal de notificação.

Padrão de design

A operação que envia dados para OpenAI segue o padrão de transformação:

A atividade de origem fornece os dados usados para construir o prompt (por exemplo, resultado de consulta de registro do Salesforce ou linha de banco de dados). A transformação mapeia esses dados nos campos de solicitação do prompt. A atividade Prompt V2 envia a solicitação para OpenAI e armazena a resposta.

Uma segunda operação, encadeada no sucesso da primeira, usa uma transformação para ler a resposta de IA e rotear o texto gerado para a atividade de destino (por exemplo, postá-lo em um canal do Slack ou gravá-lo em um campo de banco de dados).

Parte 1: Configurar a conexão OpenAI

1. No Studio, abra seu projeto e clique na guia Endpoints e conectores do projeto na paleta de componentes de design.

2. Clique no conector OpenAI para abrir a configuração de conexão.

3. Nome da conexão: Digite um nome que identifique esta conexão, por exemplo OpenAI.

4. Chave de API/Segredo: Digite sua chave de API OpenAI.

   Dica

   Armazene a chave de API como uma variável de projeto com seu valor oculto e, em seguida, referencie a variável aqui usando o ícone de variável ou digitando [ para selecioná-la. Isso mantém a chave fora da configuração de conexão diretamente e facilita a rotação sem editar o projeto.

5. Versão da API: Deixe definido como o valor padrão V1, que é a única versão suportada. (Esta é a versão da API OpenAI da conexão e não está relacionada à atividade Prompt V2 usada posteriormente neste guia.)

6. Clique em Testar para verificar a conexão e, em seguida, clique em Salvar alterações.

Parte 2: Configurar a atividade Prompt V2

A atividade Prompt V2 é um destino: ela consome dados mapeados de uma transformação e os envia para OpenAI usando a API de Respostas do OpenAI.

1. Na paleta de componentes de design, expanda o endpoint OpenAI que você criou. Arraste o tipo de atividade Prompt V2 para a tela de design para criar uma instância de atividade.

2. Clique duas vezes na atividade para abrir sua configuração.

Etapa 1: Digite um nome e especifique as configurações

1. Nome: Digite um nome para a atividade, por exemplo Resumir registro.

2. Chat ID: Deixe em branco para um prompt de uma única volta como o deste guia; um chatId é gerado automaticamente. Para continuar uma conversa existente ou chamar ferramentas registradas por uma atividade anterior Register Tools V2 ou Register MCP Server Tools, digite o chatId dessa atividade aqui.

3. Texto do prompt: Digite o texto do prompt base. Este campo aceita uma string estática ou uma referência de variável. Se o prompt precisar incorporar campos de dados de origem dinamicamente (por exemplo, incluindo uma ID de registro ou valor de campo), deixe este campo como uma instrução geral e substitua-o pelo prompt completo construído na transformação (consulte Parte 3).

Exemplo de prompt estático:

Summarize the following support case in one sentence:

1. Modelo: Selecione o modelo OpenAI a usar. O padrão é gpt-4. Para obter a lista completa de modelos suportados, consulte Conector OpenAI.

2. Configurações opcionais: Clique para expandir:

   • Função: Selecione Usuário para um prompt de usuário padrão. Use Sistema para definir o comportamento do assistente ou Assistente para fornecer respostas de exemplo.
   • Temperatura: Controla a aleatoriedade da resposta. Valores mais próximos de 0 produzem saídas mais determinísticas; valores mais próximos de 2 produzem saídas mais variadas.
   • Máximo de tokens: Limita o comprimento da resposta. Defina isso para evitar conclusões inesperadamente longas.

3. Clique em Próximo.

Etapa 2: Revisar os esquemas de dados

Os esquemas de solicitação e resposta são exibidos. De acordo com a API de Respostas do OpenAI, o esquema de solicitação inclui input, model, max_tokens, temperature e top_p. O esquema de resposta inclui um array output de itens; um item message possui um array content, cada um com um type (output_text para conteúdo gerado) e o text gerado, além de seu próprio campo error por item para itens como chamadas de ferramentas.

Clique em Concluído para salvar a configuração da atividade.

Parte 3: Mapear dados de origem para o prompt em uma transformação

Na transformação que precede a atividade Prompt V2, mapeie os campos de origem para o esquema de solicitação da atividade Prompt V2.

O campo mais importante a mapear é input. Use um nó de script para construir a string de prompt completa combinando a instrução estática com valores de campo da origem:

<trans>
"Summarize the following support case in one sentence:\n\n" +
"Subject: " + Source.Subject + "\n" +
"Description: " + Source.Description
</trans>

Onde Source.Subject e Source.Description são campos do esquema de resposta da atividade de origem (por exemplo, campos retornados por uma atividade Query do Salesforce).

Para substituir o modelo definido na configuração da atividade, mapeie o campo model para uma string literal ou uma variável de projeto:

<trans>
$openai_model
</trans>

Parte 4: Acessar a resposta da IA

O esquema de resposta da atividade Prompt V2 está disponível em qualquer transformação dentro da mesma operação ou em uma operação a jusante.

Encadear uma operação a jusante

Configure a ação On Success da operação Prompt V2 para executar uma segunda operação que processa a resposta da IA:

1. Abra as configurações da operação Prompt V2.

2. Na guia Ações, defina a ação On Success como Executar Operação e selecione a operação a jusante.

Para obter mais informações sobre encadeamento de operações, consulte Configurar tratamento de erros em operações.

Ler o texto gerado

Na transformação da operação a jusante, o esquema de resposta da atividade Prompt V2 fornece o texto gerado pela IA aninhado em output. De acordo com a API de Respostas do OpenAI, mapeie o campo de destino para o texto do primeiro item de saída:

<trans>
Source.output[0].content[0].text
</trans>

Por exemplo, mapeie este campo para um campo text de mensagem do Slack para postar o resumo da IA em um canal (consulte Enviar uma notificação do Slack de uma operação do Studio) ou mapeie-o para um campo de banco de dados para armazenar o resultado.

Verificar erros

Cada item no array output tem seu próprio campo error, preenchido quando esse item específico falha (por exemplo, uma chamada de ferramenta com falha). Adicione um nó de script à transformação que verifica output[0].error e chama RaiseError se estiver preenchido:

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

Verificar a integração

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

2. Nos logs da operação, confirme que a atividade Prompt V2 foi concluída com sucesso e que a operação downstream foi acionada.

3. Inspecione o log da operação downstream para verificar se output[0].content[0].text contém uma resposta válida gerada por IA.

4. Se a atividade Prompt V2 falhar com um erro de autenticação, verifique a chave de API na conexão OpenAI e confirme se ela não foi revogada em sua conta OpenAI.

Para padrões de IA mais avançados baseados nessa base, consulte Processar documentos com IA, Rotear respostas de LLM para operações do Studio usando chamadas de função e Criar um chat LLM multi-turno com histórico de conversa.