Die Dokumentation ist das Handbuch eines Dienstes
Die Dokumentation einer API ist das Handbuch eines Dienstes, den jemand anderes gebaut hat. Sie sagt, was Sie anfordern können, was Sie senden müssen und was zurückkommt.
Sie schnell zu lesen ist eine Kernfähigkeit. Sie macht aus einer Beschreibung einen funktionierenden Aufruf.
Am Ende dieser Lektion
Notiz
Ich kann die Dokumentation einer API in einen funktionierenden Aufruf verwandeln.
Schlüsselwörter
| Begriff | Was er bedeutet | Beispiel |
|---|---|---|
| Endpunkt | ein URL-Pfad, der genau eine Aufgabe erledigt | /v1/chat/completions |
| Parameter | eine benannte Eingabe eines Aufrufs | |
| Pflicht | ein Parameter, den Sie senden müssen | |
| Standardwert | der Wert, der gilt, wenn Sie nichts senden | |
| Fehlertabelle | die Liste der Status und was jeder bedeutet |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Eine Dokumentationsseite hat vier Teile
Die meisten Seiten enthalten dieselben vier Dinge. Der Endpunkt sagt, wohin der Aufruf geht. Die Parameterliste sagt, was Sie senden dürfen. Ein Beispiel zeigt einen funktionierenden Aufruf. Die Fehlertabelle sagt, was jeder Fehler bedeutet.
Lesen Sie sie in dieser Reihenfolge. Die nächste Tabelle ist eine Beispielseite, geschrieben für diese Lektion.
Beispiel: eine Parameterliste
| Parameter | Typ | Pflicht | Standard |
|---|---|---|---|
| messages | Liste | Ja | Keiner |
| max_tokens | ganze Zahl, 1 bis 4096 | Nein | 256 |
| temperature | Zahl, 0 bis 2 | Nein | 1 |
| stream | wahr oder falsch | Nein | falsch |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Den Aufruf machen, den die Seite beschreibt
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';(async()=>{const koerper={model:'lab',messages:[{role:'user',content:'Nennen Sie eine Verwendung einer API in fünf Wörtern.'}],max_tokens:30,temperature:0};console.log('Gesendet: max_tokens='+koerper.max_tokens+', temperature='+koerper.temperature);try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify(koerper)});const j=await r.json();if(r.ok===false)throw new Error(r.status+' '+j.error.message);console.log('Modell: '+j.choices[0].message.content)}catch(e){console.log('Keine Antwort ('+e.message+'). Aufgezeichnetes Beispiel:');console.log('Modell: Wetterdaten für eine App abrufen.')}})()"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Das Beispiel zeigt die Form
Kopieren Sie zuerst das Beispiel und bringen Sie es zum Laufen. Das beweist, dass Ihre Umgebung stimmt. Ändern Sie dann einen Parameter nach dem anderen und prüfen Sie jede Änderung in der Parameterliste.
Die Liste nennt Typ, Bereich und Standardwert. Ein Wert außerhalb des Bereichs ergibt einen Fehler, prüfen Sie ihn also vor dem Senden.
Parameter anhand der Seite prüfen
docker exec -w /home/node/project agent node -e "const spez={max_tokens:{von:1,bis:4096},temperature:{von:0,bis:2}};const pruefen=(p)=>{const aus=[];for(const k in p){if(spez[k]===undefined){aus.push('unbekannt '+k);continue}if(k==='max_tokens'&&Number.isInteger(p[k])===false)aus.push(k+' muss eine ganze Zahl sein');else if(p[k]<spez[k].von||p[k]>spez[k].bis)aus.push(k+' muss von '+spez[k].von+' bis '+spez[k].bis+' reichen')}return aus};for(const p of [{max_tokens:50},{max_tokens:5000},{max_tokens:2.5,temperature:3},{top:1}])console.log(JSON.stringify(p)+' -> '+(pruefen(p).join('; ')||'ok'))"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die Fehlertabelle sagt, was zu tun ist
Eine gute Fehlertabelle nennt nicht nur einen Status. Sie sagt Ihnen, ob Sie Ihren Aufruf korrigieren, warten oder es später versuchen sollen.
Ein 4xx-Status heißt meist, dass Sie etwas ändern. Ein 5xx-Status heißt, dass der Dienst ein Problem hat, Sie versuchen es also später erneut.
Beispiel: eine Fehlertabelle
| Status | Bedeutung | Was zu tun ist |
|---|---|---|
| 400 | Der Body ist falsch | Den Body korrigieren |
| 401 | Schlüssel fehlt oder ist falsch | Den Schlüssel prüfen |
| 403 | Hier nicht erlaubt | Die Meldung lesen |
| 429 | Zu viele Anfragen | Warten, dann erneut versuchen |
| 503 | Der Dienst ist nicht bereit | Später erneut versuchen |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Einen Status mit der Fehlertabelle lesen
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';const rat={200:'hat geklappt, Body lesen',400:'Body korrigieren',401:'Schlüssel prüfen',403:'Meldung lesen',429:'warten, dann erneut versuchen',503:'später erneut versuchen'};(async()=>{try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify({model:'lab',messages:[{role:'user',content:'Sagen Sie Hallo.'}],max_tokens:10})});console.log('Status '+r.status+': '+(rat[r.status]||'nicht in der Tabelle'));if(r.status>299)console.log('Aufgezeichnetes Beispiel eines guten Aufrufs: Status 200: '+rat[200])}catch(e){console.log('Keine Antwort vom Dienst ('+e.message+'). Aufgezeichnetes Beispiel:');console.log('Status 429: '+rat[429])}})()"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Ein häufiger Fehler
Warnung
Viele glauben, das Beispiel in der Dokumentation sei die ganze API. Ein Beispiel zeigt nur einen Aufruf. Die Parameterliste sagt, was Sie sonst noch senden dürfen, und die Fehlertabelle sagt, was bei einem Fehlschlag zu tun ist. Lesen Sie alle drei.