Membuat dan menjalankan ekstensi

Dokumen ini menunjukkan fungsi utama Vertex AI layanan ekstensi:

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

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

• Gunakan ekstensi penafsir kode untuk membuat dan menjalankan pada kode sumber.
• Menggunakan ekstensi Vertex AI Search mengakses dan menelusuri korpus situs web dan data tak terstruktur untuk respons yang relevan terhadap pertanyaan natural language.

Membuat dan mengimpor ekstensi

Dokumen ini mengasumsikan bahwa Anda sudah memiliki layanan API yang 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 mengubahnya menjadi {i>string<i}. Kemudian, Anda harus menentukan manifes ekstensi, file spesifikasi, dan mengirimkan permintaan pendaftaran ke layanan ekstensi.

Membuat file spesifikasi API

Ekstensi dapat dibuat oleh siapa saja melalui file yang mendefinisikan dan menjelaskan Endpoint API. Endpoint API dapat bersifat publik atau pribadi, dan dihosting di 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. Ini harus menetapkan URL server API. Ekstensi Vertex AI layanan ini tidak mendukung banyak server.

  servers:
    - url: API_SERVICE_URL
  

• Objek paths. Objek ini harus menjelaskan berbagai operasi yang disediakan oleh layanan API serta input parameter 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. Sebagai Anda dapat menggunakan objek komponen untuk memberikan definisi skema objek yang ditentukan dalam objek jalur. Anda juga dapat menggunakan objek {i>components <i}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 berkata "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

Upload file spesifikasi

Anda dapat mengupload file spesifikasi ke 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 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 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 penalaran. 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 dalam dua cara:

• Gunakan openApiGcsUri untuk meneruskan URI Cloud Storage 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 semua pengguna, atau hanya pribadi tersedia untuk pengguna yang diotorisasi dalam satu atau beberapa organisasi.

Permintaan impor ekstensi harus berisi konfigurasi autentikasi. Anda dapat pilih di 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 lebih lanjut konfigurasi autentikasi, 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 menyediakan contoh-contoh ini.

Kode berikut menunjukkan format toolUseExamples untuk satu contoh, dengan satu parameter input dan satu parameter output. Dalam contoh ini, baik permintaan maupun parameter respons berjenis 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 sesuai 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 contoh nilai, dalam format nilai kunci. Gunakan API_SERVICE_INPUT_VAR untuk memberikan parameter input yang didefinisikan 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 menyediakan parameter output yang didefinisikan 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 berkata "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 otentikasi ketika 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 autentikasi ketik variabel authType dan berikan konfigurasi autentikasi. Anda dapat memilih di antara metode otentikasi 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 penyimpanan secret dan akses. Platform Vertex AI Extensions tidak menyimpan data rahasia secara langsung. Anda memiliki tanggung 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: SecretManager resource versi rahasia yang menyimpan tombolnya. Parameter ini memiliki format berikut: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

• HTTP_ELEMENT_LOCATION: Lokasi kunci API di HTTP permintaan. 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 penyimpanan secret dan akses. 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: SecretManager resource versi rahasia 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 dan 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: Wilayah pilihan Anda. Jika Anda tidak yakin, pilih us-central1.

2. Jalankan perintah curl berikut untuk mengirim 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 Anda, 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 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 ekstensi toolUseExamples. Jika Anda menentukan toolUseExamples saat mengupdate , maka pembaruan akan menggantikan contoh. Misalnya, jika Anda memiliki contoh a dan b, lalu update ekstensi dengan contoh c, lalu 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: Ini mode hanya berfokus pada eksekusi API. Ekstensi memicu pemicu yang ditentukan Operasi API dan menampilkan hasil mentah tanpa pemrosesan lebih lanjut.

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

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

Bagian ini menjelaskan cara melakukan execute ekstensi.

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

Jika ekstensi Anda menggunakan autentikasi OIDC dan token ID, lihat Jalankan 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 dijalankan. Operasi layanan API didefinisikan dalam File spesifikasi API.
   • API_SERVICE_INPUT_VAR: Variabel input yang sesuai dengan API_SERVICE_OPERATION_ID dan ditentukan di elemen 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 di file spesifikasi API dan sesuai dengan API layanan.
   • API_SERVICE_OUTPUT_VALUE: Nilai string yang merupakan serialisasi objek respons. Jika file spesifikasi API Anda menetapkan Skema respons JSON, Anda harus mengurai string output ini ke dalam JSON pada milik Anda sendiri.

Menjalankan ekstensi dengan autentikasi OAuth dan token akses

Jika ekstensi Anda menggunakan autentikasi OAuth dan token akses, Anda dapat menjalankan 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 dijalankan. Operasi layanan API didefinisikan 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 menggunakan autentikasi OIDC dan token ID, Anda dapat menjalankan 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 dijalankan. Operasi layanan API didefinisikan 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 Anda.