# ストリーミング

> Server-sent events（SSE）のチャンク形式、keepalive コメント、最終チャンクの usage と cost、切断時の動作。

Source: https://kiln.bricksum.com/docs/ja/streaming

chat/completions リクエストで stream を true にすると、生成されるトークンを server-sent events（SSE）としてリアルタイムに受信できます。ゲートウェイはモデルサーバーのイベントを届いた順に転送します。その際に keepalive コメントを加え、usage を要求した場合は最終 usage チャンクにコストを追加し、要求しない場合はそのチャンクを取り除きます。

## リクエスト

stream は JSON の真偽値 true で送信してください。ゲートウェイは文字列 "true" と数値 1 もストリーミングとして読み取りますが、SDK や他の OpenAI 形式のサーバーは真偽値を想定しています。公式 OpenAI SDK はこの値を設定し、ストリームの解析も行います。

**curl**
```bash
curl https://api.bricksum.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

**Python**
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bricksum.com/v1",
    api_key="sk-bk-...",
)

stream = client.chat.completions.create(
    model="qwen3-32b",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

**JavaScript**
```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bricksum.com/v1",
  apiKey: process.env.KILN_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "qwen3-32b",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content ?? "");
}
```

## イベント形式

レスポンスの Content-Type は text/event-stream です。各イベントは chat.completion.chunk を含む data: 行 1 つで、choices[0].delta に新しいテキストが入ります。最後の delta に finish_reason が含まれ、ストリームは data: [DONE] で終了します。

**text/event-stream**
```text
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

メモ

ほとんどの OpenAI SDK は stream=true を渡すと SSE を解析して delta オブジェクトを返します。空行で分割しコメント行を読み飛ばす処理が必要なのは、生の HTTP クライアントだけです。

## keepalive コメント

モデルがまだトークンを返していない間、ゲートウェイは 15 秒ごとに SSE コメント行を送り、プロキシやクライアントのタイムアウトを防ぎます。負荷が高く、リクエストがモデルサーバーのキューで待っている間も同様です。コロンで始まる行はコメントでデータを含まないため、無視してください。負荷が高いときに最初のトークンまで時間がかかるのは正常で、エラーではありません。

**comment line**
```text
: keepalive
```

## トークン使用量とコスト

デフォルトではストリームに usage は含まれません。 `stream_options.include_usage` を true にすると、ストリームの最後に choices が空で usage オブジェクトにトークン数を含むチャンクが 1 つ追加されます。

**request**
```json
{
  "model": "qwen3-32b",
  "messages": [{"role": "user", "content": "Hello!"}],
  "stream": true,
  "stream_options": { "include_usage": true }
}
```

**final chunk**
```text
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21,"cost":0.000001155}}

data: [DONE]
```

ゲートウェイはそのチャンクに usage.cost を追加します。このリクエストでクレジットから差し引かれた USD 金額で、usage のトークン数とモデルのトークン単価から計算されます。非ストリーミングのレスポンスにも同じ usage.cost フィールドが含まれます。usage を要求しない場合、このチャンクは届く前に取り除かれます。 この例のトークン数と cost は gpt-oss-120b で測定した例示の値で、qwen3-32b の値ではありません。

計測されたすべてのレスポンスには `X-Neocloud-Generation-Id` ヘッダーが含まれます。値はこのリクエストの使用量イベント ID です。ログと一緒に保存しておくと、請求やエラーをそのリクエストまでたどれます。

## 切断とエラー

- クライアントがストリームの途中で切断しても、生成はすぐには中止されません。ゲートウェイは使用量を記録するためにストリームを最後まで読み取り、生成されたトークンは課金されます。
- モデルサーバーがストリームの途中で失敗した場合、エラーはそのまま渡され、そのリクエストは課金されません。
- ストリームが finish_reason: "length" で終わる場合は max_tokens を増やしてください。reasoning トークンも max_tokens に含まれます。既知の制限は [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) を参照してください。