Criar e executar extens�es

As extens�es s�o conex�es com APIs externas. Elas podem processar dados em tempo real e se conectar a APIs externas para realizar a��es reais. A Vertex AI fornece um servi�o de extens�o que pode importar, gerenciar e executar extens�es.

Esse servi�o de extens�o pode ser vinculado a um aplicativo que processa consultas do usu�rio e se comunica com um LLM. O servi�o de extens�o pode fornecer ao aplicativo um conjunto de extens�es e as opera��es que as extens�es podem executar. Sempre que o aplicativo recebe uma consulta do usu�rio, ele fornece essas informa��es ao LLM. Se o modelo determinar que precisa delegar o processamento de consultas a uma extens�o, ele fornecer� uma chamada de extens�o solicitada e os valores de par�metro associados. O aplicativo redireciona essa solicita��o para o servi�o de extens�o, que a executa. Por fim, o servi�o de extens�o envia o resultado dessa opera��o ao aplicativo, que o retransmite ao modelo.

Este documento mostra a principal funcionalidade do servi�o de extens�o da Vertex AI:

• Como criar e importar extens�es.
• Como gerenciar extens�es.
• Como executar extens�es.

Para saber como importar e executar uma extens�o fornecida pelo Google, consulte:

• Use a extens�o int�rprete de c�digo para gerar e executar c�digo.
• Use a extens�o Vertex AI para Pesquisa para acessar e pesquisar corpus de sites e dados n�o estruturados para fornecer respostas relevantes a perguntas de linguagem natural.

Criar e importar extens�es

Este documento pressup�e que voc� j� tenha um servi�o de API em execu��o que possa oferecer suporte a uma extens�o. Para criar uma extens�o, � necess�rio definir a interface com uma API externa em um arquivo de especifica��o da API. Fa�a o upload desse arquivo de especifica��o em um bucket do Cloud Storage ou converta-o em uma string. Em seguida, defina um manifesto de extens�o, inclua o arquivo de especifica��o e envie uma solicita��o de registro para o servi�o de extens�o.

Criar um arquivo de especifica��o de API

Uma extens�o pode ser criada por qualquer pessoa usando arquivos que definem e descrevem os endpoints de API das extens�es. Os endpoints da API podem ser p�blicos ou privados e hospedados em qualquer nuvem ou no local.

Um arquivo de especifica��o de API descreve a interface de um servi�o de API. Forne�a um arquivo de especifica��o da API no formato YAML compat�vel com a OpenAPI 3.0. Esse arquivo de especifica��o precisa definir o seguinte:

• Um objeto de servidor. Esse objeto precisa definir um URL do servidor da API. O servi�o de extens�o da Vertex AI n�o oferece suporte a v�rios servidores.

  servers:
    - url: API_SERVICE_URL
  

• Um objeto de caminhos. Esse objeto precisa descrever as v�rias opera��es fornecidas pelo servi�o da API e os par�metros de entrada que correspondem a cada opera��o. Cada opera��o precisa ter um identificador exclusivo e uma resposta.

  paths:
    ...
      get:
        operationId: API_SERVICE_OPERATION_ID
        ...
        parameters:
          - name: API_SERVICE_INPUT_VAR
            ...
        responses:
        ...
  

• Um objeto "components". Esse objeto � opcional. Voc� pode usar o objeto de componentes para definir objetos reutiliz�veis. Por exemplo, � poss�vel usar o objeto de componentes para fornecer uma defini��o dos esquemas de objetos definidos no objeto de caminhos. Voc� tamb�m pode usar o objeto de componentes para descrever os par�metros de sa�da do servi�o da API.

  components:
    schemas:
      Result:
        ...
        properties:
          API_SERVICE_OUTPUT_VAR:
          ...
  

Para saber mais sobre a OpenAPI, consulte a Especifica��o da OpenAPI.

O exemplo a seguir � um arquivo de especifica��o de API para um servi�o de API que diz "hello" no idioma solicitado:

  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: Hello Extension
    description: Learn to build Vertex AI extensions
  servers:
    - url: [API_SERVICE_URL]
  paths:
    /hello:
      get:
        operationId: "say_hello"
        description: "Say hello in prompted language."
        parameters:
          - name: "apiServicePrompt"
            in: query
            description: "Language"
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Successful operation.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Result"
  components:
    schemas:
      Result:
        description: "Hello in the requested language."
        properties:
          apiServiceOutput:
            type: string

Fazer upload do arquivo de especifica��o

Fa�a upload do arquivo de especifica��es para um bucket do Cloud Storage ou converta-o em uma string.

Se voc� fizer upload do arquivo de especifica��o em um bucket do Cloud Storage, conceda � conta de servi�o Vertex AI Extension Service Agent (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com) o papel de Leitor de objetos do Storage. Para saber como listar os buckets no seu projeto, consulte Como listar buckets. Para aprender a copiar um objeto para um bucket do Cloud Storage, consulte Copiar, renomear e mover objetos.

Definir uma solicita��o de importa��o de extens�o

Depois de criar um arquivo de especifica��o de API, voc� pode definir uma solicita��o de importa��o de extens�o em um arquivo JSON. Uma solicita��o de importa��o de extens�o precisa conter uma refer�ncia ao seu arquivo de especifica��o da API (apiSpec) e � configura��o de autentica��o (authConfig). Para conectar a extens�o a um modelo de linguagem grande (LLM) e conferir como a extens�o funciona, inclua o par�metro opcional toolUseExamples. Se voc� quiser apenas executar a extens�o, n�o inclua o par�metro toolUseExamples.

Uma solicita��o de importa��o de extens�o tem o seguinte formato:

{
  "displayName":  "DISPLAY_NAME_HUMAN",
  "description": "DESCRIPTION_HUMAN",
  "manifest": {
    "name": "EXTENSION_NAME_LLM",
    "description": "DESCRIPTION_LLM",
    "apiSpec": { ... },
    "authConfig": { ... },
  }
  "toolUseExamples": [ ... ],
}

• DISPLAY_NAME_HUMAN: o nome da extens�o que � exibido aos usu�rios.
• DESCRIPTION_HUMAN: a descri��o da extens�o que � exibida aos usu�rios.
• EXTENSION_NAME_LLM: o nome da extens�o usada pelo LLM para racioc�nio.
• DESCRIPTION_LLM: a descri��o da extens�o usada pelo LLM para o racioc�nio. Forne�a uma descri��o significativa e informativa.

Refer�ncia ao arquivo de especifica��o da API

Sua solicita��o de importa��o de extens�o precisa conter uma refer�ncia ao seu arquivo de especifica��o da API. Voc� pode fornecer o arquivo de especifica��o de duas maneiras:

• Use openApiGcsUri para transmitir o URI do Cloud Storage do arquivo YAML.

  "apiSpec": {
    "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
  },
  

  • BUCKET_NAME: o nome do bucket do Cloud Storage que armazena o arquivo de especifica��o.
  • SPECIFICATION_FILE_NAME: o nome do arquivo de especifica��o da API.

• Use openApiYaml para transmitir o arquivo YAML como uma string.

Configura��o da autentica��o

As extens�es podem ser p�blicas (dispon�veis para qualquer usu�rio usar) ou privadas (dispon�veis apenas para usu�rios autorizados em uma ou mais organiza��es).

Uma solicita��o de importa��o de extens�o precisa conter uma configura��o de autentica��o. � poss�vel escolher entre os seguintes m�todos de autentica��o:

• NO_AUTH: sem autentica��o
• API_KEY_AUTH: autentica��o com chave de API
• HTTP_BASIC_AUTH: autentica��o b�sica HTTP
• OAUTH: autentica��o do OAuth
• OIDC_AUTH: autentica��o OIDC

Para saber mais sobre as configura��es de autentica��o, consulte Especificar uma configura��o de autentica��o.

Exemplos que demonstram como a extens�o funciona

Para melhores resultados, uma solicita��o de importa��o de extens�o precisa conter exemplos que demonstrem como a extens�o funciona. Use o par�metro toolUseExamples para fornecer esses exemplos.

O c�digo a seguir mostra o formato de toolUseExamples para um �nico exemplo, com um �nico par�metro de entrada e de sa�da. Nesse exemplo, os par�metros de solicita��o e resposta s�o do tipo string.

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "API_SERVICE_OPERATION_ID",
      },
      "displayName": "EXAMPLE_DISPLAY_NAME",
      "query": "EXAMPLE_QUERY",
      "requestParams": {
        "fields": [
          {
            "key": "API_SERVICE_INPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_INPUT",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "API_SERVICE_OUTPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_OUTPUT",
            },
          }
        ],
      },
      "responseSummary": "EXAMPLE_SUMMARY"
    }
],

• query: um exemplo de consulta que pode usar essa extens�o. Use EXAMPLE_QUERY para fornecer o texto da consulta.
• extensionOperation: uma opera��o de extens�o adequada para responder � query. Use API_SERVICE_OPERATION_ID para fornecer o ID de uma opera��o de extens�o definida no arquivo de especifica��o da API.
• displayName: um nome de exibi��o para o exemplo. Use EXAMPLE_DISPLAY_NAME para fornecer uma breve descri��o.
• requestParams: os par�metros de solicita��o necess�rios para extensionOperation e valores de exemplo, no formato de chave-valor. Use API_SERVICE_INPUT_VAR para fornecer um par�metro de entrada definido no arquivo de especifica��o da API e correspondente a API_SERVICE_OPERATION_ID. Use EXAMPLE_INPUT para fornecer um exemplo de um valor de entrada que corresponda a EXAMPLE_QUERY.
• responseParams: os par�metros de resposta de extensionOperation e os valores de exemplo no formato de chave-valor. Use API_SERVICE_OUTPUT_VAR para fornecer um par�metro de sa�da definido no arquivo de especifica��o da API e correspondente ao servi�o da API. Use EXAMPLE_OUTPUT para fornecer um exemplo de um valor de sa�da que corresponde a EXAMPLE_INPUT.
• responseSummary: um exemplo de resumo que o aplicativo pode fornecer em resposta a query. Use EXAMPLE_SUMMARY para fornecer o texto do resumo.

Veja a seguir um exemplo de toolUseExamples para um servi�o de API que diz "hello" no idioma solicitado:

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "say_hello",
      },
      "displayName": "Say hello in the requested language",
      "query": "Say hello in French",
      "requestParams": {
        "fields": [
          {
            "key": "apiServicePrompt",
            "value": {
              "string_value": "French",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "apiServiceOutput",
            "value": {
              "string_value": "bonjour",
            },
          }
        ],
      },
      "responseSummary": "Bonjour"
    }
],

Especificar uma configura��o de autentica��o

� necess�rio especificar uma configura��o de autentica��o ao definir uma solicita��o de importa��o de extens�o.

Se a extens�o n�o exigir autentica��o, defina a vari�vel authType como NO_AUTH:

"authConfig": {
  "authType": "NO_AUTH"
}

Se a extens�o exigir autentica��o, defina o tipo na vari�vel authType e forne�a uma configura��o de autentica��o. � poss�vel escolher entre os seguintes m�todos de autentica��o:

• Autentica��o de chave de API HTTP
• Autentica��o b�sica HTTP
• Autentica��o OAuth
• Autentica��o do OIDC

Autentica��o de chave de API

Para dar suporte � autentica��o de chave de API, a Vertex AI se integra ao SecretManager para armazenamento e acesso a secrets. A plataforma de Extens�es da Vertex AI n�o armazena os dados de secrets diretamente. Voc� � respons�vel por gerenciar o ciclo de vida do recurso SecretManager.

Especifique authConfig desta maneira:

"authConfig": {
  "authType": "API_KEY_AUTH",
  "apiKeyConfig": {
    "name": "API_KEY_CONFIG_NAME",
    "apiKeySecret": "API_KEY_SECRET",
    "httpElementLocation": "HTTP_ELEMENT_LOCATION",
  },
}

• API_KEY_CONFIG_NAME: o nome da chave de API. Por exemplo, na solicita��o de API https://example.com/act?api_key=<API KEY>, API_KEY_CONFIG_NAME corresponde a api_key.
• API_KEY_SECRET: recurso de vers�o de secret SecretManager que armazena a chave. Esse par�metro tem o seguinte formato: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

• HTTP_ELEMENT_LOCATION: o local da chave de API na solicita��o HTTP. Os valores poss�veis s�o:

  • HTTP_IN_QUERY
  • HTTP_IN_HEADER
  • HTTP_IN_PATH
  • HTTP_IN_BODY
  • HTTP_IN_COOKIE

  Para saber mais, consulte Como descrever par�metros.

Autentica��o b�sica HTTP

Para dar suporte � autentica��o b�sica HTTP, a Vertex AI se integra ao SecretManager para armazenamento e acesso a secrets. A plataforma de Extens�es da Vertex AI n�o armazena os dados de secrets diretamente. Voc� precisa gerenciar o ciclo de vida do recurso SecretManager por conta pr�pria.

Especifique authConfig desta maneira:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}

• CREDENTIAL_SECRET: recurso de vers�o de secret SecretManager que armazena a credencial codificada em base64 Esse par�metro tem o seguinte formato: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

Autentica��o OAuth

A Vertex AI oferece suporte a dois m�todos de autentica��o OAuth: token de acesso e conta de servi�o.

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {}
}

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}

Autentica��o do OIDC

A Vertex AI � compat�vel com dois m�todos de autentica��o OIDC: token de ID e conta de servi�o.

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {}
}

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}

Importar a extens�o com a Vertex AI

Depois de definir uma solicita��o de importa��o de extens�o, � poss�vel importar a extens�o com a Vertex AI.

1. Defina as seguintes vari�veis de shell:

   ENDPOINT="LOCATION-aiplatform.googleapis.com"
   URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
   

   • PROJECT_ID: seu projeto.
   • LOCATION: uma regi�o de sua escolha. Se voc� n�o tiver certeza, escolha us-central1.

2. Execute o seguinte comando curl para enviar a solicita��o de importa��o:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @IMPORT_REQUEST.json "${URL}/extensions:import"
   

   • IMPORT_REQUEST: o nome do arquivo JSON que cont�m a solicita��o de importa��o de extens�o.

   A resposta tem o seguinte formato:

   {
     "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata",
       "genericMetadata": {
         "createTime": "[CREATE_TIME]",
         "updateTime": "[UPDATE_TIME]"
       }
     }
   }
   

3. Defina as vari�veis de shell com base na sa�da da solicita��o de importa��o:

   EXTENSION_ID=EXTENSION_ID
   IMPORT_OPERATION_ID=IMPORT_OPERATION_ID
   

4. Para verificar o status da importa��o, execute o seguinte comando curl:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
   "${URL}/operations/${IMPORT_OPERATION_ID}"
   

Gerencie as extens�es

Para listar todas as extens�es registradas, execute o seguinte comando curl:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"

Para receber uma extens�o, execute o seguinte comando curl:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"

Voc� pode atualizar displayName, description ou toolUseExamples da extens�o. Se voc� especificar toolUseExamples ao atualizar uma extens�o, a atualiza��o substituir� os exemplos. Por exemplo, se voc� tiver exemplos a e b e atualizar a extens�o com o exemplo c, a extens�o atualizada conter� apenas o exemplo c. Para atualizar uma extens�o execute o seguinte comando curl:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

Para excluir uma extens�o, execute o seguinte comando curl:

curl \
 -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}

Executar uma extens�o

Se a extens�o usa autentica��o OAuth e um token de acesso, consulte Executar uma extens�o com autentica��o OAuth e um token de acesso.

Se a extens�o usa a autentica��o OIDC e um token de ID, consulte Executar uma extens�o com autentica��o OIDC e um token de ID.

Caso contr�rio, voc� pode execut�-lo usando as seguintes etapas:

1. Crie um arquivo chamado execute-extension.json com o seguinte conte�do:

   {
     "operation_id": "API_SERVICE_OPERATION_ID",
     "operation_params": {
       "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE"
     }
   }
   

   • API_SERVICE_OPERATION_ID: o ID da opera��o de servi�o da API que voc� quer executar. As opera��es de servi�o da API s�o definidas no arquivo de especifica��o da API.
   • API_SERVICE_INPUT_VAR: uma vari�vel de entrada que corresponde a API_SERVICE_OPERATION_ID e � definida no arquivo de especifica��o da API.
   • API_SERVICE_INPUT_VALUE: um valor de entrada para a extens�o.

2. Execute o seguinte comando curl:

   curl \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
   "${URL}/extensions/${EXTENSION_ID}:execute"
   

   A resposta tem o seguinte formato:

   {
     "output": {
       "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}"
     }
   }
   

   • API_SERVICE_OUTPUT_VAR: um par�metro de sa�da definido no arquivo de especifica��o da API e corresponde ao servi�o da API.
   • API_SERVICE_OUTPUT_VALUE: um valor de string que � uma serializa��o do objeto de resposta. Se o arquivo de especifica��o da API definir um esquema de resposta JSON, ser� necess�rio analisar essa string de sa�da em JSON por conta pr�pria.

Executar uma extens�o com autentica��o OAuth e um token de acesso

Se a extens�o usar autentica��o OAuth e um token de acesso, ser� poss�vel execut�-la seguindo estas etapas:

1. Crie um arquivo chamado execute-extension.json com o seguinte conte�do:

   {
     "operation_id": "API_SERVICE_OPERATION_ID",
     "operation_params": {...},
     "runtime_auth_config": {
       "authType": "OAUTH",
       "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"}
     }
   }
   

   • API_SERVICE_OPERATION_ID: o ID da opera��o de servi�o da API que voc� quer executar. As opera��es de servi�o da API s�o definidas no arquivo de especifica��o da API.

2. Execute o seguinte comando curl:

   curl \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
   "${URL}/extensions/${EXTENSION_ID}:execute"
   

Executar uma extens�o com autentica��o OIDC e um token de ID

Se a extens�o usar a autentica��o OIDC e um token de ID, ser� poss�vel execut�-la com as seguintes etapas:

1. Crie um arquivo chamado execute-extension.json com o seguinte conte�do:

   {
     "operation_id": "API_SERVICE_OPERATION_ID",
     "operation_params": {...},
     "runtime_auth_config": {
       "authType": "OIDC_AUTH",
       "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"}
     }
   }
   

   • API_SERVICE_OPERATION_ID: o ID da opera��o de servi�o da API que voc� quer executar. As opera��es de servi�o da API s�o definidas no arquivo de especifica��o da API.

2. Execute o seguinte comando curl:

   curl \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
   "${URL}/extensions/${EXTENSION_ID}:execute"
   

A seguir

• Criar e implantar seu framework de orquestra��o de LLMs