Gevinster:
- Kan beskrive den grunnleggende strukturen til en LLM API-forespørsel (endepunkt, modell, meldinger, max_tokens)
- Forstår forskjellen mellom system-, bruker- og assistentroller og statsløs samtalehistorikk
- Kan lese og tolke felt (innholdsblokker, stop_reason, usage) av det returnerte svaret
I tidligere moduler brukte vi kunstig intelligens fra et chattevindu. Men hvis du ønsker å bygge inn AI i ditt eget produkt, automatisering eller arbeidsflyt, vil ikke et chat-grensesnitt kutte det; Du må koble til modellen programmatisk, det vil si med kode eller et automatiseringsverktøy. Navnet på denne broen er API (Application Programming Interface, kontrakten som lar to programvare snakke med visse regler). Når du er ferdig med denne enheten, vil du vite hva som utgjør en LLM (Large Language Model) API-forespørsel, hva meldingsroller gjør og hvordan du leser svaret. Dette er grunnlaget som resten av modulen skal bygges på.
Hvordan fungerer API?
Den grunnleggende flyten i APIen er denne: du sender en forespørsel i et bestemt format; Serveren returnerer et svar i et spesifikt format. I LLM-er er dette vanligvis et HTTP-anrop (HTTP: standardprotokoll for overføring av forespørsel-svar på nettet) til en enkelt adresse (endepunkt, den faste adressen på serveren som håndterer forespørselen din). For eksempel, i et meldings-API, går alle forespørsler til én enkelt adresse og bæres i kroppen som JSON (JavaScript Object Notation — et tekstformat som består av nøkkel/verdi-par som kan leses av både mennesker og maskiner).
I en forespørsel spesifiserer du minst disse tre tingene:
- Modell: Hvilken modell du skal bruke (f.eks. en rask og billig modell eller en kraftig modell).
- max_tokens: Maksimalt antall tokens (den minste enheten som teksten behandles i, som vil bli behandlet i detalj i neste enhet) som modellen kan produsere; dvs. utgangsgrense.
- meldinger: Liste over meldinger som utgjør samtalen.
Trinn for trinn: Slik setter du opp en forespørsel
- Forbered endepunktet og legitimasjonen. Du legger til API-nøkkelen din (den hemmelige strengen som bekrefter identiteten din) til forespørselen i en overskrift. Du legger aldri inn nøkkelen i koden; Vi dekker sikker oppbevaring i enhet 9.
- Velg modell og utgangsgrense. Lettvektsmodell + små max_tokens for en enkel oppgave; Kraftig modell + større grense for en kompleks oppgave.
- Sett opp meldingslisten. List the system instruction, user message, and past rounds (if any).
- Send forespørselen og analyser svaret. Les tekstinnholdet, stoppårsak og tokenbruk fra den returnerte JSON.
Meldingsroller: system, bruker, assistent
En samtale består av meldinger ordnet i en sekvens, og hver melding har en rolle. Rollen bestemmer hvordan modellen behandler den teksten.
Rolle
Hvem skriver
Formål
systemet
Utbygger/operatør
Permanente instrukser, personlighet og regler som gjelder gjennom hele samtalen
bruker
sluttbruker
Brukerens gjeldende spørsmål eller input
assistent
modell
Svar produsert av modellen (og tidligere svar)
Systemrollen er tilgjengelig som et eget systemfelt i forespørselskroppen hos de fleste tilbydere; bruker og assistent er oppført sekvensielt i meldingslisten. 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": "Du er en bedriftsstøtteassistent. Gi et kort, formelt og bekreftet svar. Ikke lag opp informasjon du ikke er sikker på.", "messages": [ { "role": "bruker", "content": "Hvordan starter jeg returprosessen?" } ]}
Tale er statsløs
Her er den vanligste misforståelsen: LLM API-kall er statsløse - serveren beholder ikke noe minne mellom to forespørsler. Modellen husker ikke din forrige forespørsel. Hvis du setter opp en chat med flere runder, må du sende tidligere runder på nytt med hver nye forespørsel. Modellens «minne» består av en liste over meldinger du har sendt.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Hei, jeg heter Deniz." }, { "role": "assistent", "content": "Hei Deniz, hvordan kan jeg hjelpe deg?" }, { "role": "user", "content": "Jeg sa nettopp navnet mitt, husker du?" } ]}
Svar på den tredje meldingen riktig avhenger av at du sender begge tidligere meldinger. Hvis du ikke sender det, vil ikke modellen vite "Sea" og vil svare feil. Dette påvirker også kostnadene direkte: jo lengre samtalen er, jo større blir listen, og hver forespørsel bruker flere tokens.
Tips: I lange samtaler, oppsummering og flytting av gamle runder (oppsummering + siste runder) i stedet for å sende hele historien reduserer kostnadene og bevarer kontekstvinduet. Vi vil utdype dette i enhet 6 og 11.
Les svaret
Når modellen returnerer et svar, mottar du et strukturert objekt, ikke ren tekst. Typiske områder:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "For å starte en retur, gå til 'Mine bestillinger'-siden i kontoen din..." } ], "stop_reason", "stop_reason", "input_reason": "end_tokens:" 47, "output_tokens": 88 }}
- innhold: Selve responsen; Det er en liste over innholdsblokker. Tekstfeltet til tekstblokken er selve svaret.
- stop_reason: Hvorfor modellen stoppet. end_turn = naturlig slutt; max_tokens = sitter fast ved utgangsgrense (svaret kan være ufullstendig); refusal = nektet av sikkerhetsmessige årsaker. Koden din bør alltid se på stop_reason først.
- bruk: Legg inn og ut tokennumre. Det er grunnlaget for kostnads- og grensesporing.
OBS: Hvis stop_reason er max_tokens, er ikke svaret fullført. Å behandle dette som en "vellykket respons" og vise halv tekst til brukeren er en av de vanligste feilene i produksjonen. Øk enten max_tokens eller bruk strømming.
Svak forespørsel / Sterk forespørsel
Samme oppgave med to forskjellige systemmeldinger:
# SVAK Du er en assistent. Svar på spørsmålene.
# STERK Du er en bedriftsstøtteassistent. Regler:- Stol utelukkende på informasjonen i policydokumentet som er gitt; Hvis det ikke er i dokumentet, si "Jeg har ikke denne informasjonen, jeg sender den til den aktuelle enheten." – Svar bør ikke overstige 3 setninger, være formelle og tydelige. - Ikke be om personlige data (TC ID-nummer, kortnummer) og ikke gjenta. – Ikke gjett når du ikke er sikker.
Kraftig versjon; Den definerer omfang, form, sikkerhetsmargin og atferd i usikkerhet. Konsistensen til modellutgangen kommer direkte fra denne klarheten.
Tre minivesker
Tilfelle 1 — Støtterobot (statsløshetsfelle). Et e-handelsteam tok boten live; Når brukeren sa "kanseller den forrige ordren", "glemte" boten ordrenummeret. Årsak: de sendte hver forespørsel med bare den siste meldingen. Løsning: de la de siste 6 rundene til meldingslisten. Resultat: kontekst bevart, men input per forespørsel økte fra 40 tokens til ~600 tokens – vi dekker kostnadsleksjonen i enhet 2.
Sak 2 — Ufullstendig kontraktssammendrag. Et juridisk team hadde 10-siders kontrakter skissert; max_tokens: 300 forble lavt, sammendrag ble avbrutt midt i setningen. stop_reason var max_tokens hver gang, men ingen så. økte max_tokens til 1500 og lagt til stop_reason check; Den avkortede oppsummeringsraten gikk ned fra 18 % til 0 %.
Case 3 – Blande roller. Et markedsføringsteam skrev alle instruksjonene inn i brukermeldingen, og lot systemet stå tomt. Når brukerinndata blandes med instruksjoner, vil modellen noen ganger følge brukerens kommando om å "glemme de tidligere reglene." De flyttet permanente regler til systemet; Ved å skille brukerinndata fra instruksjoner, ble regelbrudd redusert betydelig.
Vanlige feil
- Glemte å sende fortiden: Modellen antas å "ikke huske"; mens den er statsløs. Du bærer konteksten.
- Ser ikke på `stop_reason`: Svaret stoppet med max_tokens anses som komplett.
- Innbygging av instruksjonen i `bruker`: Vedvarende regler i systemet; øyeblikkelig input går til brukeren. Blanding skaper sikkerhetssårbarheter.
- Forveksler "innhold" med en vanlig streng: Svaret er en liste over blokker; les tekstfeltet til den første tekstblokken, bekreft typen før du får innhold[0] med en blind indeks.
- Innbygging av nøkkelen i koden: Bruk en miljøvariabel (enhet 9).
Dypere: Innholdsblokker og flerdelte svar
Å forstå hvorfor innholdsfeltet i svaret er en liste er grunnleggende for de avanserte funksjonene du vil møte senere. Noen ganger returnerer modellen ikke en enkelt tekstblokk, men flere blokker: en tankeblokk, etterfulgt av en tekstblokk; eller en tekstblokk etterfulgt av en blokk med verktøybruk. Det er derfor det er skjørt å blindt telle innhold[0] som et "svar". Den riktige tilnærmingen er å gå gjennom listen og sortere den etter type: du samler tekstinnholdet i blokker hvis typefelt er tekst, og behandler andre typer (tenkning, verktøy) separat.
Det denne forskjellen gjør i praksis er at du kan logge modellens resonnement (hvis noen) uten å avsløre det for brukeren, omdirigere verktøykall til separat logikk og kun skrive ut selve svaret på skjermen. Etter hvert som modulen skrider frem (spesielt i enhetene 4 og 11) vil du se hvor nyttig denne blokkstrukturen er for å validere og dirigere utdata.
Et annet praktisk poeng: du kan få tilgang til samme modell fra forskjellige leverandørplattformer (direkte API, via en skyleverandør). Selv om endepunktadressen og autentiseringsformatet kan endres, forblir grunnleggende konsepter som meldingsroller, statsløshet og responsstruktur de samme. Så det grunnleggende i denne enheten gjelder uansett hvilken plattform du bruker.
Oppsummert
En LLM API-forespørsel består av modellen, utgangsgrensen og meldingslisten; roller (system, bruker, assistent) bestemmer oppførselen til modellen. Samtaler er statsløse: du bærer konteksten med hver forespørsel. Responsen er et strukturert objekt; Lesing og tolkning av innholds-, stop_reason og bruksfeltene er grunnlaget for holdbarhet i produksjonen.
Søknadsoppgave
Velg en oppgave fra ditt eget yrke (f.eks. sortere innkommende e-post, lage korte oppsummeringer). På et stykke papir: (1) skriv systemprompten med 4-5 regler, (2) sett opp en eksempelbrukermelding og en 2-runders historikk hvis noen, (3) bestem en rimelig verdi for max_tokens og skriv begrunnelsen, (4) skriv hvilke stop_reason-verdier du vil håndtere i det returnerte svaret og hvordan.
sjekkliste
- [ ] Jeg kan telle de tre obligatoriske delene av en forespørsel (modell, max_tokens, meldinger).
- [ ] Jeg kan forklare forskjellen mellom system-, bruker- og assistentroller.
- [ ] Jeg vet at samtaler er statsløse og at jeg må bære fortiden.
- Jeg kan lese og kommentere [ ] innhold, stop_reason og bruksfelt.
- [ ] Med max_tokens kan jeg legge merke til og håndtere det avkortede svaret.