ドキュメントはサービスの説明書
APIのドキュメントは、他の人が作ったサービスの説明書です。何を頼めるか、何を送るか、何が返るかが書いてあります。
これを素早く読む力は、開発者の基本です。紙の上の説明を、動く呼び出しに変えられます。
このレッスンのゴール
メモ
APIのドキュメントを、動く呼び出しに変えられる。
キーワード
| ことば | いみ | れい |
|---|---|---|
| エンドポイント | 1つの仕事をするURLのパス | /v1/chat/completions |
| パラメーター | 呼び出しに渡す、名前付きの入力 | |
| 必須 | 必ず送らなければならないパラメーター | |
| デフォルト | 何も送らないときに使われる値 | |
| エラー表 | ステータスと、その意味の一覧 |
学生が入力するセルは、このプレビューでは空白です。
ドキュメントのページは4つの部分
ほとんどのページには、同じ4つのものがあります。エンドポイントは、呼び出しの送り先です。パラメーターの一覧は、送ってよいものです。例は、動く呼び出し1つです。エラー表は、失敗の意味です。
この順に読みましょう。次の表は、このレッスンのために書いた例のページです。
例：パラメーターの一覧
| パラメーター | 型 | 必須 | デフォルト |
|---|---|---|---|
| messages | リスト | はい | なし |
| max_tokens | 整数、1から4096 | いいえ | 256 |
| temperature | 数、0から2 | いいえ | 1 |
| stream | true か false | いいえ | false |
学生が入力するセルは、このプレビューでは空白です。
ページが説明する呼び出しをする
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';(async()=>{const body={model:'lab',messages:[{role:'user',content:'APIの使い道を1つ、10文字ほどで答えてください。'}],max_tokens:30,temperature:0};console.log('送信：max_tokens='+body.max_tokens+', temperature='+body.temperature);try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify(body)});const j=await r.json();if(r.ok===false)throw new Error(r.status+' '+j.error.message);console.log('モデル：'+j.choices[0].message.content)}catch(e){console.log('応答なし（'+e.message+'）。記録済みサンプル：');console.log('モデル：アプリに天気のデータを取り込む。')}})()"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
例は形を見せてくれる
まず例をコピーして、動かします。これで、自分の環境が正しいと確かめられます。次に、パラメーターを1つずつ変え、そのたびにパラメーターの一覧で確かめます。
一覧には、型、範囲、デフォルトが書いてあります。範囲の外の値はエラーになるので、送る前に確かめましょう。
ページに照らして検査する
docker exec -w /home/node/project agent node -e "const spec={max_tokens:{min:1,max:4096},temperature:{min:0,max:2}};const check=(p)=>{const out=[];for(const k in p){if(spec[k]===undefined){out.push('不明：'+k);continue}if(k==='max_tokens'&&Number.isInteger(p[k])===false)out.push(k+' は整数にしてください');else if(p[k]<spec[k].min||p[k]>spec[k].max)out.push(k+' は '+spec[k].min+' から '+spec[k].max+' の間にしてください')}return out};for(const p of [{max_tokens:50},{max_tokens:5000},{max_tokens:2.5,temperature:3},{top:1}])console.log(JSON.stringify(p)+' -> '+(check(p).join('; ')||'ok'))"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
エラー表はすることを教える
良いエラー表は、ステータスの名前を挙げるだけではありません。呼び出しを直すのか、待つのか、後で試すのかを教えてくれます。
4xx のステータスは、たいてい、こちらが何かを変えます。5xx のステータスは、サービス側の問題なので、後でもう一度試します。
例：エラー表
| ステータス | 意味 | すること |
|---|---|---|
| 400 | ボディが間違っている | ボディを直す |
| 401 | キーがないか、間違っている | キーを確かめる |
| 403 | ここでは許可されていない | メッセージを読む |
| 429 | リクエストが多すぎる | 待ってから再試行する |
| 503 | サービスの準備ができていない | 後でもう一度試す |
学生が入力するセルは、このプレビューでは空白です。
エラー表でステータスを読む
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';const advice={200:'成功。ボディを読む',400:'ボディを直す',401:'キーを確かめる',403:'メッセージを読む',429:'待ってから再試行する',503:'後でもう一度試す'};(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:'こんにちはと言ってください。'}],max_tokens:10})});console.log('ステータス '+r.status+'：'+(advice[r.status]||'表にありません'));if(r.status>299)console.log('成功した呼び出しの記録済みサンプル：ステータス 200：'+advice[200])}catch(e){console.log('サービスから応答なし（'+e.message+'）。記録済みサンプル：');console.log('ステータス 429：'+advice[429])}})()"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
よくある間違い
注意
ドキュメントの例が、APIのすべてだと考える人が多くいます。例が見せるのは、呼び出し1つだけです。ほかに何を送れるかはパラメーターの一覧に、失敗したときの対応はエラー表にあります。3つとも読みましょう。