Vertex AI menyediakan Extension API yang dapat mendaftarkan, mengelola, dan menjalankan ekstensi. Vertex AI juga menyediakan serangkaian ekstensi bawaan dari Extension API, termasuk ekstensi penafsir kode dan ekstensi Vertex AI Search.
Batasan
Extension API hanya tersedia di wilayah us-central1
.
Contoh sintaksis
Sintaksis untuk membuat resource ekstensi.
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 )
Daftar parameter
Isi permintaan
Parameter | |
---|---|
|
Opsional: Nama tampilan ekstensi yang ditampilkan kepada pengguna dari API dan UI. Ini harus berupa string UTF-8 hingga 128 karakter. |
|
Opsional: Deskripsi ekstensi yang ditampilkan kepada pengguna dari API dan UI. Ini harus berupa string UTF-8 hingga 1 MB. |
Manifes ekstensi. |
|
Opsional: Konfigurasi runtime yang mengontrol perilaku runtime ekstensi. Untuk ekstensi penafsir kode, formatnya adalah sebagai berikut: "runtimeConfig": { "codeInterpreterRuntimeConfig": { "fileInputGcsBucket": string, "fileOutputGcsBucket": string } } Untuk ekstensi Vertex AI Search, formatnya adalah sebagai berikut: "runtimeConfig": { "vertexAiSearchRuntimeConfig": { "servingConfigName": string, } } |
manifest
Manifes ekstensi.
Parameter | |
---|---|
|
Nama ekstensi yang digunakan oleh LLM untuk alasan. Ini harus berupa string UTF-8 hingga 128 karakter. |
|
Deskripsi dalam bahasa alami tentang penggunaan ekstensi. Deskripsi ditampilkan ke LLM untuk membantunya melakukan penalaran.Deskripsi ini harus berupa string UTF-8 hingga 1 MB. |
Spesifikasi API yang ditampilkan ke LLM untuk penalaran. Anda harus memberikan deskripsi yang bermakna dan informatif. "apiSpec": { "openApiGcsUri": string } |
|
Jenis autentikasi yang didukung oleh ekstensi ini. Permintaan impor ekstensi harus berisi konfigurasi autentikasi. "authConfig": { "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH", "googleServiceAccountConfig": { "serviceAccount": string }, } |
apiSpec
Spesifikasi API yang ditampilkan ke LLM untuk penalaran.
Parameter | |
---|---|
|
URI Cloud Storage dari file YAML OpenAPI yang menjelaskan API ekstensi, seperti |
authConfig
Jenis autentikasi yang didukung oleh ekstensi ini.
Parameter | |
---|---|
|
Metode autentikasi. Nilai yang didukung: |
googleServiceAccountConfig
Ekstensi penafsir kode dan ekstensi Penelusuran Vertex AI hanya mendukung autentikasi Akun Layanan Google, dengan Vertex AI menggunakan Agen Layanan Ekstensi Vertex AI untuk mengakses API.
Parameter | |
---|---|
|
Opsional: Akun layanan yang digunakan untuk menjalankan eksekusi ekstensi. Jika akun layanan ditentukan, izin |
runtimeConfig
Objek runtimeConfig
berisi konfigurasi tambahan yang digunakan saat menjalankan ekstensi.
Ekstensi penafsir kode
Parameter | |
---|---|
|
Opsional: Bucket Cloud Storage untuk input file ke ekstensi. Agen Layanan Kode Kustom Ekstensi Vertex harus diberi izin |
|
Opsional: Bucket Cloud Storage untuk output file dari ekstensi. Agen Layanan Kode Kustom Ekstensi Vertex harus diberi izin |
Ekstensi Vertex AI Search
Parameter | |
---|---|
|
Nama konfigurasi penayangan Vertex AI Search untuk menentukan resource Vertex AI Search yang digunakan ekstensi. Format:
|
Menjalankan ekstensi
Parameter | |
---|---|
|
ID operasi yang dipilih untuk dieksekusi di ekstensi ini. |
|
Opsional: Minta parameter yang digunakan untuk menjalankan operasi ini. JSON harus dalam bentuk peta dengan nama parameter sebagai kunci dan nilai parameter sebenarnya sebagai nilai. Misalnya, untuk menetapkan parameter yang disebut |
Contoh
Mengimpor ekstensi penafsir kode
Buat atau daftarkan resource ekstensi.
Contoh ini menunjukkan cara mengimpor ekstensi penafsir kode.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region untuk memproses permintaan.
- DISPLAY_NAME: Nama tampilan ekstensi yang ditampilkan kepada pengguna dari API dan UI. Ini harus berupa string UTF-8 hingga 128 karakter.
- DESCRIPTION: Deskripsi ekstensi yang ditampilkan kepada pengguna dari API dan UI. Ini harus berupa string UTF-8 hingga 1 MB.
- MANIFEST_NAME: Nama ekstensi yang digunakan oleh LLM untuk alasan. Ini harus berupa string UTF-8 hingga 128 karakter
- MANIFEST_DESCRIPTION: Deskripsi bahasa alami yang ditampilkan ke LLM. Deskripsi ini harus menjelaskan penggunaan ekstensi, dan sangat penting bagi LLM untuk melakukan penalaran. Ini harus berupa string UTF-8 hingga 1 MB.
- GCS_URI: URI Cloud Storage dari file YAML OpenAPI yang menjelaskan API ekstensi.
- AUTH_TYPE: Metode autentikasi. Nilai yang didukung:
GOOGLE_SERVICE_ACCOUNT_AUTH
.
Metode HTTP dan URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import
Isi JSON permintaan:
{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "manifest": { "name": "NAME", "description": "MANIFEST_DESCRIPTION", "apiSpec": { "openApiGcsUri": "GCS_URI", }, "authConfig": { "authType": "AUTH_TYPE", "googleServiceAccountConfig": {} } } }
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
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
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
$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
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Python API.
Mengimpor dengan konfigurasi runtime
Buat atau daftarkan resource ekstensi.
Contoh ini menunjukkan cara mengimpor ekstensi Vertex AI Search dengan menentukan RuntimeConfig
.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region untuk memproses permintaan.
- DISPLAY_NAME: Nama tampilan ekstensi yang ditampilkan kepada pengguna dari API dan UI. Ini harus berupa string UTF-8 hingga 128 karakter.
- DESCRIPTION: Deskripsi ekstensi yang ditampilkan kepada pengguna dari API dan UI. Ini harus berupa string UTF-8 hingga 1 MB.
- MANIFEST_NAME: Nama ekstensi yang digunakan oleh LLM untuk alasan. Ini harus berupa string UTF-8 hingga 128 karakter
- MANIFEST_DESCRIPTION: Deskripsi bahasa alami yang ditampilkan ke LLM. Deskripsi ini harus menjelaskan penggunaan ekstensi, dan sangat penting bagi LLM untuk melakukan penalaran. Ini harus berupa string UTF-8 hingga 1 MB.
- GCS_URI: URI Cloud Storage dari file YAML OpenAPI yang menjelaskan API ekstensi.
- AUTH_TYPE: Metode autentikasi. Nilai yang didukung:
GOOGLE_SERVICE_ACCOUNT_AUTH
. - SERVING_CONFIG_NAME: Nama konfigurasi penayangan Vertex AI Search untuk menentukan resource Vertex AI Search yang digunakan ekstensi. Format:
projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}
Metode HTTP dan URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import
Isi JSON permintaan:
{ "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, } } } }
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
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
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
$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, } } )
Menjalankan ekstensi
Untuk mengeksekusi ekstensi, panggil ekstensi secara langsung dan berikan parameter eksekusi dalam permintaan.
Contoh ini mengeksekusi ekstensi penafsir kode generate_and_execute
untuk
mendapatkan jawaban untuk kueri find the max value in the list: [1,2,3,4,-5]
.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region untuk memproses permintaan.
- EXTENSION_ID: ID ekstensi.
- OPERATION_ID: ID operasi yang dipilih untuk dieksekusi di ekstensi ini.
- QUERY: Parameter Permintaan untuk menjalankan operasi dalam format Nilai Kunci,
{"query": "What is Vertex AI?"}.
Metode HTTP dan URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute
Isi JSON permintaan:
{ "operation_id": "OPERATION_ID", "operation_params": { "query": "QUERY", } }
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
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
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
$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
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Python API.
Mencantumkan Ekstensi
Mencantumkan ekstensi dalam project.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region untuk memproses permintaan.
- EXTENSION_ID: ID ekstensi.
Metode HTTP dan URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Jalankan perintah berikut:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions"
PowerShell
Jalankan perintah berikut:
$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
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Python API.
Mendapatkan ekstensi
Mendapatkan detail ekstensi.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region untuk memproses permintaan.
- EXTENSION_ID: ID ekstensi.
Metode HTTP dan URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Jalankan perintah berikut:
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
Jalankan perintah berikut:
$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
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Python API.
Mengupdate ekstensi
Mengupdate ekstensi.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region untuk memproses permintaan.
- EXTENSION_ID: ID ekstensi.
- UPDATE_MASK: Parameter yang akan diperbarui. Nilai yang diterima,
displayName
,description
, atautoolUseExamples
.
Metode HTTP dan URL:
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"
Isi JSON permintaan:
{ "description": "UPDATE_MASK", }
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
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
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
$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
Menghapus Ekstensi
Menghapus ekstensi.
Contoh ini menghapus ekstensi yang terkait dengan ID ekstensi.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region untuk memproses permintaan.
- EXTENSION_ID: ID ekstensi.
Metode HTTP dan URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Jalankan perintah berikut:
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
Jalankan perintah berikut:
$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
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Python API.