Ir para o conteúdo

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 a OpenAI e recebam texto gerado por IA em retorno. Este guia aborda o padrão comum de construir um prompt da OpenAI a partir de dados de origem, enviá-lo para a OpenAI usando a atividade Prompt V2 e depois rotear a resposta da 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 a OpenAI segue o padrão de transformação:

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Source activity] --> B[Transformation] --> C[OpenAI Prompt V2 activity] C -->|On Success| D["Transformation
Map AI response"] --> E[Target activity]

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

Uma segunda operação, encadeada no sucesso da primeira, usa uma transformação para ler a resposta da IA e rotear o texto gerado para a atividade de destino (por exemplo, postá-lo em um canal do Slack ou escrevê-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 Project endpoints and connectors na paleta do componente de design.

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

  3. Connection Name: Digite um nome que identifique essa conexão, por exemplo OpenAI.

  4. API/Secret Key: Digite sua chave de API da 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. API Version: Mantenha essa opção definida como o valor padrão V1, que é a única versão compatível. (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 Test para verificar a conexão e depois clique em Save Changes.

Parte 2: Configurar a atividade Prompt V2

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

  1. Na paleta do componente de design, expanda o endpoint da 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: Inserir um nome e especificar configurações

  1. Name: Digite um nome para a atividade, por exemplo Summarize Record.

  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 Register Tools V2 ou Register MCP Server Tools anterior, insira o chatId dessa atividade aqui.

  3. Prompt text: 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, incluir uma ID de registro ou valor de campo), deixe este campo como uma instrução geral e substitua-o pelo prompt construído completo na transformação (veja Parte 3).

    Exemplo de prompt estático:

    Summarize the following support case in one sentence:
    
  4. Modelo: Selecione o modelo OpenAI a usar. O padrão é gpt-4. Para obter uma lista completa de modelos suportados, consulte conector OpenAI.

  5. 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.
    • Max Tokens: Limita o comprimento da resposta. Defina isso para evitar conclusões inesperadamente longas.
  6. 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 ferramenta.

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 completo 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 de Consulta 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>

Dica

Não é necessário mapear cada campo do esquema de solicitação. Os campos não mapeados usam os valores configurados na própria atividade Prompt V2. Mapeie apenas os campos que precisam variar com base nos dados de origem.

Parte 4: Acessar a resposta de 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 downstream.

Encadear uma operação downstream

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

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

  2. Na aba Ações, defina a ação On Success para Executar Operação e selecione a operação downstream.

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 downstream, o esquema de resposta da atividade Prompt V2 fornece o texto gerado por IA aninhado sob 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 esse campo para um campo text de mensagem do Slack para postar o resumo de 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.

Nota

A atividade Prompt V2 usa a API de Respostas do OpenAI, que aninha o texto gerado sob output em vez de sob choices como na API Chat Completions do OpenAI. A atividade Prompt (Descontinuada) descontinuada e o conector Azure OpenAI usam a API Chat Completions e retornam choices[0].message.content.

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. Implantar e executar a operação Prompt V2 manualmente.

  2. Nos logs de 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 gerada por IA válida.

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

Dica

Para agendar a operação para ser executada automaticamente, consulte Agendar uma operação para ser executada automaticamente.

Para padrões de IA mais avançados construídos nesta base, consulte Processar documentos com IA, Rotear respostas LLM para operações do Studio usando chamadas de função e Criar um chat LLM multiturno com histórico de conversa.