Membuat dan menjalankan ekstensi

Dokumen ini menunjukkan fungsi utama layanan ekstensi Vertex AI:

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

Membuat dan mengimpor ekstensi

Dokumen ini mengasumsikan bahwa Anda sudah memiliki layanan API yang berjalan dan 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. Kemudian, 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 beberapa server.

    servers:
  - url: API_SERVICE_URL

  • Objek jalur. 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 mendeskripsikan 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 "halo" 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

Mengupload file spesifikasi

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

Jika Anda mengupload file spesifikasi ke bucket Cloud Storage, berikan peran Storage Object Viewer kepada akun layanan Vertex AI Extension Service Agent (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com). 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) guna 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 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 memberikan 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 dapat bersifat publik, tersedia untuk digunakan oleh setiap pengguna, atau pribadi, hanya tersedia untuk 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 satu parameter output. 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 memberikan 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 memberikan 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 sesuai 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 Anda memerlukan autentikasi, Anda harus menetapkan jenis autentikasi di variabel authType dan memberikan konfigurasi autentikasi. Anda dapat memilih antara metode autentikasi berikut:

Autentikasi kunci API

Untuk mendukung autentikasi kunci API, Vertex AI terintegrasi dengan SecretManager untuk penyimpanan dan akses secret. 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 https://example.com/act?api_key=<API KEY>, API_KEY_CONFIG_NAME sesuai 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 Menjelaskan parameter.

Autentikasi dasar HTTP

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

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.

Token akses

Tentukan authConfig sebagai berikut:

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

Biarkan kolom oauthConfig kosong saat Anda mengimpor ekstensi. Jika memilih untuk menjalankan ekstensi terdaftar, Anda harus memberikan token akses di kolom oauthConfig permintaan eksekusi. Untuk mempelajari lebih lanjut, lihat Menjalankan ekstensi.

Akun layanan

Tentukan authConfig sebagai berikut:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI menggunakan akun layanan ini untuk membuat token akses.

Lakukan langkah-langkah berikut untuk mengizinkan Vertex AI Extension Service Agent mendapatkan token akses dari SERVICE_ACCOUNT_NAME.

  1. Buka halaman IAM.

    Buka IAM

  2. Pilih tab Service Accounts.

  3. Klik akun layanan Anda. Nilai SERVICE_ACCOUNT_NAME di authConfig harus sesuai dengan nama akun layanan Anda.

  4. Klik tab Izin.

  5. Klik Grant Access.

  6. Di bagian Tambahkan akun utama, di kolom New principals, masukkan service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. Akun utama ini sesuai dengan akun layanan Vertex AI Extension Service Agent.

  7. Di bagian Assign roles, cari dan pilih peran Service Account Token Creator. Peran ini mencakup izin iam.serviceAccounts.getAccessToken.

  8. Klik tombol Save.

Autentikasi OIDC

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

Token ID

Tentukan authConfig sebagai berikut:

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

Biarkan kolom oidcConfig kosong saat Anda mengimpor ekstensi. Jika memilih untuk menjalankan ekstensi terdaftar, Anda harus memberikan token ID di kolom oidcConfig permintaan eksekusi. Untuk mempelajari lebih lanjut, lihat Menjalankan ekstensi.

Akun layanan

Tentukan authConfig sebagai berikut:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI menggunakan akun layanan ini untuk membuat token OpenID Connect (OIDC). Vertex AI menetapkan audiens untuk token ke API_SERVICE_URL, seperti yang ditentukan dalam file spesifikasi API.

Lakukan langkah-langkah berikut untuk mengizinkan Vertex AI Extension Service Agent mendapatkan token akses dari SERVICE_ACCOUNT_NAME.

  1. Buka halaman IAM.

    Buka IAM

  2. Pilih tab Service Accounts.

  3. Klik akun layanan Anda. Nilai SERVICE_ACCOUNT_NAME di authConfig harus sesuai dengan nama akun layanan Anda.

  4. Klik tab Izin.

  5. Klik Grant Access.

  6. Di bagian Tambahkan akun utama, di kolom New principals, masukkan service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. Akun utama ini sesuai dengan akun layanan Vertex AI Extension Service Agent.

  7. Di bagian Assign roles, cari dan pilih peran Service Account Token Creator. Peran ini mencakup izin iam.serviceAccounts.getOpenIdToken.

  8. Klik tombol Save.

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="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
    • PROJECT_ID: Project Anda.
    • LOCATION: Region pilihan Anda. Jika Anda 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"

    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 semua ekstensi 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 memperbarui displayName, description, atau toolUseExamples ekstensi. Jika Anda menentukan toolUseExamples saat mengupdate ekstensi, update akan menggantikan contoh. Misalnya, jika Anda memiliki contoh a dan b, perbarui ekstensi dengan contoh c, maka ekstensi yang diperbarui hanya 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

Ada dua cara untuk menjalankan ekstensi:

  • execute: Mode ini hanya berfokus pada eksekusi API. Ekstensi memicu operasi API yang ditentukan dan menampilkan hasil mentah tanpa pemrosesan lebih lanjut.

  • query: Mode ini dirancang untuk interaksi cerdas. Hal ini melibatkan beberapa langkah:

    • Permintaan model: Kueri dan skema ekstensi diberikan ke Gemini sebagai perintah dan FunctionDeclaration.
    • Eksekusi API: Jika model menentukan bahwa penggunaan alat diperlukan, ekstensi akan otomatis memanggil operasi API atas nama model, dan mengambil hasilnya.
    • Integrasi model: Hasil API dimasukkan ke dalam model, yang memprosesnya untuk menghasilkan respons akhir yang relevan secara kontekstual. Pada dasarnya, query bertindak sebagai agen alat tunggal, menggunakan API untuk mencapai sasarannya.

Bagian ini menjelaskan cara execute ekstensi.

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

Jika ekstensi Anda menggunakan autentikasi OIDC dan token ID, lihat 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 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