API Extensions

Extensões são ferramentas usadas por modelos de linguagem grandes (LLMs) para acessar dados externos, executar cálculos e realizar 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 predefinidas da API Extension, incluindo a extensão do interpretador de código e a extensão da Vertex AI para Pesquisa.

Limitações

A API Extension só está disponível na região us-central1.

Exemplo de sintaxe

Sintaxe para criar um recurso de extensão.

curl

curl -X POST \

-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/extensions:import \
-d '{
  "displayName": "...",
  "description": "...",
  "manifest": {
    ...
    "apiSpec": {
      ...
    },
    "authConfig": {
      ...
    }
    ...
  }
}'

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

Corpo da solicitação

Parâmetros

displayName

Opcional: string

O nome de exibição da extensão 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 exibida aos usuários na API e na interface. Precisa ser uma string UTF-8 com até 1 MB.

manifest

JsonDict|ExtensionManifest

O manifesto da extensão.

runtimeConfig

Opcional: JsonDict|RuntimeConfig

A configuração do ambiente de execução que controla o comportamento do ambiente de execução da extensão.

Para a extensão do interpretador de código, o formato é o seguinte:

  "runtimeConfig": {
    "codeInterpreterRuntimeConfig": {
        "fileInputGcsBucket": string,
        "fileOutputGcsBucket": string
    }
  }

Para a extensão da Vertex AI para Pesquisa, o formato é o seguinte: 

  "runtimeConfig": {
    "vertexAiSearchRuntimeConfig": {
      "servingConfigName": string,
    }
  }

manifest

O manifesto da extensão.

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 do uso da extensão. A descrição é mostrada ao LLM para ajudá-lo a realizar o raciocínio. Ela precisa ser uma string UTF-8 de até 1 MB.

apiSpec

ApiSpec

A especificação da API mostrada ao LLM para raciocínio. É preciso fornecer uma descrição significativa e informativa. apiSpec contém a referência ao URI do Cloud Storage que armazena o arquivo YAML da OpenAPI. 

  "apiSpec": {
    "openApiGcsUri": string
  }

authConfig

JsonDict|AuthConfig

O tipo de autenticação aceita pela extensão.

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

"authConfig": {
  "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
  "googleServiceAccountConfig": {
    "serviceAccount": string
  },
}

apiSpec

A especificação da API mostrada ao LLM para raciocínio.

Parâmetros

openApiGcsUri

string

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

authConfig

O tipo de autenticação aceito pela extensão.

Parâmetros

authType

string

Método de autenticação. Valores aceitos: GOOGLE_SERVICE_ACCOUNT_AUTH.

googleServiceAccountConfig

As extensões do interpretador de código e da Vertex AI para Pesquisa só aceitam a autenticação da 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.

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

O objeto runtimeConfig contém outras configurações usadas ao executar a extensão.

Extensão do interpretador de código

Parâmetros

fileInputGcsBucket

Opcional: string

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

fileOutputGcsBucket

Opcional: string

O bucket do Cloud Storage para a saída de arquivo da extensão. O agente de serviço de código personalizado da extensão da Vertex precisa receber a permissão roles/storage.objectUser nesse bucket. Se ela não for especificada, o conteúdo do arquivo será exibido no corpo da resposta.

Extensão da Vertex AI para Pesquisa

Parâmetros

servingConfigName

string

Nome da configuração de exibição da Vertex AI para Pesquisa para especificar qual recurso da Vertex AI para Pesquisa a extensão usa. Formato:

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

Executar a extensão

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 são usados para executar essa operação. O JSON deve estar no formato de um mapa, com o nome do parâmetro como chave e o valor real do parâmetro como valor. Por exemplo, para definir um parâmetro chamado query para a string "O que é a Vertex AI?", use {"query": "What is Vertex AI?"}.

Exemplos

Importar uma extensão do interpretador de código

Criar ou registrar um recurso de extensão.

Este exemplo mostra como importar uma extensão do interpretador de código.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • DISPLAY_NAME: o nome de exibição da extensão mostrado aos usuários na API e na interface. Precisa ser uma string UTF-8 com até 128 caracteres.
  • DESCRIPTION: a descrição da extensão mostrada aos usuários na API e na interface. Precisa ser uma string UTF-8 com até 1 MB.
  • MANIFEST_NAME: o nome da extensão usada pelo LLM para raciocínio. Precisa ser uma string UTF-8 com até 128 caracteres.
  • MANIFEST_DESCRIPTION: 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.
  • GCS_URI: o URI do Cloud Storage do arquivo YAML da OpenAPI que descreve a API da extensão.
  • AUTH_TYPE: o método de autenticação. Valores aceitos: GOOGLE_SERVICE_ACCOUNT_AUTH.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import

Corpo JSON da solicitação:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "manifest": {
    "name": "NAME",
    "description": "MANIFEST_DESCRIPTION",
    "apiSpec": {
      "openApiGcsUri": "GCS_URI",
    },
    "authConfig": {
      "authType": "AUTH_TYPE",
      "googleServiceAccountConfig": {}
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = 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",
        },
    },
)
print(extension.resource_name)
# Example response:
# projects/123456789012/locations/us-central1/extensions/12345678901234567

Fazer importação com uma configuração de ambiente de execução

Criar ou registrar um recurso de extensão.

Este exemplo mostra como importar uma extensão da Vertex AI para Pesquisa especificando RuntimeConfig.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • DISPLAY_NAME: o nome de exibição da extensão mostrado aos usuários na API e na interface. Precisa ser uma string UTF-8 com até 128 caracteres.
  • DESCRIPTION: a descrição da extensão mostrada aos usuários na API e na interface. Precisa ser uma string UTF-8 com até 1 MB.
  • MANIFEST_NAME: o nome da extensão usada pelo LLM para raciocínio. Precisa ser uma string UTF-8 com até 128 caracteres.
  • MANIFEST_DESCRIPTION: 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.
  • GCS_URI: o URI do Cloud Storage do arquivo YAML da OpenAPI que descreve a API da extensão.
  • AUTH_TYPE: o método de autenticação. Valores aceitos: GOOGLE_SERVICE_ACCOUNT_AUTH.
  • SERVING_CONFIG_NAME: o nome da configuração de exibição da Vertex AI para Pesquisa para especificar qual recurso da Vertex AI para Pesquisa a extensão usa. Formato: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import

Corpo JSON da solicitação:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "manifest": {
    "name": "NAME",
    "description": "MANIFEST_DESCRIPTION",
    "apiSpec": {
      "openApiGcsUri": "GCS_URI",
    },
    "authConfig": {
      "authType": "AUTH_TYPE",
      "googleServiceAccountConfig": {}
    },
    runtime_config={
      "vertex_ai_search_runtime_config": {
          "serving_config_name": SERVING_CONFIG_NAME,
      }
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content

Python

import vertexai
from vertexai.preview import extensions

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

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 uma extensão

Para executar uma extensão, chame diretamente a extensão e forneça os parâmetros de execução na solicitação.

Este exemplo executa a extensão do interpretador de código generate_and_execute para conseguir a resposta para a consulta find the max value in the list: [1,2,3,4,-5].

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • EXTENSION_ID: o ID da extensão.
  • OPERATION_ID: o ID selecionado da operação a ser executada nesta extensão.
  • QUERY: os parâmetros da solicitação para executar a operação em um formato de chave-valor, {"query": "What is Vertex AI?"}..

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute

Corpo JSON da solicitação:

{
  "operation_id": "OPERATION_ID",
  "operation_params": {
    "query": "QUERY",
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "your-extension-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)

response = extension.execute(
    operation_id="generate_and_execute",
    operation_params={"query": "find the max value in the list: [1,2,3,4,-5]"},
)
print(response)
# Example response:
# {
#     "generated_code": "```python\n# Find the maximum value in the list\ndata = [1, 2,..", ..
#     "execution_result": "The maximum value in the list is: 4\n",
#     "execution_error": "",
#     "output_files": [],
# }

Listar extensões

Liste extensões em um projeto.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • EXTENSION_ID: o ID da extensão.

Método HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions" | Select-Object -Expand Content

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

import vertexai
from vertexai.preview import extensions

# TODO (developer):Update project_id
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extensions = extensions.Extension.list()
print(extensions)
# Example response:
# [<vertexai.extensions._extensions.Extension object at 0x76e8ced37af0>
# resource name: projects/[PROJECT_ID]/locations/us-central1/extensions/1234567890123456]

Adquirir uma extensão

Confira os detalhes de uma extensão.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • EXTENSION_ID: o ID da extensão.

Método HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "your-extension-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)
print(extension.resource_name)
# Example response:
# projects/[PROJECT_ID]/locations/us-central1/extensions/12345678901234567

Atualizar uma extensão

Atualize uma extensão.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • EXTENSION_ID: o ID da extensão.
  • UPDATE_MASK: o parâmetro a ser atualizado. Valores aceitos: displayName, description ou toolUseExamples.

Método HTTP e URL: 

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"

Corpo JSON da solicitação:

{
  "description": "UPDATE_MASK",
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK""

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"" | Select-Object -Expand Content

Excluir extensão

Exclua uma extensão.

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • EXTENSION_ID: o ID da extensão.

Método HTTP e URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "extension_id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)
extension.delete()
# Example response:
# ...
# Extension resource projects/[PROJECT_ID]/locations/us-central1/extensions/[extension_id] deleted.

A seguir