Panduan developer untuk Gemini 3.5 Flash

Gemini 3.5 Flash adalah model andalan yang berkecepatan tinggi dan hemat biaya dalam rangkaian Gemini 3. Dirancang untuk memberikan kemampuan agentic yang hampir setara dengan Pro tanpa mengorbankan performa atau nilai, model ini kini tersedia secara umum (GA) bagi developer yang menggunakan Gemini API dan untuk perusahaan yang menggunakan Gemini Enterprise Agent Platform.

Dokumen ini membahas hal-hal baru di 3.5 Flash, kapan Anda harus menggunakannya, cara bermigrasi ke 3.5 Flash, dan memberikan panduan memulai untuk menggunakan 3.5 Flash.

Bagaimana posisinya dalam rangkaian model Gemini?

Tabel berikut adalah perbandingan yang mencakup beberapa spesifikasi antara 3.5 Flash, 3.1 Pro, dan 3.1 Flash-Lite:

	Gemini 3.5 Flash	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite
ID Model	gemini-3.5-flash	gemini-3.1-pro-preview	gemini-3.1-flash-lite
Tahap peluncuran	GA	Pratinjau	GA
Jenis input	Teks, Gambar, Audio, Video	Teks, Gambar, Audio, Video	Teks, Gambar, Audio, Video
Jenis output	Teks	Teks	Teks
Jendela konteks	1.048.576	1.048.576	1.048.576
Panjang token output maksimum	65.536	65.536	65.536
Region yang didukung	Global, Multi-region, Amerika, Eropa, Asia Pasifik	Global	Global, Multi-region
Tingkat penalaran yang didukung	MINIMAL, LOW, MEDIUM, HIGH (Default: MEDIUM)	LOW, MEDIUM, HIGH (Default: HIGH)	MINIMAL, LOW, MEDIUM, HIGH (Default: MINIMAL)
Fokus utama	Tugas seimbang, panggilan alat, dan penalaran menengah	Tugas dengan penalaran mendalam dan kompleksitas tinggi	Tugas bervolume tinggi, sensitif terhadap biaya, dan sensitif terhadap latensi

Lihat halaman model 3.5 Flash untuk mengetahui daftar lengkap kemampuan, alat, dan opsi konsumsi yang didukung.

Perincian kasus penggunaan

Strategi yang direkomendasikan untuk Agentic Workflows menggunakan pendekatan bertingkat untuk mengoptimalkan kualitas, kecepatan, dan biaya:

• Gemini Pro: Gunakan untuk tugas kognitif kompleksitas tinggi yang memerlukan penalaran mendalam, seperti perencanaan awal, pemecahan masalah kompleks, coding yang sulit, dan pengambilan keputusan penting.
• Gemini Flash: Gunakan sebagai "pekerja keras" utama untuk tugas eksekusi, panggilan alat, dan langkah-langkah penalaran menengah, yang menawarkan keseimbangan terbaik antara performa dan efisiensi.
• Gemini Flash-Lite: Deploy untuk tugas pra-pemrosesan dan struktural bervolume tinggi dan berlatensi rendah yang mengutamakan kecepatan dan biaya, seperti pemilihan rute intent, ekstraksi data, pemberian tag, dan klasifikasi.

Apa yang baru di Gemini 3.5 Flash?

Gemini 3.5 Flash menghadirkan perubahan dan peningkatan berikut pada jajaran model Gemini:

• Performa terdepan yang berkelanjutan: Model Flash kami yang paling cerdas, dioptimalkan untuk tugas agentic dan coding dalam skala besar.
• Eksekusi agentic: Deployment sub-agen, pemecahan masalah, dan loop agentic yang cepat dalam skala besar.
• Coding yang lebih baik: Siklus coding iteratif, eksplorasi cepat, dan pembuatan prototipe untuk menguji jalur alternatif dan mengeksplorasi solusi secara dinamis.
• Jangka panjang: Alur kerja multilangkah dan penggunaan alat dalam skala besar.
• Retensi penalaran: Model mempertahankan penalaran perantara di seluruh percakapan multi-turn secara otomatis. Tidak perlu mengubah API.
• Level penalaran default baru: Level penalaran default diubah dari HIGH menjadi MEDIUM.
• Peningkatan penalaran LOW: Tingkat penalaran rendah kini ditingkatkan secara signifikan untuk tugas kode dan agen yang memerlukan lebih sedikit langkah, sehingga menawarkan kualitas yang kuat dengan latensi dan biaya yang lebih rendah.

Anda dapat menemukan detail selengkapnya di bagian Perubahan utama.

Catatan: Anda mungkin melihat peningkatan jumlah token yang dilaporkan. Infrastruktur yang diupgrade secara akurat menghitung semua komponen permintaan, termasuk metadata kompleks seperti skema respons dan panggilan fungsi, yang kurang dihitung dalam versi sebelumnya.

Panduan Memulai

Sebelum memulai, Anda harus melakukan autentikasi ke Agent Platform menggunakan Kredensial Default Aplikasi (ADC) atau kunci API. Lihat Mulai menggunakan Gemini Enterprise Agent Platform untuk informasi selengkapnya.

Dalam blok kode berikut, ganti PROJECT_ID dengan project ID Anda.

Penginstalan

Pastikan Anda menggunakan google-genai SDK terbaru:

pip install --upgrade google-genai

Permintaan dasar

Python

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

Perubahan penting

Bagian ini menjelaskan lebih detail perubahan berikut yang diperkenalkan di Gemini 3.5 Flash:

• Tingkat penalaran default baru (MEDIUM)
• Retensi penalaran
• Tidak digunakan lagi: Parameter sampling
• Tidak digunakan lagi: thinking_budget

Tingkat penalaran default baru

Tingkat penalaran default untuk model Gemini 3 kini adalah MEDIUM, berubah dari HIGH di versi pratinjau Gemini 3 Flash. Thinking level MEDIUM memberikan hasil yang kuat di berbagai tugas, sekaligus lebih cepat dan lebih hemat biaya.

Tingkat penalaran yang didukung adalah:

• MINIMAL: Cocok dengan setelan "tanpa penalaran" untuk sebagian besar kueri. Model ini mungkin berpikir sangat minimal untuk tugas-tugas kompleks seperti coding. Meminimalkan latensi untuk aplikasi chat atau throughput tinggi.
• LOW: Penalaran ringan untuk sebagian besar tugas dengan kecepatan tinggi dan biaya lebih rendah.
• MEDIUM: (Default) Setelan seimbang untuk sebagian besar tugas yang memerlukan penalaran.
• HIGH: Memaksimalkan penalaran untuk mengoptimalkan performa tugas. Model mungkin memerlukan waktu lebih lama daripada setelan MEDIUM untuk menghasilkan token pertama, tetapi outputnya akan lebih menyeluruh.

Misalnya, gunakan HIGH untuk teka-teki logika, soal cerita matematika, atau skenario rumit yang mengharuskan model melakukan penalaran melalui beberapa langkah:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

Parameter thinking_level bersifat opsional. Jika dihilangkan, 3.5 Flash akan menggunakan setelan defaultnya (MEDIUM).

Catatan: Parameter thinking_level dan parameter thinking_budget lama bersifat eksklusif satu sama lain. Menggunakan keduanya dalam permintaan akan menampilkan error 400.

Retensi penalaran

Model ini mempertahankan penalaran perantara di seluruh percakapan multi-giliran secara otomatis. Jika ada dalam histori percakapan, konteks penalaran akan diteruskan secara otomatis, sehingga meningkatkan performa pada tugas multilangkah yang kompleks seperti proses debug iteratif dan pemfaktoran ulang kode. Tidak perlu mengubah API.

Pemikiran dari giliran sebelumnya kini dipertahankan secara default. Layanan tidak lagi menghapus histori pemikiran dari konteks percakapan sebelum meneruskannya ke model.

Saat mengirim histori percakapan, konsistenlah dengan giliran sebelumnya: sertakan konteks lengkap (pemikiran, panggilan fungsi, respons) atau hilangkan sepenuhnya. Konteks parsial dapat menurunkan performa model.

Catatan: Retensi penalaran dapat meningkatkan penggunaan token dan waktu respons. Untuk kueri yang sederhana dan independen, menghapus pemikiran di antara giliran dapat membantu.

Tidak digunakan lagi: Parameter sampling

Parameter sampling berikut tidak lagi direkomendasikan untuk model Gemini 3:

• temperature
• top_p
• top_k

Model ini mengelola pengambilan sampelnya sendiri untuk mendapatkan hasil yang optimal. Hapus parameter ini dari semua permintaan. Untuk memastikan determinisme, tentukan petunjuk sistem dengan aturan eksplisit untuk kasus penggunaan spesifik Anda.

Tidak digunakan lagi: thinking_budget

Parameter thinking_budget numerik mentah tidak lagi didukung di semua model Gemini 3. Gunakan enum string thinking_level sebagai gantinya.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

Praktik terbaik

Bagian ini menjelaskan praktik terbaik berikut untuk menggunakan 3.5 Flash:

• Menggunakan pencocokan respons ketat untuk panggilan fungsi
• Menyertakan konten multimodal dalam respons fungsi parts
• Menggunakan petunjuk inline dalam respons fungsi
• Mengurangi panggilan alat yang tidak perlu

Menggunakan pencocokan respons ketat untuk panggilan fungsi

Respons yang tidak cocok menyebabkan model menampilkan respons kosong dengan finish_reason: STOP dalam sebagian besar kasus. Selalu ikuti konvensi berikut:

• Sertakan id: Setiap FunctionResponse harus menyertakan id dari FunctionCall yang sesuai.
• Cocokkan name: name dalam respons harus cocok dengan name dalam panggilan.
• Jumlah kecocokan: Menampilkan tepat satu FunctionResponse untuk setiap FunctionCall yang diterima.

Kode berikut adalah contoh panggilan fungsi yang benar:

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

Menyertakan konten multimodal dalam respons fungsi parts

Memberikan gambar di luar respons fungsi dapat menyebabkan perilaku model yang tidak terduga, seperti kebocoran pemikiran, dan menghasilkan kualitas yang lebih rendah. Ikuti rekomendasi yang disertakan dalam Pengantar panggilan fungsi dan sertakan konten multimodal di bagian respons fungsi yang Anda kirim ke model. Model dapat memproses konten multimodal ini dalam giliran berikutnya untuk menghasilkan respons yang lebih akurat.

Contoh:

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

Menggunakan petunjuk inline dalam respons fungsi

Memberikan petunjuk platform bersama dengan respons fungsi sebagai parts berikutnya dapat menyebabkan perilaku model yang tidak terduga seperti kebocoran pemikiran dan menghasilkan kualitas yang lebih rendah. Sebagai gantinya, tambahkan ke akhir teks respons fungsi yang dipisahkan oleh dua baris baru.

Contoh:

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

Mengurangi panggilan alat yang tidak perlu

Jika Anda mengalami penggunaan panggilan alat yang berlebihan, dua teknik berikut dapat membantu meminimalkannya:

1. Kurangi tingkat penalaran: Tingkat penalaran yang lebih tinggi mendorong model untuk menggunakan lebih banyak alat guna mengeksplorasi dan memverifikasi, sehingga menurunkan tingkat penalaran dapat mengurangi panggilan alat.

2. Tambahkan petunjuk sistem: Jika penggunaan berlebihan tetap terjadi setelah menyesuaikan tingkat pemikiran, pertimbangkan perintah yang membatasi penggunaan alat. Contoh:

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

Bermigrasi ke 3.6 Flash dari 3.5 Flash atau 3.1 Pro

Untuk bermigrasi ke 3.6 Flash dari 3.5 Flash atau 3.1 Pro, lakukan langkah-langkah berikut:

1. Perbarui ID model: Ubah string model dalam panggilan API Anda menjadi gemini-3.6-flash.
2. Sesuaikan kode Anda dengan aturan API rangkaian Gemini 3 yang baru: Gemini 3.6 Flash menerapkan aturan parameter dan konvensi API yang ditetapkan di seluruh rangkaian Gemini 3 secara ketat:
   • Hapus temperature, top-K, dan top-P: Hapus parameter kustom ini dari payload Anda. Meskipun tidak akan menampilkan error, model akan mengabaikannya sepenuhnya. Sebagai gantinya, gunakan parameter thinking_level atau output terstruktur json_schema untuk mengontrol determinisme output.
   • Hapus penalti frekuensi dan kehadiran: Hapus semua konfigurasi kustom untuk penalti frekuensi atau kehadiran agar panggilan API Anda tidak menampilkan error runtime.
   • Pastikan integrasi chat Anda tidak mencoba melakukan pengisian awal model: Tinjau array histori pesan Anda untuk memastikan payload API Anda tidak berakhir dengan giliran pengguna atau giliran model yang kosong. Jika objek terakhir dalam array histori Anda adalah peran "model" (GenerateContent API) atau jenis "model_output" (Interactions API), restrukturisasi urutan untuk menghindari pemicuan error validasi yang ketat.
   • Gunakan thinking_level: Hapus instance parameter thinking_budget yang tidak digunakan lagi dan gunakan thinking_level sebagai gantinya.
   • Menerapkan konvensi panggilan fungsi yang ketat: FunctionResponse harus sama persis dengan id, name, dan jumlah eksekusi FunctionCall sebelumnya. Jika Anda perlu menambahkan petunjuk inline, tempatkan petunjuk tersebut langsung di dalam teks respons fungsi yang dipisahkan oleh dua baris baru (\n\n).
3. Memperhitungkan perubahan alur kerja:
   • Jika aplikasi Anda mengandalkan loop percakapan multi-turn, uji alur kerja Anda untuk memastikan keringkasan langkah baru model tidak memicu penghentian dini.
   • Jika membangun agen pembuatan skrip dasar atau frontend, pantau panggilan execute_code eksplorasi yang tidak perlu karena bias baru model terhadap pemeriksaan terprogram di awal.

Solusi untuk persyaratan teks sebelum alat tersedia

Jika perintah Anda mengharuskan model untuk menghasilkan teks terstruktur (XLM, YAML, Json, dll.) (misalnya, <UPDATE>...</UPDATE>) tepat sebelum melakukan panggilan alat, panggilan alat terkadang dapat gagal dengan error Malformed_Function_Call. Anda dapat menggunakan salah satu solusi berikut untuk mengatasi masalah ini:

• (Direkomendasikan) Instruksikan model untuk menempatkan catatan pra-alatnya di dalam panggilan fungsi update() khusus, bukan teks mentah. Lihat bagian berikutnya untuk mengetahui petunjuk penerapan yang mendetail.
• Perintahkan model untuk menulis catatan sebagai header Markdown (misalnya, # UPDATE, ## PLAN), bukan teks terstruktur.
• Jangan mewajibkan model untuk menghasilkan teks sebelum panggilan alat.

Solusi yang direkomendasikan: Gabungkan catatan kerja dalam panggilan fungsi khusus

Alih-alih petunjuk asli:

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

Gunakan petunjuk yang diperbarui ini:

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

Perbarui semua referensi ke format XML <UPDATE> lama dalam permintaan pelanggan. Kemudian, tambahkan deklarasi fungsi yang sesuai untuk fungsi update:

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

Model akan melakukan dua panggilan dalam langkah yang sama: panggilan update() yang menggantikan XML terstruktur, dan panggilan fungsi sebenarnya yang ingin dilakukan.

Referensi lainnya

• Halaman model Gemini 3.5 Flash
• Notebook pengantar