Criar e executar extensões

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

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

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

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.

Token de acesso

Especifique authConfig desta maneira:

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

Deixe o campo oauthConfig em branco ao importar a extensão. Se você optar por executar uma extensão registrada, forneça um token de acesso no campo oauthConfig da solicitação de execução. Para saber mais, consulte Executar a extensão.

Conta de serviço

Especifique authConfig desta maneira:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: a Vertex AI usa essa conta de serviço para gerar tokens de acesso.

Siga as etapas abaixo para permitir que Vertex AI Extension Service Agent receba tokens de acesso da SERVICE_ACCOUNT_NAME.

  1. Acessar a página IAM

    Acessar IAM

  2. Selecione a guia Contas de serviço.

  3. Clique na sua conta de serviço. O valor de SERVICE_ACCOUNT_NAME em authConfig precisa corresponder ao nome da conta de serviço.

  4. Clique na guia Permissões.

  5. Clique em Permitir acesso.

  6. Na seção Adicionar principais, no campo Novos principais, digite service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. Esse principal corresponde à conta de serviço Vertex AI Extension Service Agent.

  7. Na seção Atribuir papéis, encontre e selecione o papel Service Account Token Creator. Esse papel inclui a permissão iam.serviceAccounts.getAccessToken.

  8. Clique no botão Save.

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.

Token de ID

Especifique authConfig desta maneira:

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

Deixe o campo oidcConfig em branco ao importar a extensão. Se você optar por executar uma extensão registrada, será necessário fornecer um token de ID no campo oidcConfig da solicitação de execução. Para saber mais, consulte Executar a extensão.

Conta de serviço

Especifique authConfig desta maneira:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: a Vertex AI usa essa conta de serviço para gerar tokens do OpenID Connect (OIDC). A Vertex AI define o público do token como API_SERVICE_URL, conforme definido no arquivo de especificação da API.

Siga as etapas abaixo para permitir que Vertex AI Extension Service Agent receba tokens de acesso da SERVICE_ACCOUNT_NAME.

  1. Acessar a página IAM

    Acessar IAM

  2. Selecione a guia Contas de serviço.

  3. Clique na sua conta de serviço. O valor de SERVICE_ACCOUNT_NAME em authConfig precisa corresponder ao nome da conta de serviço.

  4. Clique na guia Permissões.

  5. Clique em Permitir acesso.

  6. Na seção Adicionar principais, no campo Novos principais, digite service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. Esse principal corresponde à conta de serviço Vertex AI Extension Service Agent.

  7. Na seção Atribuir papéis, encontre e selecione o papel Service Account Token Creator. Esse papel inclui a permissão iam.serviceAccounts.getOpenIdToken.

  8. Clique no botão Save.

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"

    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}"

Gerenciar 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

Há duas maneiras de executar uma extensão:

  • execute: esse modo se concentra apenas na execução da API. A extensão aciona a operação de API específica e retorna os resultados brutos sem nenhum processamento adicional.

  • query: esse modo foi projetado para interações inteligentes. Isso envolve várias etapas:

    • Solicitação de modelo: a consulta e o esquema da extensão são fornecidos ao Gemini como uma instrução e FunctionDeclaration, respectivamente.
    • Execução de API: se o modelo determinar que o uso da ferramenta é necessário, a extensão vai chamar automaticamente a operação de API em nome do modelo e extrair os resultados.
    • Integração de modelos: os resultados da API são enviados ao modelo, que os processa para gerar a resposta final relevante ao contexto. Em essência, query atua como um agente de ferramenta única, usando a API para alcançar as metas.

Esta seção descreve como execute 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