モデルが走る前
ユーザーはプロンプトと cheap・fast・smart のようなエイリアスを提供します。本番サーバーはタスクを受け入れる前に認証、ワークスペース所有権、権限をチェックします。プロバイダーのモデル ID と秘密情報はその境界の背後に留まります — 実際のプロバイダーモデルへの対応はコントラクトではなく設定なので、フレンドリーなエイリアスがクライアントに必要な唯一のモデル語彙です。
耐久性のあるタスクレコードは、バックグラウンド実行が始まる前にリクエストに ID を与えます。その ID は送信、ワーカー、使用量レコード、結果を結びつけます。ユーザーが別の場所へ移動した後に作業を回復する方法も提供します。
順序が重要です：高価な作業は安いチェックを通ってから始まります。何かがキューに入る前に認証・所有権・権限を検証することで、未認証や未払いのリクエストがプロバイダーに届くことを防ぎ — 失敗をユーザーに説明可能にします。AI モジュールガイドがそれらのチェックの居場所を文書化し、ワークスペース境界の記事が所有権がクライアントから信頼されるのではなくサーバーで導出される理由を説明しています。
誰のキー、誰の上限かを決める
AI 機能は支出の決定です。supastack ではワークスペースが独自のプロバイダーキーを持ち込めます — 暗号化して保存され、クライアントには公開されません — あるいはプラットフォームキーで動かし、モデル価格カタログに対してワークスペースごとの予算を強制します。どんな実装でも問いは同じです：誰が支払い、上限はどこで強制されるか？
強制はブラウザ側の見積もりではなくサーバーワークフローに属します。生成後にチェックされる予算は超過支出を記録するだけですが、ディスパッチ前にチェックされればそれを防げます。プロバイダーキーセットアップが設定側をカバーしています。
実行を明示的にする
Trigger.dev が ai.generate ワークフローを実行します。能力認識型ルーターが設定されたポリシーとリクエスト要件に従ってモデルを選びます。そのポリシーを運用入力として扱います：利用不可のエイリアスはインターフェースに機能する選択肢として現れるべきではありません。
送信中のネットワーク障害は、作業がキューに入ったかクライアントを不確かにすることがあります。本番経路はタスクスコープの冪等性キーと保存された送信を使い、復旧が元のリクエストを再利用できるようにします。タイムアウトごとに新しいタスクを送ると、作業とコストの重複のリスクがあります。
耐久性はインターフェースをシンプルに保つものでもあります：画面はリトライを指揮するのではなく、タスク状態を読んで描画します。生成がモデル呼び出し・ツールステップ・スケジュールにまたがるとき、明示的なワークフローコントラクト — enqueue・status・cancel — が「処理中」を誠実に保ちます。
失敗モードに名前をつける
リクエストと結果の間には、失敗し得る特定の有限の集合があります。抽象的な「エラー」ではなく、それぞれ名前で設計します — すべてのタスクは説明可能な状態で終わるべきです：キュー済み、実行中、理由付きの失敗、または結果付きの完了。タスク復旧がキットの復旧側の参照です。
その下にあるインターフェース要件は、どの状態も嘘をつけないことです。処理より長生きするスピナーや、一度も走らなかったタスクへの成功メッセージは、起きるのを待っているサポートチケットと課金トラブルです。
- 送信がタイムアウト — 再キューではなく、保存された送信とタスクスコープの冪等性キーで復旧する。
- プロバイダーがタスク途中で失敗 — インターフェースが表示できる理由を付けてタスクを失敗にする。
- 予算枯渇 — 支出の後ではなくディスパッチ前に拒否する。
- ユーザーが移動 — 耐久レコードと復旧 URL が状態と結果を復元する。
起きたことを追跡する
生成はテキスト以上のものを生み出します。アプリケーションは使用量とタスク結果を記録し、インターフェースは認証済み API 経由で状態を読みます。使用量レコードが予算を強制可能にするものです — 結果が返された後に推定されるのではなく、返される前に書かれます。
完了メールは別の配信レコードを持つ別のステップです。成功したモデル応答はメールが配信されたことを確立しません。これらの結果を区別しておくと、モデルを不必要に再実行せずに障害を説明し再試行しやすくなります。
結果にはユーザーが戻れる居場所も必要です：タスクページ、履歴リスト、完了メールで届く復旧 URL。一時的な通知にしか存在しない生成は、二度作ってほしいと頼まれる作業です。
それぞれの境界を検証する
決定的な fake アダプターを使って、まずアプリケーションの決定をテストします：拒否されたアクセス、無効化されたエイリアス、重複送信、結果復旧、汎用エラー。これらのテストはプロバイダー認証情報なしで実行されるべきです。
次に、実際の統合には明示的にオプトインのプロバイダースモークプロセスを使います。文書化されたサンドボックス設定と外部呼び出しへの承認が必要です。この区別は通常の開発を速く保ちながら、本番証拠を具体的で追跡可能にします。
製品が変わってもその分割を安定に保ちます：すべての境界決定の近くに決定的なカバレッジを置き、プロバイダー交換・ルーターポリシー変更・新しいエイリアスが、顧客を失敗させる前にテストを失敗させるようにします。
SaaS の AI 機能についてよくある質問
AI をペイウォールの後ろに置く話では、毎回いくつかの質問が出てきます。
- AI 機能の認可はどこで行うべきですか？ — 何かがキューに入る前です：認証し、ワークスペースを解決し、権限をチェックし、それからタスクを作る。生成後に走るチェックは悪用を記録するだけです。
- BYOK サポートは必要ですか？ — 顧客が独自のプロバイダー関係を持っているなら、イエスです：誰が支払い、誰がレート制限を所有するかを決めます。キーは暗号化して保存し、クライアントから遠ざけてください — AI 設定ガイドがそのモデルをカバーしています。
- 再試行による二重課金をどう防ぎますか？ — 冪等性キーをタスクにスコープし、復旧中に保存された送信を再利用すれば、タイムアウトが 2 回目の課金対象実行を作れなくなります。
- どんな使用データを記録すべきですか？ — タスクごとに：モデル、消費ユニット、価格カタログに対するコスト、ワークスペース — ジョブを再実行せずに予算を強制し支出の質問に答えられるだけの量です。
- 生成をバックグラウンドジョブに置くべきなのはいつですか？ — リクエストを生き延び得るときは常にです。モデルの遅延・再試行・複数ステップの作業は耐久実行を支持します。インラインに属するのは即時で安い呼び出しだけです。