API Extensions

Extensões são ferramentas para que modelos de linguagem grandes acessem dados externos, executem cálculos e realizem outras operações. Elas podem processar dados em tempo real e realizar ações no mundo real. A Vertex AI fornece a API Extension, que pode registrar, gerenciar e executar extensões. A Vertex AI também fornece um conjunto de extensões pré-criadas da API Extension, incluindo a extensão de interpretador de código, a extensão Vertex AI para Pesquisa etc.

Limitação

  • Ela está disponível apenas na região "us-central1".

Importar extensão

Criar ou registrar um recurso de extensão.

Sintaxe

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import

Python

from vertexai.preview import extensions

extensions.Extension.create(
  manifest: Union[JsonDict, ExtensionManifest],
  display_name: Optional[str] = None,
  description: Optional[str] = None,
  runtime_config: Optional[Union[JsonDict, RuntimeConfig]] = None
)

Lista de parâmetros

Parâmetros

displayName

Opcional: string

O nome de exibição da extensão que é mostrado aos usuários na API e na interface. Precisa ser uma string UTF-8 com até 128 caracteres.

description

Opcional: string

A descrição da extensão que é exibida aos usuários na API e na interface. Precisa ser uma string UTF-8 com até 1 MB.

manifest

JsonDict|ExtensionManifest

Manifesto da extensão.

runtimeConfig

Opcional: JsonDict|RuntimeConfig

Configuração do ambiente de execução que controla o comportamento do ambiente de execução dessa extensão.

ExtensionManifest

Parâmetros

name

string

O nome da extensão usada pelo LLM para raciocínio. Precisa ser uma string UTF-8 com até 128 caracteres.

description

string

A descrição em linguagem natural mostrada ao LLM. Ela precisa descrever o uso da extensão e é essencial para que o LLM realize o raciocínio. Precisa ser uma string UTF-8 com até 1 MB.

apiSpec

ApiSpec

A especificação da API mostrada ao LLM para raciocínio. É preciso fornecer uma descrição significativa e informativa.

authConfig

JsonDict|AuthConfig

Tipo de autenticação aceita por esta extensão.

ApiSpec

ApiSpec contém a referência ao URI do Cloud Storage que armazena o arquivo YAML da OpenAPI.

"apiSpec": {
  "openApiGcsUri": string
}
Parâmetros

openApiGcsUri

string
URI do Cloud Storage do arquivo YAML da OpenAPI que descreve a API de extensão, por exemplo, gs://vertex-extension-public/code_interpreter.yaml

AuthConfig

Uma solicitação de importação de extensão precisa conter uma configuração de autenticação.

Autenticação da conta de serviço do Google

As extensões de interpretador de código e Vertex AI para Pesquisa aceitam apenas a conta de serviço do Google em que a Vertex AI usa o agente de serviço de extensão da Vertex AI para acessar as APIs. Para permitir a autenticação da conta de serviço do Google, especifique authConfig:

"authConfig": {
  "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
  "googleServiceAccountConfig": {
    "serviceAccount": string
  },
}
Parâmetros

serviceAccount

Opcional: string

A conta de serviço em que ocorre a execução da extensão. Se a conta de serviço for especificada, a permissão iam.serviceAccounts.getAccessToken precisará ser concedida ao [Agente de serviço de extensão](/vertex-ai/docs/general/access-control#service-agents) da Vertex AI na conta de serviço especificada. Se ela não for especificada, o agente de serviço de extensão da Vertex AI será usado para executar a extensão.

RuntimeConfig

A configuração do ambiente de execução contém outras configurações usadas ao executar a extensão.

Para a extensão de interpretador de código, o runtimeConfig pode ser definido como:

"runtimeConfig": {
   "codeInterpreterRuntimeConfig": {
      "fileInputGcsBucket": string,
      "fileOutputGcsBucket": string
   }
}
Parâmetros

fileInputGcsBucket

Opcional: string

Bucket do Cloud Storage para a entrada de arquivo dessa extensão. Se não for especificado, aceitará a entrada do bucket do Cloud Storage. O agente de serviço de código personalizado da extensão da Vertex precisa receber a permissão roles/storage.objectViewer para esse bucket. Se não for especificado, a extensão só aceitará o conteúdo do arquivo do corpo da solicitação e rejeitará as entradas do arquivo do Cloud Storage.

fileOutputGcsBucket

Opcional: string

Bucket do Cloud Storage para a saída de arquivo dessa extensão. Se for especificado, gravará todos os arquivos de saída no bucket do Cloud Storage. O agente de serviço de código personalizado da extensão da Vertex precisa receber a permissão roles/storage.objectUser para esse bucket. Se não for especificado, o conteúdo do arquivo será gerado no corpo da resposta.

Para a extensão Vertex AI para Pesquisa, o runtimeConfig precisa ser definido como:

"runtimeConfig": {
  "vertexAiSearchRuntimeConfig": {
    "servingConfigName": string,
  }
}
Parâmetros

servingConfigName

string

Nome da configuração de disponibilização da Vertex AI para Pesquisa para especificar qual recurso da Vertex AI para Pesquisa a extensão usará. Formato:

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

Exemplos

Importar interpretador de código

Este exemplo mostra como os usuários podem importar uma extensão de interpretador de código.

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import \
 -d '{
    "displayName": "Code Interpreter",
    "description": "This extension generates and executes code",
    "manifest": {
      "name": "code_interpreter_tool",
      "description": "Google Code Interpreter Extension",
      "apiSpec": {
        "openApiGcsUri": "gs://vertex-extension-public/code_interpreter.yaml",
      },
      "authConfig": {
        "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        "googleServiceAccountConfig": {}
      }
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID,location=REGION)

extension_code_interpreter = extensions.Extension.create(
    display_name = "Code Interpreter",
    description = "This extension generates and executes code in the specified language",
    manifest = {
        "name": "code_interpreter_tool",
        "description": "Google Code Interpreter Extension",
        "api_spec": {
            "open_api_gcs_uri": "gs://vertex-extension-public/code_interpreter.yaml"
        },
        "auth_config": {
            "google_service_account_config": {},
            "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        },
    },
)

Importe com RuntimeConfig

Este exemplo mostra como os usuários podem importar uma extensão com RuntimeConfig (usando a extensão da Vertex AI para Pesquisa como exemplo).

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import \
 -d '{
    "displayName": "Vertex AI Search extension",
    "description": "A search extension",
    "manifest": {
      "name": "vertex_ai_search",
      "description": "Vertex AI Search Extension",
      "apiSpec": {
        "openApiGcsUri": "gs://vertex-extension-public/vertex_ai_search.yaml",
      },
      "authConfig": {
        "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        "googleServiceAccountConfig": {}
      }
    },
    "runtimeConfig": {
      "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "'${SERVING_CONFIG_NAME}'",
      }
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

extension_vertex_ai_search = extensions.Extension.create(
    display_name = "vertex_ai_search",
    description = "This extension search from provided datastore",
    manifest = {
        "name": "vertex_ai_search",
        "description": "Google Vertex AI Search Extension",
        "api_spec": {
            "open_api_gcs_uri": "gs://vertex-extension-public/vertex_ai_search.yaml"
        },
        "auth_config": {
            "google_service_account_config": {},
            "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        },
    },
    runtime_config={
        "vertex_ai_search_runtime_config": {
            "serving_config_name": SERVING_CONFIG_NAME,
        }
    }
)

Executar extensão

Execute uma extensão, que chama diretamente a operação da extensão com os parâmetros fornecidos na solicitação.

Sintaxe

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}/:execute

Python

from vertexai.preview import extensions

extension.execute(
  operation_id: str,
  operation_params: Optional[Union[JsonDict, Struct]] = None,
)

Lista de parâmetros

Parâmetros

operation_id

string

O ID selecionado da operação a ser executada nesta extensão

operation_params

Opcional: JsonDict|Struct

Parâmetros de solicitação que serão usados para executar essa operação. O JSON deve estar em um formato de mapa com o nome do parâmetro como chave e o valor real do parâmetro como valor. Por exemplo, se essa operação exigir que um parâmetro "query" seja definido como "O que é a Vertex AI?", será possível definir algo como {"query": "O que é a Vertex AI?"}.

Exemplos

Este exemplo executa a extensão de interpretador de código generate_and_execute para receber a resposta para a consulta "encontre o valor máximo na lista: [1,2,3,4,-5]".

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}:execute \
 -d '{
   "operation_id": "generate_and_execute",
   "operation_params": {
      "query": "find the max value in the list: [1,2,3,4,-5]",
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

code_interpreter_extensions = extensions.Extension(EXTENSION_ID)
extension_code_interpreter.execute(
    operation_id = "generate_and_execute",
    operation_params = {"query": "find the max value in the list: [1,2,3,4,-5]"},
)

Listar extensão

Liste recursos de extensões no projeto.

Exemplo

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1

curl

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID,location=REGION)

extensions.Extension.list()

Receber extensão

Receba um recurso de extensão.

Exemplo

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID

curl

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

extension = extensions.Extension(EXTENSION_ID)

Atualizar extensão

Atualize um recurso de extensão. É possível atualizar o nome de exibição, a descrição ou o toolUseExamples da extensão.

Exemplo

Este exemplo atualiza a descrição da extensão para "Uma boa ferramenta".

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

Excluir extensão

Exclua um recurso de extensão.

Exemplo

Este exemplo exclui a extensão associada ao ID da extensão.

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID

curl

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

extension_code_interpreter = extensions.Extension(
    "${EXTENSION_ID}"
)
extension_code_interpreter.delete()

Mais informações

Para consultar a documentação detalhada, acesse: