Mga nadagdag:
- Maaaring ilarawan ang pangunahing istraktura ng isang kahilingan sa LLM API (endpoint, modelo, mga mensahe, max_tokens)
- Nauunawaan ang pagkakaiba sa pagitan ng mga tungkulin ng system, user at assistant at walang estadong kasaysayan ng pag-uusap
- Maaaring basahin at bigyang-kahulugan ang mga field (mga bloke ng nilalaman, stop_reason, paggamit) ng ibinalik na tugon
Sa mga nakaraang module, gumamit kami ng artificial intelligence mula sa isang chat window. Ngunit kung gusto mong i-embed ang AI sa iyong sariling produkto, automation o workflow, hindi ito mapuputol ng interface ng chat; Kailangan mong kumonekta sa modelo sa programmatically, iyon ay, gamit ang code o isang automation tool. Ang pangalan ng tulay na ito ay API (Application Programming Interface, ang kontrata na nagpapahintulot sa dalawang software na makipag-usap sa ilang partikular na panuntunan). Kapag natapos mo ang unit na ito, malalaman mo kung ano ang bumubuo sa isang kahilingan sa LLM (Large Language Model) API, kung ano ang ginagawa ng mga tungkulin sa mensahe, at kung paano basahin ang tugon. Ito ang pundasyon kung saan itatayo ang natitirang bahagi ng modyul.
Paano Gumagana ang API?
Ang pangunahing daloy sa API ay ito: magpadala ka ng kahilingan sa isang partikular na format; Nagbabalik ang server ng tugon sa isang partikular na format. Sa mga LLM, ito ay karaniwang isang HTTP na tawag (HTTP: karaniwang protocol para sa pagdadala ng kahilingan-tugon sa web) sa isang address (endpoint, ang nakapirming address sa server na humahawak sa iyong kahilingan). Halimbawa, sa isang API sa pagmemensahe, ang lahat ng mga kahilingan ay mapupunta sa isang address at dinadala sa katawan bilang JSON (JavaScript Object Notation — isang format ng text na binubuo ng mga key/value pairs na maaaring basahin ng mga tao at machine).
Sa isang kahilingan, tinukoy mo ang hindi bababa sa tatlong bagay na ito:
- Modelo: Aling modelo ang iyong gagamitin (hal. isang mabilis at murang modelo o isang makapangyarihang modelo).
- max_tokens: Ang maximum na bilang ng mga token (ang pinakamaliit na yunit kung saan pinoproseso ang teksto, na ipoproseso nang detalyado sa susunod na yunit) na maaaring gawin ng modelo; ibig sabihin, limitasyon ng output.
- mga mensahe: Listahan ng mga mensahe na bumubuo sa pag-uusap.
Hakbang sa Hakbang: Paano Mag-set Up ng Kahilingan
- Ihanda ang endpoint at mga kredensyal. Idagdag mo ang iyong API key (ang sikretong string na nagpapatunay sa iyong pagkakakilanlan) sa kahilingan sa isang header. Hindi mo kailanman i-embed ang susi sa code; Sasakupin namin ang ligtas na imbakan sa unit 9.
- Piliin ang modelo at limitasyon ng output. Magaang modelo + maliit na max_tokens para sa isang simpleng gawain; Napakahusay na modelo + mas malaking limitasyon para sa isang kumplikadong gawain.
- I-set up ang listahan ng mensahe. List the system instruction, user message, and past rounds (if any).
- Ipadala ang kahilingan at i-parse ang tugon. Basahin ang nilalaman ng text, ihinto ang dahilan, at paggamit ng token mula sa ibinalik na JSON.
Mga Tungkulin sa Mensahe: system, user, assistant
Ang isang pag-uusap ay binubuo ng mga mensahe na nakaayos sa isang pagkakasunod-sunod, at ang bawat mensahe ay may tungkulin. Tinutukoy ng tungkulin kung paano tinatrato ng modelo ang tekstong iyon.
Tungkulin
Sino ang nagsusulat
Layunin
sistema
Developer/operator
Permanenteng mga tagubilin, personalidad at mga panuntunan na nalalapat sa buong pag-uusap
gumagamit
end user
Kasalukuyang tanong o input ng user
katulong
modelo
Tugon na ginawa ng modelo (at mga nakaraang tugon)
Ang papel ng system ay magagamit bilang isang hiwalay na field ng system sa katawan ng kahilingan sa karamihan ng mga provider; user at assistant ay nakalista nang sunud-sunod sa listahan ng mga mensahe. 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": "Isa kang corporate support assistant. Magbigay ng maikli, pormal at na-verify na tugon. Huwag gumawa ng impormasyon na hindi ka sigurado.", "messages": [ { "role": "user", "content": "Paano ko sisimulan ang proseso ng pagbabalik ko?" } ]}
Ang pagsasalita ay Stateless
Narito ang pinakakaraniwang maling kuru-kuro: Ang mga tawag sa LLM API ay walang estado — ang server ay walang memorya sa pagitan ng dalawang kahilingan. Hindi naaalala ng modelo ang iyong nakaraang kahilingan. Kung nagse-set up ka ng isang multi-round na chat, kakailanganin mong ipadala muli ang mga nakaraang round sa bawat bagong kahilingan. Ang "memorya" ng modelo ay binubuo ng isang listahan ng mga mensaheng ipinadala mo.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Hello, my name is Deniz." }, { "role": "assistant", "content": "Hello Deniz, paano kita matutulungan?" }, { "role": "user", "content": "Kakasabi ko lang ng pangalan ko, naalala mo ba?" } ]}
Ang wastong pagsagot sa ikatlong mensahe ay nakasalalay sa iyong pagpapadala ng parehong mga nakaraang mensahe. Kung hindi mo ito ipapadala, hindi malalaman ng modelo ang "Dagat" at sasagot ng mali. Direkta rin itong nakakaapekto sa gastos: kung mas mahaba ang pag-uusap, mas malaki ang listahan, ang bawat kahilingan ay kumonsumo ng higit pang mga token.
Tip: Sa mahabang pag-uusap, ang pagbubuod at paglipat ng mga lumang round (buod + huling ilang pag-ikot) sa halip na ipadala ang buong kasaysayan ay binabawasan ang gastos at pinapanatili ang window ng konteksto. Palalimin natin ito sa unit 6 at 11.
Basahin ang Sagot
Kapag nagbalik ang modelo ng tugon, makakatanggap ka ng structured object, hindi plain text. Mga karaniwang lugar:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Upang magsimula ng pagbabalik, pumunta sa pahina ng 'Aking Mga Order' sa iyong account..." } ], "stop_reason" ","us_toks_turn:": "end_toks" "output_tokens": 88 }}
- nilalaman: Ang tugon mismo; Ito ay isang listahan ng mga bloke ng nilalaman. Ang text field ng text block ay ang aktwal na sagot.
- stop_reason: Bakit huminto ang modelo. end_turn = natural na katapusan; max_tokens = natigil sa limitasyon ng output (maaaring hindi kumpleto ang tugon); pagtanggi = tinanggihan para sa mga kadahilanang pangseguridad. Ang iyong code ay dapat palaging tumingin sa stop_reason muna.
- paggamit: Mga numero ng token ng input at output. Ito ang batayan ng pagsubaybay sa gastos at limitasyon.
Pansin: Kung ang stop_reason ay max_tokens, ang tugon ay hindi nakumpleto. Ang pagtrato dito bilang isang "matagumpay na tugon" at ang pagpapakita ng kalahating teksto sa user ay isa sa mga pinakakaraniwang pagkakamali sa produksyon. Alinman sa pagtaas ng max_tokens o gumamit ng streaming.
Mahinang prompt / Malakas na prompt
Parehong gawain na may dalawang magkaibang prompt ng system:
# MAHINA Isa kang katulong. Sagutin ang mga tanong.
# STRONGIsa kang corporate support assistant. Mga Panuntunan:- Umasa lamang sa impormasyon sa ibinigay na dokumento ng patakaran; Kung wala ito sa dokumento, sabihin ang "Wala akong impormasyong ito, idinidirekta ko ito sa nauugnay na yunit." - Ang mga sagot ay hindi dapat lumampas sa 3 pangungusap, maging pormal at malinaw. - Huwag humingi ng personal na data (TC ID number, card number) at huwag ulitin. - Huwag hulaan kapag hindi ka sigurado.
Napakahusay na bersyon; Tinutukoy nito ang saklaw, anyo, margin ng kaligtasan, at pag-uugali sa kawalan ng katiyakan. Ang pagkakapare-pareho ng output ng modelo ay direktang nagmumula sa kalinawan na ito.
Tatlong Mini Case
Case 1 — Suporta sa bot (statelessness trap). Kinuha ng isang e-commerce team ang bot nang live; Kapag sinabi ng user na "kanselahin ang nakaraang order", "nakalimutan" ng bot ang numero ng order. Dahilan: ipinapadala nila ang bawat kahilingan kasama lamang ang huling mensahe. Solusyon: idinagdag nila ang huling 6 na round sa listahan ng mga mensahe. Resulta: napanatili ang konteksto, ngunit tumaas ang input sa bawat kahilingan mula 40 token hanggang ~600 token — sasakupin namin ang aralin sa gastos sa unit 2.
Kaso 2 — Hindi kumpletong buod ng kontrata. Ang isang legal na koponan ay nagkakaroon ng 10-pahinang mga kontrata na nakabalangkas; max_tokens: 300 ang nanatiling mababa, ang mga buod ay pinutol sa kalagitnaan ng pangungusap. Ang stop_reason ay max_tokens sa bawat oras ngunit walang nakatingin. tumaas ang max_tokens sa 1500 at nagdagdag ng stop_reason check; Bumaba ang naputol na rate ng buod mula 18% hanggang 0%.
Kaso 3 — Paghahalo ng mga tungkulin. Sinusulat ng isang marketing team ang lahat ng mga tagubilin sa mensahe ng user, na iniwang blangko ang system. Kapag ang input ng user ay may halong pagtuturo, kung minsan ay susunod ang modelo sa utos ng user na "kalimutan ang mga nakaraang panuntunan." Inilipat nila ang mga permanenteng panuntunan sa sistema; Sa pamamagitan ng paghihiwalay ng input ng user mula sa pagtuturo, makabuluhang nabawasan ang mga paglabag sa panuntunan.
Mga karaniwang pagkakamali
- Nakakalimutang ipadala ang nakaraan: Ang modelo ay naisip na "hindi naaalala"; samantalang ito ay walang estado. Dala mo ang konteksto.
- Hindi tumitingin sa `stop_reason`: Ang tugon na huminto na may max_tokens ay itinuturing na kumpleto.
- Pag-embed ng pagtuturo sa `user`: Mga paulit-ulit na panuntunan sa system; mapupunta ang instant input sa user. Ang paghahalo ay lumilikha ng mga kahinaan sa seguridad.
- Napagkakamalang `content` ang isang plain string: Ang sagot ay isang listahan ng mga block; basahin ang field ng text ng unang text block, i-verify ang uri nito bago kumuha ng content[0] na may blind index.
- Pag-embed ng key sa code: Gumamit ng environment variable (unit 9).
Mas Malalim: Mga Block ng Nilalaman at Mga Sagot na Maramihang Bahagi
Ang pag-unawa kung bakit ang field ng nilalaman sa tugon ay isang listahan ay mahalaga sa mga advanced na feature na makikita mo sa ibang pagkakataon. Minsan ang modelo ay hindi nagbabalik ng isang bloke ng teksto, ngunit ilang mga bloke: isang bloke ng pag-iisip, na sinusundan ng isang bloke ng teksto; o isang bloke ng teksto na sinusundan ng isang bloke ng paggamit ng tool. Iyon ang dahilan kung bakit ang walang taros na pagbibilang ng content[0] bilang isang "sagot" ay marupok. Ang tamang diskarte ay dumaan sa listahan at pag-uri-uriin ito ayon sa uri: kinokolekta mo ang nilalaman ng teksto ng mga bloke na ang field ng uri ay teksto, at tinatrato ang iba pang mga uri (pag-iisip, tool) nang hiwalay.
Ang ginagawa ng pagkakaibang ito sa pagsasanay ay maaari mong i-log ang pangangatwiran ng modelo (kung mayroon man) nang hindi ibinubunyag ito sa user, i-redirect ang mga tawag sa tool sa hiwalay na lohika, at i-print lamang ang aktwal na sagot sa screen. Habang umuusad ang module (lalo na sa mga unit 4 at 11) makikita mo kung gaano kapaki-pakinabang ang block structure na ito para sa pagpapatunay at pagdidirekta ng output.
Isa pang praktikal na punto: maa-access mo ang parehong modelo mula sa iba't ibang platform ng provider (direktang API, sa pamamagitan ng cloud provider). Bagama't maaaring magbago ang endpoint address at format ng pagpapatunay, ang mga pangunahing konsepto tulad ng mga tungkulin sa mensahe, statelessness, at istraktura ng pagtugon ay nananatiling pareho. Kaya ang mga pangunahing kaalaman sa unit na ito ay nalalapat kahit anong platform ang iyong gamitin.
Sa buod
Ang isang kahilingan sa LLM API ay binubuo ng modelo, limitasyon ng output, at listahan ng mensahe; ang mga tungkulin (system, user, assistant) ay tumutukoy sa pag-uugali ng modelo. Ang mga tawag ay walang estado: dala mo ang konteksto sa bawat kahilingan. Ang tugon ay isang nakabalangkas na bagay; Ang pagbabasa at pagbibigay-kahulugan sa nilalaman, stop_reason at mga larangan ng paggamit ay ang batayan ng tibay sa produksyon.
Gawain ng aplikasyon
Pumili ng isang gawain mula sa iyong sariling propesyon (hal. pag-uuri ng papasok na e-mail, paggawa ng maikling buod). Sa isang piraso ng papel: (1) isulat ang prompt ng system na may 4-5 na panuntunan, (2) i-set up ang isang sample na mensahe ng user at isang 2-round na kasaysayan kung mayroon, (3) tukuyin ang isang makatwirang halaga para sa max_tokens at isulat ang katwiran, (4) listahan kung aling mga halaga ng stop_reason ang iyong hahawakan sa ibinalik na tugon at kung paano.
checklist
- [ ] Mabibilang ko ang tatlong mandatoryong bahagi ng isang kahilingan (modelo, max_tokens, mga mensahe).
- [ ] Maaari kong ipaliwanag ang pagkakaiba sa pagitan ng mga tungkulin ng system, user at assistant.
- [ ] Alam kong walang estado ang mga tawag at kailangan kong dalhin ang nakaraan.
- Maaari akong magbasa at magkomento sa [ ] nilalaman, stop_reason at mga field ng paggamit.
- [ ] Sa max_tokens maaari kong mapansin at mahawakan ang pinutol na tugon.