API Ekstensi

Ekstensi adalah alat untuk model bahasa besar guna mengakses data eksternal, menjalankan komputasi, dan melakukan operasi lainnya. Mereka dapat memproses data real-time dan melakukan tindakan nyata. Vertex AI menyediakan Extension API yang dapat mendaftarkan, mengelola, dan mengeksekusi ekstensi. Vertex AI juga menyediakan serangkaian ekstensi bawaan dari Extension API termasuk ekstensi penerjemah kode, ekstensi Vertex AI Search, dll.

Batasan

  • Ini hanya tersedia di region "us-central1".

Impor Ekstensi

Buat atau daftarkan resource ekstensi.

Sintaksis

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
)

Daftar parameter

Parameter

displayName

Opsional: string

Nama tampilan ekstensi yang ditampilkan kepada pengguna dari API dan UI. String ini harus berupa string UTF-8 yang berisi hingga 128 karakter.

description

Opsional: string

Deskripsi ekstensi yang ditampilkan kepada pengguna dari API dan UI. String ini harus berupa string UTF-8 yang berukuran hingga 1 MB.

manifest

JsonDict|ExtensionManifest

Manifes ekstensi.

runtimeConfig

Opsional: JsonDict|RuntimeConfig

Konfigurasi runtime mengontrol perilaku runtime Ekstensi ini.

ExtensionManifest

Parameter

name

string

Nama ekstensi yang digunakan oleh LLM untuk penalaran. String ini harus berupa string UTF-8 yang berisi hingga 128 karakter.

description

string

Deskripsi natural language yang ditampilkan kepada LLM. Judul tersebut harus menjelaskan penggunaan ekstensi, dan penting bagi LLM untuk melakukan penalaran. String ini harus berupa string UTF-8 yang berukuran hingga 1 MB.

apiSpec

ApiSpec

Spesifikasi API yang ditampilkan ke LLM untuk alasan. Anda harus memberikan deskripsi yang bermakna dan informatif.

authConfig

JsonDict|AuthConfig

Jenis autentikasi yang didukung oleh ekstensi ini.

ApiSpec

ApiSpec berisi referensi ke URI Cloud Storage yang menyimpan file yaml OpenAPI.

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

openApiGcsUri

string
URI Cloud Storage dari file YAML OpenAPI yang mendeskripsikan API ekstensi, misalnya gs://vertex-extension-public/code_interpreter.yaml

AuthConfig

Permintaan impor ekstensi harus berisi konfigurasi autentikasi.

Autentikasi Akun Layanan Google

Ekstensi penafsir Kode dan ekstensi Vertex AI Search hanya mendukung Akun Layanan Google tempat Vertex AI menggunakan Vertex AI Extension Service Agent untuk mengakses API. Untuk mendukung autentikasi Akun Layanan Google, tentukan authConfig:

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

serviceAccount

Opsional: string

Akun layanan tempat eksekusi ekstensi dijalankan. Jika akun layanan ditentukan, izin iam.serviceAccounts.getAccessToken harus diberikan ke Vertex AI [Agen Layanan Ekstensi](/vertex-ai/docs/general/access-control#service-agents) di akun layanan yang ditentukan. Jika tidak ditentukan, Agen Layanan Ekstensi Vertex AI akan digunakan untuk menjalankan Ekstensi.

RuntimeConfig

Konfigurasi runtime berisi konfigurasi tambahan yang digunakan saat menjalankan ekstensi.

Untuk ekstensi penafsir kode, runtimeConfig dapat ditetapkan sebagai:

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

fileInputGcsBucket

Opsional: string

Bucket Cloud Storage untuk input file Ekstensi ini. Jika ditentukan, mendukung input dari bucket Cloud Storage. Agen Layanan Kode Kustom Ekstensi Vertex harus diberi izin Role/storage.objectViewer ke bucket ini. Jika tidak ditentukan, ekstensi hanya akan menerima konten file dari isi permintaan dan menolak input file Cloud Storage.

fileOutputGcsBucket

Opsional: string

Bucket Cloud Storage untuk output file Ekstensi ini. Jika ditentukan, tulis semua file output ke bucket Cloud Storage. Agen Layanan Kode Kustom Ekstensi Vertex harus diberi izin roles/storage.objectUser ke bucket ini. Jika tidak ditentukan, konten file akan dihasilkan dalam isi respons.

Untuk ekstensi Vertex AI Search, runtimeConfig harus ditetapkan ke:

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

servingConfigName

string

Vertex AI Search menyediakan nama konfigurasi untuk menentukan resource Vertex AI Search mana yang akan digunakan ekstensi. Format:

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

Contoh

Impor penafsir kode

Contoh ini menunjukkan cara pengguna dapat mengimpor ekstensi penafsir kode.

  • ID_PROJECT = PROJECT_ID
  • WILAYAH = 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",
        },
    },
)

Impor dengan RuntimeConfig

Contoh ini menunjukkan cara pengguna dapat mengimpor ekstensi dengan RuntimeConfig (menggunakan ekstensi Vertex AI Search sebagai contoh).

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,
        }
    }
)

Menjalankan Ekstensi

Jalankan ekstensi yang akan langsung memanggil operasi ekstensi dengan parameter yang diberikan dalam permintaan.

Sintaksis

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

Daftar parameter

Parameter

operation_id

string

ID operasi yang dipilih yang akan dieksekusi di ekstensi ini

operation_params

Opsional: JsonDict|Struct

Parameter permintaan yang akan digunakan untuk menjalankan operasi ini. JSON harus dalam bentuk peta dengan nama parameter sebagai kunci dan nilai parameter sebenarnya sebagai nilai. Misalnya, jika operasi ini memerlukan parameter "query" yang disetel ke "What is Vertex AI?". Anda dapat menyetelnya ke sesuatu seperti {"query": "What is Vertex AI?"}.

Contoh

Contoh ini mengeksekusi ekstensi penafsir kode generate_and_execute untuk mendapatkan jawaban atas kueri "temukan nilai maksimum dalam daftar: [1,2,3,4,-5]".

  • ID_PROJECT = PROJECT_ID
  • WILAYAH = 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]"},
)

Mencantumkan Ekstensi

Mencantumkan resource ekstensi dalam project.

Contoh

  • ID_PROJECT = PROJECT_ID
  • WILAYAH = 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()

Dapatkan Ekstensi

Mendapatkan resource ekstensi.

Contoh

  • ID_PROJECT = PROJECT_ID
  • WILAYAH = 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)

Mengupdate Ekstensi

Memperbarui resource ekstensi. Anda dapat memperbarui displayName, deskripsi, atau toolUseExamples ekstensi.

Contoh

Contoh ini memperbarui deskripsi ekstensi menjadi "Alat yang bagus".

  • ID_PROJECT = PROJECT_ID
  • WILAYAH = 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.",
}'

Hapus Ekstensi

Menghapus resource ekstensi.

Contoh

Contoh ini menghapus ekstensi yang terkait dengan ID ekstensi.

  • ID_PROJECT = PROJECT_ID
  • WILAYAH = 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()

Jelajahi lebih lanjut

Untuk dokumentasi mendetail, lihat: