> ## Documentation Index
> Fetch the complete documentation index at: https://candy-208aed2d-85.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# openai-serve の設定

> 環境変数、ルーティング、モデル検証、上限（Safety limits）をまとめます。

`openai-serve` は環境変数で設定します。

ローカル開発では `apps/openai-serve/.envrc.sample`（direnv）を利用できます。

## 環境変数

| Name                                 | Default           | Notes                                    |
| ------------------------------------ | ----------------- | ---------------------------------------- |
| `OPENAI_SERVE_HTTP_ADDR`             | `127.0.0.1:8080`  | HTTP listen `host:port`                  |
| `OPENAI_SERVE_LCPD_GRPC_ADDR`        | `127.0.0.1:50051` | `lcpd-grpcd` gRPC address                |
| `OPENAI_SERVE_API_KEYS`              | (empty)           | 設定すると `Authorization: Bearer ...` を必須にする |
| `OPENAI_SERVE_DEFAULT_PEER_ID`       | (empty)           | デフォルトの LCP peer id（66 hex chars）         |
| `OPENAI_SERVE_MODEL_MAP`             | (empty)           | `model=peer_id;model2=peer_id`           |
| `OPENAI_SERVE_MODEL_ALLOWLIST`       | (empty)           | カンマ区切りの model IDs                        |
| `OPENAI_SERVE_ALLOW_UNLISTED_MODELS` | `false`           | `true` なら model 検証をスキップ                  |
| `OPENAI_SERVE_MAX_PRICE_MSAT`        | `0`               | 0 より大きい場合、上限超の quote を拒否                 |
| `OPENAI_SERVE_TIMEOUT_QUOTE`         | `5s`              | gRPC quote timeout                       |
| `OPENAI_SERVE_TIMEOUT_EXECUTE`       | `120s`            | gRPC execute timeout                     |
| `OPENAI_SERVE_LOG_LEVEL`             | `info`            | `debug`, `info`, `warn`, `error`         |

## ログ（プライバシー）

`openai-serve` のログは、生のユーザー入力を永続化しなくても運用できるように設計しています。

* ログには、生のプロンプト（`messages[].content`）や生のモデル出力を残してはいけません。
* `info` は、運用メタデータ（model/peer/job id、価格、時間、byte/token カウント）を記録します。
* `debug` は HTTP リクエストログがより詳細になり（`client_ip` を含むことがあります）、よりセンシティブとして扱ってください。

## ルーティング（peer の選び方）

`model` ごとに Provider peer は以下の順で決定されます:

1. `OPENAI_SERVE_MODEL_MAP`（マップ先の peer が connected/LCP-ready の場合）
2. `OPENAI_SERVE_DEFAULT_PEER_ID`（設定されており connected/LCP-ready の場合）
3. manifest の `supported_tasks` で model を広告している peer（存在する場合）
4. フォールバックとして、接続されている peer の先頭

接続中の LCP peers が 0 の場合、リクエストは失敗します。

## モデル検証（model validation）

誤ルーティングや想定外の課金を防ぐため、`model` を検証します。

* `OPENAI_SERVE_MODEL_ALLOWLIST` が設定されている場合: allowlist に含まれる `model` のみ許可します
  （ただし `OPENAI_SERVE_ALLOW_UNLISTED_MODELS=true` の場合は例外）。
* それ以外の場合: 接続 peer が `supported_tasks` を広告しているなら、少なくとも 1 peer が広告している `model` のみ許可します。
  もし全 peer が `supported_tasks` を広告していない場合は、ゲートウェイを使える状態に保つため検証をスキップします。

## Safety limits

* `OPENAI_SERVE_MAX_PRICE_MSAT`: quote 価格の上限（超えたら拒否）
* `OPENAI_SERVE_TIMEOUT_QUOTE` / `OPENAI_SERVE_TIMEOUT_EXECUTE`: quote/execution の時間上限

## 認証

`OPENAI_SERVE_API_KEYS` を設定すると（カンマ区切り）、すべての `/v1/*` が以下を要求します:

```text theme={null}
Authorization: Bearer <key>
```

`/healthz` は意図的に保護しません（ローカルのヘルスチェック用途）。
必要に応じてリバースプロキシ側で保護してください。