Vinster:
- Kan beskriva den grundläggande strukturen för en LLM API-begäran (slutpunkt, modell, meddelanden, max_tokens)
- Förstår skillnaden mellan system-, användar- och assistentroller och tillståndslös konversationshistorik
- Kan läsa och tolka fält (innehållsblock, stop_reason, användning) av det returnerade svaret
I tidigare moduler använde vi artificiell intelligens från ett chattfönster. Men om du vill bädda in AI i din egen produkt, automation eller arbetsflöde, kommer ett chattgränssnitt inte att klippa det; Du måste ansluta till modellen programmatiskt, det vill säga med kod eller ett automationsverktyg. Namnet på denna brygga är API (Application Programming Interface, kontraktet som tillåter två programvaror att prata med vissa regler). När du är klar med den här enheten kommer du att veta vad som utgör en LLM (Large Language Model) API-förfrågan, vad meddelanderoller gör och hur du läser svaret. Detta är grunden som resten av modulen kommer att byggas på.
Hur fungerar API?
Grundflödet i API:t är detta: du skickar en begäran i ett visst format; Servern returnerar ett svar i ett specifikt format. I LLM är detta vanligtvis ett HTTP-anrop (HTTP: standardprotokoll för att överföra begäran-svar på webben) till en enda adress (slutpunkt, den fasta adressen på servern som hanterar din begäran). Till exempel, i ett meddelande-API går alla förfrågningar till en enda adress och bärs i kroppen som JSON (JavaScript Object Notation — ett textformat som består av nyckel/värdepar som kan läsas av både människor och maskiner).
I en begäran anger du åtminstone dessa tre saker:
- Modell: Vilken modell du ska använda (t.ex. en snabb och billig modell eller en kraftfull modell).
- max_tokens: Det maximala antalet tokens (den minsta enheten som texten bearbetas i, som kommer att bearbetas i detalj i nästa enhet) som modellen kan producera; dvs utgångsgräns.
- meddelanden: Lista över meddelanden som utgör konversationen.
Steg för steg: Hur man ställer in en förfrågan
- Förbered slutpunkten och användaruppgifterna. Du lägger till din API-nyckel (den hemliga strängen som bevisar din identitet) till begäran i en rubrik. Du bäddar aldrig in nyckeln i koden; Vi kommer att täcka säker förvaring i enhet 9.
- Välj modell och effektgräns. Lättviktsmodell + små max_tokens för en enkel uppgift; Kraftfull modell + större gräns för en komplex uppgift.
- Ställ in meddelandelistan. List the system instruction, user message, and past rounds (if any).
- Skicka begäran och analysera svaret. Läs textinnehållet, stopporsak och tokenanvändning från den returnerade JSON.
Meddelanderoller: system, användare, assistent
En konversation består av meddelanden ordnade i en sekvens, och varje meddelande har en roll. Rollen avgör hur modellen behandlar den texten.
Roll
Vem skriver
Syfte
systemet
Utvecklare/operatör
Permanenta instruktioner, personlighet och regler som gäller genom hela samtalet
användare
slutanvändare
Användarens aktuella fråga eller input
assistent
modell
Svar producerat av modellen (och tidigare svar)
Systemrollen är tillgänglig som ett separat systemfält i begärandekroppen hos de flesta leverantörer; användare och assistent listas sekventiellt i meddelandelistan. 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 är en företagssupportassistent. Ge ett kort, formellt och verifierat svar. Skapa inte information som du inte är säker på.", "messages": [ { "role": "user", "content": "Hur startar jag min returprocess?" } ]}
Tal är statslöst
Här är den vanligaste missuppfattningen: LLM API-anrop är tillståndslösa – servern behåller inget minne mellan två förfrågningar. Modellen kommer inte ihåg din tidigare förfrågan. Om du ställer in en chatt i flera omgångar måste du skicka om tidigare omgångar med varje ny begäran. Modellens "minne" består av en lista med meddelanden du har skickat.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Hej, jag heter Deniz." }, { "role": "assistent", "content": "Hej Deniz, hur kan jag hjälpa dig?" }, { "role": "user", "content": "Jag sa precis mitt namn, minns du?" } ]}
Att svara på det tredje meddelandet korrekt beror på att du skickar båda tidigare meddelandena. Om du inte skickar det kommer modellen inte att känna till "Sea" och kommer att svara felaktigt. Detta påverkar också kostnaden direkt: ju längre konversationen är, desto större blir listan, varje begäran förbrukar fler tokens.
Tips: I långa samtal, sammanfatta och flytta gamla omgångar (sammanfattning + senaste omgångarna) istället för att skicka hela historiken minskar kostnaderna och bevarar sammanhangsfönstret. Vi kommer att fördjupa detta i enheterna 6 och 11.
Läs svaret
När modellen returnerar ett svar får du ett strukturerat objekt, inte vanlig text. Typiska områden:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistent", "content": [ { "type": "text", "text": "För att initiera en retur, gå till sidan "Mina beställningar" i ditt konto..." } ], "stop_reason", "stop_reason", "input_reason": "put_entokens:" 47, "output_tokens": 88 }}
- innehåll: Själva svaret; Det är en lista över innehållsblock. Textfältet i textblocket är själva svaret.
- stop_reason: Varför modellen slutade. end_turn = naturligt slut; max_tokens = har fastnat vid utgångsgränsen (svaret kan vara ofullständigt); refusal = nekad av säkerhetsskäl. Din kod bör alltid titta på stop_reason först.
- användning: Mata in och mata ut tokennummer. Det är grunden för kostnads- och gränsspårning.
Observera: Om stop_reason är max_tokens, är svaret inte slutfört. Att behandla detta som ett "lyckat svar" och visa halv text för användaren är ett av de vanligaste misstagen i produktionen. Antingen öka max_tokens eller använd streaming.
Svag prompt / Stark prompt
Samma uppgift med två olika systemuppmaningar:
# SVAGDu är en assistent. Svara på frågorna.
# STARK Du är en företagssupportassistent. Regler:- Lita enbart på informationen i det tillhandahållna policydokumentet; Om det inte finns i dokumentet, säg "Jag har inte den här informationen, jag hänvisar den till relevant enhet." – Svar bör inte överstiga 3 meningar, vara formella och tydliga. - Fråga inte efter personuppgifter (TC ID-nummer, kortnummer) och upprepa inte. – Gissa inte när du är osäker.
Kraftfull version; Den definierar omfattning, form, säkerhetsmarginal och beteende i osäkerhet. Konsistensen i modellens utdata kommer direkt från denna tydlighet.
Tre minifodral
Fall 1 — Supportbot (statslöshetsfälla). Ett e-handelsteam tog boten live; När användaren sa "avbryt föregående beställning" "glömde" boten beställningsnumret. Anledning: de skickade varje förfrågan med bara det sista meddelandet. Lösning: de lade till de senaste 6 omgångarna till meddelandelistan. Resultat: sammanhanget bevarat, men indata per begäran ökade från 40 tokens till ~600 tokens — vi täcker kostnadsläxan i enhet 2.
Fall 2 — Ofullständig kontraktssammanfattning. Ett juridiskt team hade 10-sidiga kontrakt beskrivna; max_tokens: 300 förblev låg, sammanfattningar skar bort mitten av meningen. stop_reason var max_tokens varje gång men ingen tittade. ökade max_tokens till 1500 och lade till stop_reason check; Den trunkerade sammanfattningsfrekvensen minskade från 18 % till 0 %.
Fall 3 – Blanda roller. Ett marknadsföringsteam skrev alla instruktioner i användarmeddelandet och lämnade systemet tomt. När användarinmatning blandas med instruktioner, skulle modellen ibland följa användarens kommando att "glömma de tidigare reglerna." De flyttade permanenta regler till systemet; Genom att separera användarinmatning från instruktioner minskade regelöverträdelserna avsevärt.
Vanliga misstag
- Att glömma att skicka det förflutna: Modellen är tänkt att "inte komma ihåg"; medan den är statslös. Du bär sammanhanget.
- Tittar inte på `stop_reason`: Svaret som stoppades med max_tokens anses vara komplett.
- Bädda in instruktionen i `användare`: Beständiga regler i systemet; omedelbar input går till användaren. Blandning skapar säkerhetssårbarheter.
- Misstag "innehåll" för en vanlig sträng: Svaret är en lista med block; läs textfältet i det första textblocket, verifiera dess typ innan du får innehåll[0] med ett blindindex.
- Bädda in nyckeln i koden: Använd en miljövariabel (enhet 9).
Djupare: Innehållsblock och flerdelade svar
Att förstå varför innehållsfältet i svaret är en lista är grundläggande för de avancerade funktioner du kommer att stöta på senare. Ibland returnerar modellen inte ett enda textblock, utan flera block: ett tankeblock följt av ett textblock; eller ett textblock följt av ett verktygsanvändningsblock. Det är därför det är bräckligt att blint räkna innehåll[0] som ett "svar". Det korrekta tillvägagångssättet är att gå igenom listan och sortera den efter typ: du samlar in textinnehållet i block vars typfält är text, och behandlar andra typer (tänkande, verktyg) separat.
Vad denna distinktion gör i praktiken är att du kan logga modellens resonemang (om något finns) utan att avslöja det för användaren, omdirigera verktygsanrop till separat logik och bara skriva ut själva svaret på skärmen. När modulen fortskrider (särskilt i enheterna 4 och 11) kommer du att se hur användbar denna blockstruktur är för att validera och styra utdata.
En annan praktisk punkt: du kan komma åt samma modell från olika leverantörsplattformar (direkt API, via en molnleverantör). Även om slutpunktsadressen och autentiseringsformatet kan ändras, förblir grundläggande begrepp som meddelanderoller, tillståndslöshet och svarsstruktur desamma. Så grunderna i den här enheten gäller oavsett vilken plattform du använder.
Sammanfattningsvis
En LLM API-begäran består av modellen, utdatagränsen och meddelandelistan; roller (system, användare, assistent) avgör modellens beteende. Samtalen är statslösa: du bär sammanhanget med varje förfrågan. Svaret är ett strukturerat objekt; Att läsa och tolka innehållet, stop_reason och användningsfält är grunden för hållbarhet i produktionen.
Applikationsuppgift
Välj en uppgift från ditt eget yrke (t.ex. sortera inkommande e-post, skapa korta sammanfattningar). På ett papper: (1) skriv systemprompten med 4-5 regler, (2) ställ in ett exempel på ett användarmeddelande och en historik i 2 omgångar, (3) bestäm ett rimligt värde för max_tokens och skriv motiveringen, (4) lista vilka stop_reason-värden du kommer att hantera i det returnerade svaret och hur.
checklista
- [ ] Jag kan räkna de tre obligatoriska delarna av en begäran (modell, max_tokens, meddelanden).
- [ ] Jag kan förklara skillnaden mellan system-, användar- och assistentroller.
- [ ] Jag vet att samtal är statslösa och att jag måste bära det förflutna.
- Jag kan läsa och kommentera [ ] innehåll, stop_reason och användningsfält.
- [ ] Med max_tokens kan jag lägga märke till och hantera det trunkerade svaret.