Keuntungan:
- Dapat menggambarkan struktur dasar permintaan API LLM (titik akhir, model, pesan, max_tokens)
- Memahami perbedaan antara peran sistem, pengguna dan asisten serta riwayat percakapan tanpa kewarganegaraan
- Dapat membaca dan menafsirkan bidang (blok konten, stop_reason, penggunaan) dari respons yang dikembalikan
Pada modul sebelumnya, kami menggunakan kecerdasan buatan dari jendela obrolan. Namun jika Anda ingin menanamkan AI ke dalam produk, otomatisasi, atau alur kerja Anda sendiri, antarmuka obrolan tidak akan cukup; Anda perlu terhubung ke model secara terprogram, yaitu dengan kode atau alat otomatisasi. Nama jembatan ini adalah API (Application Programming Interface, kontrak yang memungkinkan dua perangkat lunak berbicara dengan aturan tertentu). Saat Anda menyelesaikan unit ini, Anda akan mengetahui apa yang dimaksud dengan permintaan API LLM (Model Bahasa Besar), apa yang dilakukan peran pesan, dan cara membaca responsnya. Ini adalah fondasi di mana modul selanjutnya akan dibangun.
Bagaimana Cara Kerja API?
Alur dasar dalam API adalah ini: Anda mengirim permintaan dalam format tertentu; Server mengembalikan respons dalam format tertentu. Di LLM, ini biasanya berupa panggilan HTTP (HTTP: protokol standar untuk membawa permintaan-respons di web) ke satu alamat (titik akhir, alamat tetap di server yang menangani permintaan Anda). Misalnya, dalam API perpesanan, semua permintaan dikirim ke satu alamat dan dibawa ke dalam isi sebagai JSON (JavaScript Object Notation — format teks yang terdiri dari pasangan kunci/nilai yang dapat dibaca oleh manusia dan mesin).
Dalam permintaan, Anda menentukan setidaknya tiga hal berikut:
- Model: Model mana yang akan Anda gunakan (misalnya model yang cepat dan murah atau model yang canggih).
- max_tokens: Jumlah token maksimum (unit terkecil tempat teks diproses, yang akan diproses secara detail di unit berikutnya) yang dapat dihasilkan model; yaitu batas keluaran.
- pesan: Daftar pesan yang membentuk percakapan.
Langkah demi Langkah: Cara Mengatur Permintaan
- Siapkan titik akhir dan kredensial. Anda menambahkan kunci API Anda (string rahasia yang membuktikan identitas Anda) ke permintaan di header. Anda tidak pernah memasukkan kunci ke dalam kode; Kami akan membahas penyimpanan yang aman di unit 9.
- Pilih model dan batas keluaran. Model ringan + max_tokens kecil untuk tugas sederhana; Model yang kuat + batasan yang lebih besar untuk tugas yang kompleks.
- Siapkan daftar pesan. List the system instruction, user message, and past rounds (if any).
- Kirim permintaan dan parsing responsnya. Baca konten teks, alasan penghentian, dan penggunaan token dari JSON yang dikembalikan.
Peran Pesan: sistem, pengguna, asisten
Percakapan terdiri dari pesan-pesan yang disusun secara berurutan, dan setiap pesan mempunyai peran. Peran menentukan bagaimana model memperlakukan teks tersebut.
Peran
Siapa yang menulis
Tujuan
sistem
Pengembang/operator
Instruksi permanen, kepribadian, dan aturan yang berlaku sepanjang percakapan
pengguna
pengguna akhir
Pertanyaan atau masukan pengguna saat ini
asisten
model
Respon yang dihasilkan oleh model (dan respons sebelumnya)
Peran sistem tersedia sebagai bidang sistem terpisah di badan permintaan di sebagian besar penyedia; pengguna dan asisten dicantumkan secara berurutan dalam daftar pesan. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Anda adalah asisten dukungan perusahaan. Berikan tanggapan yang singkat, formal, dan terverifikasi. Jangan mengarang informasi yang Anda tidak yakin.", "messages": [ { "role": "user", "content": "Bagaimana cara memulai proses pengembalian saya?" } ]}
Pidato tidak memiliki kewarganegaraan
Inilah kesalahpahaman yang paling umum: Panggilan API LLM tidak memiliki kewarganegaraan — server tidak menyimpan memori di antara dua permintaan. Model tidak mengingat permintaan Anda sebelumnya. Jika Anda menyiapkan obrolan multi-putaran, Anda harus mengirim ulang putaran sebelumnya dengan setiap permintaan baru. "Memori" model terdiri dari daftar pesan yang telah Anda kirim.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Halo, nama saya Deniz." }, { "role": "asisten", "konten": "Halo Deniz, ada yang bisa saya bantu?" }, { "role": "user", "content": "Saya baru saja menyebutkan nama saya, apakah Anda ingat?" } ]}
Menjawab pesan ketiga dengan benar bergantung pada Anda mengirimkan kedua pesan sebelumnya. Jika Anda tidak mengirimkannya, model tidak akan mengetahui "Laut" dan akan menjawab salah. Hal ini juga secara langsung mempengaruhi biaya: semakin lama percakapan, semakin besar daftarnya, setiap permintaan menghabiskan lebih banyak token.
Tip: Dalam percakapan yang panjang, meringkas dan memindahkan putaran lama (ringkasan + beberapa putaran terakhir) daripada mengirimkan seluruh riwayat akan mengurangi biaya dan mempertahankan jendela konteks. Kita akan memperdalamnya pada unit 6 dan 11.
Baca Jawabannya
Saat model mengembalikan respons, Anda menerima objek terstruktur, bukan teks biasa. Area umum:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "asisten", "konten": [ { "type": "text", "text": "Untuk memulai pengembalian, buka halaman 'Pesanan Saya' di akun Anda..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- isi: Respons itu sendiri; Ini adalah daftar blok konten. Bidang teks dari blok teks adalah jawaban sebenarnya.
- stop_reason: Mengapa model berhenti. end_turn = akhir alami; max_tokens = terhenti pada batas keluaran (respon mungkin tidak lengkap); penolakan = ditolak karena alasan keamanan. Kode Anda harus selalu melihat stop_reason terlebih dahulu.
- penggunaan: Nomor token masukan dan keluaran. Ini adalah dasar pelacakan biaya dan batas.
Perhatian: Jika stop_reason adalah max_tokens, responsnya tidak selesai. Memperlakukan ini sebagai "respons berhasil" dan menampilkan separuh teks kepada pengguna adalah salah satu kesalahan paling umum dalam produksi. Tingkatkan max_tokens atau gunakan streaming.
Perintah lemah / Perintah kuat
Tugas yang sama dengan dua perintah sistem yang berbeda:
# LEMAHKamu adalah seorang asisten. Jawab pertanyaannya.
# STRONGAnda adalah asisten dukungan perusahaan. Aturan:- Hanya mengandalkan informasi dalam dokumen kebijakan yang disediakan; Jika tidak ada dalam dokumen, katakan “Saya tidak punya informasi ini, saya arahkan ke unit terkait”. - Jawaban tidak boleh lebih dari 3 kalimat, formal dan jelas. - Jangan meminta data pribadi (nomor ID TC, nomor kartu) dan jangan mengulanginya. - Jangan menebak ketika Anda tidak yakin.
Versi yang kuat; Ini mendefinisikan ruang lingkup, bentuk, margin keamanan, dan perilaku dalam ketidakpastian. Konsistensi keluaran model berasal langsung dari kejelasan ini.
Tiga Kasus Mini
Kasus 1 — Bot pendukung (perangkap tanpa kewarganegaraan). Tim e-niaga menghidupkan bot tersebut; Ketika pengguna mengatakan "batalkan pesanan sebelumnya", bot "lupa" nomor pesanannya. Alasan: mereka mengirimkan setiap permintaan hanya dengan pesan terakhir. Solusi: mereka menambahkan 6 putaran terakhir ke daftar pesan. Hasilnya: konteks dipertahankan, namun masukan per permintaan meningkat dari 40 token menjadi ~600 token — kita akan membahas pelajaran biaya di unit 2.
Kasus 2 — Ringkasan kontrak tidak lengkap. Sebuah tim hukum sedang menguraikan kontrak sepanjang 10 halaman; max_tokens: 300 tetap rendah, ringkasan terpotong di tengah kalimat. stop_reason selalu max_tokens tetapi tidak ada yang melihat. meningkatkan max_tokens menjadi 1500 dan menambahkan pemeriksaan stop_reason; Tingkat ringkasan terpotong menurun dari 18% menjadi 0%.
Kasus 3 — Mencampur peran. Tim pemasaran menulis semua instruksi ke dalam pesan pengguna, membiarkan sistem kosong. Ketika input pengguna dicampur dengan instruksi, model terkadang mematuhi perintah pengguna untuk "melupakan aturan sebelumnya". Mereka memindahkan aturan permanen ke dalam sistem; Dengan memisahkan masukan pengguna dari instruksi, pelanggaran aturan berkurang secara signifikan.
Kesalahan umum
- Lupa mengirimkan masa lalu: Model dianggap “tidak ingat”; padahal itu tidak memiliki kewarganegaraan. Anda membawa konteksnya.
- Tidak melihat `stop_reason`: Respons dihentikan dengan max_tokens dianggap selesai.
- Menanamkan instruksi di `pengguna`: Aturan persisten ke dalam sistem; input instan diberikan kepada pengguna. Pencampuran menciptakan kerentanan keamanan.
- Salah mengira `konten` sebagai string biasa: Jawabannya adalah daftar blok; membaca bidang teks dari blok teks pertama, verifikasi jenisnya sebelum mendapatkan konten[0] dengan indeks buta.
- Menyematkan kunci dalam kode: Gunakan variabel lingkungan (unit 9).
Lebih Dalam: Blok Konten dan Jawaban Multi-Bagian
Memahami mengapa bidang konten dalam respons berupa daftar merupakan hal mendasar untuk fitur lanjutan yang akan Anda temui nanti. Terkadang model tidak mengembalikan satu blok teks pun, tetapi beberapa blok: satu blok pemikiran, diikuti oleh satu blok teks; atau blok teks diikuti dengan blok penggunaan alat. Itu sebabnya menghitung secara membabi buta content[0] sebagai "jawaban" adalah hal yang rapuh. Pendekatan yang benar adalah dengan menelusuri daftar dan mengurutkannya berdasarkan jenis: Anda mengumpulkan konten teks dari blok yang bidang tipenya adalah teks, dan memperlakukan tipe lain (pemikiran, alat) secara terpisah.
Perbedaan ini dalam praktiknya adalah Anda dapat mencatat alasan model (jika ada) tanpa mengungkapkannya kepada pengguna, mengalihkan panggilan alat ke logika terpisah, dan hanya mencetak jawaban sebenarnya di layar. Seiring kemajuan modul (terutama di unit 4 dan 11) Anda akan melihat betapa bergunanya struktur blok ini untuk memvalidasi dan mengarahkan keluaran.
Poin praktis lainnya: Anda dapat mengakses model yang sama dari platform penyedia yang berbeda (API langsung, melalui penyedia cloud). Meskipun alamat titik akhir dan format autentikasi dapat berubah, konsep dasar seperti peran pesan, keadaan tanpa kewarganegaraan, dan struktur respons tetap sama. Jadi dasar-dasar dalam unit ini berlaku apa pun platform yang Anda gunakan.
Singkatnya
Permintaan API LLM terdiri dari model, batas keluaran, dan daftar pesan; peran (sistem, pengguna, asisten) menentukan perilaku model. Panggilan tidak memiliki kewarganegaraan: Anda membawa konteks pada setiap permintaan. Responsnya adalah objek terstruktur; Membaca dan menafsirkan bidang konten, stop_reason, dan penggunaan adalah dasar ketahanan dalam produksi.
Tugas aplikasi
Pilih tugas dari profesi Anda (misalnya menyortir email masuk, membuat ringkasan singkat). Di selembar kertas: (1) tulis perintah sistem dengan 4-5 aturan, (2) siapkan contoh pesan pengguna dan riwayat 2 putaran jika ada, (3) tentukan nilai yang masuk akal untuk max_tokens dan tulis pembenarannya, (4) daftarkan nilai stop_reason mana yang akan Anda tangani dalam respons yang dikembalikan dan bagaimana caranya.
daftar periksa
- [] Saya dapat menghitung tiga bagian wajib dari sebuah permintaan (model, max_tokens, pesan).
- [ ] Saya dapat menjelaskan perbedaan antara peran sistem, pengguna, dan asisten.
- [ ] Saya tahu bahwa panggilan telepon tidak memiliki kewarganegaraan dan saya harus mengingat masa lalu.
- Saya dapat membaca dan mengomentari konten [], stop_reason, dan bidang penggunaan.
- [ ] Dengan max_tokens saya dapat memperhatikan dan menangani respons terpotong.