Mengimpor, mengelola, dan menjalankan ekstensi

Ekstensi adalah koneksi ke API eksternal. API tersebut dapat memproses data real-time dan terhubung ke API eksternal untuk melakukan tindakan dunia nyata. Vertex AI menyediakan layanan ekstensi yang dapat mengimpor, mengelola, dan menjalankan ekstensi.

Layanan ekstensi ini dapat ditautkan ke aplikasi yang memproses kueri pengguna dan berkomunikasi dengan LLM. Layanan ekstensi dapat menyediakan kumpulan ekstensi dan operasi yang dapat dijalankan oleh ekstensi. Setiap kali menerima kueri pengguna, aplikasi memberikan informasi ini kepada LLM. Jika model menentukan bahwa model harus mendelegasikan pemrosesan kueri ke ekstensi, model akan menyediakan panggilan ekstensi yang diminta dan parameter value yang terkait. Aplikasi merelai permintaan ini ke layanan ekstensi, yang kemudian menjalankan ekstensi. Terakhir, layanan ekstensi mengirimkan hasil operasi ini ke aplikasi, yang kemudian mengembalikannya ke model.

Dokumen ini menunjukkan fungsi utama layanan ekstensi Vertex AI:

• Cara membuat dan mengimpor ekstensi.
• Cara mengelola ekstensi.
• Cara menjalankan ekstensi.

Untuk mempelajari cara mengimpor dan menjalankan ekstensi yang disediakan oleh Google, lihat artikel berikut:

• Gunakan ekstensi penafsir kode untuk membuat dan menjalankan kode.
• Gunakan ekstensi Vertex AI Search untuk mengakses dan menelusuri korpus situs dan data tidak terstruktur guna memberikan respons yang relevan terhadap pertanyaan natural language.

Membuat dan mengimpor ekstensi

Dokumen ini mengasumsikan bahwa Anda sudah memiliki layanan API berjalan yang dapat mendukung ekstensi. Untuk membuat ekstensi, Anda harus menentukan antarmukanya dengan API eksternal dalam file spesifikasi API. Anda harus mengupload file spesifikasi ini ke bucket Cloud Storage atau mengonversinya menjadi string. Selanjutnya, Anda harus menentukan manifes ekstensi, menyertakan file spesifikasi, dan mengirim permintaan pendaftaran ke layanan ekstensi.

Membuat file spesifikasi API

Ekstensi dapat dibuat oleh siapa saja melalui file yang menentukan dan menjelaskan endpoint API ekstensi. Endpoint API dapat bersifat publik atau pribadi dan dihosting di cloud atau infrastruktur lokal.

File spesifikasi API menjelaskan antarmuka layanan API. Anda harus menyediakan file spesifikasi API dalam format YAML yang kompatibel dengan OpenAPI 3.0. File spesifikasi ini harus menentukan hal berikut:

• Objek server. Objek ini harus menentukan URL server API. Layanan ekstensi Vertex AI tidak mendukung banyak server.

  servers:
    - url: API_SERVICE_URL
  

• Objek path. Objek ini harus menjelaskan berbagai operasi yang disediakan oleh layanan API dan parameter input yang sesuai dengan setiap operasi. Setiap operasi harus memiliki ID unik dan respons.

  paths:
    ...
      get:
        operationId: API_SERVICE_OPERATION_ID
        ...
        parameters:
          - name: API_SERVICE_INPUT_VAR
            ...
        responses:
        ...
  

• Objek komponen. Objek ini bersifat opsional. Anda dapat menggunakan objek komponen untuk menentukan objek yang dapat digunakan kembali. Misalnya, Anda dapat menggunakan objek komponen untuk memberikan definisi skema objek yang ditentukan dalam objek jalur. Anda juga dapat menggunakan objek komponen untuk menjelaskan parameter output layanan API.

  components:
    schemas:
      Result:
        ...
        properties:
          API_SERVICE_OUTPUT_VAR:
          ...
  

Untuk mempelajari OpenAPI lebih lanjut, lihat Spesifikasi OpenAPI.

Contoh berikut adalah file spesifikasi API untuk layanan API yang mengatakan "hello" dalam bahasa yang diminta:

  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: Hello Extension
    description: Learn to build Vertex AI extensions
  servers:
    - url: [API_SERVICE_URL]
  paths:
    /hello:
      get:
        operationId: "say_hello"
        description: "Say hello in prompted language."
        parameters:
          - name: "apiServicePrompt"
            in: query
            description: "Language"
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Successful operation.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Result"
  components:
    schemas:
      Result:
        description: "Hello in the requested language."
        properties:
          apiServiceOutput:
            type: string

Upload file spesifikasi

Anda dapat mengupload file spesifikasi ke bucket Cloud Storage atau mengonversinya menjadi string.

Jika Anda mengupload file spesifikasi ke bucket Cloud Storage, berikan peran Storage Object Viewer kepada akun layanan Vertex AI Extension Service Agent ([email protected]). Untuk mempelajari cara membuat daftar bucket di project Anda, lihat Mencantumkan bucket. Untuk mempelajari cara menyalin objek ke bucket Cloud Storage, baca artikel Menyalin, mengganti nama, dan memindahkan objek.

Menentukan permintaan impor ekstensi

Setelah membuat file spesifikasi API, Anda dapat menentukan permintaan impor ekstensi dalam file JSON. Permintaan impor ekstensi harus berisi referensi ke file spesifikasi API (apiSpec) dan konfigurasi autentikasi (authConfig). Untuk menghubungkan ekstensi ke model bahasa besar (LLM) untuk melihat cara kerja ekstensi, sertakan parameter toolUseExamples opsional. Jika Anda hanya ingin menjalankan ekstensi, jangan sertakan parameter toolUseExamples.

Permintaan impor ekstensi memiliki format berikut:

{
  "displayName":  "DISPLAY_NAME_HUMAN",
  "description": "DESCRIPTION_HUMAN",
  "manifest": {
    "name": "EXTENSION_NAME_LLM",
    "description": "DESCRIPTION_LLM",
    "apiSpec": { ... },
    "authConfig": { ... },
  }
  "toolUseExamples": [ ... ],
}

• DISPLAY_NAME_HUMAN: Nama ekstensi yang ditampilkan kepada pengguna.
• DESCRIPTION_HUMAN: Deskripsi ekstensi yang ditampilkan kepada pengguna.
• EXTENSION_NAME_LLM: Nama ekstensi yang digunakan oleh LLM untuk alasan.
• DESCRIPTION_LLM: Deskripsi ekstensi yang digunakan oleh LLM untuk memberikan alasan. Anda harus memberikan deskripsi yang bermakna dan informatif.

Referensi ke file spesifikasi API Anda

Permintaan impor ekstensi Anda harus berisi referensi ke file spesifikasi API. Anda dapat menyediakan file spesifikasi dengan dua cara:

• Gunakan openApiGcsUri untuk meneruskan Cloud Storage URI file YAML.

  "apiSpec": {
    "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
  },
  

  • BUCKET_NAME: Nama bucket Cloud Storage yang menyimpan file spesifikasi.
  • SPECIFICATION_FILE_NAME: Nama file spesifikasi API.

• Gunakan openApiYaml untuk meneruskan file YAML sebagai string.

Konfigurasi autentikasi

Ekstensi bisa bersifat publik, tersedia untuk digunakan oleh semua pengguna, atau pribadi, hanya tersedia bagi pengguna yang diberi otorisasi dalam satu atau beberapa organisasi.

Permintaan impor ekstensi harus berisi konfigurasi autentikasi. Anda dapat memilih antara metode autentikasi berikut:

• NO_AUTH: Tidak ada autentikasi
• API_KEY_AUTH: Autentikasi kunci API
• HTTP_BASIC_AUTH: Autentikasi dasar HTTP
• OAUTH: Autentikasi OAuth
• OIDC_AUTH: Autentikasi OIDC

Untuk mempelajari konfigurasi autentikasi lebih lanjut, lihat Menentukan konfigurasi autentikasi.

Contoh yang menunjukkan cara kerja ekstensi

Untuk hasil terbaik, permintaan impor ekstensi harus berisi contoh yang menunjukkan cara kerja ekstensi. Gunakan parameter toolUseExamples untuk memberikan contoh ini.

Kode berikut menunjukkan format toolUseExamples untuk satu contoh, dengan satu parameter input dan parameter output tunggal. Dalam contoh ini, parameter permintaan dan respons adalah jenis string.

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "API_SERVICE_OPERATION_ID",
      },
      "displayName": "EXAMPLE_DISPLAY_NAME",
      "query": "EXAMPLE_QUERY",
      "requestParams": {
        "fields": [
          {
            "key": "API_SERVICE_INPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_INPUT",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "API_SERVICE_OUTPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_OUTPUT",
            },
          }
        ],
      },
      "responseSummary": "EXAMPLE_SUMMARY"
    }
],

• query: Contoh kueri yang dapat memanfaatkan ekstensi ini. Gunakan EXAMPLE_QUERY untuk menyediakan teks kueri.
• extensionOperation: Operasi ekstensi yang cocok untuk menjawab query. Gunakan API_SERVICE_OPERATION_ID untuk memberikan ID operasi ekstensi yang ditentukan dalam file spesifikasi API.
• displayName: Nama tampilan untuk contoh. Gunakan EXAMPLE_DISPLAY_NAME untuk memberikan deskripsi singkat.
• requestParams: Parameter permintaan yang diperlukan untuk extensionOperation dan nilai contoh, dalam format nilai kunci. Gunakan API_SERVICE_INPUT_VAR untuk menyediakan parameter input yang ditentukan dalam file spesifikasi API dan sesuai dengan API_SERVICE_OPERATION_ID. Gunakan EXAMPLE_INPUT untuk memberikan contoh nilai input yang sesuai dengan EXAMPLE_QUERY.
• responseParams: Parameter respons extensionOperation dan contoh nilai dalam format nilai kunci. Gunakan API_SERVICE_OUTPUT_VAR untuk memberikan parameter output yang ditentukan dalam file spesifikasi API dan sesuai dengan layanan API. Gunakan EXAMPLE_OUTPUT untuk memberikan contoh nilai output yang terkait dengan EXAMPLE_INPUT.
• responseSummary: Contoh ringkasan yang mungkin diberikan aplikasi sebagai respons terhadap query. Gunakan EXAMPLE_SUMMARY untuk memberikan teks ringkasan.

Berikut adalah contoh toolUseExamples untuk layanan API yang mengatakan "halo" dalam bahasa yang diminta:

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "say_hello",
      },
      "displayName": "Say hello in the requested language",
      "query": "Say hello in French",
      "requestParams": {
        "fields": [
          {
            "key": "apiServicePrompt",
            "value": {
              "string_value": "French",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "apiServiceOutput",
            "value": {
              "string_value": "bonjour",
            },
          }
        ],
      },
      "responseSummary": "Bonjour"
    }
],

Menentukan konfigurasi autentikasi

Anda harus menentukan konfigurasi autentikasi saat menentukan permintaan impor ekstensi.

Jika ekstensi Anda tidak memerlukan autentikasi, tetapkan variabel authType ke NO_AUTH:

"authConfig": {
  "authType": "NO_AUTH"
}

Jika ekstensi memerlukan autentikasi, Anda harus menetapkan jenis autentikasi dalam variabel authType dan memberikan konfigurasi autentikasi. Anda dapat memilih antara metode autentikasi berikut:

• Autentikasi kunci HTTP API
• Autentikasi dasar HTTP
• Autentikasi OAuth
• Autentikasi OIDC

Autentikasi kunci API

Untuk mendukung autentikasi kunci API, Vertex AI terintegrasi dengan SecretManager untuk akses dan penyimpanan rahasia. Platform Vertex AI Extensions tidak menyimpan data rahasia secara langsung. Anda bertanggung jawab untuk mengelola siklus proses resource SecretManager.

Tentukan authConfig sebagai berikut:

"authConfig": {
  "authType": "API_KEY_AUTH",
  "apiKeyConfig": {
    "name": "API_KEY_CONFIG_NAME",
    "apiKeySecret": "API_KEY_SECRET",
    "httpElementLocation": "HTTP_ELEMENT_LOCATION",
  },
}

• API_KEY_CONFIG_NAME: Nama kunci API. Misalnya, dalam permintaan API http://example.com/act?api_key=<API KEY>, API_KEY_CONFIG_NAME berkaitan dengan api_key.
• API_KEY_SECRET: Resource versi secret SecretManager yang menyimpan kunci. Parameter ini memiliki format berikut: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

• HTTP_ELEMENT_LOCATION: Lokasi kunci API dalam permintaan HTTP. Nilainya dapat berupa:

  • HTTP_IN_QUERY
  • HTTP_IN_HEADER
  • HTTP_IN_PATH
  • HTTP_IN_BODY
  • HTTP_IN_COOKIE

  Untuk mempelajari lebih lanjut, lihat Mendeskripsikan parameter.

Autentikasi dasar HTTP

Untuk mendukung autentikasi dasar HTTP, Vertex AI terintegrasi dengan SecretManager untuk akses dan penyimpanan secret. Platform Vertex AI Extensions tidak menyimpan data rahasia secara langsung. Anda harus mengelola sendiri siklus proses resource SecretManager.

Tentukan authConfig sebagai berikut:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}

• CREDENTIAL_SECRET: Resource versi secret SecretManager yang menyimpan kredensial yang dienkode base64. Parameter ini memiliki format berikut: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

Autentikasi OAuth

Vertex AI mendukung dua metode autentikasi OAuth: token akses dan akun layanan.

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {}
}

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}

Autentikasi OIDC

Vertex AI mendukung dua metode autentikasi OIDC: token ID dan akun layanan.

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {}
}

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}

Mengimpor ekstensi dengan Vertex AI

Setelah menentukan permintaan impor ekstensi, Anda dapat mengimpor ekstensi dengan Vertex AI.

1. Tetapkan variabel shell berikut:

   ENDPOINT="LOCATION-aiplatform.googleapis.com"
   URL="http://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
   

   • PROJECT_ID: Project Anda.
   • LOCATION: Region pilihan Anda. Jika tidak yakin, pilih us-central1.

2. Jalankan perintah curl berikut untuk mengirimkan permintaan impor:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @IMPORT_REQUEST.json "${URL}/extensions:import"
   

   • IMPORT_REQUEST: Nama file JSON yang berisi permintaan impor ekstensi.

   Respons memiliki format berikut:

   {
     "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata",
       "genericMetadata": {
         "createTime": "[CREATE_TIME]",
         "updateTime": "[UPDATE_TIME]"
       }
     }
   }
   

3. Tetapkan variabel shell berdasarkan output permintaan impor:

   EXTENSION_ID=EXTENSION_ID
   IMPORT_OPERATION_ID=IMPORT_OPERATION_ID
   

4. Untuk memeriksa status impor, jalankan perintah curl berikut:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
   "${URL}/operations/${IMPORT_OPERATION_ID}"
   

Kelola ekstensi

Untuk menampilkan daftar semua ekstensi yang terdaftar, jalankan perintah curl berikut:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"

Untuk mendapatkan ekstensi, jalankan perintah curl berikut:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"

Anda dapat mengupdate displayName, description, atau toolUseExamples ekstensi. Jika Anda menentukan toolUseExamples saat mengupdate ekstensi, update tersebut akan menggantikan contoh yang ada. Misalnya, jika Anda memiliki contoh a dan b, mengupdate ekstensi dengan contoh c, maka ekstensi yang diupdate hanya akan berisi contoh c.Untuk memperbarui deskripsi ekstensi, jalankan perintah curl berikut:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

Untuk menghapus ekstensi, jalankan perintah curl berikut:

curl \
 -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}

Menjalankan ekstensi

Jika ekstensi Anda menggunakan autentikasi OAuth dan token akses, baca artikel Menjalankan ekstensi dengan autentikasi OAuth dan token akses.

Jika ekstensi Anda menggunakan autentikasi OIDC dan token ID, baca artikel Menjalankan ekstensi dengan autentikasi OIDC dan token ID.

Jika tidak, Anda dapat menjalankannya menggunakan langkah-langkah berikut:

1. Buat file bernama execute-extension.json dengan konten berikut:

   {
     "operation_id": "API_SERVICE_OPERATION_ID",
     "operation_params": {
       "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE"
     }
   }
   

   • API_SERVICE_OPERATION_ID: ID operasi layanan API yang ingin Anda jalankan. Operasi layanan API ditentukan dalam file spesifikasi API.
   • API_SERVICE_INPUT_VAR: Variabel input yang sesuai dengan API_SERVICE_OPERATION_ID dan ditentukan dalam file spesifikasi API.
   • API_SERVICE_INPUT_VALUE: Nilai input untuk ekstensi.

2. Jalankan perintah curl berikut:

   curl \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
   "${URL}/extensions/${EXTENSION_ID}:execute"
   

   Respons memiliki format berikut:

   {
     "output": {
       "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}"
     }
   }
   

   • API_SERVICE_OUTPUT_VAR: Parameter output yang ditentukan dalam file spesifikasi API dan sesuai dengan layanan API.
   • API_SERVICE_OUTPUT_VALUE: Nilai string yang merupakan serialisasi objek respons. Jika file spesifikasi API Anda menentukan skema respons JSON, Anda harus mengurai string output ini menjadi JSON sendiri.

Menjalankan ekstensi dengan autentikasi OAuth dan token akses

Jika ekstensi Anda menggunakan autentikasi OAuth dan token akses, Anda dapat menjalankannya menggunakan langkah-langkah berikut:

1. Buat file bernama execute-extension.json dengan konten berikut:

   {
     "operation_id": "API_SERVICE_OPERATION_ID",
     "operation_params": {...},
     "runtime_auth_config": {
       "authType": "OAUTH",
       "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"}
     }
   }
   

   • API_SERVICE_OPERATION_ID: ID operasi layanan API yang ingin Anda jalankan. Operasi layanan API ditentukan dalam file spesifikasi API.

2. Jalankan perintah curl berikut:

   curl \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
   "${URL}/extensions/${EXTENSION_ID}:execute"
   

Menjalankan ekstensi dengan autentikasi OIDC dan token ID

Jika ekstensi Anda menggunakan autentikasi OIDC dan token ID, Anda dapat menjalankannya menggunakan langkah-langkah berikut:

1. Buat file bernama execute-extension.json dengan konten berikut:

   {
     "operation_id": "API_SERVICE_OPERATION_ID",
     "operation_params": {...},
     "runtime_auth_config": {
       "authType": "OIDC_AUTH",
       "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"}
     }
   }
   

   • API_SERVICE_OPERATION_ID: ID operasi layanan API yang ingin Anda jalankan. Operasi layanan API ditentukan dalam file spesifikasi API.

2. Jalankan perintah curl berikut:

   curl \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
   "${URL}/extensions/${EXTENSION_ID}:execute"
   

Langkah selanjutnya

• Bangun dan deploy framework orkestrasi LLM.