Usar chamadas de função do SAP com modelos hospedados na Vertex AI

Este documento descreve como usar a chamada de função do SAP com os seguintes modelos hospedados da Vertex AI usando o SDK da Vertex AI para ABAP:

É possível definir funções personalizadas e fornecê-las aos modelos do Gemini e do Claude 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. Com essa saída, é possível escrever aplicativos que usam a saída estruturada e chamam APIs externas. A saída da API resultante pode ser incorporada a um novo 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 SAP:

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

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

  1. O usuário fornece um comando de entrada.
  2. O SDK transmite o comando de entrada e as declarações de função ao 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 do 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 ao 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á usar o recurso de chamada de função sem invocar nenhum módulo de função do SAP. Nesse caso, siga o fluxo de trabalho típico de chamada 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 chamadas de função do SAP com o Gemini, verifique se você ou seus administradores concluíram os seguintes pré-requisitos:

Para o Gemini:

Para o Claude:

Enriqueça o contexto do modelo de IA com dados da SAP

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

Instanciar a classe de invocador multimodal

Para invocar a chamada de função no SAP com os modelos do Gemini , use a classe /GOOG/CL_GENERATIVE_MODEL.

Para invocar a chamada de função no SAP com os modelos do Claude , use a classe /GOOG/CL_MODEL_CLAUDE.

Para instanciar a classe, transmita a chave do modelo configurada nos parâmetros de geração de modelos.

Gemini

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

Claude

DATA(lo_model) = NEW /goog/cl_model_claude( 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 do 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 do SAP usando 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 enviar feedback ao contexto do LLM. Você também pode mudar ou modificar o texto do comando em CV_PROMPT com base na lógica personalizada e na exigência da sua empresa para instruir ainda mais 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.

Gemini

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 ).

Claude

DATA lt_parameters TYPE /goog/cl_model_claude=>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 o funcionamento da função, defina o valor como ABAP_TRUE.
  • FUNCTION_MODULE_NAME: nome do módulo de função 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 backup. Se um comando do usuário não fornecer informações suficientes para chamar uma função específica, você pode instruir o modelo a selecionar essa função alternativa.

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 no 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 a um modelo, use o método GENERATE_CONTENT. Para receber a resposta gerada pelo modelo com o contexto adicional adicionado do módulo de função SAP usando a chamada 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 seu comando de texto.

Receber o nome da função selecionada e os valores de parâmetro

Para receber a função selecionada pelo modelo (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 seu comando de texto.

Você pode acessar o nome da função selecionada em LV_FUNCTION_NAME e os parâmetros sugeridos em LT_FUNCTION_PARAMETERS. Você pode usar essas informações para validar, rastrear e registrar as ações do modelo de acordo com as diretrizes de gerenciamento de eventos e informações de segurança da empresa.

Exemplo de código

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

Gemini

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.

Claude

DATA lt_parameters TYPE /goog/cl_model_claude=>tt_parameter_properties.
TRY.
DATA(lo_model) = NEW /goog/cl_model_claude( 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 modelo.
  • 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 o funcionamento da função, defina o valor como ABAP_TRUE.
  • FUNCTION_MODULE_NAME: nome do módulo de função SAP.
  • FUNCTION_MODULE_DESCRIPTION: descrição do módulo de função do SAP.
  • PROMPT: seu comando de texto.

Encadeamento automático de funções

Com o recurso de encadeamento automático de funções, é possível 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 do SAP está ativada.

O exemplo de código a seguir ilustra o encadeamento automático de funções. Para o comando Get the air quality in my current location, o modelo 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 ao módulo de função Z_GET_CURRENT_AIR_QUALITY para receber a qualidade do ar dos pontos de longitude e latitude especificados.

Gemini

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.

Claude

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//goog/cl_model_claude( iv_model_key = 'claude' ).
    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 o encadeamento automático 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 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