SMT Inferensi AI

Transformasi Metode Tunggal (SMT) Inferensi AI memungkinkan Anda mendapatkan inferensi pada pesan Pub/Sub dari model Gemini Enterprise Agent Platform. Anda dapat menggunakan model kustom Anda sendiri yang di-deploy di endpoint Agent Platform, atau menggunakan model Google dan partner yang tersedia melalui Agent Platform. Inferensi model ditambahkan ke setiap pesan, sehingga tersedia untuk pemrosesan downstream bersama dengan data pesan asli.

Kasus penggunaan untuk SMT Inferensi AI mencakup hal berikut:

  • Pengayaan real-time: Tambahkan konteks, klasifikasi, prediksi, sentimen, atau embedding ke data peristiwa saat mengalir melalui Pub/Sub.

  • Pipeline AI yang disederhanakan: Tidak perlu lagi layanan perantara untuk mendapatkan inferensi dari model AI. Pub/Sub menangani panggilan model AI dan memperkaya pesan dengan inferensi.

  • Mengurangi latensi untuk pipeline AI: Hapus hop jaringan tambahan dalam arsitektur Anda untuk mencapai latensi end-to-end yang lebih rendah.

  • Kontrol alur yang ditingkatkan: Untuk menghindari kelebihan beban pada endpoint model, Pub/Sub mengoptimalkan kecepatan permintaan ke model AI. Untuk mengetahui informasi selengkapnya, lihat Alur pesan dalam dokumen ini.

SMT AI Inference mendukung jenis model berikut:

  • Model yang di-deploy sendiri. Model terbuka, partner, dan kustom yang di-deploy ke endpoint Agent Platform publik bersama atau khusus.

  • Model Model-as-a-Service (MaaS). Model yang ditawarkan sebagai layanan melalui Model Garden, seperti Gemini dan Claude, yang tidak mengharuskan Anda mengelola deployment. Untuk mengetahui daftar model MaaS yang kompatibel dengan SMT AI Inference, lihat Model MaaS yang kompatibel.

Peran dan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat topik atau langganan dengan SMT, minta administrator untuk memberi Anda peran IAM Pub/Sub Editor (roles/pubsub.editor) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat topik atau langganan dengan SMT. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat topik atau langganan dengan SMT:

  • Buat topik: pubsub.topics.create pada project
  • Membuat langganan: pubsub.subscriptions.create pada project

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Izin akun layanan

SMT AI Inference menggunakan akun layanan IAM untuk memanggil endpoint Agent Platform. Secara default, akun ini menggunakan akun Agen Layanan Cloud Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com). Anda juga dapat memberikan akun layanan Anda sendiri.

Akun layanan memerlukan izin berikut pada project Google Cloudyang berisi endpoint Agent Platform:

  • aiplatform.endpoints.get
  • aiplatform.endpoints.predict

Untuk memberikan izin ini, tetapkan peran Agent Platform User ke akun layanan (baik menggunakan akun layanan Cloud Pub/Sub Service Agent atau akun layanan kustom).

Pemrosesan pesan

Bagian ini menjelaskan cara SMT Inferensi AI memproses pesan Pub/Sub.

Input

Data pesan Pub/Sub harus berupa permintaan untuk dikirim ke model AI, sebagai string JSON. Anda juga dapat menentukan parameter model tambahan untuk dikirim dengan setiap permintaan. SMT menggabungkan parameter ini dengan data pesan dan mengirimkan JSON yang digabungkan ke endpoint model.

Misalnya, jika Anda memiliki:

  • Masukkan data pesan: {"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
  • Parameter SMT: {"temperature": 0.2}

Payload yang dihasilkan dan dikirim ke model adalah:

{
  "messages": [
    {
      "role": "user",
      "content": "Explain photosynthesis"
    }
  ],
  "temperature": 0.2
}

Jika parameter yang ditentukan dalam konfigurasi SMT memiliki nama yang sama dengan kolom dalam data pesan, nilai dalam data pesan akan diprioritaskan.

Tabel berikut menunjukkan API yang dipanggil SMT untuk mendapatkan inferensi, berdasarkan jenis model.

Deployment model Jenis model API
Di-deploy sendiri Semua rawPredict
Model as a Service (MaaS)

Model dasar Gemini

Contoh: gemini-3.0-pro

 Chat Completions API

Model Gemini lainnya

Contoh: gemini-embeddings

 rawPredict
Anthropic, Mistral AI, atau AI21 rawPredict
Semua model MaaS lainnya Chat Completions API

Untuk memformat data pesan dan parameter model dengan benar, lihat dokumentasi untuk model Anda. Misalnya, untuk model dasar Gemini, lihat contoh Chat Completions API.

Jika aplikasi penayang Anda tidak dapat memformat pesan dalam struktur JSON tertentu yang diperlukan oleh model (seperti format Chat Completions API), Anda dapat merangkai UDF JavaScript SMT sebelum SMT Inferensi AI untuk melakukan pra-pemrosesan dan memformat payload permintaan. Sebagai contoh, lihat Melakukan pra-pemrosesan payload dengan UDF JavaScript.

Output

Jika panggilan ke endpoint model berhasil, SMT akan memperkaya pesan Pub/Sub asli dengan respons model. Pesan yang telah di-enrich adalah string JSON seperti berikut, dengan ORIGINAL_MESSAGE adalah data pesan asli dan INFERENCE_RESULT adalah respons dari model:

{
  "original_message": { ORIGINAL_MESSAGE },
  "model_output": { INFERENCE_RESULT }
}

Alur pesan

SMT Topik: Saat Anda menentukan SMT Inferensi AI pada suatu topik, Pub/Sub menangani pesan masuk sebagai berikut:

  1. Aplikasi penayang mengirim pesan ke topik Pub/Sub.

  2. Pesan dikirim ke endpoint model yang dikonfigurasi untuk inferensi. Pesan yang telah di-enrich, yang berisi data asli dan inferensi model, ditulis ke penyimpanan internal Pub/Sub.

  3. Pub/Sub mengirimkan pesan yang telah di-enrich ke semua langganan yang terlampir.

SMT Langganan: Saat Anda menentukan SMT Inferensi AI pada langganan, Pub/Sub menangani pesan masuk sebagai berikut:

  1. Aplikasi penayang mengirimkan pesan ke topik Pub/Sub.

  2. Pub/Sub mengirimkan pesan ke langganan.

  3. Pesan dikirim ke endpoint model yang dikonfigurasi untuk inferensi.

  4. Langganan mengirimkan pesan yang diperkaya ke aplikasi pelanggan.

  5. Pub/Sub mengoptimalkan tingkat permintaan ke model AI untuk memaksimalkan throughput, berdasarkan latensi dan kuota deployment Anda. Catatan: Kemampuan ini tidak didukung saat menggunakan unary pull API.

Anda dapat merangkai SMT AI Inference dengan satu atau beberapa SMT UDF JavaScript. Gunakan pola ini untuk melakukan pra-pemrosesan pesan agar sesuai dengan format input yang diharapkan model Anda, atau melakukan pasca-pemrosesan output model sebelum dikirim ke pelanggan.

Praktik Terbaik: Sebaiknya gunakan SMT Langganan, bukan SMT Topik untuk Inferensi AI. Jika endpoint model AI di-throttle, mengalami lonjakan latensi, atau menjadi tidak tersedia, potensi dampak pada pipeline Anda lebih besar dengan SMT topik:

  • Dengan SMT topik, permintaan publikasi akan gagal, yang berdampak langsung pada ketersediaan aplikasi penayang Anda.

  • Dengan SMT Langganan, Pub/Sub akan mencoba ulang pengiriman, termasuk mengeksekusi SMT, sesuai dengan kebijakan percobaan ulang langganan. Anda juga dapat mengonfigurasi topik yang dihentikan pengirimannya untuk menangani kegagalan persisten tanpa memengaruhi ketersediaan penyerapan.

Membuat SMT Inferensi AI

SMT dapat dikonfigurasi pada topik atau langganan Pub/Sub.

  • SMT topik dijalankan sebelum Pub/Sub menyimpan pesan, dan hasilnya tersedia untuk semua pelanggan.

  • SMT langganan dijalankan sebelum pesan dikirim, dan hasilnya hanya tersedia untuk langganan tersebut.

Konsol

  1. Di konsol Google Cloud , buka halaman Topik Pub/Sub.

    Buka Topik

  2. Membuat topik atau langganan.

    • Untuk membuat topik, klik Buat topik. Halaman Create topic akan terbuka.

    • Untuk membuat langganan:

      1. Klik nama topik tempat Anda menginginkan langganan.

      2. Klik Create subscription. Halaman Add subscription to topic akan terbuka.

  3. Di bagian Transformasi, klik Tambahkan transformasi.

  4. Untuk Transform type, pilih AI Inference.

  5. Untuk Endpoint, masukkan nama resource lengkap endpoint model Anda:

    • Model yang di-deploy sendiri: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Model Model Garden: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  6. Opsional. Pilih Service account yang akan digunakan saat memanggil endpoint Agent Platform. Untuk mengetahui informasi selengkapnya, lihat Izin akun layanan.

  7. Opsional. Di kolom Parameters, masukkan parameter model sebagai objek JSON. SMT menggabungkan parameter ini dengan setiap pesan sebelum memanggil model. Contoh:

    {
  "temperature": 0.5,
  "max_tokens": 1000
}

  8. Untuk membuat topik atau langganan, klik Buat.

gcloud

Membuat file definisi

Buat file YAML atau JSON yang menentukan Inference AI.

YAML 

- aiInference:
    endpoint: "ENDPOINT_RESOURCE"
    unstructuredInference: {
        parameters:
          MODEL_PARAMETERS
    }
    service_account_email: SERVICE_ACCOUNT

JSON 

{
  "aiInference": {
    "endpoint": "ENDPOINT_RESOURCE",
    "unstructuredInference": {
        "parameters": {
          MODEL_PARAMETERS
        }
    }
    "service_account_email": SERVICE_ACCOUNT
  }
}

Ganti kode berikut:

  • ENDPOINT_RESOURCE: Nama resource lengkap endpoint model. Gunakan format berikut:

    • Model yang di-deploy sendiri: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Model Model Garden: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  • MODEL_PARAMETERS: Opsional. Parameter model, yang ditentukan sebagai objek JSON. SMT menggabungkan parameter ini dengan setiap pesan sebelum memanggil model. Contoh:

    {
  "temperature": 0.5,
  "max_tokens": 1000
}

  • SERVICE_ACCOUNT: Opsional. Email akun layanan yang akan digunakan saat memanggil endpoint. Untuk mengetahui informasi selengkapnya, lihat Izin akun layanan.

Membuat topik atau langganan

Untuk membuat topik, jalankan perintah gcloud pubsub topics create.

gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Ganti kode berikut:

  • TOPIC_ID: ID atau nama topik yang ingin Anda buat.
  • TRANSFORMS_FILE: Jalur ke file definisi.

Untuk membuat langganan, jalankan perintah gcloud pubsub subscriptions create.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=projects/PROJECT_ID/topics/TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Ganti kode berikut:

  • SUBSCRIPTION_ID: ID atau nama langganan yang akan dibuat.

  • PROJECT_ID: ID project yang berisi topik.

  • TOPIC_ID: ID topik yang akan di-subscribe.

  • TRANSFORMS_FILE: Jalur ke file definisi.

Memvalidasi dan menguji

Secara opsional, Anda dapat memvalidasi dan menguji SMT yang dikonfigurasi, sebelum membuat topik atau langganan. Untuk informasi selengkapnya, baca dokumen berikut:

Contoh

Menggunakan SMT Inferensi AI

Contoh berikut menunjukkan cara membuat langganan dengan SMT AI Inference, lalu menggunakannya untuk mengirim perintah ke Gemini.

gcloud

  1. Dengan menggunakan editor teks, buat file bernama ai-smt.yaml dan tempelkan teks berikut:

    - aiInference:
    endpoint: projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-3.8-flash
    unstructuredInference: {
        parameters: {
            "max_tokens": 25000
        }
    }

    Ganti kode berikut:

    • PROJECT_ID: ID project Google Cloud Anda.
    • LOCATION: Lokasi endpoint yang akan dipanggil. Contoh: us-central1.

  2. Membuat topik Pub/Sub baru.

    gcloud pubsub topics create TOPIC_ID

    Ganti TOPIC_ID dengan nama topik yang akan dibuat. Contoh: topic-1.

  3. Buat langganan yang memiliki SMT Inferensi AI.

    gcloud pubsub subscriptions create TOPIC_ID-sub \
  --ack-deadline=600 \
  --topic TOPIC_ID \
  --message-transforms-file ai-smt.yaml

  4. Memublikasikan pesan ke topik. Pesan tersebut berisi perintah yang diformat untuk Chat Completions API.

    gcloud pubsub topics publish TOPIC_ID --message=$'{
  "model":"google/gemini-3.8-flash","messages":[{
    "role": "user",
    "content": "Explain how AI works in a few words"
    }]
  }'

  5. Menerima pesan dari langganan.

    gcloud pubsub subscriptions pull TOPIC_ID-sub

    Jika panggilan ke Agent Platform berhasil, pesan akan diperkaya dengan output dari perintah.

Memproses muatan terlebih dahulu dengan UDF JavaScript

Jika aplikasi penayang Anda memancarkan teks mentah, log, atau payload peristiwa, bukan JSON terstruktur yang diperlukan oleh model AI (seperti format Chat Completions yang kompatibel dengan OpenAI), Anda dapat menggabungkan SMT UDF JavaScript sebelum SMT Inferensi AI. UDF berfungsi sebagai lapisan terjemahan, mengubah pesan mentah menjadi format yang diharapkan model.

Contoh UDF JavaScript berikut menunjukkan cara melakukan pra-pemrosesan pesan yang berisi perintah teks menjadi permintaan API Chat Completions yang kompatibel dengan Gemini 3.8 Flash:

/**
 * Pre-processes a message containing a text prompt into a
 * Chat Completions API request compatible with Gemini 3.8 Flash.
 */
function prepareGeminiRequest(message, metadata) {
  // Assuming the incoming message data is a raw text prompt
  const promptText = message.data;

  const chatRequest = {
    "model": "google/gemini-3.8-flash",
    "messages": [
      {
        "role": "user",
        "content": promptText
      }
    ]
  };

  // Replace the message data with the stringified JSON request
  message.data = JSON.stringify(chatRequest);
  return message;
}

Anda juga dapat merangkai UDF JavaScript pasca-pemrosesan setelah SMT AI Inference untuk mengekstrak kolom tertentu dari respons model sebelum mengirimkannya ke pelanggan.

Model MaaS yang kompatibel

Tabel berikut mencantumkan model Model-as-a-Service (MaaS) yang telah diuji Google dengan SMT AI Inference dan diketahui kompatibel. Daftar ini dapat berubah sewaktu-waktu, karena model tidak digunakan lagi atau model MaaS baru ditambahkan.

ModelPanggilan API
google/gemini-3.8-flash Chat Completions API
google/gemini-3.7-flash Chat Completions API
google/gemini-3.6-flash Chat Completions API
google/gemini-3.5-flash Chat Completions API
google/gemini-3.5-flash-lite Chat Completions API
google/gemini-3.1-flash-lite Chat Completions API
google/gemini-3.1-pro-preview Chat Completions API
google/gemini-3-flash-preview Chat Completions API
google/gemini-3.1-flash-image Chat Completions API
google/gemini-3-pro-image Chat Completions API
google/gemini-2.5-flash-image Chat Completions API
google/gemini-2.5-pro Chat Completions API
google/gemini-2.5-flash-lite Chat Completions API
google/gemini-2.5-flash Chat Completions API
google/gemini-2.0-flash-lite-001 Chat Completions API
google/gemini-2.0-flash-001 Chat Completions API
meta/llama-4-maverick-17b-128e-instruct-maas Chat Completions API
meta/llama-4-scout-17b-16e-instruct-maas Chat Completions API
meta/llama-3.3-70b-instruct-maas Chat Completions API
deepseek-ai/deepseek-r1-0528-maas Chat Completions API
deepseek-ai/deepseek-v3.1-maas Chat Completions API
qwen/qwen3-235b-a22b-instruct-2507-maas Chat Completions API
qwen/qwen3-coder-480b-a35b-instruct-maas Chat Completions API
openai/gpt-oss-20b-maas Chat Completions API
openai/gpt-oss-120b-maas Chat Completions API
google/text-multilingual-embedding-002 rawPredict
google/text-embedding-005 rawPredict
google/text-embedding-large-exp-03-07 rawPredict
google/gemini-embedding-001 rawPredict
google/multimodalembedding rawPredict
anthropic/claude-sonnet-4-6 rawPredict
anthropic/claude-sonnet-4-5 rawPredict
anthropic/claude-sonnet-4 rawPredict
anthropic/claude-opus-4-6 rawPredict
anthropic/claude-opus-4-5 rawPredict
anthropic/claude-opus-4-1 rawPredict
anthropic/claude-opus-4 rawPredict
anthropic/claude-haiku-4-5 rawPredict
mistralai/mistral-ocr-2505 rawPredict
mistralai/mistral-small-2503 rawPredict
mistralai/mistral-medium-3 rawPredict
mistralai/codestral-2 rawPredict

Batasan

  • Hanya satu SMT Inferensi AI yang diizinkan per topik atau langganan.

  • Endpoint pribadi tidak didukung. Model yang di-deploy sendiri harus dihosting di endpoint Agent Platform publik.

  • Endpoint global hanya didukung untuk model dasar Gemini. Untuk model lainnya, Anda harus menggunakan endpoint regional.

  • Pub/Sub tidak memvalidasi data pesan input. Anda bertanggung jawab untuk memastikan format data sudah benar.

  • Transformasi mengirimkan satu permintaan inferensi per pesan Pub/Sub. Pengelompokan sisi klien tidak dilakukan.

  • Inferensi batch asinkron tidak didukung.

  • Inferensi tidak boleh memerlukan waktu lebih dari 60 detik. Jika melebihi 60 detik, upaya pengiriman akan mengalami waktu tunggu habis dan Pub/Sub akan mencoba lagi, hingga durasi retensi pesan dan setelan kebijakan percobaan ulang yang dikonfigurasi. Jika upaya kehabisan waktu, pesan akan diteruskan ke topik yang dihentikan pengirimannya, jika dikonfigurasi.

Model yang tidak didukung

SMT Inferensi AI tidak mendukung model MaaS berikut. Banyak dari model ini memiliki versi yang di-deploy sendiri yang dapat Anda gunakan.

  • deepseek-ai/deepseek-ocr-maas
  • deepseek-ai/deepseek-v3.2-maas
  • google/gemini-embedding-2-preview
  • google/lyria-002
  • google/lyria-3-clip-preview
  • google/lyria-3-pro-preview
  • google/veo-3.1-fast-generate-001
  • google/veo-3.1-generate-001
  • intfloat/multilingual-e5-large-instruct-maas
  • intfloat/multilingual-e5-small-instruct-maas
  • minimaxai/minimax-m2-maas
  • moonshotai/kimi-k2-thinking-maas
  • qwen/qwen3-next-80b-a3b-instruct-maas
  • qwen/qwen3-next-80b-a3b-thinking-maas
  • zai-org/glm-4.7-maas
  • zai-org/glm-5-maas

Batasan regional

Batasan berikut berlaku untuk SMT Inferensi AI berdasarkan region endpoint Agent Platform.

  • Jika SMT Inferensi AI ditentukan pada suatu topik, region endpoint harus berada dalam region yang diizinkan oleh kebijakan penyimpanan pesan topik tersebut.

    Batasan ini juga berlaku untuk SMT langganan jika Terapkan region dalam transit untuk pesan Pub/Sub batasan kebijakan organisasi berlaku.

  • Jika SMT Inferensi AI ditentukan pada langganan ekspor, maka region endpoint harus berada di region resource terkait:

  • Jika permintaan publikasi dibuat ke region selain region endpoint, Pub/Sub akan otomatis mengalihkan permintaan ke region endpoint.

  • Jika Anda menarik dari langganan dengan SMT Inferensi AI, dan permintaan pull dibuat ke region selain region endpoint, Pub/Sub akan menolak permintaan tersebut. Sebaiknya gunakan endpoint lokasi untuk langganan pull. Batasan ini berlaku untuk pull streaming dan pull unary.

  • Jika langganan push memiliki SMT Inferensi AI, langganan akan mengirimkan pesan dari region endpoint. Jika terjadi pelanggaran batasan regional, Pub/Sub akan berhenti mengirim pesan dari langganan tersebut.

Pemecahan masalah

Bagian ini memberikan tips pemecahan masalah untuk SMT Inferensi AI.

  • Error SMT topik. Jika inferensi gagal saat pesan dipublikasikan, seluruh permintaan publikasi akan gagal. Informasi error ditampilkan ke klien penayang.

  • Error SMT langganan. Jika inferensi gagal saat pesan dikirim (misalnya, karena ketidaktersediaan model yang berkepanjangan, kuota yang terus habis, atau error argumen yang tidak valid), pesan asli yang tidak diubah akan diteruskan ke topik yang dihentikan pengirimannya yang dikonfigurasi. Hal ini memastikan tidak ada data yang hilang. Pesan yang diteruskan mencakup atribut CloudPubSubDeadLetterSourceSMTErrorMessage yang berisi detail kegagalan SMT. Sebaiknya siapkan topik yang dihentikan pengirimannya saat menggunakan SMT pada langganan.

  • Error inferensi model. Jika inferensi gagal dan menampilkan error, periksa hal berikut:

    • Pastikan endpoint yang dikonfigurasi sudah benar.

    • Pastikan data pesan Pub/Sub berisi permintaan inferensi yang valid untuk model Anda.

    • Pastikan semua parameter model valid.

    Inferensi mungkin gagal karena alasan lain, seperti masalah konektivitas.

  • Error izin atau endpoint. Jika akun layanan yang dikonfigurasi kehilangan izin ke endpoint, atau endpoint dihapus, SMT akan gagal.

Kuota dan batas

  • Selain kuota dan batas Pub/Sub, SMT Inferensi AI tunduk pada kuota dan pembatasan kapasitas endpoint Agent Platform. Kontrol alur bawaan Pub/Sub secara otomatis menyesuaikan rasio permintaan untuk menghindari kelebihan beban pada endpoint, tetapi rasio tersebut tidak boleh melebihi kuota model.

  • Ukuran pesan akhir yang ditransformasi, termasuk pesan asli dan output inferensi, harus lebih kecil dari batas ukuran pesan Pub/Sub. Jika pesan yang diubah melebihi batas, transformasi akan gagal.

Langkah berikutnya