実験を記録し、サービスに組み込む

目安: 50分。演習の状態: 未実行 (not-run)。本文は学習ガイドであり、動作や品質の実測記録ではありません。

前提となる章: 画像・3DとローカルAIをつなぐ

独自の概念図。矢印は依存関係や判断の順序を示し、性能の実測を表さない。

1. 1固定課題と条件
2. 2measured・estimated・not-runの記録
3. 3品質・費用・遅延・権限の確認
4. 4採否判断
5. 5rollback計画

学習目標

• 実測・推定・未実行を明示した記録を残す
• 品質・費用・遅延・権限の四軸でリリースを判断する

仕事の役割

• 学習者: 仮説・データ・評価を設計する
• モデル: 指定した変換を試す
• アプリ: 制限・検証・権限を保証する

入力 → 工程 → 出力

入力	工程	出力
固定評価、モデル一式、runtime、予算・運用条件	測定→比較→ガードレール→段階的な運用確認	再現可能な実験台帳、採否判断、rollback手順

比較条件を揃える

モデル名だけの速度報告は再現できない。モデルIDとrevision、quantization、runtime版、hardware、入力token数、最大出力数、実際の出力数、context、同時数、batch、cold/warmを記録する。TTFT、prefill速度、decode速度、全体時間、ピークメモリはそれぞれ意味が違う。

測定は同じ入力セットで複数回行い、ばらつきも見る。最初のモデル読み込みとwarm状態を混ぜない。GPU処理が非同期のframeworkでは同期や公式計測方法を確認し、Pythonの関数呼び出し時間だけをGPU処理時間とみなさない。

Transformersのcache文書 はメモリと待ち時間のトレードオフを説明し、Ollama FAQ はruntimeやネットワーク設定の確認に使う。ワークシートには実際の観察条件を記録し、提供元の対応機能と本教材の動作実測を混同しない。

三つの状態を明示する

measuredは実際にその条件で測った値、estimatedは式・単価・仮定から求めた値、not-runはまだ試していない計画である。空欄を0で埋めると「費用ゼロ」「メモリゼロ」と誤読されるのでnullにする。本教材の例示コードはnot-run、容量の計算例はestimatedである。

費用には通貨、取得日時、課金単位、含めた項目を付ける。API token数とGPU時間は直接同じものではなく、モデルとhardwareで実際のthroughputを測って初めて比較の材料になる。品質基準に合格した処理件数も分母として記録する。

開発用推論を運用へ進める条件

backendに最大入力・最大出力・timeout・同時数・rate limitを設定する。JSONはparseできるだけでなくschemaと値を検証し、失敗時には再試行の回数を制限する。モデルが返したツール呼び出しは、アプリ側で権限と引数を検査してから実行する。

生成ログは機密を最小限にし、保存期間とアクセスを決める。異常時にモデル版を戻せるよう、base、adapter、tokenizer、prompt、検索index版をまとめて管理する。モデル差し替えはコード変更と同様に固定評価と段階的な確認を通す。

完成の基準を持つ

卒業制作は「架空製品の日本語用語検索・根拠付き回答」でよい。小型モデル、公開または自作の資料、RAG、必要ならadapterを比較し、どこまでできて何ができないかを説明する。高性能モデルを動かしたことより、失敗を再現し改善策を選べることを目標にする。

停止条件は予算超過だけではない。権利不明のデータ、重大な誤り、測定不能な状態、再現できない変更が見つかったら範囲を戻す。サービスにAIを入れる判断は、モデル単体の点数ではなく利用者への効果と失敗時の回復方法まで含めて行う。

自分で進める工程

1. 基準となる実験条件を保存する
2. 実測・推定・未実行を区別する
3. 品質の最低条件と停止条件を決める
4. latencyとメモリを同時数ごとに測る
5. 権限・ログ・rollbackを確認する

品質を確認する

• 実測・推定・未実行を明示した記録を残す
• 品質・費用・遅延・権限の四軸でリリースを判断する
• 未実測の欄がnullで残り、結論が検証した用途の範囲に収まっているか

失敗を切り分ける

注意すること	具体的な確認方法
一回の最速値だけでサービスの速度を宣伝しない	課題を固定して繰り返し、初回・ウォーム時の条件、待ち時間の分布、試行数を示す。
モデルの回答をそのまま外部操作の許可として扱わない	実行権限はアプリ側で管理する。対象を検証し、必要な承認を経て操作する。

演習: 実験を記録し、サービスに組み込む

状態: 未実行 (not-run)。

小型モデル単体とRAG付きの二条件で、同じ架空製品QAを比較する

提出するもの: 品質・速度・メモリ・費用・失敗例を含む採否メモ

完了の確認: 未実測の欄がnullで残り、結論が検証した用途の範囲に収まっているか

実験記録用ワークシートに計画・条件・観察を記録する。未測定値は null とし、推定値は式と仮定を残します。

共通の測定プロトコル

状態	意味
measured	実際に指定条件で測定した値
estimated	式・仮定・公開仕様から推定した値
not-run	まだ実行していない計画。数値はnull

比較で固定する条件

• 入力と評価セットを固定
• coldとwarmを分離
• 同時数を固定
• 複数回の分布を報告
• 単位と式を表示
• 機密をログへ残さない

台帳に必ず残す項目

キー	未実行の教材例
status	not-run
measuredAt	null（未測定・未確定）
modelId	Qwen/Qwen2.5-0.5B-Instruct
modelRevision	null（未測定・未確定）
tokenizerRevision	null（未測定・未確定）
adapterId	null（未測定・未確定）
runtime	transformers
runtimeVersion	null（未測定・未確定）
hardware	null（未測定・未確定）
os	null（未測定・未確定）
quantization	none
inputTokens	null（未測定・未確定）
maxOutputTokens	64
actualOutputTokens	null（未測定・未確定）
contextLimit	512
concurrency	1
batchSize	1
coldOrWarm	null（未測定・未確定）
ttftSeconds	null（未測定・未確定）
decodeTokensPerSecond	null（未測定・未確定）
totalSeconds	null（未測定・未確定）
peakMemoryGB	null（未測定・未確定）
cost	下の内訳を記録
quality	下の内訳を記録
notes	教材例。実行・計測していない。

費用・品質の内訳

キー	初期値
cost.status	not-run
cost.amount	null（未測定・未確定）
cost.currency	null（未測定・未確定）
cost.unit	null（未測定・未確定）
cost.gpuHours	null（未測定・未確定）
cost.inputTokens	null（未測定・未確定）
cost.outputTokens	null（未測定・未確定）
cost.includes	なし（未設定）
quality.testSetVersion	null（未測定・未確定）
quality.passed	null（未測定・未確定）
quality.total	null（未測定・未確定）
quality.criticalErrors	null（未測定・未確定）

この例には計測結果がありません。modelId、生成上限、context、同時数などは予定条件です。null は未知であり、ゼロを意味しません。

実験記録用ワークシート

次の計画を手元のJSONファイルへコピーする。実行前にモデルとpackageのrevisionを埋め、待ち時間・メモリ・token使用量・費用は観察するまで null のままにする。評価セットの版と元の出力を付け、試行ごとに別の記録を保存する。このページは記録形式を示し、観察結果を自動保存する機能ではない。

contextLimit はchat templateのtokenを含む入力と出力の合計予算である。この計画は合計512token、出力上限64なので、tokenize後の入力を448以下にする。前のCPU例は入力単体の上限を512としている。その上限を、この小さな合計予算へそのまま流用しない。

{
  "status": "not-run",
  "measuredAt": null,
  "modelId": "Qwen/Qwen2.5-0.5B-Instruct",
  "modelRevision": null,
  "tokenizerRevision": null,
  "adapterId": null,
  "runtime": "transformers",
  "runtimeVersion": null,
  "hardware": null,
  "os": null,
  "quantization": "none",
  "inputTokens": null,
  "maxOutputTokens": 64,
  "actualOutputTokens": null,
  "contextLimit": 512,
  "concurrency": 1,
  "batchSize": 1,
  "coldOrWarm": null,
  "ttftSeconds": null,
  "decodeTokensPerSecond": null,
  "totalSeconds": null,
  "peakMemoryGB": null,
  "cost": {
    "status": "not-run",
    "amount": null,
    "currency": null,
    "unit": null,
    "gpuHours": null,
    "inputTokens": null,
    "outputTokens": null,
    "includes": []
  },
  "quality": {
    "testSetVersion": null,
    "passed": null,
    "total": null,
    "criticalErrors": null
  },
  "notes": [
    "教材例。実行・計測していない。"
  ]
}

手元の実験台帳を使う

ブラウザー内の実験台帳を開く。まず計画を記録し、不明な値は空欄にする。実行済みとして保存するには出力の証拠が必要。この台帳はモデルを実行せず、記録をアップロードしない。上の記録表を別の文書として使ってもよい。