Winst:
- Kan de basisstructuur van een LLM API-verzoek beschrijven (eindpunt, model, berichten, max_tokens)
- Begrijpt het verschil tussen systeem-, gebruikers- en assistentrollen en staatloze gespreksgeschiedenis
- Kan velden (inhoudsblokken, stop_reason, gebruik) van het geretourneerde antwoord lezen en interpreteren
In eerdere modules gebruikten we kunstmatige intelligentie vanuit een chatvenster. Maar als je AI wilt inbedden in je eigen product, automatisering of workflow, dan is een chatinterface niet voldoende; U moet programmatisch verbinding maken met het model, dat wil zeggen met code of een automatiseringstool. De naam van deze brug is API (Application Programming Interface, het contract waarmee twee software met bepaalde regels kan praten). Wanneer u dit blok voltooit, weet u wat een LLM (Large Language Model) API-verzoek inhoudt, wat berichtrollen doen en hoe u het antwoord kunt lezen. Dit is de basis waarop de rest van de module zal worden gebouwd.
Hoe werkt de API?
De basisstroom in de API is deze: u verzendt een verzoek in een bepaald formaat; De server retourneert een antwoord in een specifiek formaat. In LLM's is dit meestal een HTTP-aanroep (HTTP: standaardprotocol voor het overbrengen van verzoek-antwoord op internet) naar één enkel adres (eindpunt, het vaste adres op de server die uw verzoek afhandelt). In een berichten-API gaan alle verzoeken bijvoorbeeld naar één adres en worden ze in de hoofdtekst overgedragen als JSON (JavaScript Object Notation – een tekstformaat dat bestaat uit sleutel/waarde-paren die door zowel mensen als machines kunnen worden gelezen).
In een verzoek specificeer je minimaal deze drie zaken:
- Model: Welk model u gaat gebruiken (bijvoorbeeld een snel en goedkoop model of een krachtig model).
- max_tokens: Het maximale aantal tokens (de kleinste eenheid waarin de tekst wordt verwerkt, die in de volgende eenheid in detail zal worden verwerkt) dat het model kan produceren; d.w.z. uitgangslimiet.
- berichten: Lijst met berichten waaruit het gesprek bestaat.
Stap voor stap: zo stelt u een verzoek in
- Bereid het eindpunt en de referenties voor. U voegt uw API-sleutel (de geheime string die uw identiteit bewijst) toe aan het verzoek in een header. Je sluit de sleutel nooit in de code in; Veilige opslag behandelen we in unit 9.
- Selecteer het model en de uitvoerlimiet. Lichtgewicht model + kleine max_tokens voor een eenvoudige taak; Krachtig model + grotere limiet voor een complexe taak.
- Stel de berichtenlijst in. List the system instruction, user message, and past rounds (if any).
- Verzend het verzoek en parseer het antwoord. Lees de tekstinhoud, stopreden en tokengebruik van de geretourneerde JSON.
Berichtrollen: systeem, gebruiker, assistent
Een gesprek bestaat uit berichten die in een bepaalde volgorde zijn gerangschikt, en elk bericht heeft een rol. De rol bepaalt hoe het model met die tekst omgaat.
Rol
Wie schrijft
Doel
systeem
Ontwikkelaar/exploitant
Permanente instructies, persoonlijkheid en regels die gedurende het hele gesprek gelden
gebruiker
eindgebruiker
De huidige vraag of invoer van de gebruiker
assistent
model
Reactie geproduceerd door het model (en eerdere reacties)
Bij de meeste providers is de systeemrol beschikbaar als afzonderlijk systeemveld in de aanvraagtekst; gebruiker en assistent worden opeenvolgend weergegeven in de berichtenlijst. 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": "Je bent een bedrijfsondersteuningsassistent. Geef een kort, formeel en geverifieerd antwoord. Verzin geen informatie waar je niet zeker van bent.", "messages": [ { "role": "user", "content": "Hoe start ik mijn retourproces?" } ]}
Spraak is staatloos
Dit is de meest voorkomende misvatting: LLM API-aanroepen zijn staatloos: de server bewaart geen geheugen tussen twee verzoeken. Het model onthoudt uw eerdere verzoek niet. Als u een chat met meerdere rondes opzet, moet u bij elk nieuw verzoek eerdere rondes opnieuw verzenden. Het "geheugen" van het model bestaat uit een lijst met berichten die u hebt verzonden.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Hallo, mijn naam is Deniz." }, { "rol": "assistent", "content": "Hallo Deniz, hoe kan ik je helpen?" }, { "role": "user", "content": "Ik zei net mijn naam, weet je nog?" } ]}
Het correct beantwoorden van het derde bericht hangt af van het feit of u beide voorgaande berichten verzendt. Als u het niet verzendt, kent het model "Zee" niet en zal het onjuist antwoorden. Dit heeft ook rechtstreeks invloed op de kosten: hoe langer het gesprek, hoe groter de lijst, waarbij elk verzoek meer tokens verbruikt.
Tip: Bij lange gesprekken bespaart het samenvatten en verplaatsen van oude rondes (samenvatting + laatste paar rondes) in plaats van het verzenden van de hele geschiedenis de kosten en blijft het contextvenster behouden. In blok 6 en 11 verdiepen we dit.
Lees het antwoord
Wanneer het model een antwoord retourneert, ontvangt u een gestructureerd object en geen platte tekst. Typische gebieden:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistent", "content": [ { "type": "text", "text": "Om een retourzending te starten, gaat u naar de pagina 'Mijn bestellingen' in uw account..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- inhoud: het antwoord zelf; Het is een lijst met inhoudsblokken. Het tekstveld van het tekstblok is het daadwerkelijke antwoord.
- stop_reason: Waarom het model is gestopt. end_turn = natuurlijk einde; max_tokens = vastgelopen op uitvoerlimiet (reactie is mogelijk onvolledig); weigering = geweigerd om veiligheidsredenen. Uw code moet altijd eerst naar stop_reason kijken.
- gebruik: Invoer- en uitvoertokennummers. Het is de basis voor het volgen van kosten en limieten.
Let op: als stop_reason max_tokens is, is het antwoord niet voltooid. Dit behandelen als een "succesvolle reactie" en de gebruiker een halve tekst laten zien, is een van de meest voorkomende fouten in de productie. Verhoog max_tokens of gebruik streaming.
Zwakke prompt/sterke prompt
Dezelfde taak met twee verschillende systeemprompts:
# ZWAKJe bent een assistent. Beantwoord de vragen.
# STRONGJe bent een bedrijfsondersteuningsassistent. Regels: - Vertrouw uitsluitend op de informatie in het verstrekte polisdocument; Als het niet in het document staat, zegt u: "Ik heb deze informatie niet, ik stuur deze door naar de betreffende eenheid." - Antwoorden mogen niet langer zijn dan 3 zinnen, formeel en duidelijk zijn. - Vraag niet om persoonlijke gegevens (TC ID-nummer, kaartnummer) en herhaal dit niet. - Gok niet als je het niet zeker weet.
Krachtige versie; Het definieert reikwijdte, vorm, veiligheidsmarge en gedrag in onzekerheid. De consistentie van de modeluitvoer komt rechtstreeks voort uit deze duidelijkheid.
Drie mini-hoesjes
Geval 1 — Ondersteuningsbot (staatloosheidsval). Een e-commerceteam nam de bot live; Toen de gebruiker zei "de vorige bestelling annuleren", "vergat" de bot het bestelnummer. Reden: ze stuurden elk verzoek alleen met het laatste bericht. Oplossing: ze hebben de laatste 6 rondes toegevoegd aan de berichtenlijst. Resultaat: context behouden, maar input per verzoek verhoogd van 40 tokens naar ~600 tokens – we behandelen de kostenles in unit 2.
Geval 2 — Onvolledig contractoverzicht. Een juridisch team liet contracten van tien pagina's uittekenen; max_tokens: 300 bleef laag, samenvattingen werden halverwege de zin afgebroken. stop_reason was elke keer max_tokens, maar niemand keek. max_tokens verhoogd naar 1500 en stop_reason-controle toegevoegd; Het ingekorte samenvattingspercentage daalde van 18% naar 0%.
Geval 3 — Rollen vermengen. Een marketingteam schreef alle instructies in het gebruikersbericht, waardoor het systeem blanco bleef. Wanneer gebruikersinvoer werd gecombineerd met instructies, voldeed het model soms aan het commando van de gebruiker om "de vorige regels te vergeten". Ze hebben permanente regels naar het systeem verplaatst; Door gebruikersinvoer te scheiden van instructie daalden de regelovertredingen aanzienlijk.
Veel voorkomende fouten
- Vergeten het verleden te verzenden: er wordt gedacht dat het model zich "niet herinnert"; terwijl het staatloos is. Jij draagt de context.
- Niet kijken naar `stop_reason`: het antwoord dat gestopt is met max_tokens wordt als voltooid beschouwd.
- Inbedden van de instructie in `user`: Persistente regels in het systeem; directe invoer gaat naar de gebruiker. Door het combineren ontstaan er beveiligingsproblemen.
- `content` verwarren met een gewone string: het antwoord is een lijst met blokken; lees het tekstveld van het eerste tekstblok, verifieer het type voordat u inhoud[0] krijgt met een blinde index.
- De sleutel in de code inbedden: Gebruik een omgevingsvariabele (eenheid 9).
Dieper: inhoudsblokken en meerdelige antwoorden
Begrijpen waarom het inhoudsveld in het antwoord een lijst is, is van fundamenteel belang voor de geavanceerde functies die u later zult tegenkomen. Soms retourneert het model niet één enkel tekstblok, maar meerdere blokken: een denkblok, gevolgd door een blok tekst; of een tekstblok gevolgd door een blok voor gereedschapsgebruik. Daarom is het blindelings tellen van content[0] als een "antwoord" kwetsbaar. De juiste aanpak is om door de lijst te gaan en deze op type te sorteren: je verzamelt de tekstinhoud van blokken waarvan het typeveld tekst is, en behandelt andere typen (denken, gereedschap) afzonderlijk.
Wat dit onderscheid in de praktijk betekent, is dat je de redenering van het model (indien aanwezig) kunt loggen zonder deze aan de gebruiker bekend te maken, toolaanroepen om te leiden naar afzonderlijke logica en alleen het daadwerkelijke antwoord op het scherm af te drukken. Naarmate de module vordert (vooral in de eenheden 4 en 11) zul je zien hoe nuttig deze blokstructuur is voor het valideren en sturen van de uitvoer.
Nog een praktisch punt: je hebt toegang tot hetzelfde model vanaf verschillende providerplatforms (directe API, via een cloudprovider). Hoewel het eindpuntadres en de authenticatie-indeling kunnen veranderen, blijven basisconcepten zoals berichtrollen, staatloosheid en responsstructuur hetzelfde. De basisbeginselen in dit apparaat zijn dus van toepassing, ongeacht welk platform u gebruikt.
Samengevat
Een LLM API-verzoek bestaat uit het model, de uitvoerlimiet en de berichtenlijst; rollen (systeem, gebruiker, assistent) bepalen het gedrag van het model. Oproepen zijn staatloos: u draagt bij elk verzoek de context mee. Het antwoord is een gestructureerd object; Het lezen en interpreteren van de inhouds-, stop_reason- en gebruiksvelden vormt de basis voor duurzaamheid in de productie.
Applicatie taak
Kies een taak uit je eigen vakgebied (bijvoorbeeld binnenkomende e-mail sorteren, korte samenvattingen maken). Op een stuk papier: (1) schrijf de systeemprompt met 4-5 regels, (2) stel een voorbeeldgebruikersbericht en een eventuele geschiedenis van twee ronden in, (3) bepaal een redelijke waarde voor max_tokens en schrijf de rechtvaardiging, (4) vermeld welke stop_reason-waarden u in het geretourneerde antwoord zult verwerken en hoe.
controlelijst
- [ ] Ik kan de drie verplichte delen van een verzoek tellen (model, max_tokens, berichten).
- [ ] Ik kan het verschil tussen systeem-, gebruikers- en assistentrollen uitleggen.
- [ ] Ik weet dat oproepen staatloos zijn en dat ik het verleden moet dragen.
- Ik kan [ ] inhoud, stop_reason en gebruiksvelden lezen en erop reageren.
- [ ] Met max_tokens kan ik het ingekorte antwoord opmerken en verwerken.