Gevinster:
- Kan beskrive den grundlæggende struktur af en LLM API-anmodning (slutpunkt, model, beskeder, max_tokens)
- Forstår forskellen mellem system-, bruger- og assistentroller og statsløs samtalehistorik
- Kan læse og fortolke felter (indholdsblokke, stop_reason, brug) af det returnerede svar
I tidligere moduler brugte vi kunstig intelligens fra et chatvindue. Men hvis du vil indlejre AI i dit eget produkt, automatisering eller arbejdsgang, vil en chatgrænseflade ikke skære det; Du skal oprette forbindelse til modellen programmatisk, det vil sige med kode eller et automatiseringsværktøj. Navnet på denne bro er API (Application Programming Interface, kontrakten, der tillader to software at tale med bestemte regler). Når du er færdig med denne enhed, vil du vide, hvad der udgør en LLM (Large Language Model) API-anmodning, hvad meddelelsesroller gør, og hvordan du læser svaret. Dette er fundamentet, som resten af modulet skal bygges på.
Hvordan virker API'en?
Det grundlæggende flow i API'en er dette: du sender en anmodning i et bestemt format; Serveren returnerer et svar i et bestemt format. I LLM'er er dette normalt et HTTP-kald (HTTP: standardprotokol til at overføre anmodningssvar på nettet) til en enkelt adresse (slutpunkt, den faste adresse på serveren, der håndterer din anmodning). For eksempel i en messaging API går alle anmodninger til en enkelt adresse og føres i kroppen som JSON (JavaScript Object Notation - et tekstformat bestående af nøgle/værdi-par, der kan læses af både mennesker og maskiner).
I en anmodning angiver du mindst disse tre ting:
- Model: Hvilken model du vil bruge (f.eks. en hurtig og billig model eller en kraftig model).
- max_tokens: Det maksimale antal tokens (den mindste enhed, som teksten behandles i, som vil blive behandlet i detaljer i næste enhed), som modellen kan producere; dvs. outputgrænse.
- beskeder: Liste over beskeder, der udgør samtalen.
Trin for trin: Sådan opretter du en anmodning
- Forbered slutpunktet og legitimationsoplysninger. Du tilføjer din API-nøgle (den hemmelige streng, der beviser din identitet) til anmodningen i en header. Du indlejrer aldrig nøglen i koden; Vi dækker sikker opbevaring i enhed 9.
- Vælg model og outputgrænse. Letvægtsmodel + små max_tokens til en simpel opgave; Kraftig model + større grænse for en kompleks opgave.
- Opsæt beskedlisten. List the system instruction, user message, and past rounds (if any).
- Send anmodningen og parse svaret. Læs tekstindholdet, stopårsagen og tokenbrug fra den returnerede JSON.
Meddelelsesroller: system, bruger, assistent
En samtale består af beskeder arrangeret i en rækkefølge, og hver besked har en rolle. Rollen bestemmer, hvordan modellen behandler den tekst.
Rolle
Hvem skriver
Formål
system
Udvikler/operatør
Faste instruktioner, personlighed og regler, der gælder gennem hele samtalen
bruger
slutbruger
Brugerens aktuelle spørgsmål eller input
assistent
model
Svar produceret af modellen (og tidligere svar)
Systemrollen er tilgængelig som et separat systemfelt i anmodningsorganet hos de fleste udbydere; bruger og assistent vises sekventielt i meddelelseslisten. 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 virksomhedssupportassistent. Giv et kort, formelt og verificeret svar. Opstil ikke oplysninger, du ikke er sikker på.", "messages": [ { "role": "bruger", "content": "Hvordan starter jeg min returproces?" } ]}
Tale er statsløs
Her er den mest almindelige misforståelse: LLM API-kald er statsløse - serveren beholder ingen hukommelse mellem to anmodninger. Modellen husker ikke din tidligere anmodning. Hvis du opretter en chat med flere runder, skal du sende tidligere runder igen med hver ny anmodning. Modellens "hukommelse" består af en liste over beskeder, du har sendt.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "bruger", "content": "Hej, mit navn er Deniz." }, { "role": "assistant", "content": "Hej Deniz, hvordan kan jeg hjælpe dig?" }, { "role": "user", "content": "Jeg sagde lige mit navn, kan du huske?" } ]}
At besvare den tredje besked korrekt afhænger af, at du sender begge tidligere beskeder. Hvis du ikke sender det, kender modellen ikke "Hav" og svarer forkert. Dette påvirker også direkte omkostningerne: Jo længere samtalen er, jo større er listen, og hver anmodning bruger flere tokens.
Tip: I lange samtaler reducerer opsummering og flytning af gamle runder (resumé + sidste par runder) i stedet for at sende hele historikken omkostningerne og bevarer kontekstvinduet. Vi vil uddybe dette i enhed 6 og 11.
Læs svaret
Når modellen returnerer et svar, modtager du et struktureret objekt, ikke almindelig tekst. Typiske områder:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "For at starte en returnering skal du gå til siden 'Mine ordrer' på din konto..." } ], "stop_reason", "stop_reason", "input_reason": "put_tokens:" 47, "output_tokens": 88 }}
- indhold: Selve svaret; Det er en liste over indholdsblokke. Tekstfeltet i tekstblokken er det faktiske svar.
- stop_reason: Hvorfor modellen stoppede. end_turn = naturlig ende; max_tokens = sidder fast ved outputgrænsen (svaret kan være ufuldstændigt); refusal = afvist af sikkerhedsmæssige årsager. Din kode skal altid se på stop_reason først.
- brug: Indtast og output tokennumre. Det er grundlaget for omkostnings- og grænsesporing.
Bemærk: Hvis stop_reason er max_tokens, er svaret ikke afsluttet. At behandle dette som et "succesfuldt svar" og vise halv tekst til brugeren er en af de mest almindelige fejl i produktionen. Forøg enten max_tokens eller brug streaming.
Svag prompt / Stærk prompt
Samme opgave med to forskellige systemprompter:
# SVAGDu er assistent. Besvar spørgsmålene.
# STÆRK Du er en virksomhedssupportassistent. Regler:- Stol udelukkende på oplysningerne i det leverede politikdokument; Hvis det ikke er i dokumentet, skal du sige "Jeg har ikke disse oplysninger, jeg sender dem til den relevante enhed." - Svar bør ikke overstige 3 sætninger, være formelle og klare. - Spørg ikke om personlige data (TC ID-nummer, kortnummer) og gentag ikke. - Gæt ikke, når du ikke er sikker.
Kraftig version; Den definerer omfang, form, sikkerhedsmargin og adfærd i usikkerhed. Konsistensen af modeloutputtet kommer direkte fra denne klarhed.
Tre mini etuier
Tilfælde 1 — Support bot (statsløshedsfælde). Et e-handelsteam tog botten live; Når brugeren sagde "annuller den forrige ordre", "glemte" botten ordrenummeret. Årsag: de sendte hver anmodning med kun den sidste besked. Løsning: de tilføjede de sidste 6 runder til meddelelseslisten. Resultat: kontekst bevaret, men input pr. anmodning steg fra 40 tokens til ~600 tokens - vi dækker omkostningslektionen i enhed 2.
Sag 2 — Ufuldstændig kontraktresumé. Et juridisk team havde 10-siders kontrakter skitseret; max_tokens: 300 forblev lavt, sammendrag afskærede midt i sætningen. stop_reason var max_tokens hver gang, men ingen kiggede. øget max_tokens til 1500 og tilføjet stop_reason check; Den trunkerede opsummeringsrate faldt fra 18 % til 0 %.
Case 3 - Blanding af roller. Et marketingteam var ved at skrive alle instruktionerne ind i brugermeddelelsen og efterlod systemet tomt. Når brugerinput blandet med instruktion, ville modellen nogle gange overholde brugerens kommando om at "glemme de tidligere regler." De flyttede permanente regler til systemet; Ved at adskille brugerinput fra instruktion faldt regelovertrædelser markant.
Almindelige fejl
- Glemmer at sende fortiden: Modellen menes at "ikke huske"; hvorimod den er statsløs. Du bærer konteksten.
- Ser ikke på `stop_reason`: Svaret stoppet med max_tokens anses for at være komplet.
- Indlejring af instruktionen i `bruger`: Vedvarende regler i systemet; øjeblikkelig input går til brugeren. Blanding skaber sikkerhedssårbarheder.
- Forveksler 'indhold' med en almindelig streng: Svaret er en liste over blokke; læs tekstfeltet i den første tekstblok, bekræft dens type, før du får indhold[0] med et blindt indeks.
- Indlejring af nøglen i koden: Brug en miljøvariabel (enhed 9).
Dybere: Indholdsblokke og flerdelte svar
At forstå, hvorfor indholdsfeltet i svaret er en liste, er grundlæggende for de avancerede funktioner, du vil støde på senere. Nogle gange returnerer modellen ikke en enkelt tekstblok, men flere blokke: en tankeblok efterfulgt af en tekstblok; eller en tekstblok efterfulgt af en værktøjsbrugsblok. Derfor er det skrøbeligt at blindt tælle indhold[0] som et "svar". Den korrekte tilgang er at gennemgå listen og sortere den efter type: du samler tekstindholdet i blokke, hvis typefelt er tekst, og behandler andre typer (tænkning, værktøj) separat.
Hvad denne skelnen gør i praksis er, at du kan logge modellens ræsonnement (hvis nogen) uden at afsløre det for brugeren, omdirigere værktøjsopkald til separat logik og kun udskrive det faktiske svar på skærmen. Efterhånden som modulet skrider frem (især i enhed 4 og 11) vil du se, hvor nyttig denne blokstruktur er til at validere og styre output.
Et andet praktisk punkt: du kan få adgang til den samme model fra forskellige udbyderplatforme (direkte API, via en cloud-udbyder). Selvom slutpunktsadressen og godkendelsesformatet kan ændre sig, forbliver grundlæggende begreber som meddelelsesroller, statsløshed og svarstruktur de samme. Så det grundlæggende i denne enhed gælder, uanset hvilken platform du bruger.
Sammenfattende
En LLM API-anmodning består af modellen, outputgrænsen og meddelelseslisten; roller (system, bruger, assistent) bestemmer modellens adfærd. Opkald er statsløse: du bærer konteksten med hver anmodning. Responsen er et struktureret objekt; Læsning og fortolkning af indhold, stop_reason og brugsfelter er grundlaget for holdbarhed i produktionen.
Ansøgningsopgave
Vælg en opgave fra din egen profession (f.eks. sortering af indgående e-mail, lav korte resuméer). På et stykke papir: (1) skriv systemprompten med 4-5 regler, (2) opsæt et eksempel på en brugerbesked og en eventuel 2-runders historik, (3) bestem en rimelig værdi for max_tokens og skriv begrundelsen, (4) skriv hvilke stop_reason-værdier du vil håndtere i det returnerede svar og hvordan.
tjekliste
- [ ] Jeg kan tælle de tre obligatoriske dele af en anmodning (model, max_tokens, beskeder).
- [ ] Jeg kan forklare forskellen mellem system-, bruger- og assistentroller.
- [ ] Jeg ved, at opkald er statsløse, og at jeg skal bære fortiden.
- Jeg kan læse og kommentere [ ] indhold, stop_reason og brugsfelter.
- [ ] Med max_tokens kan jeg bemærke og håndtere det trunkerede svar.