Usar chamadas de função do SAP com o Gemini

Este documento descreve como usar a chamada de função SAP com a Gemini, usando o SDK da Vertex AI para ABAP.

É possível definir funções personalizadas e fornecê-las aos modelos do Gemini usando o recurso Chamada de função. Os modelos não invocam diretamente as funções personalizadas, mas geram uma saída de dados estruturados que especifica o nome da função e os argumentos sugeridos. Essa saída permite que você escreva apps que usam a saída estruturada e chamam APIs externas. A saída da API resultante pode ser incorporada a outro comando de modelo, permitindo respostas de consulta mais abrangentes.

O SDK da Vertex AI para ABAP simplifica a chamada de função para desenvolvedores ABAP, oferecendo oportunidades para invocar a lógica personalizada escrita em módulos de função do SAP:

  • Transmitir nomes de módulo de função SAP ao modelo como declarações de função, descrevendo o nome da função, a finalidade dela e os parâmetros relacionados.
  • Definir a invocação automática do módulo de função SAP implicitamente ao invocar o modelo.

Confira a seguir a jornada típica de um desenvolvedor ABAP para invocar a chamada de função do SAP:

  1. O usuário fornece uma solicitação de entrada.
  2. O SDK transmite o comando de entrada e as declarações de função para o modelo.
  3. O modelo analisa o comando e as funções declaradas para derivar a função a ser chamada e sugere os valores de parâmetro para chamar a função.
  4. Se a invocação automática estiver definida, o SDK vai chamar o módulo de função SAP.
  5. Em seguida, o SDK invoca o modelo com a saída da função chamada.
  6. O modelo responde com uma resposta confiável para o comando final enriquecido com a saída da função chamada.
  7. O SDK retorna a resposta para o usuário.

Chamada de função do SAP com o Gemini

Se você optar por não invocar automaticamente os módulos de função do SAP, o SDK permitirá que você use o recurso de chamada de função sem nenhuma invocação de módulo de função do SAP. Nesse caso, siga o fluxo de trabalho típico de chamadas de função para usar ferramentas externas, como APIs e funções.

Antes de começar

Antes de usar o SDK da Vertex AI para ABAP para chamar funções SAP com o Gemini, verifique se você ou seus administradores concluíram os seguintes pré-requisitos:

Enriquecer o contexto do modelo de IA do Gemini com dados do SAP

Esta seção explica como enriquecer o contexto do modelo da IA Gemini com dados da SAP usando o SDK da Vertex AI para ABAP.

Criar a classe de invocação multimodal do Gemini

Para invocar a chamada de função no SAP, use a classe /GOOG/CL_GENERATIVE_MODEL. Você instancia a classe transmitindo a chave de modelo configurada nos parâmetros de geração de modelos.

DATA(lo_model) = NEW /goog/cl_generative_model( iv_model_key = 'MODEL_KEY' ).

Substitua MODEL_KEY pelo nome da chave do modelo, que é configurado nos parâmetros de geração de modelo.

Criar um módulo de função SAP

Para criar um módulo de função do SAP para invocação automática pelo SDK, siga o esquema fornecido:

Categoria Nome do parâmetro Tipo associado
Importando IT_FUNCTION_PARAMETERS /GOOG/T_FUNCTION_PARAMETERS
Exportando EV_FUNCTION_RESPONSE STRING
Alterando CV_PROMPT STRING
Exceções /GOOG/CX_SDK Exception Class

Com base nos parâmetros de importação, escreva sua lógica personalizada no módulo de função, que pode buscar dados SAP por meio de consultas SELECT ou chamar uma API ou um módulo externo para receber as informações ausentes.

Defina o parâmetro de exportação EV_FUNCTION_RESPONSE com as informações para feedback ao contexto do LLM. Também é possível mudar ou modificar o texto do comando em CV_PROMPT com base na lógica personalizada e no requisito de negócios para instruir o LLM com base em diferentes cenários de negócios.

Adicionar declaração de função

Para adicionar uma declaração de função ao contexto da LLM, use o método ADD_FUNCTION_DECLARATION. Chame o método ADD_FUNCTION_DECLARATION sempre que precisar adicionar uma função ao contexto.

DATA lt_parameters TYPE /goog/cl_generative_model=>tt_parameter_properties.
APPEND VALUE #( parameter_name = 'PARAMETER_NAME'
                type           = 'PARAMETER_TYPE'
                description    = 'PARAMETER_DESCRIPTION'
                is_required    = 'PARAMETER_IS_REQUIRED' ) TO lt_parameters.
lo_model->add_function_declaration( iv_name        = 'FUNCTION_MODULE_NAME'
                                    iv_description = 'FUNCTION_MODULE_DESCRIPTION'
                                    it_parameters  = lt_parameters ).

Substitua:

  • PARAMETER_NAME: nome do parâmetro.
  • PARAMETER_TYPE: o tipo de dados do parâmetro, como string, integer ou boolean.
  • PARAMETER_DESCRIPTION: uma explicação clara da finalidade e do formato esperado do parâmetro.
  • PARAMETER_IS_REQUIRED: se esse parâmetro for obrigatório para a função funcionar, defina o valor como ABAP_TRUE.
  • FUNCTION_MODULE_NAME: nome do módulo de função da SAP.
  • FUNCTION_MODULE_DESCRIPTION: descrição do módulo de função do SAP.

Também é possível declarar uma função sem parâmetros, que pode servir como uma função de substituição ou de backup. Se uma solicitação do usuário não fornecer informações suficientes para chamar uma função específica, você poderá instruir o Gemini a selecionar essa função substituta.

Definir a invocação automática do módulo de função SAP

Para definir a invocação automática da função SAP selecionada pelo modelo, use o método SET_AUTO_INVOKE_SAP_FUNCTION. Se ABAP_TRUE for transmitido no parâmetro de importação IV_AUTO_INVOKE, o módulo de função será invocado pelo SDK e a resposta dele será incluída com o contexto do LLM para gerar a resposta final.

Defina o módulo de função seguindo o esquema descrito na seção Criar módulo de função do SAP.

lo_model->set_auto_invoke_sap_function( abap_true ).

Gerar conteúdo com chamadas de função

Para transmitir o texto do comando ao modelo Gemini, use o método GENERATE_CONTENT. Para receber a resposta gerada pelo Gemini com o contexto adicional adicionado do módulo de função SAP por meio de chamadas de função, use o método GET_TEXT.

DATA(lv_response) = lo_model->generate_content( iv_prompt_text ='PROMPT'
                           )->get_text( ).

Substitua PROMPT pelo comando de texto.

Conseguir o nome da função selecionada e os valores do parâmetro

Para receber a função selecionada pelo Gemini (entre as funções declaradas) e os parâmetros sugeridos, use o método GET_FUNCTION_CALL.

DATA(lo_response) = lo_model_key->set_auto_invoke_sap_function( abap_true
                               )->generate_content( iv_prompt_text = 'PROMPT' ).
lo_response->get_function_call( IMPORTING ev_function_name       = DATA(lv_function_name)
                                          et_function_parameters = DATA(lt_function_parameters) ).

Substitua PROMPT pelo comando de texto.

É possível conferir o nome da função selecionada do Gemini em LV_FUNCTION_NAME e os parâmetros sugeridos em LT_FUNCTION_PARAMETERS. Você pode usar essas informações para validar, acompanhar e registrar ações do Gemini de acordo com as diretrizes de informações de segurança e gerenciamento de eventos da sua empresa.

Exemplo de código

O exemplo de código abaixo ilustra como usar a chamada de função SAP para receber uma resposta final do modelo.

DATA lt_parameters TYPE /goog/cl_generative_model=>tt_parameter_properties.
TRY.
  DATA(lo_model) = NEW /goog/cl_generative_model( iv_model_key = 'MODEL_KEY' ).
  APPEND VALUE #( parameter_name = 'PARAMETER_NAME'
                  type           = 'PARAMETER_TYPE'
                  description    = 'PARAMETER_DESCRIPTION'
                  is_required    = 'PARAMETER_IS_REQUIRED' ) TO lt_parameters.
  DATA(lv_response) = lo_model->add_function_declaration(
                                    iv_name        = 'FUNCTION_MODULE_NAME'
                                    iv_description = 'FUNCTION_MODULE_DESCRIPTION'
                                    it_parameters  = lt_parameters
                              )->set_auto_invoke_sap_function( abap_true
                              )->generate_content( iv_prompt_text ='PROMPT'
                              )->get_text( ).
  IF lv_response IS NOT INITIAL.
      cl_demo_output=>display( lv_response ).

  ENDIF.
 CATCH /goog/cx_sdk INTO DATA(lo_cx_sdk).
  cl_demo_output=>display( lo_cx_sdk->get_text( ) ).

ENDTRY.

Substitua:

  • MODEL_KEY: o nome da chave do modelo, que é configurado nos parâmetros de geração de modelos.
  • PARAMETER_NAME: nome do parâmetro.
  • PARAMETER_TYPE: o tipo de dados do parâmetro, como string, integer ou boolean.
  • PARAMETER_DESCRIPTION: uma explicação clara da finalidade e do formato esperado do parâmetro.
  • PARAMETER_IS_REQUIRED: se esse parâmetro for obrigatório para a função funcionar, defina o valor como ABAP_TRUE.
  • FUNCTION_MODULE_NAME: nome do módulo de função da SAP.
  • FUNCTION_MODULE_DESCRIPTION: descrição do módulo de função do SAP.
  • PROMPT: o texto do comando.

Encadeamento automático de funções

O recurso de encadeamento automático de funções permite invocar vários módulos de função definidos pelo usuário para gerar uma resposta. Esse recurso só é compatível quando a invocação automática de módulos de função SAP está ativada.

O exemplo de código a seguir ilustra a vinculação automática de funções. Para o comando Get the air quality in my current location, a API Gemini primeiro invoca o módulo de função Z_GET_CURRENT_LOCATION para receber as informações de longitude e latitude e, em seguida, transmite essas informações para o módulo de função Z_GET_CURRENT_AIR_QUALITY para receber a qualidade do ar para os pontos de longitude e latitude fornecidos.

gv_prompt = 'Get the air quality in my current location'.

  gv_system_instruction = 'You are a helpful weather assistant bot. You can turn find my location and get the weather information like temperature' &&
  'You can also alert me about EarthQuakes and Storm.' &&
  'You can also provide me information on Air Quality based on a location' &&
  'Do not perform any other tasks.'.

  TRY.

      DATA(lo_model_key) = NEW /goog/cl_generative_model( iv_model_key = 'gemini-flash-2' ).

      gv_final_op = lo_model_key->gs_ai_config-model_id.

      lo_model_key->add_function_declaration( iv_name        = 'Z_GET_CURRENT_LOCATION'
                                              iv_description = 'Get the current location'
                                              it_parameters  = gt_parameters ).
      CLEAR gt_parameters.

      gs_parameter-parameter_name = |Latitude|.
      gs_parameter-type = 'string'.
      gs_parameter-description = |Latitude|.
      gs_parameter-is_required = abap_true.

      APPEND gs_parameter TO gt_parameters.
      CLEAR gs_parameter.

      gs_parameter-parameter_name = |Longitude|.
      gs_parameter-type = 'string'.
      gs_parameter-description = |Longitude|.
      gs_parameter-is_required = abap_true.

      APPEND gs_parameter TO gt_parameters.
      CLEAR gs_parameter.

      lo_model_key->add_function_declaration( iv_name        = 'Z_GET_WEATHER_INFORMATION'
                                              iv_description = 'Gets weather information like temperature for a given location which is latitude and longitude'
                                              it_parameters  = gt_parameters ).


      lo_model_key->add_function_declaration( iv_name        = 'Z_GET_CURRENT_AIR_QUALITY'
                                              iv_description = 'Gets weather information like temperature for a given location which is latitude and longitude'
                                              it_parameters  = gt_parameters ).


      lo_model_key->add_function_declaration( iv_name        = 'GET_EARTHQUAKE_POSSIBILITY'
                                              iv_description = 'Gets possibility of Earthquake for a given location which is latitude and longitude'
                                              it_parameters  = gt_parameters ).


      lo_model_key->add_function_declaration( iv_name        = 'GET_STORM_POSSIBILITY'
                                              iv_description = 'Gets possibility of a STORM for a given location which is latitude and longitude'
                                              it_parameters  = gt_parameters ).

      lo_model_key->set_system_instructions(
        EXPORTING
          iv_text = gv_system_instruction
      ).

      DATA(lo_response) = lo_model_key->set_auto_invoke_sap_function( abap_true
                                     )->generate_content( iv_prompt_text = gv_prompt ).

      DATA(ls_response) = lo_response->get_response( ).
      /ui2/cl_json=>serialize(
        EXPORTING
          data   = ls_response-candidates[ 1 ]-content-parts           " Data to serialize
        RECEIVING
          r_json = DATA(lv_json_string)                 " JSON string
      ).
      IF lv_json_string IS NOT INITIAL.
        CLEAR gv_output.
        gv_output = lv_json_string.

      ENDIF.

    CATCH /goog/cx_sdk INTO DATA(lo_cx_sdk).
      cl_demo_output=>display( lo_cx_sdk->get_text( ) ).
  ENDTRY.

  lo_model_key->close( ).
  CLEAR lo_model_key.
  CLEAR lo_response.
  CLEAR ls_response.

Para desativar a vinculação automática de funções e receber apenas a resposta da primeira função do LLM, use o método SET_FUNCTION_CALLING_CONFIG e defina o parâmetro IV_DISABLE_FUNCTION_CHAINING como ABAP_TRUE. Exemplo:


      lo_model_key->set_function_calling_config( iv_disable_function_chaining = abap_true ).
      DATA(lo_response) = lo_model_key->set_auto_invoke_sap_function( abap_true
                                     )->generate_content( iv_prompt_text = gv_prompt ).

Se você quiser receber todos os módulos de função invocados pelo SDK e os parâmetros transmitidos a eles, chame o método GET_ALL_FUNCTION_CALLS:

      DATA(lo_response) = lo_model_key->set_auto_invoke_sap_function( abap_true
                                     )->generate_content( iv_prompt_text = gv_prompt ).

      DATA(ls_response) = lo_response->get_all_function_calls( ).

A seguir