Extensions API

Erweiterungen sind Tools für Large Language Models, die auf externe Daten zugreifen, Berechnungen ausführen und andere Vorgänge ausführen können. Sie können Echtzeitdaten verarbeiten und reale Aktionen ausführen. Vertex AI stellt die Extension API bereit, die Erweiterungen registrieren, verwalten und ausführen kann. Vertex AI bietet außerdem eine Reihe vordefinierter Erweiterungen aus der Extension API, einschließlich Code-Interpreter-Erweiterung, Vertex AI Search-Erweiterung usw.

Beschränkung

  • Diese ist nur in der Region „us-central1“ verfügbar.

Erweiterung importieren

Erweiterungsressource erstellen oder registrieren

Syntax

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  http://${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
)

Parameterliste

Parameter

displayName

Optional: string

Der Anzeigename der Erweiterung, der Nutzern über die API und die Benutzeroberfläche angezeigt wird. Dies sollte ein UTF-8-String mit bis zu 128 Zeichen sein.

description

Optional: string

Die Beschreibung der Erweiterung, die Nutzern über die API und die Benutzeroberfläche angezeigt wird. Dies sollte ein UTF-8-String mit bis zu 1 MB sein.

manifest

JsonDict|ExtensionManifest

Manifest der Erweiterung.

runtimeConfig

Optional: JsonDict|RuntimeConfig

Laufzeitkonfiguration, die das Laufzeitverhalten dieser Erweiterung steuert.

ExtensionManifest

Parameter

name

string

Der Name der Erweiterung, die vom LLM aus Gründen verwendet wird. Dies sollte ein UTF-8-String mit bis zu 128 Zeichen sein.

description

string

Die Beschreibung in natürlicher Sprache, die dem LLM angezeigt wird. Sie sollte die Verwendung der Erweiterung beschreiben. Es ist wichtig, damit das LLM Logik ausführen kann. Dies sollte ein UTF-8-String mit bis zu 1 MB sein.

apiSpec

ApiSpec

Die API-Spezifikation, die dem LLM aus Logik angezeigt wird. Geben Sie eine aussagekräftige und informative Beschreibung.

authConfig

JsonDict|AuthConfig

Authentifizierungstyp, der von dieser Erweiterung unterstützt wird.

ApiSpec

ApiSpec enthält den Verweis auf den Cloud Storage-URI, in dem die OpenAPI-YAML-Datei gespeichert wird.

"apiSpec": {
  "openApiGcsUri": string
}
Parameter

openApiGcsUri

string
Cloud Storage-URI der OpenAPI-YAML-Datei, die die Erweiterungs-API beschreibt. z. B. gs://vertex-extension-public/code_interpreter.yaml

AuthConfig

Eine Anfrage zum Importieren einer Erweiterung muss eine Authentifizierungskonfiguration enthalten.

Authentifizierung mit einem Google-Dienstkonto

Sowohl die Code Interpreter-Erweiterung als auch die Vertex AI Search-Erweiterung unterstützen nur Google-Dienstkonten, bei denen Vertex AI den Vertex AI Extension Service Agent für den Zugriff auf die APIs verwendet. Geben Sie authConfig an, um die Google-Dienstkontoauthentifizierung zu unterstützen:

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

serviceAccount

Optional: string

Das Dienstkonto, mit dem die Erweiterung ausgeführt wird. Wenn das Dienstkonto angegeben ist, sollte dem Vertex AI-[Extension Service Agent](/vertex-ai/docs/general/access-control#service-agents) für das angegebene Dienstkonto die Berechtigung iam.serviceAccounts.getAccessToken gewährt werden. Wenn nicht angegeben, wird der Dienst-Agent für die Vertex AI-Erweiterung zum Ausführen der Erweiterung verwendet.

RuntimeConfig

Die Laufzeitkonfiguration enthält eine zusätzliche Konfiguration, die beim Ausführen der Erweiterung verwendet wird.

Für die Code-Interpreter-Erweiterung kann runtimeConfig so festgelegt werden:

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

fileInputGcsBucket

Optional: string

Cloud Storage-Bucket für die Dateieingabe dieser Erweiterung. Unterstützt Eingaben aus dem Cloud Storage-Bucket, wenn angegeben. Der Dienst-Agent für den benutzerdefinierten Code der Vertex-Erweiterung sollte die Berechtigung roles/storage.objectViewer für diesen Bucket haben. Wenn nicht angegeben, akzeptiert die Erweiterung nur Dateiinhalte aus dem Anfragetext und lehnt Cloud Storage-Dateieingaben ab.

fileOutputGcsBucket

Optional: string

Cloud Storage-Bucket für die Dateiausgabe dieser Erweiterung. Wenn dieses Flag angegeben ist, werden alle Ausgabedateien in den Cloud Storage-Bucket geschrieben. Der Vertex Extension Custom Code Service Agent sollte die Berechtigung roles/storage.objectUser für diesen Bucket haben. Wenn nicht angegeben, wird der Dateiinhalt im Antworttext ausgegeben.

Für die Vertex AI Search-Erweiterung sollte runtimeConfig auf Folgendes festgelegt sein:

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

servingConfigName

string

Name der Vertex AI Search-Bereitstellungskonfiguration, um anzugeben, welche Vertex AI Search-Ressource die Erweiterung verwendet. Format:

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

Beispiele

Code Interpreter importieren

In diesem Beispiel wird gezeigt, wie Nutzer eine Erweiterung des Code Interpreters importieren können.

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${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",
        },
    },
)

Mit RuntimeConfig importieren

In diesem Beispiel wird gezeigt, wie Nutzer eine Erweiterung mit RuntimeConfig importieren können (als Beispiel die Erweiterung Vertex AI Search).

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${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,
        }
    }
)

Erweiterung ausführen

Führen Sie eine Erweiterung aus, die den Erweiterungsvorgang direkt mit den in der Anfrage angegebenen Parametern aufruft.

Syntax

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  http://${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,
)

Parameterliste

Parameter

operation_id

string

Die ausgewählte ID des Vorgangs, der in dieser Erweiterung ausgeführt werden soll

operation_params

Optional: JsonDict|Struct

Anfrageparameter, die für die Ausführung dieses Vorgangs verwendet werden. Der JSON-Code sollte in einer Zuordnungsform mit dem Parameternamen als Schlüssel und dem tatsächlichen Parameterwert als Wert vorliegen. Wenn für diesen Vorgang beispielsweise der Parameter „Abfrage“ auf „Was ist Vertex AI?“ festgelegt ist. können Sie es auf etwa {"query": "Was ist Vertex AI?"} festlegen.

Beispiele

In diesem Beispiel wird die Code-Interpreter-Erweiterung generate_and_execute ausgeführt, um die Antwort auf die Abfrage "Find the max value in the list: [1,2,3,4,-5]" zu erhalten.

  • 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" \
http://${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]"},
)

Listenerweiterung

Listet Erweiterungsressource innerhalb des Projekts auf.

Beispiel

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1

curl

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${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()

Erweiterung installieren

Eine Erweiterungsressource abrufen.

Beispiel

  • 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" \
http://${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)

Erweiterung aktualisieren

Erweiterungsressource aktualisieren Sie können den displayName, die Beschreibung oder toolUseExamples der Erweiterung aktualisieren.

Beispiel

In diesem Beispiel wird die Beschreibung der Erweiterung zu „A nice tool“ (Ein gutes Tool) geändert.

  • 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" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

Erweiterung löschen

Erweiterungsressource löschen

Beispiel

In diesem Beispiel wird die mit der Erweiterungs-ID verknüpfte Erweiterung gelöscht.

  • 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" \
http://${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()

Weitere Informationen

Eine ausführliche Dokumentation finden Sie unter: