Keuntungan:
- Boleh menerangkan struktur asas permintaan API LLM (titik akhir, model, mesej, max_tokens)
- Memahami perbezaan antara peranan sistem, pengguna dan pembantu serta sejarah perbualan tanpa kewarganegaraan
- Boleh membaca dan mentafsir medan (blok kandungan, stop_reason, penggunaan) bagi respons yang dikembalikan
Dalam modul sebelumnya, kami menggunakan kecerdasan buatan daripada tetingkap sembang. Tetapi jika anda ingin membenamkan AI ke dalam produk, automasi atau aliran kerja anda sendiri, antara muka sembang tidak akan memotongnya; Anda perlu menyambung ke model secara pemrograman, iaitu, dengan kod atau alat automasi. Nama jambatan ini ialah API (Antaramuka Pengaturcaraan Aplikasi, kontrak yang membenarkan dua perisian bercakap dengan peraturan tertentu). Apabila anda menyelesaikan unit ini, anda akan mengetahui apa yang membentuk permintaan API LLM (Model Bahasa Besar), peranan mesej yang dilakukan dan cara membaca respons. Ini adalah asas di mana seluruh modul akan dibina.
Bagaimanakah API Berfungsi?
Aliran asas dalam API ialah ini: anda menghantar permintaan dalam format tertentu; Pelayan mengembalikan respons dalam format tertentu. Dalam LLM, ini biasanya panggilan HTTP (HTTP: protokol standard untuk membawa respons-permintaan di web) ke satu alamat (titik akhir, alamat tetap pada pelayan yang mengendalikan permintaan anda). Contohnya, dalam API pemesejan, semua permintaan pergi ke satu alamat dan dibawa ke dalam badan sebagai JSON (JavaScript Object Notation — format teks yang terdiri daripada pasangan kunci/nilai yang boleh dibaca oleh manusia dan mesin).
Dalam permintaan, anda menentukan sekurang-kurangnya tiga perkara ini:
- Model: Model yang akan anda gunakan (cth. model yang pantas dan murah atau model yang berkuasa).
- max_tokens: Bilangan maksimum token (unit terkecil di mana teks diproses, yang akan diproses secara terperinci dalam unit seterusnya) yang boleh dihasilkan oleh model; iaitu had keluaran.
- mesej: Senarai mesej yang membentuk perbualan.
Langkah demi Langkah: Cara Menyediakan Permintaan
- Sediakan titik akhir dan kelayakan. Anda menambah kunci API anda (rentetan rahsia yang membuktikan identiti anda) pada permintaan dalam pengepala. Anda tidak sekali-kali membenamkan kunci dalam kod; Kami akan melindungi simpanan selamat di unit 9.
- Pilih model dan had keluaran. Model ringan + max_token kecil untuk tugasan mudah; Model berkuasa + had yang lebih besar untuk tugas yang kompleks.
- Sediakan senarai mesej. List the system instruction, user message, and past rounds (if any).
- Hantar permintaan dan huraikan jawapan. Baca kandungan teks, hentikan sebab dan penggunaan token daripada JSON yang dikembalikan.
Peranan Mesej: sistem, pengguna, pembantu
Perbualan terdiri daripada mesej yang disusun dalam urutan, dan setiap mesej mempunyai peranan. Peranan menentukan cara model memperlakukan teks tersebut.
Peranan
Siapa yang menulis
Tujuan
sistem
Pemaju/pengendali
Arahan kekal, personaliti dan peraturan yang terpakai sepanjang keseluruhan perbualan
pengguna
pengguna akhir
Soalan atau input semasa pengguna
pembantu
model
Respons yang dihasilkan oleh model (dan respons sebelumnya)
Peranan sistem tersedia sebagai medan sistem yang berasingan dalam badan permintaan dalam kebanyakan pembekal; pengguna dan pembantu disenaraikan secara berurutan dalam senarai mesej. 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 ialah pembantu sokongan korporat. Berikan jawapan ringkas, formal dan disahkan. Jangan reka maklumat yang anda tidak pasti.", "message": [ { "role": "user", "content": "Bagaimana cara saya memulakan proses pemulangan saya?" } ]}
Ucapan adalah Tanpa Kewarganegaraan
Berikut ialah salah tanggapan yang paling biasa: Panggilan API LLM adalah tanpa kewarganegaraan — pelayan tidak menyimpan memori antara dua permintaan. Model tidak mengingati permintaan anda sebelum ini. Jika anda menyediakan sembang berbilang pusingan, anda perlu menghantar semula pusingan lepas dengan setiap permintaan baharu. "Memori" model terdiri daripada senarai mesej yang telah anda hantar.
{ "model": "claude-opus-4-8", "max_tokens": 512, "message": [ { "role": "user", "content": "Helo, nama saya Deniz." }, { "role": "assistant", "content": "Hello Deniz, bagaimana saya boleh membantu anda?" }, { "role": "user", "content": "Saya baru sebut nama saya, awak ingat?" } ]}
Menjawab mesej ketiga dengan betul bergantung pada anda menghantar kedua-dua mesej sebelumnya. Jika anda tidak menghantarnya, model tidak akan tahu "Laut" dan akan menjawab dengan salah. Ini juga secara langsung mempengaruhi kos: semakin lama perbualan, semakin besar senarai, setiap permintaan menggunakan lebih banyak token.
Petua: Dalam perbualan yang panjang, meringkaskan dan memindahkan pusingan lama (ringkasan + beberapa pusingan terakhir) dan bukannya menghantar keseluruhan sejarah mengurangkan kos dan mengekalkan tetingkap konteks. Kami akan mendalami ini dalam unit 6 dan 11.
Baca Jawapan
Apabila model mengembalikan respons, anda menerima objek berstruktur, bukan teks biasa. Kawasan biasa:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Untuk memulakan pemulangan, pergi ke halaman 'Pesanan Saya' dalam akaun anda..." } ], "stop_reason" ": "end_toksin": "end_tokens" "output_tokens": 88 }}
- kandungan: Respons itu sendiri; Ia adalah senarai blok kandungan. Medan teks blok teks ialah jawapan sebenar.
- stop_reason: Mengapa model berhenti. hujung_pusing = hujung semula jadi; max_tokens = tersekat pada had keluaran (tindak balas mungkin tidak lengkap); enggan = enggan atas sebab keselamatan. Kod anda hendaklah sentiasa melihat stop_reason dahulu.
- penggunaan: Nombor token input dan output. Ia adalah asas penjejakan kos dan had.
Perhatian: Jika stop_reason ialah max_tokens, respons tidak selesai. Menganggap ini sebagai "tindak balas yang berjaya" dan menunjukkan separuh teks kepada pengguna adalah salah satu kesilapan yang paling biasa dalam pengeluaran. Sama ada tingkatkan max_token atau gunakan penstriman.
Gesaan lemah / Gesaan kuat
Tugas yang sama dengan dua gesaan sistem yang berbeza:
# LEMAHAnda seorang pembantu. Jawab soalan.
# KUATAnda ialah pembantu sokongan korporat. Peraturan:- Bergantung sepenuhnya pada maklumat dalam dokumen polisi yang disediakan; Jika tiada dalam dokumen, katakan "Saya tidak mempunyai maklumat ini, saya mengarahkannya ke unit yang berkaitan." - Jawapan hendaklah tidak melebihi 3 ayat, formal dan jelas. - Jangan minta data peribadi (nombor ID TC, nombor kad) dan jangan ulangi. - Jangan meneka apabila anda tidak pasti.
Versi berkuasa; Ia mentakrifkan skop, bentuk, margin keselamatan dan tingkah laku dalam ketidakpastian. Konsistensi output model datang terus daripada kejelasan ini.
Tiga Kes Mini
Kes 1 — Bot sokongan (perangkap tanpa kewarganegaraan). Pasukan e-dagang mengambil bot secara langsung; Apabila pengguna berkata "batalkan pesanan sebelumnya", bot "terlupa" nombor pesanan. Sebab: mereka menghantar setiap permintaan dengan hanya mesej terakhir. Penyelesaian: mereka menambah 6 pusingan terakhir pada senarai mesej. Keputusan: konteks dikekalkan, tetapi input setiap permintaan meningkat daripada 40 token kepada ~600 token — kami akan membincangkan pelajaran kos dalam unit 2.
Kes 2 — Ringkasan kontrak tidak lengkap. Pasukan undang-undang mempunyai kontrak 10 muka surat yang digariskan; max_tokens: 300 kekal rendah, ringkasan dipotong pertengahan ayat. stop_reason ialah max_token setiap kali tetapi tiada siapa yang melihat. meningkatkan max_token kepada 1500 dan menambah cek stop_reason; Kadar ringkasan terpotong menurun daripada 18% kepada 0%.
Kes 3 — Mencampurkan peranan. Pasukan pemasaran sedang menulis semua arahan ke dalam mesej pengguna, meninggalkan sistem kosong. Apabila input pengguna bercampur dengan arahan, model kadangkala akan mematuhi arahan pengguna untuk "melupakan peraturan sebelumnya." Mereka memindahkan peraturan tetap ke sistem; Dengan mengasingkan input pengguna daripada arahan, pelanggaran peraturan berkurangan dengan ketara.
Kesilapan biasa
- Terlupa untuk menghantar masa lalu: Model dianggap "tidak ingat"; sedangkan ia tidak bernegara. Anda membawa konteks.
- Tidak melihat `stop_reason`: Respons dihentikan dengan max_tokens dianggap lengkap.
- Membenamkan arahan dalam `pengguna`: Peraturan berterusan ke dalam sistem; input segera pergi kepada pengguna. Percampuran mewujudkan kelemahan keselamatan.
- Tersilap `kandungan` untuk rentetan biasa: Jawapannya ialah senarai blok; baca medan teks blok teks pertama, sahkan jenisnya sebelum mendapatkan kandungan[0] dengan indeks buta.
- Membenamkan kunci dalam kod: Gunakan pembolehubah persekitaran (unit 9).
Lebih Dalam: Blok Kandungan dan Jawapan Berbilang Bahagian
Memahami sebab medan kandungan dalam respons ialah senarai adalah asas kepada ciri lanjutan yang akan anda temui kemudian. Kadangkala model tidak mengembalikan satu blok teks, tetapi beberapa blok: blok pemikiran, diikuti dengan blok teks; atau blok teks diikuti dengan blok penggunaan alat. Itulah sebabnya mengira kandungan[0] secara membuta tuli sebagai "jawapan" adalah rapuh. Pendekatan yang betul ialah melalui senarai dan menyusunnya mengikut jenis: anda mengumpul kandungan teks blok yang medan jenisnya ialah teks, dan merawat jenis lain (pemikiran, alat) secara berasingan.
Apa yang dilakukan oleh perbezaan ini dalam amalan ialah anda boleh log alasan model (jika ada) tanpa mendedahkannya kepada pengguna, ubah hala panggilan alat untuk memisahkan logik dan hanya mencetak jawapan sebenar pada skrin. Semasa modul berjalan (terutamanya dalam unit 4 dan 11), anda akan melihat betapa bergunanya struktur blok ini untuk mengesahkan dan mengarahkan output.
Satu lagi perkara praktikal: anda boleh mengakses model yang sama daripada platform penyedia yang berbeza (API terus, melalui pembekal awan). Walaupun alamat titik akhir dan format pengesahan mungkin berubah, konsep asas seperti peranan mesej, ketiadaan kewarganegaraan dan struktur tindak balas tetap sama. Jadi asas dalam unit ini terpakai tidak kira apa platform yang anda gunakan.
Secara ringkasnya
Permintaan API LLM terdiri daripada model, had output dan senarai mesej; peranan (sistem, pengguna, pembantu) menentukan tingkah laku model. Panggilan adalah tanpa kewarganegaraan: anda membawa konteks dengan setiap permintaan. Tanggapan adalah objek berstruktur; Membaca dan mentafsir kandungan, hentikan_sebab dan medan penggunaan adalah asas ketahanan dalam pengeluaran.
Tugasan permohonan
Pilih tugas daripada profesion anda sendiri (cth. menyusun e-mel masuk, membuat ringkasan ringkas). Pada sehelai kertas: (1) tulis gesaan sistem dengan 4-5 peraturan, (2) sediakan sampel mesej pengguna dan sejarah 2 pusingan jika ada, (3) tentukan nilai munasabah untuk max_tokens dan tulis justifikasi, (4) senaraikan nilai stop_reason yang akan anda kendalikan dalam respons yang dikembalikan dan bagaimana.
senarai semak
- [ ] Saya boleh mengira tiga bahagian wajib permintaan (model, max_tokens, mesej).
- [ ] Saya boleh menerangkan perbezaan antara peranan sistem, pengguna dan pembantu.
- [ ] Saya tahu bahawa panggilan adalah tanpa kewarganegaraan dan saya perlu meneruskan masa lalu.
- Saya boleh membaca dan mengulas pada kandungan [ ], stop_reason dan medan penggunaan.
- [ ] Dengan max_tokens saya dapat melihat dan mengendalikan respons yang dipotong.