Usar Azure OpenAI em uma operação do Studio no Jitterbit Studio

Introdução

O conector do 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 ao Azure OpenAI usando a atividade Prompt e rotear a resposta da IA para um destino downstream, como um banco de dados, um arquivo ou um canal de notificação.

Diferentemente do conector OpenAI, o conector do Azure OpenAI se autentica usando uma URL de endpoint de recurso do Azure e uma chave de API, em vez de uma chave de conta do OpenAI, e os modelos são selecionados entre os deployments no seu recurso do Azure OpenAI, em vez de uma lista fixa.

Padrão de design

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

A atividade de origem fornece os dados usados para construir o prompt (por exemplo, um resultado de consulta de 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 ao Azure 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, escrevê-lo em um campo de banco de dados ou postá-lo 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 na paleta de componentes de design.

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

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

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

5. Chave de API/Segredo: Digite a chave de API para seu recurso do Azure OpenAI. Você pode encontrá-la no Portal do Azure no mesmo local: use o valor do campo CHAVE 1 ou CHAVE 2.

   Dica

   Armazene a chave de API como uma variável de projeto com seu valor oculto e, em seguida, faça referência à 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.

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

   • Armazenar contexto de conversa entre operações: (Apenas grupos de agentes na nuvem.) Permite que o conector mantenha o histórico de conversas entre operações no mesmo ambiente que compartilham o mesmo chatId. Use isso quando operações posteriores precisarem fazer referência a 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 Teste para verificar a conexão e depois clique em Salvar alterações.

Parte 2: Configurar a atividade Prompt

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

1. Na paleta de componentes de design, expanda o endpoint do Azure OpenAI que você criou. Arraste o tipo de atividade Prompt 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 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 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:

   Analyze the sentiment of the following customer review:
   

3. ID do modelo: Selecione o modelo Azure OpenAI a usar. A lista mostra apenas modelos implantados no seu recurso Azure OpenAI. Clique em Refresh para atualizar a lista se tiver implantado novos modelos desde que abriu esta configuração. Para informações sobre como implantar modelos, veja a documentação da Microsoft.

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

   • Role: Controla o tipo de prompt enviado ao Azure OpenAI. O padrão é System, apropriado para prompts automatizados e não interativos. Use User para simular um prompt direto do usuário. Para orientação sobre as funções Assistant e Tool, veja Atividade Prompt do Azure OpenAI.
   • Temperature: 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 Top Probability.
   • Max Tokens: Limita o comprimento da resposta. O padrão é 16. Defina isto para evitar conclusões inesperadamente longas.
   • Top Probability: Uma alternativa a Temperature para controlar a diversidade da saída. Não é recomendável usar esta configuração junto com Temperature.

5. Clique em Next.

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 Finished 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 mapear é prompt. Use um nó de script para construir a string de prompt completa combinando a instrução estática com valores de 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 do 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 a jusante.

Encadear uma operação a jusante

Configure a ação On Success 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 Actions, defina a ação On Success como Run Operation e selecione a operação a jusante.

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

Ler o texto gerado

O conector Azure OpenAI usa a API Chat Completion, que retorna o texto gerado pela IA em choices[0].message.content. Na transformação da operação a jusante, 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 de IA em um canal (consulte Enviar uma notificação do Slack de uma operação do Studio).

Verificar 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 limite de tokens excedido), os detalhes do erro aparecem em errors[0].message. Para exibi-los no log de operação, adicione um nó de script à transformação que chama RaiseError quando errors é preenchido:

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

Verificar a integração

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

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

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

4. Se a atividade Prompt falhar com um erro de autenticação, verifique a URL do endpoint e a chave de API na conexão 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 com base nessa fundação, consulte Processar documentos com IA e Rotear respostas LLM para operações do Studio usando chamadas de função.