Panduan developer untuk Gemini 3.5 Flash

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

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

Bagaimana posisinya dalam keluarga Gemini?

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

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

Perincian kasus penggunaan

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

• Gemini Pro: Khusus untuk tugas kognitif dengan kompleksitas tinggi yang memerlukan penalaran mendalam, seperti perencanaan root awal, pemecahan masalah yang kompleks, coding yang sulit, dan pengambilan keputusan penting.
• Gemini Flash: Gunakan sebagai "kuda beban" utama untuk tugas eksekusi, pemanggilan 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 latensi rendah yang mengutamakan kecepatan dan biaya, seperti perutean niat, ekstraksi data, pemberian tag, dan klasifikasi.

Apa yang baru di Gemini 3.5 Flash?

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

• Performa terdepan yang berkelanjutan: Model Flash kami yang paling cerdas, dioptimalkan untuk tugas agentic dan coding dalam skala besar.
• Eksekusi seperti agen: Deployment sub-agen, pemecahan masalah, dan loop seperti agen yang cepat dalam skala besar.
• Peningkatan kualitas coding: Siklus coding berulang, eksplorasi cepat, dan pembuatan prototipe untuk menguji jalur alternatif dan menjelajahi solusi secara dinamis.
• Horizon panjang: Alur kerja multilangkah dan penggunaan alat dalam skala besar.
• Pelestarian pemikiran: Model mempertahankan penalaran perantara di seluruh percakapan multi-giliran secara otomatis. Tidak perlu mengubah API.
• Tingkat pemikiran default baru: Tingkat pemikiran default diubah dari HIGH menjadi MEDIUM.
• Peningkatan kualitas LOW berpikir: Tingkat berpikir rendah kini ditingkatkan secara signifikan untuk tugas kode dan agentik 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.

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 mengetahui informasi selengkapnya.

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

Penginstalan

Pastikan Anda menggunakan SDK google-genai terbaru:

pip install --upgrade google-genai

Permintaan dasar

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)

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 lanjut perubahan berikut yang diperkenalkan di Gemini 3.5 Flash:

• Tingkat pemikiran 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, yang sebelumnya HIGH di versi pratinjau Gemini 3 Flash. Level pemikiran MEDIUM menghasilkan hasil yang kuat di berbagai tugas sekaligus lebih cepat dan hemat biaya.

Tingkat pemikiran yang didukung adalah:

• MINIMAL: Cocok dengan setelan "tanpa pemikiran" untuk sebagian besar kueri. Model mungkin berpikir sangat minimal untuk 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 kata matematika, atau skenario rumit yang mengharuskan model mempertimbangkan 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 tidak ada, 3.5 Flash akan menggunakan setelan defaultnya (MEDIUM).

Retensi penalaran

Model 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 refaktor 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, bersikaplah konsisten dengan pernyataan sebelumnya: sertakan konteks lengkap (pemikiran, panggilan fungsi, respons) atau hilangkan sepenuhnya. Konteks parsial dapat menurunkan performa model.

Tidak digunakan lagi: Parameter sampling

Parameter pengambilan sampel berikut tidak lagi direkomendasikan untuk model Gemini 3:

• temperature
• top_p
• top_k

Model 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 Flash 3.5:

• Menggunakan pencocokan respons yang 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

Menyediakan 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 pada giliran berikutnya untuk menghasilkan respons yang lebih berbobot.

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, ada dua teknik yang dapat membantu meminimalkannya:

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

2. Menambahkan petunjuk sistem: Jika penggunaan berlebihan terus 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 baru untuk keluarga Gemini 3: Gemini 3.6 Flash secara ketat menerapkan aturan parameter dan konvensi API yang ditetapkan di seluruh keluarga Gemini 3:
   • Menghapus suhu, top-K, dan top-P: Hapus parameter kustom ini dari payload Anda. Meskipun tidak akan memunculkan error, model akan mengabaikannya sepenuhnya. Sebagai gantinya, gunakan parameter thinking_level atau output terstruktur json_schema untuk mengontrol determinisme output.
   • Menghapus penalti frekuensi dan kehadiran: Hapus konfigurasi kustom untuk penalti frekuensi atau kehadiran guna mencegah panggilan API Anda memunculkan error runtime.
   • Pastikan integrasi chat Anda tidak mencoba pengisian otomatis model: Tinjau array histori pesan Anda untuk memastikan bahwa payload API Anda tidak diakhiri 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), susun ulang urutannya untuk menghindari pemicuan error validasi 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 langsung di dalam teks respons fungsi yang dipisahkan oleh dua baris baru (\n\n).
3. Mempertimbangkan perubahan alur kerja:
   • Jika aplikasi Anda mengandalkan loop percakapan multi-turn, uji alur kerja Anda untuk memastikan ringkasan langkah baru model tidak memicu keluar sebelum waktunya.
   • Jika membuat agen frontend atau scripting dasar, pantau panggilan execute_code eksplorasi yang tidak perlu karena bias baru model terhadap inspeksi terprogram di awal.

Solusi untuk persyaratan teks sebelum alat

Jika perintah Anda mengharuskan model 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 sementara 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.
• Instruksikan model untuk menulis catatan sebagai header Markdown (misalnya, # UPDATE, ## PLAN) dan bukan teks terstruktur.
• Jangan mewajibkan model untuk menghasilkan teks sebelum panggilan alat.

Solusi yang direkomendasikan: Gabungkan catatan kerja dalam panggilan fungsi khusus

Daripada 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