Crie e execute extensões

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

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

Crie e importe extensões

Este documento pressupõe que já tem um serviço de API em execução que pode suportar uma extensão. Para criar uma extensão, tem de definir a respetiva interface com uma API externa num ficheiro de especificação da API. Tem de carregar este ficheiro de especificação para um contentor do Cloud Storage ou convertê-lo numa string. Em seguida, tem de definir um manifesto da extensão, incluir o ficheiro de especificação e enviar um pedido de registo ao serviço de extensão.

Crie um ficheiro de especificação da API

Qualquer pessoa pode criar uma extensão através de ficheiros que definem e descrevem os pontos finais da API da extensão. Os pontos finais da API podem ser públicos ou privados e alojados em qualquer nuvem ou no local.

Um ficheiro de especificação da API descreve a interface de um serviço de API. Tem de fornecer um ficheiro de especificação da API no formato YAML compatível com a OpenAPI 3.0. Este ficheiro de especificação tem de definir o seguinte:

  • Um objeto de servidor. Este objeto tem de definir um URL do servidor da API. O serviço de extensão da Vertex AI não suporta vários servidores.

    servers:
  - url: API_SERVICE_URL

  • Um objeto paths. Este objeto tem de descrever as várias operações fornecidas pelo serviço de API e os parâmetros de entrada que correspondem a cada operação. Cada operação tem de ter um identificador exclusivo e uma resposta.

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

  • Um objeto components. Este objeto é opcional. Pode usar o objeto components para definir objetos reutilizáveis. Por exemplo, pode usar o objeto components para fornecer uma definição dos esquemas de objetos definidos no objeto paths. Também pode usar o objeto components para descrever os parâmetros de saída do serviço API.

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

Para saber mais sobre a OpenAPI, consulte a especificação da OpenAPI.

O exemplo seguinte é um ficheiro de especificação da API para um serviço de API que diz "olá" no idioma pedido:

  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

Carregue o ficheiro de especificação

Pode carregar o ficheiro de especificação para um contentor do Cloud Storage ou convertê-lo numa string.

Se carregar o ficheiro de especificação para um contentor do Cloud Storage, conceda à Vertex AI Extension Service Agent conta de serviço (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com) a função de Leitor de objetos do Storage. Para saber como listar os contentores no seu projeto, consulte o artigo Listar contentores. Para saber como copiar um objeto para um contentor do Cloud Storage, consulte o artigo Copie, mude o nome e mova objetos.

Defina um pedido de importação de extensões

Depois de criar um ficheiro de especificação da API, pode definir um pedido de importação de extensões num ficheiro JSON. Um pedido de importação de extensões tem de conter uma referência ao ficheiro de especificação da API (apiSpec) e à configuração de autenticação (authConfig). Para associar a extensão a um modelo de linguagem grande (LLM) para ver como funciona a extensão, inclua o parâmetro opcional toolUseExamples. Se quiser executar apenas a extensão, não inclua o parâmetro toolUseExamples.

Um pedido de importação de extensões 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 apresentado aos utilizadores.
  • DESCRIPTION_HUMAN: a descrição da extensão apresentada aos utilizadores.
  • EXTENSION_NAME_LLM: o nome da extensão que é usada pelo MDL para raciocínio.
  • DESCRIPTION_LLM: a descrição da extensão usada pelo LLM para raciocínio. Deve fornecer uma descrição significativa e informativa.

Referência ao ficheiro de especificação da API

O seu pedido de importação de extensões tem de conter uma referência ao seu ficheiro de especificação da API. Pode fornecer o ficheiro de especificação de duas formas:

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

    "apiSpec": {
  "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
},
    • BUCKET_NAME: o nome do contentor do Cloud Storage que armazena o ficheiro de especificação.
    • SPECIFICATION_FILE_NAME: o nome do ficheiro de especificação da API.

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

Configuração de autenticação

As extensões podem ser públicas, disponíveis para qualquer utilizador, ou privadas, apenas disponíveis para utilizadores autorizados numa ou mais organizações.

Um pedido de importação de extensões tem de conter uma configuração de autenticação. Pode escolher entre os seguintes métodos de autenticação:

  • NO_AUTH: sem autenticação
  • API_KEY_AUTH: autenticação da chave da API
  • HTTP_BASIC_AUTH: autenticação básica HTTP
  • OAUTH: autenticação OAuth
  • OIDC_AUTH: autenticação OIDC

Para saber mais sobre as configurações de autenticação, consulte o artigo Especifique uma configuração de autenticação.

Exemplos que demonstram como funciona a extensão

Para obter os melhores resultados, um pedido de importação de extensões deve conter exemplos que demonstrem como a extensão funciona. Use o parâmetro toolUseExamples para fornecer estes exemplos.

O código seguinte mostra o formato de toolUseExamples para um único exemplo, com um único parâmetro de entrada e um único parâmetro de saída. Neste exemplo, os parâmetros de pedido e de 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 uma consulta que pode tirar partido desta 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 ficheiro de especificação da API.
  • displayName: um nome a apresentar para o exemplo. Use EXAMPLE_DISPLAY_NAME para fornecer uma breve descrição.
  • requestParams: os parâmetros de pedido necessários para o extensionOperation e os valores de exemplo, no formato de chave-valor. Use API_SERVICE_INPUT_VAR para fornecer um parâmetro de entrada que esteja definido no ficheiro de especificação da API e corresponda 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 ficheiro de especificação da API e que corresponde ao serviço de API. Use EXAMPLE_OUTPUT para fornecer um exemplo de um valor de saída que corresponda a EXAMPLE_INPUT.
  • responseSummary: Um exemplo de um resumo que a aplicação pode fornecer em resposta ao query. Use EXAMPLE_SUMMARY para fornecer o texto de resumo.

Segue-se um exemplo de toolUseExamples para um serviço de API que diz "olá" no idioma pedido:

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

Especifique uma configuração de autenticação

Tem de especificar uma configuração de autenticação quando define um pedido de importação de extensões.

Se a sua extensão não exigir autenticação, defina a variável authType como NO_AUTH:

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

Se a sua extensão exigir autenticação, tem de definir o tipo de autenticação na variável authType e fornecer uma configuração de autenticação. Pode escolher entre os seguintes métodos de autenticação:

Autenticação de chave da API

Para suportar a autenticação de chaves de API, o Vertex AI integra-se com o SecretManager para o armazenamento e o acesso secretos. A plataforma de extensões do Vertex AI não armazena os dados secretos diretamente. É responsável por gerir o ciclo de vida do seu recurso SecretManager.

Especifique authConfig da seguinte forma:

"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 da API. Por exemplo, no pedido 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 secreta SecretManager que armazena a chave. Este parâmetro tem o seguinte formato: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

  • HTTP_ELEMENT_LOCATION: a localização da chave da API no pedido HTTP. Os valores possíveis são os seguintes:

    • HTTP_IN_QUERY
    • HTTP_IN_HEADER
    • HTTP_IN_PATH
    • HTTP_IN_BODY
    • HTTP_IN_COOKIE

    Para saber mais, consulte o artigo Descrever parâmetros.

Autenticação básica HTTP

Para suportar a autenticação básica de HTTP, o Vertex AI integra-se com o SecretManager para o armazenamento e o acesso secretos. A plataforma de extensões do Vertex AI não armazena os dados secretos diretamente. Tem de gerir o ciclo de vida do seu recurso SecretManager por conta própria.

Especifique authConfig da seguinte forma:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • CREDENTIAL_SECRET: recurso da versão secreta SecretManager que armazena a credencial codificada em base64. Este parâmetro tem o seguinte formato: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

Autenticação OAuth

O Vertex AI suporta dois métodos de autenticação OAuth: token de acesso e conta de serviço.

Chave de acesso

Especifique authConfig da seguinte forma:

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

Deixe o campo oauthConfig em branco quando importar a extensão. Se optar por executar uma extensão registada, tem de fornecer um token de acesso no campo oauthConfig do pedido de execução. Para saber mais, consulte Executar a extensão.

Conta de serviço

Especifique authConfig da seguinte forma:

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

Execute os passos seguintes para permitir que Vertex AI Extension Service Agent obtenha tokens de acesso de SERVICE_ACCOUNT_NAME.

  1. Aceda à página IAM.

    Aceder ao IAM

  2. Selecione o separador Contas de serviço.

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

  4. Clique no separador Diretores com acesso.

  5. Clique em Conceder acesso.

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

  7. Na secção Atribuir funções, localize e selecione a função Service Account Token Creator. Esta função inclui a autorização iam.serviceAccounts.getAccessToken.

  8. Clique no botão Guardar.

Autenticação OIDC

A Vertex AI suporta dois métodos de autenticação OIDC: token de ID e conta de serviço.

Token de ID

Especifique authConfig da seguinte forma:

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

Deixe o campo oidcConfig em branco quando importar a extensão. Se optar por executar uma extensão registada, tem de fornecer um token de ID no campo oidcConfig do pedido de execução. Para saber mais, consulte Executar a extensão.

Conta de serviço

Especifique authConfig da seguinte forma:

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

Execute os passos seguintes para permitir que Vertex AI Extension Service Agent obtenha tokens de acesso de SERVICE_ACCOUNT_NAME.

  1. Aceda à página IAM.

    Aceder ao IAM

  2. Selecione o separador Contas de serviço.

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

  4. Clique no separador Autorizações.

  5. Clique em Conceder acesso.

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

  7. Na secção Atribuir funções, localize e selecione a função Service Account Token Creator. Esta função inclui a autorização iam.serviceAccounts.getOpenIdToken.

  8. Clique no botão Guardar.

Importe a extensão com o Vertex AI

Depois de definir um pedido de importação de extensões, pode importar a extensão com o 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: o seu projeto.
    • LOCATION: uma região à sua escolha. Se não tiver a certeza, escolha us-central1.

  2. Execute o seguinte comando curl para enviar o pedido 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 variáveis de shell com base no resultado do pedido de importação:

    EXTENSION_ID=EXTENSION_ID
IMPORT_OPERATION_ID=IMPORT_OPERATION_ID

  4. Para verificar o estado 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}"

Faça a gestão de extensões

Para apresentar uma lista de todas as extensões registadas, 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 obter 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}"

Pode atualizar o displayName, o description ou o toolUseExamples da extensão. Se especificar toolUseExamples quando atualiza uma extensão, a atualização substitui os exemplos. Por exemplo, se tiver os exemplos a e b e, em seguida, atualizar a extensão com o exemplo c, a extensão atualizada contém apenas o exemplo c.Para atualizar uma descrição da 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 eliminar 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}

Execute uma extensão

Existem duas formas de executar uma extensão:

  • execute: este modo foca-se apenas na execução da API. A extensão aciona a operação da API especificada e devolve os resultados não processados sem processamento adicional.

  • query: este modo foi concebido para interações inteligentes. Envolve vários passos:

    • Pedido do modelo: a consulta e o esquema da extensão são fornecidos ao Gemini como um comando e FunctionDeclaration, respetivamente.
    • Execução da API: se o modelo determinar que é necessária a utilização de ferramentas, a extensão chama automaticamente a operação da API em nome do modelo e obtém os resultados.
    • Integração do modelo: os resultados da API são introduzidos no modelo, que os processa para gerar a resposta final contextualmente relevante. Em essência, o query funciona como um agente de ferramenta única, usando a API para alcançar os seus objetivos.

Esta secção descreve como execute uma extensão.

Se a sua extensão usar a autenticação OAuth e uma chave de acesso, consulte o artigo Execute uma extensão com a autenticação OAuth e uma chave de acesso.

Se a sua extensão usar a autenticação OIDC e um token de ID, consulte o artigo Execute uma extensão com a autenticação OIDC e um token de ID.

Caso contrário, pode executá-lo seguindo estes passos:

  1. Crie um ficheiro denominado 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 do serviço API que quer executar. As operações do serviço API estão definidas no ficheiro de especificação da API.
    • API_SERVICE_INPUT_VAR: uma variável de entrada que corresponde a API_SERVICE_OPERATION_ID e está definida no ficheiro 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 ficheiro de especificação da API e que corresponde ao serviço da API.
    • API_SERVICE_OUTPUT_VALUE: um valor de string que é uma serialização do objeto de resposta. Se o ficheiro de especificação da API definir um esquema de resposta JSON, tem de analisar esta string de saída em JSON por si.

Execute uma extensão com autenticação OAuth e uma chave de acesso

Se a sua extensão usar a autenticação OAuth e uma chave de acesso, pode executá-la através dos seguintes passos:

  1. Crie um ficheiro denominado 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)'"}
  }
}

  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"

Execute uma extensão com autenticação OIDC e um token de ID

Se a sua extensão usar a autenticação OIDC e um token de ID, pode executá-la através dos seguintes passos:

  1. Crie um ficheiro denominado 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)"}
  }
}

  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"

O que se segue?