SDEのためのAI API内部:HTTPからtoken生成まで
分割・prefill・decode・KV・ストリーム・ツールまで一要求を追い、障害境界・予算・ローカルコードを学びます。
出典とバージョン
この記事の目次
AI呼び出しは分散プログラムである
Pending状態のデプロイを診断するSRE支援を例にします。アプリがKubernetesの状態と手順書を集め、証拠をモデルへ送り、診断を表示します。修復には別の認可された実行器が必要です。アプリから生成文まで追跡する参考設計であり、ベンダー内部の再現ではありません。
前提はHTTP、TLS、認証、キュー、タイムアウトというバックエンド知識です。タイムアウトは一参加者の観測にすぎません。tokenは語彙ID、重みは学習済みパラメータ、推論は条件付き分布の計算です。学習は重みを更新しますが通常の推論は更新しません。
通信完了、モデル応答完了、業務受入れを区別します。根拠のない流暢な診断は前二者だけ満たせます。言語と要約はモデル、認可・厳密計算・状態遷移・不変条件は決定的コードが担当します。
モデル境界ではpθ(y₁…yₙ | x)を次token条件付き確率の積として扱います。θは固定重み、xは実際に送る文脈です。出力は復号判断であり正本DBへのトランザクションではありません。GPU不足の根拠にはsnapshot ID・時刻・イベントが必要です。
アプリが主体・会話・タスク状態、エンジンが一時KV、実行器が永続結果を所有します。KV喪失は会話削除でなく、応答喪失は操作取消でもありません。状態の所有者に照会して復旧します。
SDKからリクエスト受入れまで
SDKはメッセージを直列化し認証付きHTTPSを送り、イベントをオブジェクトへ変換します。通常ローカルで大モデルを動かすわけではありません。入口・割当確認・ルーター・受入制御・キューの順は実装依存です。鍵はバックエンドに置きます。
論理要求にID・期限・出力上限・設定を持たせ、通信試行には別IDを使います。セマフォで同時実行を制限し、期限内に終わらない仕事は受入れ時に拒否します。要求数制限とtoken数制限は別資源です。
会話オブジェクトが履歴を保存しても、Transformerが読むのはその推論用の文脈です。省略事実の記憶や添付の自動挿入を仮定しません。正本の履歴・証拠版・公開されるモデル版を記録します。
接続poolはDNS/TCP/TLSの反復を減らせます。HTTP/2多重化でもキューと割当は残ります。接続・無通信・総期限を分け、単調時計と残余予算を各hopで使います。
SDK3試行×worker3試行なら最大9回です。再試行の責任を統一し全試行を計上します。20秒中8秒使用なら残り12秒に待機も含めます。同一POSTも自動的に安全ではありません。 [12]
| 層 | 入力 → 出力 | 責任 |
|---|---|---|
| アプリ | 質問・証拠 → 要求 | 主体・秘密・予算 |
| 推論 | ID → スコア → ID | キュー・メモリ・生成 |
| 通信 | byte → 完全な項目 | 境界・部分・取消 |
| 実行器 | 認可操作 → 受領 | 権限・冪等・監査 |
メッセージからtokenとテンソルへ
テンプレートが役割区切りと特殊tokenを挿入し、tokenizerがモデル固有のIDに変換します。tokenは単語・文字・通信パケットと同じではありません。実際のテンプレートを数え、追加指示や媒体の利用量も考慮します。 [1]
教材のdecoderではID [B,T]から行列E [V,d]を引きX [B,T,d]を得ます。Bはバッチ、Tは長さ、Vは語彙、dは幅です。Web検索ではなく学習ベクトルの参照です。位置情報と注意・正規化・残差・前向き層が変換します。
画像・音声はBase64を文章として読むのではなく、復号後にパッチや特徴などへ変換されます。Base64の約4/3倍という転送量は視覚token課金ではありません。形式・寸法・時間・容量を別々に検査します。
教材BPEでa,b,a,bを優先規則(a,b)→abで併合すると[ab,ab]です。別語彙なら4IDかもしれません。IDはtokenizerの語彙・版と組で意味を持ち、普遍文字コードではありません。
B2,T4,d8なら出力64要素、V1000なら表8000パラメータです。行を選択するだけです。開始記号重複やassistant記号欠落で見た目が同じ文でも入力は変わります。paddingもマスクします。
Prefill:生成前に入力を処理する
因果注意のQ,K,Vは[T,d_h]、QKᵀは[T,T]です。未来をマスクし、独立成分という近似下で√d_hによって分散増大を抑えます。キー方向のsoftmaxとVの積は[T,d_h]です。複数ヘッドを結合・射影します。 [2]
既知のプロンプト位置は層内で並列処理できますが因果マスクは維持します。最後の位置から最初の生成tokenのlogitを得ます。密な注意計算はTの二乗で増え、射影やMLPも加わります。行列全体の保存回避は二乗計算の全廃ではありません。
10万行を送るより、時間範囲・schedulerイベント・引用付き手順を選びます。検索は実際の文脈上限を拡張しません。合成例では16,000−指示2,000−対話4,000−出力2,000で証拠8,000です。
射影は概ねT d²、注意積はT² d、MLPには中間幅も関係します。二乗だけでは遅延を説明できません。tilingはオンチップ再利用、融合は中間書込みを減らします。形状・精度・機種・batch次第です。
Decode・サンプリング・KVキャッシュ
Decodeは次token分布の計算・選択・追加を繰り返します。KVキャッシュで過去のキーと値を保持し、新tokenのQ/K/Vだけを計算して過去を参照します。数値実行状態であり事実DBではありません。 [3]
全注意キャッシュは約2 L B T H_kv d_h s byteです。32層、1系列、8192位置、KV8ヘッド、幅128、2 byteで1 GiB。重み・活性・管理費は別です。可変長なら位置数を合計し、窓や圧縮では式も変わります。
logitは未正規化スコアです。temperatureはsoftmax前の尺度、top-pは候補集合を調整します。真実の調整器ではありません。[2,1,0]、温度1なら約[0.6652,0.2447,0.0900]。貪欲選択も正確性や機種間再現性を保証しません。
step tではq[1,d_h]、K/V[t,d_h]、score[1,t]です。古いkey再計算は省けても履歴読出しは残ります。cacheは歴史依存を全廃しません。 [13]
16tokenブロックなら位置35は論理2・offset3。表[7,2,9]なら物理9です。固定kernel配置ではなく例です。共有prefixには参照管理・書込保護・tenant隔離が必要です。
GPUスケジューリングと遅延
重み読出しを償却するため仕事をバッチ化します。連続バッチは反復間で系列を出し入れします。長い入力・出力と到着変動が計算とKV容量を競います。総tokens/s向上と利用者遅延悪化は両立します。
PagedAttentionは論理KVを物理ブロックへ対応付け断片化を減らします。prefix cacheは互換な計算済み入力を再利用しますが、新しい応答のdecodeは残ります。回答キャッシュではなく、鍵・退避・隔離・互換性が必要です。 [4] [5]
小バッチでは重み・KVの帯域、大バッチでは演算が律速になり得ます。tensor並列は通信、prefill/decode分離はKV転送を追加します。量子化は品質・kernelとの取捨選択、投機的decodeは採択率と検証費次第です。
下界はmax(FLOPs/実効演算率,byte/実効帯域)です。80億重み×2
反復ごとにtoken/KV割当、kernel起動、ID収集、終了処理を行います。巨大prefillはdecodeを遅延させ、分割で交錯できますが取捨選択があります。拡張には待ち時間・活性token・遅延と重みロード時間を考慮します。
ストリーミングはバイト上のプロトコル
TCP読出し、HTTP chunk、SSEイベント、JSON差分、token、表示文字は別の境界です。UTF-8途中で切れることもあります。増分復号と不完全イベントの保持が必要です。EventSourceは任意の認証POSTの代用ではありません。 [6]
待機→受信→完了・失敗・取消の状態機械にします。HTTP200後のエラーや完了印なしの切断もあります。部分文を成功へ昇格させません。分割JSONのツール引数は項目完了・解析・認可まで実行しません。 [7]
プロキシのバッファで逐次表示が隠れることがあります。遅い読者には背圧か有界バッファが必要です。切断だけで計算・課金終了とは言えません。取消伝播、byte上限、アイドル時間、総期限を分けます。
UTF-8部分、部分行、イベントdataの3段bufferです。分割CRLFも1改行、空行でdispatch、複数dataを改行結合してからJSON解析します。deltaはitem ID別に蓄積します。
TCPはアプリ内の無限listを制限しません。キューbyte・総応答・遅い消費者方針を定義します。教材parserはイベント上限のみで、本番には総量・寿命上限も必要です。
ツール呼出しとエージェントループ
クライアント実行ツールではモデルが名前・引数を提案し、ホストが検証・実行して結果を返します。提供側ツールは境界が別です。「再起動した」という文は証拠ではなく、実行受領・版・監査を関連付けます。 [8]
read_snapshotとsearch_runbookはtenant制限の許可読取です。restart_deploymentは別権限と必要な承認を要求します。手順書はデータであり権限ではありません。schemaは形だけを保証します。未知ツールからshellへ逃がしません。
ラウンド・ツール数・時間・費用を制限します。書込のtimeout後は永続状態を照会してから再試行します。冪等性には指紋と衝突検出が必要です。HTTP再試行はKubernetesのexactly-onceを保証しません。
提案・検証・認可・実行・成功/失敗/不明の状態を使います。主体・namespace・対象・操作・版を承認に結び、書込直前に再確認します。対象変更後に古い承認を流用しません。
副作用前に意図を永続化してもKubernetesとの原子取引ではありません。変更と受領記録の間に障害が起きます。外部照会・重複識別が必要で、outbox単体は遠隔exactly-onceを保証しません。
遅延・費用・障害の切り分け
TTFT、token間隔、総時間、業務成功率を分けます。TTFTは接続・キュー・prefill・転送を含みます。一定間隔ΔでN tokenならTTFT+(N−1)Δ。合成例0.6秒+100×0.02秒=2.6秒です。
仮の単価は入力/出力100万tokenあたり$2/$8です。入力2,000・出力500で$0.008、ツール・再試行等は別。実際の料金ではありません。失敗も含めた総費用を受入済みタスク数で割ります。
429は指示に従い上限付き指数バックオフと揺らぎを使います。schema不正は修正し、5xxは期限・予算内だけ再試行します。ID・モデル・利用量・時間・終了理由・秘匿済み受領を記録し、原文や鍵は既定で残しません。
安定状態で
task→試行→操作をtraceにします。内部キューが見えなければclient TTFTと明記します。長さ・モデル・cache条件を揃えた分位を比較し、短い回答や拒否増を改善と混同しません。
説明の範囲と限界
対象は自己回帰テキスト生成です。embeddingはベクトル、rerankerは関連度を返し、拡散や音声は別の実行方式になり得ます。API互換性はtokenizer・ツール・隔離・停止意味の一致ではありません。
前沿は公平な混合処理、KV移動・圧縮、投機検証、低精度での品質維持です。長期信頼性、証拠の鮮度、注入耐性、モデル更新下の評価は未解決です。安価なtokenは認可を解決しません。
管理APIは運用を委任する反面内部を隠します。自前運用は調整権と容量・patch・安全責任を伴います。データ・負荷・運用力・受入コストで選び、adapterで拒否や未完了を消さないでください。
目標は状態所有者・仮説を分ける測定・安全な再実行を特定する診断です。証拠不足は不確実のまま保持します。末尾の小さな不変条件だけで本番信頼性は証明できません。
実践と検証
ローカル演習を実行
Python3.11+でpython3 lab.pyを実行します。標準ライブラリのみ、乱数なしです。モデルや本番SSEライブラリではなく通信と計算の教材です。全バイト分割幅・3種の改行・切断・不正・失敗を確認します。イベント名は独自仕様です。
Python演習をダウンロード"""Original teaching protocol, not a provider SDK. Python 3.11+, stdlib only.
No network, keys, GPU, or randomness. Feed arbitrary byte fragments.
Supports LF, CRLF and CR lines, UTF-8 BOM, comments and multiline data.
Does not implement EventSource reconnect, retry or Last-Event-ID semantics.
"""
import codecs
import json
import math
class Stream:
def __init__(self, max_event=65536):
self.decoder = codecs.getincrementaldecoder('utf-8-sig')('strict')
self.line = ''
self.data = []
self.event = ''
self.cr = False
self.size = 0
self.max_event = max_event
self.text = ''
self.state = 'waiting'
def feed(self, chunk):
self.consume(self.decoder.decode(chunk))
def consume(self, text):
for c in text:
if c == '\n' and self.cr:
self.cr = False
continue
self.cr = False
if c in '\r\n':
self.on_line(self.line)
self.line = ''
self.cr = c == '\r'
else:
self.line += c
if len(self.line.encode('utf-8')) > self.max_event:
raise ValueError('line too large')
def on_line(self, line):
if not line:
self.dispatch()
self.data, self.event, self.size = [], '', 0
return
if line.startswith(':'):
return
field, _, value = line.partition(':')
if value.startswith(' '):
value = value[1:]
if field == 'event':
self.event = value
elif field == 'data':
self.size += len(value.encode('utf-8')) + 1
if self.size > self.max_event:
raise ValueError('event too large')
self.data.append(value)
def dispatch(self):
if not self.data:
return
if self.state in {'completed', 'failed'}:
raise ValueError('data after terminal state')
payload = json.loads('\n'.join(self.data))
if not isinstance(payload, dict):
raise ValueError('payload must be object')
if self.event == 'delta':
if not isinstance(payload.get('text'), str):
raise ValueError('delta.text must be string')
self.text += payload['text']
self.state = 'streaming'
elif self.event == 'done':
if payload.get('reason') != 'stop':
raise ValueError('not an accepted completion')
self.state = 'completed'
elif self.event == 'error':
self.state = 'failed'
else:
raise ValueError('unknown teaching event')
def finish(self):
self.consume(self.decoder.decode(b'', final=True))
if self.line or self.data or self.event:
raise ValueError('unfinished event')
if self.state != 'completed':
raise ValueError('no successful completion')
return self.text
def softmax(logits):
if not logits or not all(math.isfinite(x) for x in logits):
raise ValueError('finite nonempty logits required')
m = max(logits)
values = [math.exp(x - m) for x in logits]
return [v / sum(values) for v in values]
def decode(raw, width):
s = Stream()
for start in range(0, len(raw), width):
s.feed(raw[start:start+width])
return s.finish()
def must_fail(raw):
try:
decode(raw, 1)
except (ValueError, UnicodeDecodeError):
return
raise AssertionError('invalid stream accepted')
if __name__ == '__main__':
text = 'Pending:GPU 不足'
wire = (': heartbeat\n\nevent: delta\ndata: ' +
json.dumps({'text': text}, ensure_ascii=False) +
'\n\nevent: done\ndata: {"reason":"stop"}\n\n')
raw = wire.encode()
for newline in ['\n', '\r\n', '\r']:
variant = b'\xef\xbb\xbf' + wire.replace('\n', newline).encode()
for width in range(1, len(variant)+1):
assert decode(variant, width) == text
must_fail(raw.split(b'event: done')[0])
must_fail(raw[:-1])
must_fail(b'event: error\ndata: {"error":"overloaded"}\n\n')
must_fail(b'event: delta\ndata: {bad}\n\n')
must_fail(b'event: delta\ndata: {"text":3}\n\n')
must_fail(b'\xff')
must_fail(raw + b'event: delta\ndata: {"text":"late"}\n\n')
try:
Stream(max_event=4).feed(b'data: oversized')
except ValueError:
pass
else:
raise AssertionError('size limit failed')
p = softmax([2,1,0])
assert abs(sum(p)-1) < 1e-12
assert all(abs(a-b)<1e-12 for a,b in zip(p,softmax([1002,1001,1000])))
kv = 2*32*1*8192*8*128*2
assert kv == 1024**3
cost = (2000*2+500*8)/1e6
assert abs(cost-0.008) < 1e-12
print(text)
print('softmax:', ', '.join(f'{x:.4f}' for x in p))
print(f'KV: {kv/1024**3:.1f} GiB; hypothetical cost: ${cost:.3f}')
print('PASS: byte fragmentation, newline variants, truncation, errors, bounds and arithmetic')
python3 lab.py
# Pending:GPU 不足
# softmax: 0.6652, 0.2447, 0.0900
# KV: 1.0 GiB; hypothetical cost: $0.008
# PASS: byte fragmentation, newline variants, truncation, errors, bounds and arithmeticbyte列を固定し分割だけを変えます。読出しごとのJSON解析はモデル変更なしでも失敗します。logit全体への定数加算でsoftmax不変、done削除で成功不可を確認します。事実品質の評価ではありません。
独自の模擬面接と採点
1. HTTP200でも失敗する理由は?
ヒント:3契約。受入れ・応答完了・業務受入れを分け、終端と証拠を検査します。
2. 文脈増加で容量が減る理由は?
ヒント:KVとprefill。要求別メモリに重み・活性を加えます。T倍増で単純KVは倍でも総遅延が倍とは限りません。
3. 再起動timeout後すぐ再試行できるか?
ヒント:副作用が不確実。台帳・指紋・版を照会し、記録済みなら再提示、矛盾なら拒否。不明な結果を照合します。
4. prefix cacheでdecode費用は消えるか?
ヒント:KV状態、prefixのprefill再利用、回答再利用を分けます。最後だけが生成を省きますがtenant・鮮度・互換性が必要です。
1–5点:用語、契約、仕組み、反例と障害、公平で観測可能な検証と限界。企業の実際の面接問題ではありません。
参考資料と次の教材
- Chat templates — Hugging Face Transformers (main documentation, checked 2026-11-11)https://huggingface.co/docs/transformers/main/en/chat_templating
- Attention Is All You Need — Vaswani et al., first submitted 2017-06-12; arXiv v7 2023-08-02https://arxiv.org/abs/1706.03762v7
- KV cache strategies — Hugging Face Transformers (main documentation)https://huggingface.co/docs/transformers/main/en/kv_cache
- PagedAttention — Kwon et al., arXiv v1 2023-09-12https://arxiv.org/abs/2309.06180v1
- Automatic prefix caching — vLLM documentationhttps://docs.vllm.ai/en/latest/features/automatic_prefix_caching/
- Server-sent events — WHATWG HTML standardhttps://html.spec.whatwg.org/multipage/server-sent-events.html
- Streaming messages — Claude Platform documentationhttps://platform.claude.com/docs/en/build-with-claude/streaming
- Building effective agents — Anthropic, 2024-12-19https://www.anthropic.com/research/building-effective-agents
- Attention Is All You Need — PDF v7https://arxiv.org/pdf/1706.03762v7
- PagedAttention — PDF v1https://arxiv.org/pdf/2309.06180v1
- vLLM — source codehttps://github.com/vllm-project/vllm
- HTTP Semantics — RFC 9110, June 2022https://www.rfc-editor.org/rfc/rfc9110.html
- Caching — Hugging Face Transformers (main documentation)https://huggingface.co/docs/transformers/main/en/cache_explanation