環境変数

このページはすべての RECOTEM_* 環境変数の公式リファレンスです。train スコープの変数は recotem train のみが読み取ります。serve スコープの変数は recotem serve のみが読み取ります。both スコープの変数は両方のコマンドが読み取ります。

パースに失敗した値は、変数によって致命的にも無視にもなります

以下で ⚠ が付いた変数は、プロセスの起動そのものを拒否します (ConfigError / KeyRingConfigError、終了コード 8、ポートをバインドする前)。それ以外の数値変数は env_var_unparseable 警告をログに出してデフォルト値に黙ってフォールバックします。したがって、たとえば RECOTEM_MAX_PAYLOAD_BYTES のタイプミスは、意図しない上限のままサーバーが動き続ける結果になります。クランプ対象の変数における範囲外の値も致命的ではなく、env_var_clamped 警告とともにクランプされます。変更後は起動ログで env_var_unparseable と env_var_clamped を確認してください。

認証と署名

これらの変数はアーティファクトの整合性 (署名鍵) と API 認証を制御します。シークレットとして扱う必要があります。保管の推奨事項については セキュリティ — シークレットの取り扱い を参照してください。

変数	デフォルト	スコープ	クランプ	説明
⚠ RECOTEM_SIGNING_KEYS	(必須)	both	—	kid:hex64,kid2:hex64 — HMAC-SHA256 署名/検証鍵 (64 hex 文字 = 32 生バイト)。複数エントリによりゼロダウンタイムのローテーションが可能。recotem train は常に最初のエントリで署名する。設定ミスまたは欠落した値はフェールクローズ — 未署名フォールバックなし。
⚠ RECOTEM_API_KEYS	(空)	serve	—	kid:sha256:hex64,... — API キー許可リスト。各エントリは kid と scrypt ダイジェストのペア (sha256: はダイジェストファミリーラベルであり、アルゴリズムではない)。空の値はバインドアドレスを RECOTEM_HOST の設定に関わらず 127.0.0.1 に強制する。

ヒント — 鍵の生成

これらの変数の正しいフォーマットの値を生成するには recotem keygen --type signing および recotem keygen --type api を使用してください。正確な出力フォーマットについては セキュリティ — recotem keygen 出力フォーマット を参照してください。

ネットワークバインディング

これらの変数は recotem serve が接続をリッスンする場所を制御します。

変数	デフォルト	スコープ	クランプ	説明
RECOTEM_HOST	127.0.0.1	serve	—	uvicorn バインドホスト。RECOTEM_API_KEYS が設定されている場合、Docker または Kubernetes 内では 0.0.0.0 にする必要がある。API キーが設定されていない場合は強制的に 127.0.0.1 に戻される (host_forced_to_loopback 警告あり)。
⚠ RECOTEM_PORT	8080	serve	1–65535 (致命的)	uvicorn バインドポート。他の数値変数と異なり、範囲はクランプではなく強制されます。整数でない値や範囲外の値は ConfigError となり、ポートをバインドする前に終了コード 8 で停止します (RECOTEM_PORT must be in range 1–65535, got 99999)。
RECOTEM_ALLOWED_HOSTS	127.0.0.1,localhost	serve	—	TrustedHostMiddleware に渡すカンマ区切りのリスト。未認識の Host ヘッダーを持つリクエストは拒否される。空白のみのカンマ入力はデフォルトにフォールバック。本番環境ではクライアントが使用する正確なホスト名を明示的に設定すること。
RECOTEM_ALLOWED_ORIGINS	(空)	serve	—	カンマ区切りの CORS 許可リスト。空はすべてのクロスオリジンリクエストを拒否することを意味する。ブラウザクライアントが CORS リクエストを送信する場合に設定する。

注意 — recotem serve を外部に公開する

非ループバックインターフェースにバインドするには RECOTEM_API_KEYS を設定する必要があります。RECOTEM_HOST=0.0.0.0 を設定し、RECOTEM_ALLOWED_HOSTS にクライアントの正確なホスト名を設定し、TLS を終端するリバースプロキシを前段に配置してください。recotem serve は TLS を終端しません。

制限とキャップ

これらの変数はメモリ、リクエスト、ダウンロードサイズの制限を制御します。アーティファクトの上限はデシリアライズ前に適用されます。

変数	デフォルト	スコープ	クランプ	説明
RECOTEM_MAX_ARTIFACT_BYTES	2 GiB	serve	[1 MiB, 16 GiB]	アーティファクトファイルごとのサイズ上限。デシリアライズが発生する前に適用される。ペイロード上限を一度も設定していなくても、これをペイロード上限より下げると致命的です — クロスチェックは解決後の 2 つの値を比較するため、RECOTEM_MAX_ARTIFACT_BYTES=268435456 (256 MiB) だけでも、オペレーターが設定していない RECOTEM_MAX_PAYLOAD_BYTES (デフォルト 512 MiB) を名指しして終了コード 8 で停止します。ちょうど 512 MiB は許容されます。下げる場合はペイロード側から両方まとめて下げてください。
RECOTEM_MAX_PAYLOAD_BYTES	512 MiB	serve	[1 MiB, 16 GiB]	HMAC 検証後のデシリアライズ中に適用されるペイロードごとの上限。RECOTEM_MAX_ARTIFACT_BYTES 以下でなければならない。そうでない場合は起動時に ConfigError (終了コード 8) で失敗する。デシリアライズによるメモリ展開を制限するため RECOTEM_MAX_ARTIFACT_BYTES より小さく設定されている。
RECOTEM_MAX_BODY_BYTES	128 MiB	serve	[1 MiB, 2 GiB]	HTTP リクエストボディの最大サイズ。BodySizeLimitMiddleware は、宣言された Content-Length が上限を超える場合に 413 PAYLOAD_TOO_LARGE を返し、Content-Length を持たないチャンク/ストリーミングボディに対しては受信バイト数を積算して適用する。ヘッダを省略して回避することはできない。Starlette がボディをバッファリングして JSON パースする前に適用される。
RECOTEM_MAX_DOWNLOAD_BYTES	256 MiB	train	[1 MiB, 16 GiB]	HTTP/HTTPS、ローカルファイル、オブジェクトストアのソース読み取りにおける生 I/O バイト上限。上限はストリーム途中で適用される。超過すると DataSourceError (終了コード 3) が発生する。解凍後の DataFrame はキャップしない — セキュリティ — 解凍後サイズ上限の未適用 を参照。
RECOTEM_MAX_FEATURE_DIM	5000	train	[16, 100000]	フィーチャーアウェア iALS におけるエンコード後のサイドフィーチャー次元の上限。サイド (アイテムとユーザー) ごとに独立して検査される。超過するとエンコーダ状態の構築時点で TrainingError (終了コード 4) が発生する。ボキャブラリは取得したフィーチャーテーブル全体から構築されるため、次元はインタラクション件数ではなくカタログサイズに比例する。レシピレベルで対抗できる唯一のレバーは min_frequency。トライアルあたりの時間は超線形に増加し、その指数は次元とともに上昇する (実測: 既定の上限未満では倍化のコストは 1.7〜1.9 倍、5,000 からは 5.07 倍、10,000 からは 7.46 倍 — 既定の上限がカタログを拒否したときに取る段でちょうど 3 乗に近づく)。メモリは 2 乗で増加し、どちらも training.parallelism と乗算される — オペレーション — フィーチャーアウェア iALS のサイジング を参照。

注意 — RECOTEM_MAX_FEATURE_DIM は学習時のみの上限です

これは recotem train がエンコーダを構築する際に build_encoder_state 内で適用されるもので、サービング側への影響はありません — recotem serve はこの変数を読みません。サービングのメモリガードとして扱わないでください。アーティファクトに保存されるエンコード済みフィーチャー行列は n_items × nnz_per_row に比例しますが、この変数はそれを制限しません。サービング側には RECOTEM_MAX_PAYLOAD_BYTES とホストのサイジングを使用してください。

ヒント — RECOTEM_MAX_BODY_BYTES とバッチ動詞

デフォルトの 128 MiB は、スキーマ上有効な最大の単一動詞のボディ (:recommend-related はコールドスタートのフィーチャーマッピングを最大まで埋めて約 52 MiB) は通しますが、最大のバッチのボディは意図的に通しません。:batch-recommend は約 196 MiB、:batch-recommend-related は約 13 GiB (後者は 2 GiB のクランプさえ超えます) に達します。これらは 413 で拒否されます。実際にそれほど大きなバッチを送信するオペレーターは上限を引き上げる必要があります。

HTTP フェッチャー

これらの変数は recotem train が http:// および https:// ソースパスをフェッチする方法を制御します。

変数	デフォルト	スコープ	クランプ	説明
RECOTEM_HTTP_TIMEOUT_SECONDS	30	train	[1, 600]	HTTP/HTTPS ソースフェッチの接続・読み取りタイムアウト (秒)。
RECOTEM_HTTP_ALLOW_PRIVATE	(未設定)	train	—	真値: 1、true、yes、on。設定すると HTTP フェッチャーはプライベート (RFC1918)、ループバック、リンクローカル宛への接続を許可する。クラウドメタデータサービス (AWS IMDSv1 の 169.254.169.254、GCP の metadata.google.internal) への SSRF 攻撃をブロックするため本番環境では未設定のままにすること。

注意

RECOTEM_HTTP_ALLOW_PRIVATE は本番環境では絶対に設定しないでください。その唯一の目的はデータオリジンが信頼された内部ホストであるラボ環境のサポートです。セキュリティ — ネットワークソースに対するオペレーターの責任 を参照してください。

ウォッチャーと起動

これらの変数は recotem serve がアーティファクトファイルを監視し、起動時にモデルをロードする方法を制御します。

変数	デフォルト	スコープ	クランプ	説明
⚠ RECOTEM_WATCH_INTERVAL	5	serve	[1, 30]	アーティファクトウォッチャーのポーリングインターバル (秒)。範囲外の値はクランプされますが、ここにある他の数値変数と異なり、数値でない値は致命的です (ConfigError、終了コード 8)。ウォッチャーは新しいまたは変更されたアーティファクトファイルを検知し、プロセスを再起動せずにモデルをホットスワップする。
RECOTEM_STARTUP_PARALLELISM	(自動)	serve	[1, 32]	起動時にアーティファクトを並列ロードするスレッド数。デフォルトの自動サイジングは min(len(recipes), 8)。0 の設定はセンチネルではなく — 1 にクランプして env_var_clamped 警告を出力する。デバッグには 1 に設定して逐次ロードを強制する。

ライフサイクル

これらの変数はランタイム環境、グレースフルシャットダウン、ログ出力を制御します。

変数	デフォルト	スコープ	クランプ	説明
RECOTEM_ENV	(空)	serve	—	デプロイメント環境タグ。--insecure-no-auth は development、dev、または test に設定した場合のみ許可される。--dev-allow-unsigned は development に設定した場合のみ許可される。/docs、/redoc、/openapi.json エンドポイントはフェールセキュアで、この変数が development、dev、または test のときのみ有効になる。それ以外の値 (未設定、production、prod、staging、またはカスタムタグ) の場合、これらのパスは 404 を返す。
RECOTEM_DRAIN_SECONDS	30	serve	[1, 300]	SIGTERM グレースフルドレインウィンドウ (秒)。進行中のリクエストはこのウィンドウが完了するまで待機でき、その後 uvicorn は残りの接続を閉じる。Kubernetes では terminationGracePeriodSeconds を少なくとも RECOTEM_DRAIN_SECONDS + 5 に設定すること。
⚠ RECOTEM_LOG_FORMAT	auto	both	—	ログ出力フォーマット。以下の 3 つ以外の値は致命的です (ConfigError、終了コード 8)。auto は stderr が TTY でない場合は JSON、それ以外はコンソール形式を使用する。json は構造化 JSON を強制する。console は人間が読める出力を強制する。

運用

これらの変数はストレージパス、ロック、メタデータフィールドフィルタリング、メトリクスを設定します。

変数	デフォルト	スコープ	クランプ	説明
RECOTEM_ARTIFACT_ROOT	(空)	train	—	設定した場合、レシピのローカル output.path の値はこのディレクトリ配下に存在しなければならない。シンボリックリンクエスケープは拒否される。ホスト上で train プロセスがアーティファクトを書き込める場所を制限するために使用する。
RECOTEM_LOCK_DIR	(空)	train	—	レシピごとの学習ロックファイルのディレクトリを上書きする。ローカルの output.path 値は常に <output_path>.lock でロックされる。リモートの output.path 値 (s3://、gs:// など) はホストローカルのロックファイルを必要とする。RECOTEM_LOCK_DIR が未設定の場合は <tempdir>/recotem-locks/ にフォールバックする。注意: flock はホストローカル — ホスト間のシングルライター保証にはスケジューラーレベルのミューテックスを使用すること (Kubernetes の concurrencyPolicy: Forbid など)。
RECOTEM_METADATA_FIELD_DENY	(空)	serve	—	アイテムメタデータインデックスのロード時に除外する列名のカンマ区切りリスト。除外された列はすべての推薦エンドポイント (:recommend、:recommend-related、および include_metadata=true の :batch-recommend*) のレスポンスに含まれない。マッチングは大文字小文字を区別しない — メタデータの "Internal_ID" は拒否リストに "internal_id" があればストリップされる。PII 列を API レスポンスから除外するために使用する。
RECOTEM_METRICS_ENABLED	(未設定)	serve	—	真値: 1、true、yes、on。Prometheus /v1/metrics エンドポイントを有効化する。recotem[metrics] エクストラが必要 (pip install "recotem[metrics]")。エンドポイントはオプトインでデフォルトでは無効。他のすべての /v1 ルートと同様に API キーが必要 — 有効な X-API-Key のないスクレイプは 401 を受け取るため、スクレイパーにキーを設定すること (あるいは非認証構成で動作させること。その場合はループバックのみのバインドが強制される)。パスは /metrics ではなく /v1/metrics。
RECOTEM_ALLOW_IRSPACK_VERSION_SKEW	(未設定)	serve	—	真値: 1、true、yes、on。サービング側の irspack バージョンスキューチェックを、ArtifactError (レシピは loaded: false のまま) から irspack_version_skew_allowed 警告に格下げし、ペイロードをデシリアライザに到達させる。デフォルトのルールは許可リスト方式で、irspack の major.minor が同一なら常にロードされ、major.minor が異なる場合は Recotem が実証的に検証した (best_class, 遷移) の組み合わせのみロードされる。アーティファクトが影響を受けないと分かっている場合にのみ使用すること — 互換性のないペイロードがロード可能になるわけではない。オペレーション — irspack バージョンスキュー を参照。

データソース

これらの変数は特定のデータソースの動作を調整します。recotem train のみが、対応するソースが使用されたときのみ読み取ります。詳細は データソース リファレンスを参照してください。

変数	デフォルト	スコープ	クランプ	説明
RECOTEM_BQ_REQUIRE_STORAGE_API	(未設定)	train	—	真値: 1、true、yes、on。設定すると、BigQuery Storage Read API が失敗した場合 (例: bigquery.readSessions.create IAM 権限の欠落) に BigQuery ソースがより遅い REST API にサイレントフォールバックするのではなく、DataSourceError (終了コード 3) を発生させる。スループット低下を受け入れるのではなく IAM のギャップを表面化させるために使用する。
RECOTEM_MAX_SQL_ROWS	50_000_000	train	[1_000, 500_000_000]	SQL データソースが返す行数のハードキャップ。上限を超えると DataSourceError (終了コード 3) を発生させる。行数をキャップするのであって、DataFrame の常駐メモリではない — SQL ソース — メモリバウンドの注意点 を参照。
RECOTEM_SQL_ALLOW_PRIVATE	(未設定)	train	—	真値: 1、true、yes、on。SQL ソースがプライベート / ループバックの DSN ホストを受け入れるオプトイン (デフォルトは SSRF 対策のため拒否)。あらゆるドライバルーティング形式 (netloc、?host=、?hostaddr=、?service=、?unix_socket=、絶対パスホスト、ホスト情報のないネットワーク DSN) をカバー — このフラグなしでは全てデフォルトで拒否される。各プローブ / フェッチ前の DNS リバインディング再チェックも無効化される — オプトインはホストをエンドツーエンドで信頼することを意味する。

レシピ展開

RECOTEM_RECIPE_ プレフィックスを持つ変数のみが、レシピ YAML ファイル内での ${...} 展開の対象となります。

変数	デフォルト	スコープ	説明
RECOTEM_RECIPE_*	—	train	名前が RECOTEM_RECIPE_ で始まる任意の変数は、レシピフィールドでの ${VAR_NAME} 置換の候補となる。二次的なブラックリストがこのプレフィックス内でも機密名をブロックする。

注意 — RECOTEM_RECIPE_* 展開のセキュリティ制約

二次的なブラックリストは、RECOTEM_RECIPE_ プレフィックスを持つ場合でも、機密パターンに一致する変数名の展開を拒否します。ブラックリストは完全一致、プレフィックス一致、部分文字列一致のルールを使用します — 特に、部分文字列 KEY を含む名前は拒否されます。RECOTEM_RECIPE_ プレフィックスはデータセット名、日付範囲、パーティション列、機能フラグなどの非機密設定値を対象としています。このプレフィックスの下にシークレットを格納しないでください。完全なルールと例については セキュリティ — レシピの環境変数展開ブラックリスト を参照してください。