0%

Hoofdstuk 12 · oefening

Mee naar huis

Vraag een API-sleutel aan en houd hem geheim

De studieassistent werkt. Hij antwoordt op basis van de notities, schrijft quizzen, voert gesprekken, blijft binnen een budget en sluit af met een code die zegt wat er is gebeurd. Tot nu toe heeft hij alleen met het cursusmodel gepraat, dat geen sleutel controleert, gratis antwoordt en binnen deze site woont. In dit hoofdstuk verhuist hij naar een echte aanbieder, het soort waarvoor je betaalt, zonder dat er een sleutel uitlekt en zonder dat je meer uitgeeft dan je van plan was.

Je project voor dit hoofdstuk

Open study_assistant.py in de projecteditor. Het is het afgeronde programma uit hoofdstuk 11, met bovenaan een paar meegeleverde toevoegingen: import json en import os, de constanten COURSE_BASE_URL en COURSE_MODEL, LOG_FILE en PRICE_PER_MILLION_OUTPUT, en drie nieuwe functies. read_api_key (deze les) en log_run (les 4) zijn nog niet af. summarize_log is afgeronde code die les 4 leest. Al het andere is zoals hoofdstuk 11 het achterliet, en dit hoofdstuk verandert alleen build_client, twee constanten, main en de guard onderaan.

Het startbestand is stages.py, net als in hoofdstuk 11. Voer python stages.py uit in de Shell en het laat elke wijziging zien zodra je die maakt. Het programma zelf draait daar ook, als python study_assistant.py ....

De andere bestanden zijn net als eerder meegeleverd: evals.py en tests/ uit hoofdstuk 10, reliable.py uit hoofdstuk 9 met het aantal quizvragen, en de bestanden die ze importeren. De controle van je werk gebruikt eigen kopieën ervan.

Een sleutel is een wachtwoord dat geld uitgeeft

Een aanbieder zoals OpenRouter geeft je een API-sleutel, een lange geheime string die met elk request meegaat. De aanbieder gebruikt hem om te weten wie er belt en wie de rekening krijgt. Wie je sleutel heeft, kan je rekening laten oplopen, dus behandel hem als een wachtwoord waar je bankpas aan vastzit:

  • Hij komt nooit in een bronbestand. Een bestand wordt gekopieerd, geüpload, gedeeld en gecommit.

  • Hij komt nooit in een chat, een screenshot of een bericht aan iemand die je helpt.

  • Lekt hij toch uit, dan trek je hem in bij de aanbieder en maak je een nieuwe. Een ingetrokken sleutel werkt niet meer, dus de gelekte kopie is waardeloos.

Eén regel is in deze cursus belangrijker dan de andere: plak nooit een echte sleutel in deze site. Niet in de sandbox, niet in een bestand in de projecteditor, niet in de en niet in Monty of een andere AI-chat. De sandbox heeft geen internet, dus een echte sleutel zou hier nutteloos zijn en alleen blootgesteld worden. Elke sleutel in deze lessen is verzonnen, en je kunt het hele hoofdstuk zonder sleutel afmaken. In les 5 gebruik je je eigen sleutel, op je eigen computer.

Omgevingsvariabelen

De gebruikelijke plek voor een sleutel is een omgevingsvariabele (environment variable): een benoemde waarde die de shell meegeeft aan elk programma dat hij start. Het programma leest die waarde terwijl het draait, dus de sleutel staat nooit in de code.

In bash stelt export een variabele in voor de rest van de terminalsessie, zodat elk programma dat je vanuit die terminal start hem ziet:

export STUDY_ASSISTANT_API_KEY=made-up-key

PowerShell schrijft hetzelfde als $env: gevolgd door de naam, een isgelijkteken en de waarde tussen aanhalingstekens, en dat blijft gelden tot je het venster sluit:

$env:STUDY_ASSISTANT_API_KEY = "made-up-key"

In bash kun je ook NAME=value vóór één commando zetten; de variabele bestaat dan alleen voor dat commando:

STUDY_ASSISTANT_API_KEY=anything python study_assistant.py ask "How do I make an independent copy of a list?"

Dat werkt hier wel, omdat het cursusmodel de sleutel negeert, dus anything is net zo goed als elke andere verzonnen waarde.

Een sleutel die je bij de prompt van de shell intypt, heeft nog één uitweg: de shell bewaart je commando’s in zijn geschiedenis, dus de sleutel blijft op schijf staan nadat je de terminal sluit. Als je geschiedenis gedeeld wordt of naar een andere computer wordt gesynchroniseerd, is dat ook een lek. Typ een sleutel in een privésessie op je eigen computer, en trek hem in als je geschiedenis die computer ooit verlaat.

Sommige tools lezen sleutels uit een .env-bestand. Dit programma doet dat niet, dus het heeft er geen nodig. Als een ander project van je er wel een gebruikt en je werkt met Git, voeg het dan toe aan .gitignore zodat het nooit gecommit wordt. De Git-cursus legt uit hoe.

os.environ

In Python is os.environ een weergave van de omgeving die werkt als een dictionary van namen naar waarden, allebei strings. Een ontbrekende naam opzoeken met vierkante haken werpt een KeyError op, net als bij een dictionary:

import os

key = os.environ["OPENROUTER_API_KEY"]  # KeyError when it is not set

get geeft in plaats daarvan een standaardwaarde, en dat is wat dit programma nodig heeft:

key = os.environ.get("OPENROUTER_API_KEY", "")

De studieassistent gebruikt een eigen naam, STUDY_ASSISTANT_API_KEY, bewaard in de constante API_KEY_ENV, omdat hij met elke aanbieder werkt en niet alleen met OpenRouter.

read_api_key

read_api_key(environ, base_url) beslist welke sleutel de client naar base_url stuurt. De functie krijgt de omgeving als parameter, environ, in plaats van zelf os.environ te lezen. build_client geeft os.environ mee, en een test of controle geeft een eigen kleine dictionary met verzonnen waarden mee, zonder de echte omgeving aan te raken.

Dat gaat in drie stappen:

  1. Lees de variabele die API_KEY_ENV noemt met environ.get(API_KEY_ENV, ""), en pas er strip() op toe. Een sleutel die met een losse spatie of regeleinde is geplakt, zou anders bij de aanbieder mislukken met een verwarrende foutmelding.

  2. Is het resultaat niet leeg, geef het dan terug.

  3. Geef anders "sandbox" terug wanneer base_url gelijk is aan COURSE_BASE_URL, omdat het cursusmodel geen sleutel controleert. Werp voor elk ander adres dit op:

raise ValueError(f"Set the {API_KEY_ENV} environment variable to your API key for {base_url}.")

Een lege waarde of een waarde met alleen spaties telt als geen sleutel.

Waarom zou je dit controleren, als de aanbieder een ontbrekende sleutel toch al zou weigeren? Vanwege de manier waarop hij zou weigeren. Als het programma geen sleutel meestuurt, laat de openai-client zich niet eens aanmaken en werpt hij openai.OpenAIError op (“Missing credentials”). Dat is geen openai.APIError, dus run_command uit hoofdstuk 11 zou hem niet afvangen en het programma zou eindigen met een traceback. Een verkeerde sleutel faalt later, als een 401 van de aanbieder. Eén regel die de variabele noemt die je moet instellen, is vriendelijker dan allebei, en in les 2 laat je main die regel afdrukken.

Pas daarna build_client aan zodat hij die sleutel meestuurt:

api_key=read_api_key(os.environ, BASE_URL)

Laat base_url, timeout en max_retries zoals ze zijn.

De afbeelding volgt de sleutel van de aanbieder naar het request en somt de plekken op waar hij nooit mag komen. Alleen de omgevingsvariabele bevat de sleutel; de code bevat alleen de naam van de variabele, in API_KEY_ENV.

De sleutel gaat van de aanbieder naar de omgevingsvariabele STUDY_ASSISTANT_API_KEY, die read_api_key leest voor build_client; hij komt nooit in een bronbestand, een chat, deze site of afgedrukte uitvoer.

Druk nooit een sleutel af

Terwijl je hieraan werkt, wil je misschien zien of de sleutel is aangekomen. Druk hem niet af, ook niet even: afgedrukte tekst belandt in de terminalgeschiedenis, screenshots, logs en chats. Druk in plaats daarvan de lengte af. Een lengte vertelt je of de variabele is ingesteld en of losse spaties zijn verwijderd, en verraadt niets. read_api_key zelf drukt niets af.

Voer het uit

Als beide functies af zijn, voer je python stages.py uit. stages.py roept je read_api_key aan met drie verzonnen omgevingen en drukt alleen af wat veilig is:

Lesson 1: read_api_key
  No key, course model: sandbox
  A made-up key with spaces around it: 8 characters (never print the key itself)
  No key, a real provider: ValueError: Set the STUDY_ASSISTANT_API_KEY environment variable to your API key for https://openrouter.ai/api/v1.

Lesson 2: the active settings
  BASE_URL: http://llm-api:8080/v1
  MODEL: pl-scripted
  STUDY_ASSISTANT_API_KEY: not set
  To change them, set STUDY_ASSISTANT_BASE_URL, STUDY_ASSISTANT_MODEL and
  STUDY_ASSISTANT_API_KEY before the program starts. On this site, leave them unset.

Run stopped at the next function to build: main gets log_file and clock in Lesson 4.

De verzonnen sleutel was " test-123 ", tien tekens met de spaties erbij, en 8 na het strippen. Het blok van les 2 draait al, omdat het alleen instellingen afdrukt; in les 2 laat je ze uit de omgeving komen.

De controles geven read_api_key eigen dictionaries mee, roepen build_client aan met verzonnen waarden in de omgeving en bekijken de client die terugkomt: de sleutel, het adres, de time-out en het aantal nieuwe pogingen. Er wordt geen request verstuurd.

Waarom krijgt read_api_key de omgeving als parameter, environ, in plaats van zelf os.environ te lezen?

De aanbieder zou een ontbrekende sleutel toch al weigeren. Waarom werpt read_api_key zelf een ValueError op voor het adres van een echte aanbieder?

Opdracht

In study_assistant.py:

  1. Schrijf read_api_key(environ, base_url): lees environ.get(API_KEY_ENV, "") en pas er strip() op toe. Geef het terug als het niet leeg is. Geef anders "sandbox" terug wanneer base_url gelijk is aan COURSE_BASE_URL, en werp voor elk ander adres ValueError(f"Set the {API_KEY_ENV} environment variable to your API key for {base_url}.") op. Druk niets af.

  2. Vervang in build_client api_key="sandbox" door api_key=read_api_key(os.environ, BASE_URL). Houd de andere argumenten zoals ze zijn.

Gebruik alleen verzonnen sleutels. Plak nooit een echte sleutel in deze site. Voer python stages.py uit om read_api_key aan het werk te zien en controleer daarna je werk.