Use Azure OpenAI em uma operação no Jitterbit Studio

Introdução

O conector Azure OpenAI permite que operações do Studio enviem dados para um modelo de linguagem hospedado no Azure e recebam texto gerado por IA em troca. Este guia cobre o padrão comum de construir um prompt a partir de dados de origem, enviá-lo para o Azure OpenAI usando a atividade Prompt e, em seguida, direcionar a resposta da IA para um alvo downstream, como um banco de dados, um arquivo ou um canal de notificação.

Diferentemente do conector OpenAI, o conector Azure OpenAI autentica usando uma URL de endpoint de recurso do Azure e uma chave de API, em vez de uma chave de conta OpenAI, e os modelos são selecionados a partir das implantações em seu recurso Azure OpenAI, em vez de uma lista fixa.

Padrão de design

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

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

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

Parte 1: Configurar a conexão do Azure OpenAI

1. No Studio, abra seu projeto e clique na aba Endpoints e conectores do projeto no painel de componentes de design.

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

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

4. Endpoint: Insira a URL do endpoint para o seu recurso Azure OpenAI. Você pode encontrá-la no Portal do Azure em Gerenciamento de Recursos > Chaves e Endpoint na barra lateral esquerda.

5. Chave da API/Chave Secreta: Insira a chave da API para o seu recurso Azure OpenAI. Você pode encontrá-la no Portal do Azure na mesma localização: use o valor do campo CHAVE 1 ou CHAVE 2.

   Dica

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

6. Configurações Opcionais: Clique para expandir. Duas configurações são relevantes para casos de uso comuns:

   • Armazenar contexto de chat entre operações: (apenas grupos de agentes em nuvem.) Permite que o conector mantenha o histórico da conversa entre operações no mesmo ambiente que compartilham o mesmo chatId. Use isso quando operações posteriores precisarem referenciar turnos anteriores em uma conversa.
   • Adicionar uma fonte de dados: Conecta uma instância do Azure AI Search ou Azure Cosmos DB para MongoDB (vCore) para que as respostas do Azure OpenAI sejam fundamentadas em seus próprios dados.

7. Clique em Testar para verificar a conexão, depois clique em Salvar Alterações.

Parte 2: Configurar a atividade Prompt

A atividade Prompt é um alvo: ela consome dados mapeados de uma transformação e os envia para o Azure OpenAI.

1. No painel de componentes de design, expanda o endpoint Azure OpenAI que você criou. Arraste o tipo de atividade Prompt para a tela de design para criar uma instância da atividade.

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

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

1. Nome: Insira um nome para a atividade, por exemplo Analisar Sentimento.

2. Texto do prompt: Insira o texto base do prompt. Se o prompt precisar incorporar campos de dados de origem dinamicamente (por exemplo, incluindo o texto de uma avaliação de cliente ou uma descrição de caso de suporte), insira a instrução estática aqui e construa o prompt completo na transformação (veja Parte 3).

   Exemplo de prompt estático:

   Analise o sentimento da seguinte avaliação de cliente:
   

3. ID do Modelo: Selecione o modelo Azure OpenAI a ser utilizado. A lista mostra apenas modelos implantados em seu recurso Azure OpenAI. Clique em Atualizar para atualizar a lista se você implantou novos modelos desde que abriu esta configuração. Para informações sobre como implantar modelos, consulte a documentação da Microsoft.

4. Configurações Opcionais: Clique para expandir:

   • Função: Controla o tipo de prompt enviado ao Azure OpenAI. O padrão é Sistema, que é apropriado para prompts automatizados e não interativos. Use Usuário para simular um prompt direto do usuário. Para orientações sobre as funções Assistente e Ferramenta, veja atividade de prompt do Azure OpenAI.
   • 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. Não é recomendável usar esta configuração junto com Probabilidade Máxima.
   • Máx Tokens: Limita o comprimento da resposta. O padrão é 16. Defina isso para evitar conclusões inesperadamente longas.
   • Probabilidade Máxima: Uma alternativa à Temperatura para controlar a diversidade da saída. Não é recomendável usar esta configuração junto com Temperatura.

5. Clique em Próximo.

Etapa 2: Revisar os esquemas de dados

Os esquemas de solicitação e resposta são exibidos. O esquema de solicitação inclui prompt, model, max_tokens, temperature e top_p. O esquema de resposta inclui choices (um array contendo o texto gerado, index e finish_reason), usage (contagens de tokens) e errors.

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, mapeie os campos de origem para o esquema de solicitação da atividade Prompt.

O campo mais importante a ser mapeado é prompt. Use um nó de script para construir a string completa do prompt, combinando a instrução estática com os valores dos campos da origem:

<trans>
"Analyze the sentiment of the following customer review:\n\n" +
Source.ReviewText
</trans>

Onde Source.ReviewText é um campo do esquema de resposta da atividade de origem (por exemplo, um campo retornado por uma atividade Query de banco de dados).

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>
$azure_openai_model
</trans>

Parte 4: Acessar a resposta da IA

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

Encadear uma operação subsequente

Configure a ação Em Sucesso da operação Prompt para executar uma segunda operação que processa a resposta da IA:

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

2. Na aba Ações, defina a ação Em Sucesso como Executar Operação e selecione a operação subsequente.

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

Ler o texto gerado

O conector Azure OpenAI utiliza a API de Chat Completion, que retorna o texto gerado pela IA em choices[0].message.content. Na transformação da operação subsequente, mapeie este campo para o destino:

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

Por exemplo, mapeie choices[0].message.content para um campo de banco de dados para armazenar o resultado, ou para um campo text de mensagem do Slack para postar a resposta da IA em um canal (veja Enviar uma notificação do Slack a partir de uma operação do Studio).

Verifique se há erros

O esquema de resposta também inclui um array errors. Se o Azure OpenAI retornar um erro (por exemplo, devido a um nome de implantação de modelo inválido ou um limite de token excedido), os detalhes do erro aparecem em errors[0].message. Para exibir esses detalhes no log da operação, adicione um nó de script à transformação que chama RaiseError quando errors estiver populado:

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

Verifique a integração

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

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

3. Inspecione o log da operação subsequente para verificar se choices[0].message.content contém uma resposta válida gerada pela IA.

4. Se a atividade Prompt falhar com um erro de autenticação, verifique a URL do endpoint e a chave da API na conexão do Azure OpenAI e confirme se a chave não foi rotacionada no Portal do Azure.

Para padrões de IA mais avançados construídos sobre esta base, veja Processar documentos com IA e Roteie respostas LLM para operações do Studio usando chamada de função.