KubernetesでAIを構築:原資料からトークン生成APIまで
データ、学習、チェックポイント、公開、推論の全経路。実行済みCPU教材、任意GPT-2学習、Kubernetes設定とGPUの境界を収録。
出典とバージョン
この記事の目次
構成と責任の境界
| 段階 | 入力 → 出力 | 責任と障害境界 |
|---|---|---|
| 取り込み | 記録 → 不変スナップショット | データ担当:無許可・不正形式を隔離し記録する。 |
| 前処理 | 快照 → 分割定義と分詞器 | データ工程:形式・近似重複・漏洩境界。再試行で分割を変えない。 |
| 学習 | 版付きデータと設定 → checkpoint | 学習担当:全rankを一緒に復元。不完全な保存を選ばない。 |
| 公開 | 候補と根拠 → 承認版 | モデル担当:拒否で現行版を置換せず、判定版を記録。 |
| 推論提供 | 承認重み・分詞器 → 準備済み副本 | 基盤:検証後にロード・準備し、失敗副本へ流さない。 |
| 要求 | 認証済み入力と予算 → ストリーム | ゲートウェイ・エンジン:列・期限・取消を制御。観測済み出力を再生成しない。 |
ツールより先にサービスの契約を定める
版管理した資料から学習する私有テキスト補完サービスを構築します。オフラインでは許可済み記録からデータ、分詞器、学習、チェックポイント、承認版を作ります。オンラインでは認証、予算確認、分詞、実行、生成トークン返却を行います。Kubernetesはプロセスを配置しますが、品質や権限を自動保証しません。
配布キットは小さな学習済みbigramモデルで全経路を接続します。学習、厳密な再開、制品検証、HTTP、ストリームをローカル実行しました。二層GPT-2学習コードとvLLM参考設定もありますが未実行です。ここにはDocker、クラスタ、GPUがありません。CPU教材と実運用GPU基盤を区別し、小モデルを実用助手とは呼びません。
記録d17を追います。原資料R1→変換C2→データD3→分詞器T1→実行J4→保存K400→出力M1です。公開R7はM1・T1・イメージdigest・生成上限を結びます。要求q9は開始時に別名をR7へ一度だけ解決します。制御面は望ましい版と方針を変更し、データ面はバイトを運び計算します。登録庫は参照と根拠を保存し、GPUプロセスではありません。Serviceは副本へ接続し、チェックポイントへは接続しません。別名変更と展開完了は異なります。
先修知識を障害の説明につなげる
イメージはコードとライブラリを含みますが、互換なホストGPUドライバまでは含みません。Podは実行単位、Jobは完了管理、Deploymentは複製維持、Serviceは宛先選択です。PVCのアクセス方式や配置制約も重要です。データ位置や最適化状態なしの再起動は学習の復旧ではありません。
tokenは特定分詞器の整数、logitsはスコア、softmaxは確率、交差エントロピーは損失です。学習は重みを更新し、推論は固定重みを使います。再開可能な保存状態は推論用出力より多くの情報を含みます。一貫性、HTTP、TLS、認証、指標が正しいモデルと利用者を結びます。
kubectlのJobはAPI serverで認証・認可・准入を経て保存されます。制御器がPodを作り、schedulerが資源要求・制約・巻の位置からノードを選びます。kubeletはruntimeに起動を頼み状態を報告します。device pluginはGPU、CSIは巻を扱い、最適化器はコンテナ内で動きます。Runningでもロード中の場合があり、通常のService対象は別のreadinessで決まります。startup probeは初期化中の早すぎる再起動を防ぎ、readiness失敗自体は再起動しません。
取り込み:学習窓より先に記録を固定する
各資料にID、許可、取得時刻、ハッシュ、保存規則を付け、原本と清掃コードの版を記録します。表、コード、境界を保ち、完全重複と近似重複を分けます。重なる窓を作る前に資料・利用者・時刻で分割し、検証への漏えいを防ぎます。ハッシュ分割だけでは関連資料をまとめられません。
キットは独自CC0合成JSONLの空白正規化、完全重複除去、ハッシュ分割を行います。実運用には個人情報、同意、隔離、資料バランス、派生物への削除伝播が必要です。目録は血縁を記録しても学習許可を決めません。オブジェクト削除は重みの忘却ではなく、再学習が必要な場合があります。
原資料のoffsetは、定義した手順で不変オブジェクトとmanifestを永続化してから確認します。再試行は同じ内容アドレスへ書けますが、変換版が違えば派生IDも変えます。ハッシュは同意・品質・意味の類似を証明しません。近似重複をまとめてから群単位で分割します。hash mod 5の検証率は期待値20%であり、有限資料で厳密20%ではありません。原本100 GBと派生60 GBだけで最低160 GBです。分片のストリームはメモリを制限しますが、圧縮・サイズ・順序がCPUと読み増幅を決めます。
分詞器、パッキング、学習契約
版には語彙、正規化、特殊ID、必要ならチャットテンプレートを含めます。別の分詞器は入力IDを静かに変えます。Transformer例は訓練側だけでバイトBPEを学びEOSを付け、パディングを損失から除きます。資料を詰める際は注意が資料境界を越えてよいか決めます。
IDと教師ラベルはB×T、logitsはB×T×Vです。因果モデルは次tokenを予測します。使用モデルは内部で教師ラベルをずらすため、入力IDを複製しpaddingを−100とし、ローダで再度ずらしません。検証も同じ契約で有効token数によって重み付けします。
仮の例で“AI helps”を[17,42]、EOSを1とします。[17,42,1]から17→42と[17,42]→1を学びます。教材の実IDではありません。B4・T128・V512ならlogitsは262144個、FP32で1 MiBです。embeddingでB×T×dへ写し、位置で順序を表します。文書の梱包では後文書が前文書を見てよいか決めます。EOSは自動的な注意力境界ではなく、損失と注意力のpadding遮蔽も別操作です。
学習で実際に計算するもの
前向き計算で埋め込みと因果層からlogitsを作り、損失は次tokenの低確率を罰します。逆伝播が導関数を計算しAdamWがモーメントと重みを更新します。勾配蓄積には損失の尺度調整が必要です。微小バッチ2×蓄積8×データ並列4は64系列ですがtoken数まで同じとは限りません。
実測例は直前文字だけに依存するV×V表を学びます。自回帰学習ですが注意機構はありません。任意のGPT-2例は2層4頭幅128で、包装工程の教材です。事前学習、SFT、選好学習、RLでは資料や参照モデル、資源の使い方が異なり、rollout提供と最適化Jobは別の仕事です。
損失のbは系列、tは次トークン位置、mは有効目標で1・paddingで0、N_validはmの総和です。B_microは副本あたり系列数、Aは累積回数、Dはデータ並列数です。有効トークン数が異なると微バッチの等重み平均はトークン平均になりません。
一つの因果headはT×d_modelのXからQ・K・Vを作ります。QKᵀはT×Tで、未来位置を−∞にして行softmax、Vを掛けてT×d_hを得ます。出力投影・残差は幅を保ち、FFNは位置ごと、attentionは位置間を処理します。逆伝播は連鎖則です。[0,0]のlogitsと目標1なら確率[0.5,0.5]、損失0.6931、勾配[0.5,−0.5]です。SGD0.1で[−0.05,0.05]になり損失約0.6444へ減ります。AdamWは二つのモーメントと初期偏り補正、独立の重み減衰を使うため、重みだけの復元では次の更新が変わります。
Mは許可0・未来−∞のmask、d_hは幅、z_jはlogit、yは目標IDです。AdamWのg_tは勾配、β₁/β₂は係数、ηは学習率、λ_wは減衰、εは安定化です。平方は要素別で、偏り補正あり・AMSGradなしの一般式です。精度や実装で数値が変わります。
並列化とスケジューリングを区別する
データ並列は複製と勾配同期、テンソル並列は層内分割、パイプラインは層分割、shardingは状態分割です。混合精度Adamの一例では活性値を除き16byte/parameter程度で、7Bなら112GB。BF16推論重み14GBとは違い、普遍的な実装値でもありません。
rank間でworld size、接続、集団通信順序を揃えます。互聯が同期費用を左右します。Kueue型准入は配額、gang配置は一部workerだけの占有を扱い、勾配算法とは別です。rank障害には時間制限と協調終了、完全な保存点からの再開が必要です。Deployment複製増加は分散学習器にはなりません。
同じ局所batchなら各副本のg_rをall-reduceで合計しDで割ります。有効token数が違う場合は全体token数で重み付けします。理想ringのrank当たり転送は2(D−1)G/D bytesです。D4・G8 GBなら12 GB、25 GB/sでも帯域下限0.48秒です。張量並列は層内通信が頻繁で高速リンク向きです。ZeROは最適化状態・勾配・パラメータを順に分片し、通信とメモリを交換します。pipelineは空泡も生じ、stage増加が高速化を保証しません。
Gは副本の勾配bytes、Dはrank数、B_netは有効bytes/sで十進単位です。全体時間でなく下限です。
二つのライフサイクルに合わせて資源を選ぶ
有限の準備・学習にはJob、継続推論にはDeployment、内部名にはServiceを使います。CPU準備とGPU学習、低遅延推論の資源・優先度を分け、CPUとRAMも確保します。driver、runtime、pluginがGPUを割当可能にします。GPU制限を過剰割当してもメモリは増えません。
キットはnamespace、RWO巻、Job、Deploymentを使います。読取専用とハッシュで不完全制品を拒否し、単純化のためRecreateの停止を受け入れます。実運用は不可変承認オブジェクトを各Podへ独立配置し、完全ロード後にreadyにします。ストレージとGPUの配置可能領域を揃えます。
CPU request1は配置予約、limit2はruntime/cgroupによる実行制限です。memory requestは配置に使い、limit超過はOOMになりえます。GPU資源は空きVRAM bytesでなく装置数です。Pendingでは装置・affinity・巻を切り分け、起動後CUDA失敗ではdriver/runtime/権限を調べます。RWOは一ノードでの読み書きであり、一Pod限定でもノード間共有FSでもありません。教材の巻は分散データサービスではありません。
チェックポイント、候補、公開版を分ける
再開点には重み、最適化・scheduler状態、step、乱数、データ版と位置を保存します。分片を一時領域へ書き、揃ってから完了印を公開します。object storeは複数書込を原子的にはしません。読取側は完全な目録だけを選びます。
推論出力は架構、分詞器、adapter、精度、ハッシュ、許可を残し学習状態を省きます。登録庫は制品と承認の目録です。公開版は候補・イメージ・設定を環境ごとに結び、復旧はモデル名だけでなく互換な組合せ全体を戻します。
一意なshardを書き、hashを計算し、全サイズ・hashのmanifestを作ります。完全性確認後に条件付き書込で最新完全版ポインタを更新します。読者はmanifestを検証し、一覧で版を推測しません。その前の障害はゴミを残すだけです。教材の一時ファイル+renameは部分ファイル露出を防ぎますが、停電耐久性はFS・directory syncにも依存します。有効ファイルと良質モデルは別で、rollbackでも送信済みtokenは撤回できません。
モデルファイルから最初と次のtokenへ
readyになる前に制品検証、重みロード、バッファ確保、kernel初期化、代表形状の予熱をします。prefillはpromptからKVを作り、decodeは再利用して生成します。連続バッチは効率を上げますが公平性と取消が必要です。分詞、待ち行列、通信bufferも初token時間に影響します。
KV概算は2×層×KV頭×頭次元×byte×常駐tokenです。32層8KV頭128次元BF16なら131,072byte/token、8,192tokenで1GiBに付加費用が加わります。GQAのKV頭とquery頭を混同しません。重みが入っても文脈が入るとは限らず、重みとKVの量子化も別です。
Lは層数、H_KVはKVヘッド数、d_hは幅、bはスカラーのバイト数、T_iは系列iの常駐トークン数です。2はkeyとvalueです。分配器の費用は含まず、潜在注意力・圧縮キャッシュにはそのまま適用できません。
PrefillはT位置を計算して層ごとにK/Vを保存します。Decodeはqueryを一つ追加し、古いK/Vを再計算せず増えるcacheを読みます。密なprompt相互作用は概ね二乗、decode一歩は文脈に線形で、投影・FFNは別です。ページKVは論理blockを物理blockへ写します。block16、長さ17と31なら64slot中16未使用、各128予約なら256slotです。速度測定ではありません。prefix共有はモデル・分詞・位置・設定の一致と安全な参照数管理が必要です。
Pはblock当たりtoken数、T_iは長さです。各系列をblock単位へ切り上げ、prefix共有・metadataは除外します。
APIを制御された状態機械として扱う
client→TLS→認証・方針→配額・准入→router→私有推論→streamと進みます。GPU使用前に本文量、モデル権限、分詞後長さ、出力予約を確認します。request IDで追跡し、aliasは一要求中同じ版を指します。
streamは増分イベントです。bufferと期限を揃え、開示後の再試行による重複文や課金を防ぎます。再試行は開示前に限定するか再開契約を定めます。切断をengineへ伝えKVと枠を解放し、生成されたtool提案を取引の権限と混同しません。
利用者が送るtenantを信用せず資格を検証します。主体を許可モデル・予算へ写し、その分詞器で入力+予約出力が文脈以内か確認します。容量を予約し実使用で精算します。SSEは空行で区切り、TCP断片を利用者側で蓄積します。HTTP成功後も生成は失敗しうるため両方の終了状態を記録します。EOS・上限・期限・取消で止めます。温度によるlogits調整は事実性の保証ではありません。
容量、伸縮、公開費用
GPU率だけでなく待ち数・時間、系列数、token、KV、初token・token間時間で伸縮します。Little則は安定時の平均であり飽和時の裾を予測しません。10件/秒×2秒=20件ですがメモリは文脈にも依存します。
起動には配置、ダウンロード、ロード、予熱が必要でHPAは消せません。余裕を予約し待ち行列を制限します。canaryは同等分布で比較します。PDBは自発的中断を制限するだけです。drainで新規准入を止め有界streamを終えます。単一GPU Recreateには停止があり、遊休・公開用容量も費用に含めます。
TTFTを入口・認証分詞・待機・prefill・転送へ分けます。例20+10+80+150+10=270 msです。prefillを30 ms減らしても数秒の列は直りません。batchで全体速度が上がっても個人待ちが増えます。教材M/M/1では
全段階の安全性と可観測性
取り込み、学習、承認、提供のidentityを分けます。提供Podは承認制品を読み、自己昇格や資料変更をしません。短期資格情報、出網制限、監査を使い、不要なKubernetes tokenを載せません。NetworkPolicyはCNI依存でAPI利用者認証ではありません。
データhash、run、保存点、公開版、image、requestを結び、拒否、throughput、loss、保存時間、GPU故障、待ち、token、取消を測ります。promptや任意IDを指標labelにすると高cardinalityと漏えいを招きます。traceは制限・保存期限を設けます。観測欠落は無故障ではなく可用性も正確性とは別です。
権限は別に追跡します。trainerはD3読取・自run書込、公開制御器が承認、提供主体は承認版読取だけです。labelはtenant認証ではありません。NetworkPolicyは接続、IAMはオブジェクト操作を制御します。queue/prefill/decode span、受理拒否counter、遅延histogram、容量gaugeを集めます。IDは採樣traceやexemplarに置き、無限labelにしません。版を応答に記録します。span欠如は採樣・欠落・未完了でも起こります。
制御点と制約から構成を選ぶ
cloudはnode、保存、identityを提供しても、データ契約と承認はチームが持ちます。NVIDIAはdevice、PyTorchは学習、Kubernetesは調停、vLLMは提供とKVに近い役割です。registryは目録、object storeはbytes、gatewayは外部准入です。dashboardで公開権限を代替しません。
prefill/decode分離、KV転送、prefix routing、offloadは効率と引換えに通信や取消状態を増やします。adapter、量子化、推測生成も隔離・校正・計算を足します。まず単機の不変条件と律速を確認します。可搬性能、公平性、監査可能な削除、長文脈品質、大規模復旧は未解決です。
最適化が移す資源を見ます。量子化は重み・精度を減らしますが校正・kernelが必要でKVも自動的に減りません。prefix cacheは意味類似でなく互換な共通prefixが条件です。prefill/decode分離ではKV転送が増え、1 GiBを10 GiB/sで運ぶだけで最低0.1秒です。投機decodeは草稿と検証が必要で採択率・検証費用が重要です。各手法の元の瓶頸、移した作業、新障害、単純案が勝つ条件を説明します。
実装と検証
1. CPUの全経路を実行
Python 3.11の独立環境で解凍先へ移動します。100件の独自CC0合成記録は配管確認用で、実用コーパスではありません。正規化・重複除去・ハッシュ分割を行ってからペアを作ります。種42、SGDで次文字の交差エントロピーを最小化します。Attentionはなく、NLL<4の門限は教材専用です。
python3.11 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python pipeline.py prepare --source corpus.jsonl --root ./run
python pipeline.py train --root ./run --steps 400
python pipeline.py promote --root ./run
python serve.py --root ./run --port 8000# In another terminal
curl -s http://127.0.0.1:8000/health
curl -s http://127.0.0.1:8000/v1/completions -H 'Content-Type: application/json' \
-d '{"prompt":"A model","max_tokens":16}'
curl -N http://127.0.0.1:8000/v1/completions -H 'Content-Type: application/json' \
-d '{"prompt":"A model","max_tokens":16,"stream":true}'2. CPU版をビルド・配置
Docker、kubectl、fsGroup対応の既定StorageClass、NetworkPolicy対応CNIが必要です。kindはローカル像をロードでき、他クラスタはレジストリへpushして二箇所のimageを変えます。restricted、UID10001、API tokenなし、私有Serviceです。単一RWOとRecreateは可用性より単純さを優先します。初回承認前の再起動は想定内ですが本番は順序制御します。公開しないでください。
docker build -t tokenlab-ai:local .
# For kind only; otherwise push image to your registry and edit YAML
kind load docker-image tokenlab-ai:local
kubectl apply -f kubernetes.yaml
kubectl -n tokenlab-ai wait --for=condition=complete job/train-v1 --timeout=600s
kubectl -n tokenlab-ai rollout status deployment/model-v1 --timeout=300s
kubectl -n tokenlab-ai port-forward service/model-api 8000:8000
# Then run the curl commands above; Ctrl-C stops the local tunnel.3. 実際のTransformer学習へ移る
任意経路は学習記録のみでbyte-BPEを学び、ランダム初期化の二層GPT-2を学習します。4ヘッド、幅・文脈128、AdamW 3e-4です。paddingラベルは-100、ラベル移動はGPT-2内部なので二重に行いません。最適化器・RNGを保存し、safetensors・分詞器・設定を出力、トークン重み付き検証NLLの承認後にapproved/を作成します。既存版は上書きしません。この経路は未実行です。
# Separate environment recommended; optional path not executed here
pip install -r requirements-transformer.txt
python transformer.py --root ./run --steps 200
python transformer.py --root ./run --steps 400 --resume
python approve_transformer.py --root ./run --max-nll 4.0
# Optional training Job (existing namespace/PVC required)
docker build -f Dockerfile.transformer -t tokenlab-transformer:lab .
kind load docker-image tokenlab-transformer:lab
kubectl -n tokenlab-ai scale deployment model-v1 --replicas=0
kubectl apply -f transformer-job.yaml
kubectl -n tokenlab-ai wait --for=condition=complete job/transformer-train --timeout=7200s4. GPU推論:別途検証する統合
任意Jobは同じartifacts PVCを使います。ノード間RWO競合を避けCPU Deploymentを停止します。vLLMは承認済みモデルと私有Serviceを使用します。0.14.0の対応表にGPT2LMHeadModelはありますが、この出力は未検証です。UID、キャッシュ、安全設定をrestrictedに適合させ、方針を緩めません。互換ドライバ・device plugin・GPU・接続可能なストレージが必要です。
実測、失敗例、公平な比較
CPU教材の初期NLLは3.73767 nat/token、400ステップ後1.70074、検証1.70306でした。bigramの損失でありTransformerのベンチマークではありません。連続400と再開200+200のバイト一致、HTTP/SSE終了、不正予算、制品改変を確認します。各自で再現し、ベンダー比較には使わないでください。
python verify.py
python mechanism_math.py
# PASS: loss descent, exact resume, artifact integrity, HTTP generation, SSE, invalid inputクラスタでは学習中断、候補改変、未知文字、同時実行枯渇、SSE切断、readiness失敗を試します。データ、分詞器、精度、長さ、到着履歴、ハードを固定し、待機・TTFT・トークン間遅延・失敗・費用・品質を併記します。速い失敗は改善ではありません。単一副本では無停止切替を実証できません。
独自面接演習 · 企業の実際の出題ではありません
1. 重みを復元しても再開結果が変わる理由は?
ヒント1
Adamと次のバッチを考える。
ヒント2
RNG、モーメント、scheduler、データ位置、並列構成が次の更新を変える。
回答と分析
推論出力と再開チェックポイントは別物です。データ指紋、最適化器、RNGを復元し、厳密一致か統計的一致かを定義します。異なるGPU間の厳密一致は保証されません。連続実行と中断実行を比較します。
採点:1 名称、2 状態説明、3 障害追跡、4 正しい復元と限界、5 公平な反例と取捨選択の説明。
2. 14 GBモデルが24 GB GPUで失敗する理由は?
ヒント1
重みはメモリの一部だけ。
ヒント2
KV、作業領域、予約、断片化を含める。
回答と分析
32層・KV8ヘッド・幅128・BF16で128 KiB/token。8192トークンを8系列でKVだけで8 GiBです。14十進GBの重み以外の余裕は小さいためトークン准入制限とピーク計測が必要です。重み量子化とKV量子化は別です。
採点:1 名称、2 状態説明、3 障害追跡、4 正しい復元と限界、5 公平な反例と取捨選択の説明。
3. 最初のトークン送信後に再試行すべきか?
ヒント1
利用者は出力を見たか?
ヒント2
再生成で重複・変化・二重課金が起こりうる。
回答と分析
観測済みストリームを透明に再生成しません。中断を通知し、同一イベントを再送する再開プロトコルがなければ利用者が新規要求を出します。出力前の再試行も期限内で制限します。切断時は計算とKVを解放します。IDだけで冪等性は得られません。
採点:1 名称、2 状態説明、3 障害追跡、4 正しい復元と限界、5 公平な反例と取捨選択の説明。
完全な実装ファイル(コード注釈は英語)
mechanism_math.py
"""Deterministic checks for the article's synthetic arithmetic. Standard library only.
No cluster, model benchmark, GPU, network or stochastic experiment.
"""
import math
p0=0.5
loss0=-math.log(p0)
loss1=math.log(math.exp(-0.05)+math.exp(0.05))-0.05
assert abs(loss0-0.69314718056)<1e-10
assert abs(loss1-0.64439666007)<1e-10 and loss1<loss0
# First AdamW moment correction with a scalar gradient.
g=0.5;beta1=0.9;beta2=0.999
m=(1-beta1)*g;v=(1-beta2)*g*g
assert math.isclose(m/(1-beta1),g)
assert math.isclose(v/(1-beta2),g*g)
assert 4*128*512*4==1024**2
assert 2*(4-1)*8/4/25==0.48
slots=16*sum(math.ceil(t/16) for t in [17,31])
assert slots==64 and slots-17-31==16
assert 2*32*8*128*2*8192==1024**3
assert sum([20,10,80,150,10])==270
assert 1/(10-8)==0.5 and 1/(10-9.5)==2
print('PASS: gradient step, AdamW bias correction, logits bytes, ring budget, KV blocks, TTFT and queue arithmetic')
pipeline.py
"""Transparent language-model lifecycle. Python 3.11 + numpy 2.3.5.
The model is a learned bigram softmax, not a Transformer or general assistant.
"""
import argparse, hashlib, json, os, tempfile
from pathlib import Path
import numpy as np
def digest(b): return hashlib.sha256(b).hexdigest()
def atomic(path, data):
path=Path(path); path.parent.mkdir(parents=True,exist_ok=True)
fd,tmp=tempfile.mkstemp(dir=path.parent)
with os.fdopen(fd,'wb') as f: f.write(data); f.flush(); os.fsync(f.fileno())
os.replace(tmp,path)
def prepare(source,out):
records=[json.loads(x) for x in Path(source).read_text().splitlines() if x.strip()]
seen=set(); groups={'train':[],'validation':[]}
for r in records:
if r.get('license')!='CC0' or not isinstance(r.get('text'),str): raise ValueError('unsupported rights/schema')
text=' '.join(r['text'].split())
if not text: raise ValueError('empty text')
h=digest(text.encode())
if h in seen: continue
seen.add(h)
# Split before windows; one source record never crosses splits.
groups['validation' if int(h[:8],16)%5==0 else 'train'].append({'id':r['id'],'text':text,'sha256':h})
if not all(groups.values()): raise ValueError('both splits required')
payload=json.dumps(groups,sort_keys=True).encode()
atomic(Path(out)/'dataset.json',payload)
atomic(Path(out)/'data-manifest.json',json.dumps({'sha256':digest(payload),'source_sha256':digest(Path(source).read_bytes()),'split':'content-hash modulo 5','counts':{k:len(v) for k,v in groups.items()}},indent=2).encode())
return groups
def pairs(records,vocab):
lookup={c:i+2 for i,c in enumerate(vocab)}; xs=[];ys=[]
for r in records:
ids=[0]+[lookup[c] for c in r['text']]+[1]
xs.extend(ids[:-1]);ys.extend(ids[1:])
return np.array(xs),np.array(ys)
def loss(w,x,y):
z=w[x]; z=z-z.max(axis=1,keepdims=True)
return float(np.mean(np.log(np.exp(z).sum(axis=1))-z[np.arange(len(x)),y]))
def train(root,steps=400,resume=False):
root=Path(root); raw=(root/'dataset.json').read_bytes();ds=json.loads(raw)
# Vocabulary belongs to training data. Fixture is ASCII; production needs UNK policy.
vocab=sorted(set(''.join(r['text'] for r in ds['train'])))
if any(c not in vocab for r in ds['validation'] for c in r['text']): raise ValueError('validation has unknown characters')
x,y=pairs(ds['train'],vocab); vx,vy=pairs(ds['validation'],vocab)
rng=np.random.default_rng(42);w=np.zeros((len(vocab)+2,)*2);start=0
cp=root/'checkpoint.npz'
if resume and cp.exists():
with np.load(cp,allow_pickle=False) as c:
if str(c['data_hash'])!=digest(raw): raise ValueError('dataset changed during resume')
w=c['weights'];start=int(c['step']);rng.bit_generator.state=json.loads(str(c['rng']))
initial=loss(w,x,y)
for step in range(start,steps):
ix=rng.integers(0,len(x),size=128); xx=x[ix];yy=y[ix]
z=w[xx];z-=z.max(axis=1,keepdims=True);p=np.exp(z);p/=p.sum(axis=1,keepdims=True)
p[np.arange(len(xx)),yy]-=1;g=np.zeros_like(w);np.add.at(g,xx,p/len(xx));w-=3*g
if (step+1)%50==0 or step+1==steps:
import io
buf=io.BytesIO();np.savez(buf,weights=w,step=step+1,rng=json.dumps(rng.bit_generator.state),data_hash=digest(raw));atomic(cp,buf.getvalue())
model={'architecture':'bigram-softmax-v1','vocab':vocab,'weights':w.tolist(),'data_sha256':digest(raw),'steps':steps,'seed':42}
modelraw=json.dumps(model,separators=(',',':')).encode();atomic(root/'model.json',modelraw)
metrics={'initial_train_nll':initial,'train_nll':loss(w,x,y),'validation_nll':loss(w,vx,vy),'model_sha256':digest(modelraw),'steps':steps}
atomic(root/'metrics.json',json.dumps(metrics,indent=2).encode());print(json.dumps(metrics));return metrics
def promote(root):
root=Path(root);m=json.loads((root/'metrics.json').read_text()); raw=(root/'model.json').read_bytes()
if digest(raw)!=m['model_sha256'] or not np.isfinite(m['validation_nll']) or m['validation_nll']>=4: raise ValueError('release gate failed')
# This threshold only validates the declared teaching fixture, not language quality.
atomic(root/'release.json',json.dumps({'model_sha256':digest(raw),'data_sha256':digest((root/'dataset.json').read_bytes()),'artifact':'model.json','gate':'fixture validation NLL < 4; not a safety evaluation'},indent=2).encode())
if __name__=='__main__':
p=argparse.ArgumentParser();p.add_argument('action',choices=['prepare','train','promote']);p.add_argument('--root',default='/work');p.add_argument('--source',default='corpus.jsonl');p.add_argument('--steps',type=int,default=400);p.add_argument('--resume',action='store_true');a=p.parse_args()
if a.action=='prepare': prepare(a.source,a.root)
elif a.action=='train': train(a.root,a.steps,a.resume)
else: promote(a.root)
serve.py
"""Local/private teaching API; no public ingress, TLS or identity provider."""
import argparse, hashlib, json, threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
import numpy as np
def load(root):
root=Path(root);release=json.loads((root/'release.json').read_text());raw=(root/'model.json').read_bytes()
if hashlib.sha256(raw).hexdigest()!=release['model_sha256']: raise ValueError('artifact integrity mismatch')
return json.loads(raw),release['model_sha256']
def application(model,revision):
w=np.array(model['weights']);vocab=model['vocab'];lookup={c:i+2 for i,c in enumerate(vocab)};slots=threading.BoundedSemaphore(2)
class Handler(BaseHTTPRequestHandler):
def log_message(self,*args): pass # No prompts in request logs.
def respond(self,status,obj):
raw=json.dumps(obj).encode();self.send_response(status);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(raw)));self.end_headers();self.wfile.write(raw)
def do_GET(self):
self.respond(200 if self.path=='/health' else 404,{'model_revision':revision})
def do_POST(self):
if self.path!='/v1/completions': return self.respond(404,{'error':'not found'})
self.connection.settimeout(10)
try:
size=int(self.headers.get('Content-Length','0'))
if not 0<size<=8192: return self.respond(413,{'error':'body limit'})
body=json.loads(self.rfile.read(size))
if not isinstance(body,dict): raise ValueError('object required')
prompt=body.get('prompt','');limit=body.get('max_tokens',32)
if not isinstance(prompt,str) or len(prompt)>512 or type(limit)!=int or not 1<=limit<=128: raise ValueError('invalid prompt or token limit')
if any(c not in lookup for c in prompt): raise ValueError('unknown character')
if type(body.get('stream',False))!=bool: raise ValueError('stream must be boolean')
except (ValueError,TypeError,TimeoutError): return self.respond(400,{'error':'invalid request'})
if not slots.acquire(blocking=False): return self.respond(429,{'error':'capacity'})
try:
token=lookup[prompt[-1]] if prompt else 0;rng=np.random.default_rng(42);out=[]
if body.get('stream'):
self.send_response(200);self.send_header('Content-Type','text/event-stream');self.send_header('Cache-Control','no-cache');self.send_header('Connection','close');self.end_headers();self.close_connection=True
for _ in range(limit):
z=w[token].copy();z[0]=-np.inf;p=np.exp(z-np.max(z));p/=p.sum();token=int(rng.choice(len(p),p=p))
if token==1: break
out.append(vocab[token-2])
if body.get('stream'):
self.wfile.write(('data: '+json.dumps({'token':out[-1],'model_revision':revision})+'\n\n').encode());self.wfile.flush()
if body.get('stream'): self.wfile.write(b'data: [DONE]\n\n');self.wfile.flush()
else: self.respond(200,{'text':''.join(out),'completion_tokens':len(out),'model_revision':revision})
except (BrokenPipeError,ConnectionResetError,TimeoutError): pass
finally: slots.release()
return Handler
if __name__=='__main__':
p=argparse.ArgumentParser();p.add_argument('--root',default='/work');p.add_argument('--host',default='127.0.0.1');p.add_argument('--port',type=int,default=8000);a=p.parse_args()
model,rev=load(a.root);ThreadingHTTPServer((a.host,a.port),application(model,rev)).serve_forever()
transformer.py
"""Optional real GPT-2 architecture training path; not run by Token Lab.
Python 3.11, torch 2.6.0, transformers 4.51.3, tokenizers 0.21.1.
Reads the SAME prepared dataset.json; trains its own byte BPE tokenizer.
A tiny random model demonstrates mechanics, not useful assistant capability.
"""
import argparse,json,os,random
from pathlib import Path
import torch
from tokenizers import ByteLevelBPETokenizer
from transformers import GPT2Config,GPT2LMHeadModel,PreTrainedTokenizerFast
p=argparse.ArgumentParser();p.add_argument('--root',default='/work');p.add_argument('--steps',type=int,default=200);p.add_argument('--resume',action='store_true');a=p.parse_args()
root=Path(a.root);ds=json.loads((root/'dataset.json').read_text());torch.manual_seed(42);random.seed(42)
# CPU default for broad compatibility; set DEVICE=cuda for a provisioned GPU.
device=os.environ.get('DEVICE','cpu');tokenizer=ByteLevelBPETokenizer()
tokenizer.train_from_iterator((r['text'] for r in ds['train']),vocab_size=512,min_frequency=2,special_tokens=['<bos>','<eos>','<pad>'])
tok=PreTrainedTokenizerFast(tokenizer_object=tokenizer._tokenizer,bos_token='<bos>',eos_token='<eos>',pad_token='<pad>')
config=GPT2Config(vocab_size=len(tok),n_positions=128,n_ctx=128,n_embd=128,n_layer=2,n_head=4,bos_token_id=tok.bos_token_id,eos_token_id=tok.eos_token_id,pad_token_id=tok.pad_token_id)
model=GPT2LMHeadModel(config).to(device);optimizer=torch.optim.AdamW(model.parameters(),lr=3e-4)
rows=[tok(r['text'],max_length=126,truncation=True)['input_ids']+[tok.eos_token_id] for r in ds['train']]
import hashlib
fingerprint=hashlib.sha256((root/'dataset.json').read_bytes()).hexdigest();cp=root/'transformer-checkpoint.pt';start=0
if a.resume and cp.exists():
state=torch.load(cp,map_location='cpu',weights_only=True)
if state['data_hash']!=fingerprint: raise ValueError('dataset mismatch')
model.load_state_dict(state['model']);optimizer.load_state_dict(state['optimizer']);start=state['step'];torch.set_rng_state(state['cpu_rng']);random.setstate(state['python_rng'])
if device.startswith('cuda'): torch.cuda.set_rng_state_all(state['cuda_rng'])
model.train()
for step in range(start,a.steps):
chosen=random.choices(rows,k=4);width=max(map(len,chosen));ids=torch.full((4,width),tok.pad_token_id,dtype=torch.long,device=device);mask=torch.zeros_like(ids)
for i,row in enumerate(chosen): ids[i,:len(row)]=torch.tensor(row,device=device);mask[i,:len(row)]=1
labels=ids.clone();labels[mask==0]=-100
optimizer.zero_grad(set_to_none=True);loss=model(input_ids=ids,attention_mask=mask,labels=labels).loss
loss.backward();torch.nn.utils.clip_grad_norm_(model.parameters(),1);optimizer.step()
if (step+1)%50==0 or step+1==a.steps:
state={'model':model.state_dict(),'optimizer':optimizer.state_dict(),'step':step+1,'cpu_rng':torch.get_rng_state(),'python_rng':random.getstate(),'cuda_rng':torch.cuda.get_rng_state_all() if device.startswith('cuda') else [],'data_hash':fingerprint}
tmp=root/'checkpoint.tmp';torch.save(state,tmp);os.replace(tmp,cp)
print(json.dumps({'step':step+1,'training_loss':float(loss.detach())}))
export=root/'transformer-candidate';export.mkdir(exist_ok=True)
model.save_pretrained(export,safe_serialization=True);tok.save_pretrained(export)
# Candidate only: no release pointer is changed. Evaluate before promotion.
(export/'lineage.json').write_text(json.dumps({'data_sha256':fingerprint,'seed':42,'steps':a.steps,'status':'candidate-not-approved'}))
approve_transformer.py
"""Held-out next-token NLL gate for this synthetic fixture only. Not a safety gate.
Unexecuted optional Transformer path. Uses CPU; no paid APIs or uploaded data.
"""
import argparse,hashlib,json,math,os,shutil
from pathlib import Path
import torch
from transformers import AutoTokenizer, GPT2LMHeadModel
p=argparse.ArgumentParser();p.add_argument('--root',default='/work');p.add_argument('--max-nll',type=float,required=True);a=p.parse_args()
r=Path(a.root);src=r/'transformer-candidate';dst=r/'approved'
if dst.exists(): raise ValueError('use a fresh release directory; never overwrite a served artifact')
data=json.loads((r/'dataset.json').read_text());lineage=json.loads((src/'lineage.json').read_text())
assert lineage['data_sha256']==hashlib.sha256((r/'dataset.json').read_bytes()).hexdigest()
tok=AutoTokenizer.from_pretrained(src,local_files_only=True);model=GPT2LMHeadModel.from_pretrained(src,local_files_only=True).eval()
total=0.;n=0
with torch.no_grad():
for row in data['validation']:
ids=tok(row['text'],max_length=126,truncation=True)['input_ids']+[tok.eos_token_id]
x=torch.tensor([ids]);loss=model(input_ids=x,labels=x).loss.item()
total+=loss*(len(ids)-1);n+=len(ids)-1
nll=total/n
print(json.dumps({'validation_nll':nll,'tokens':n,'threshold':a.max_nll}))
if not math.isfinite(nll) or nll>=a.max_nll: raise ValueError('candidate rejected; approved version unchanged')
files={f.name:hashlib.sha256(f.read_bytes()).hexdigest() for f in src.iterdir() if f.is_file()}
staging=r/'approval-staging'
if staging.exists(): shutil.rmtree(staging)
shutil.copytree(src,staging)
(staging/'release-manifest.json').write_text(json.dumps({'files':files,'validation_nll':nll,'gate':'synthetic fixture only','data_sha256':lineage['data_sha256']},indent=2))
os.replace(staging,dst) # Atomic directory rename on this one filesystem, not object-store transaction.
verify.py
"""Actual local training/resume/integrity/API checks; no cluster required."""
import importlib.util,json,tempfile,threading,urllib.request,urllib.error
from pathlib import Path
from http.server import ThreadingHTTPServer
import numpy as np
from pipeline import prepare,train,promote
from serve import load,application
here=Path(__file__).parent
with tempfile.TemporaryDirectory() as t:
a=Path(t)/'a';b=Path(t)/'b'
for root in (a,b):prepare(here/'corpus.jsonl',root)
metrics=train(a);train(b,200);train(b,400,True)
assert (a/'model.json').read_bytes()==(b/'model.json').read_bytes(),'resume differs'
assert metrics['train_nll']<metrics['initial_train_nll'];promote(a)
model,revision=load(a);server=ThreadingHTTPServer(('127.0.0.1',0),application(model,revision))
thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start()
url=f'http://127.0.0.1:{server.server_port}'
def post(body):
request=urllib.request.Request(url+'/v1/completions',data=json.dumps(body).encode(),headers={'Content-Type':'application/json'})
return urllib.request.urlopen(request,timeout=5).read()
assert json.loads(urllib.request.urlopen(url+'/health').read())['model_revision']==revision
result=json.loads(post({'prompt':'Data ','max_tokens':16}));assert result['completion_tokens']<=16 and result['model_revision']==revision
stream=post({'prompt':'Data ','max_tokens':16,'stream':True});assert stream.endswith(b'data: [DONE]\n\n')
try:post({'prompt':'Data ','max_tokens':0});raise AssertionError('invalid request accepted')
except urllib.error.HTTPError as e:assert e.code==400
server.shutdown();server.server_close()
(a/'model.json').write_text('{}')
try:load(a);raise AssertionError('tamper accepted')
except ValueError:pass
print('PASS: loss descent, exact resume, artifact integrity, HTTP generation, SSE, invalid input')
kubernetes.yaml
apiVersion: v1
kind: Namespace
metadata:
name: tokenlab-ai
labels:
pod-security.kubernetes.io/enforce: restricted
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: {name: artifacts, namespace: tokenlab-ai}
spec:
accessModes: [ReadWriteOnce]
resources:
requests: {storage: 1Gi}
---
apiVersion: batch/v1
kind: Job
metadata: {name: train-v1, namespace: tokenlab-ai}
spec:
backoffLimit: 1
activeDeadlineSeconds: 600
template:
metadata:
labels: {app: trainer}
spec:
restartPolicy: Never
automountServiceAccountToken: false
securityContext: {runAsNonRoot: true, runAsUser: 10001, runAsGroup: 10001, fsGroup: 10001, seccompProfile: {type: RuntimeDefault}}
containers:
- name: train
image: tokenlab-ai:local
imagePullPolicy: IfNotPresent
command: [sh, -ec]
args:
- python pipeline.py prepare --source corpus.jsonl --root /work && python pipeline.py train --root /work --resume && python pipeline.py promote --root /work
resources:
requests: {cpu: '1', memory: 256Mi}
limits: {cpu: '2', memory: 512Mi}
securityContext: {allowPrivilegeEscalation: false, readOnlyRootFilesystem: true, capabilities: {drop: [ALL]}}
volumeMounts:
- {name: artifacts, mountPath: /work}
volumes:
- name: artifacts
persistentVolumeClaim: {claimName: artifacts}
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: model-v1, namespace: tokenlab-ai}
spec:
replicas: 1
strategy: {type: Recreate}
selector:
matchLabels: {app: model-v1}
template:
metadata:
labels: {app: model-v1}
spec:
automountServiceAccountToken: false
securityContext: {runAsNonRoot: true, runAsUser: 10001, runAsGroup: 10001, fsGroup: 10001, seccompProfile: {type: RuntimeDefault}}
containers:
- name: server
image: tokenlab-ai:local
imagePullPolicy: IfNotPresent
resources:
requests: {cpu: '250m', memory: 128Mi}
limits: {cpu: '1', memory: 256Mi}
ports: [{containerPort: 8000}]
startupProbe:
httpGet: {path: /health, port: 8000}
failureThreshold: 30
periodSeconds: 2
readinessProbe:
httpGet: {path: /health, port: 8000}
periodSeconds: 5
livenessProbe:
httpGet: {path: /health, port: 8000}
periodSeconds: 15
securityContext: {allowPrivilegeEscalation: false, readOnlyRootFilesystem: true, capabilities: {drop: [ALL]}}
volumeMounts:
- {name: artifacts, mountPath: /work, readOnly: true}
volumes:
- name: artifacts
persistentVolumeClaim: {claimName: artifacts}
---
apiVersion: v1
kind: Service
metadata: {name: model-api, namespace: tokenlab-ai}
spec:
selector: {app: model-v1}
ports: [{port: 8000, targetPort: 8000}]
type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: {name: private-model, namespace: tokenlab-ai}
spec:
podSelector: {}
policyTypes: [Ingress, Egress]
ingress:
- from:
- podSelector:
matchLabels: {role: authorized-client}
ports: [{protocol: TCP, port: 8000}]
egress: []
transformer-job.yaml
# Optional, not executed here. First create namespace/PVC from kubernetes.yaml.
apiVersion: batch/v1
kind: Job
metadata:
name: transformer-train
namespace: tokenlab-ai
spec:
backoffLimit: 1
activeDeadlineSeconds: 7200
template:
metadata:
labels:
app: trainer
spec:
restartPolicy: Never
automountServiceAccountToken: false
securityContext:
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
fsGroup: 10001
seccompProfile:
type: RuntimeDefault
containers:
- name: train
image: tokenlab-transformer:lab
imagePullPolicy: IfNotPresent
command:
- sh
- -c
args:
- python pipeline.py prepare --source corpus.jsonl --root /work && python transformer.py
--root /work --steps 200 --resume && python approve_transformer.py --root
/work --max-nll 4.0
resources:
requests:
cpu: '2'
memory: 2Gi
limits:
cpu: '4'
memory: 4Gi
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
volumeMounts:
- name: artifacts
mountPath: /work
volumes:
- name: artifacts
persistentVolumeClaim:
claimName: artifacts
gpu-serving.yaml
# Optional unexecuted serving reference. Populate /models/approved first.
# Replace the image tag with a verified digest in your registry before production.
apiVersion: apps/v1
kind: Deployment
metadata: {name: transformer-v1, namespace: tokenlab-ai}
spec:
replicas: 1
strategy: {type: Recreate}
selector:
matchLabels: {app: transformer-v1}
template:
metadata:
labels: {app: transformer-v1}
spec:
automountServiceAccountToken: false
containers:
- name: vllm
image: vllm/vllm-openai:v0.14.0
args: [--model, /models/approved, --served-model-name, tokenlab-transformer, --max-model-len, '128', --dtype, float32, --gpu-memory-utilization, '0.5', --max-num-seqs, '8']
resources:
requests: {cpu: '2', memory: 4Gi}
limits: {cpu: '4', memory: 8Gi, nvidia.com/gpu: '1'}
ports: [{containerPort: 8000}]
startupProbe:
httpGet: {path: /health, port: 8000}
failureThreshold: 180
periodSeconds: 10
readinessProbe:
httpGet: {path: /health, port: 8000}
volumeMounts:
- {name: models, mountPath: /models, readOnly: true}
- {name: shm, mountPath: /dev/shm}
volumes:
- name: models
persistentVolumeClaim: {claimName: artifacts}
- name: shm
emptyDir: {medium: Memory, sizeLimit: 1Gi}
# Integrate into a separately hardened GPU namespace: the public image's UID,
# writable cache locations, device access and driver/CUDA matrix must be checked.
# Do not apply blindly to the restricted CPU namespace above. See README.
---
apiVersion: v1
kind: Service
metadata: {name: transformer-api, namespace: tokenlab-ai}
spec:
selector: {app: transformer-v1}
ports: [{port: 8000, targetPort: 8000}]
Dockerfile
FROM python:3.11.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY pipeline.py serve.py corpus.jsonl ./
USER 10001:10001
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
CMD ["python", "serve.py", "--host", "0.0.0.0"]
Dockerfile.transformer
FROM python:3.11.14-slim
WORKDIR /app
COPY requirements-transformer.txt .
RUN pip install --no-cache-dir -r requirements-transformer.txt
COPY pipeline.py transformer.py approve_transformer.py corpus.jsonl ./
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 TOKENIZERS_PARALLELISM=false
USER 10001:10001
CMD ["python", "transformer.py", "--root", "/work"]