> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# AI 機能

チャット、タスク、モデルポリシー、bring-your-own-key。

## 偽の AI を試してから、本物のプロバイダーを選択してください

最初の結果については、Web チュートリアルの /dashboard タスクに従います。ローカル フローを開始し、プロンプトをキューに入れて実行し、結果を表示します。 AI_PROVIDER=fake は、外部モデルにデータを送信したり、有料の API キーを使用したりせずに、反復可能なデモンストレーション応答を返します。

実際の生成では、まず永続化アカウントを構成し、AI プロバイダーを選択して、以下の AI 構成に従います。モデルとその価格をデータベース カタログに追加し、各エイリアスに対して許可されるモデルを選択し、ワークスペースに必要なアクセスを付与します。 fast などのエイリアスは、ユーザーに表示されるわかりやすい選択肢です。それ自体は外部プロバイダーのモデル ID ではありません。

バックグラウンドの AI task にも、構成されたジョブ サービスが必要です。モデルの選択肢が表示されない場合は、再試行する前にカタログとエイリアスのポリシーを調べてください。アクセスが拒否された場合は、アクティブなワークスペースの資格を調べてください。すべてのプロバイダー API キーを、ブラウザー、モバイル アプリ、またはデスクトップ ウィンドウではなく、Web サーバーの構成に保持します。

[資格情報不要の AI デモを試す](https://supastack.dev/ja/docs/web/ship-in-5-minutes.md)

[リアルAI生成の設定](https://supastack.dev/ja/docs/modules/ai-configuration.md)

[許可されるモデルと価格を追加](https://supastack.dev/ja/docs/web/setup-ai.md)

[バックグラウンドタスク実行の設定](https://supastack.dev/ja/docs/modules/jobs.md)


## タスクライフサイクルを追う

本番タスク API は、タスクを永続化し Trigger.dev の ai.generate ワークフローをディスパッチする前に、認証済みワークスペースと権限を検証します。ルーターは能力要件と設定済みモデルポリシーを適用します。

```
POST /api/ai/tasks
  → authenticated workspace + entitlement
  → durable task record
  → Trigger.dev ai.generate
  → model routing + generation
  → usage record + result
  → transactional completion delivery
```


## エイリアスと予算を設定する

ユーザーは有効なエイリアスを選びます：cheap・fast・smart。サーバーは基礎となるモデル ID、プロバイダー認証情報、ワークスペースポリシー、予算適用を制御します。暗号化された自前キーサポートも同じサーバー境界を維持しなければなりません。


## ワークフロー意味論を明示的に保つ

JobRunner は enqueue・status・cancel のみを約束します。Trigger.dev のワークフロー意味論は明示的で、耐久性のある実行動作を含みます。汎用コントラクトからリトライやスケジューリング保証を推測しないでください。

本番送信経路は、あいまいなディスパッチを処理するために冪等性と保存済みタスク復旧を使います。生成完了は完了メール配信とは別です。


## インストールとセットアップ

AI_PROVIDER=fake が開発を決定的に保ちます。本番プロバイダーはサーバーサイドで設定します(OpenAI、Anthropic、または OpenAI 互換エンドポイント)。キーがクライアントバンドルに入ることはありません。AI_MODEL_POLICY はユーザー向けエイリアス(cheap、fast、smart)をカタログのモデル id にマップし、空のエイリアスはその選択肢をインターフェースから除去します。

モデルカタログ(ai-model-catalog)は能力と不変の価格メタデータを持ち、価格変更後も使用レコードが説明可能なままになります。

```
POST /api/ai/tasks          → durable task + Trigger.dev dispatch
GET  /api/ai/tasks/{taskId}  → status + result
/chat                        → streaming assistant surface
```


## 実装ワークフロー

チャットサーフェスはワークスペースメンバーごとにスレッドを保持し、chat-stream-runtime でトークンをストリーミングします。長い生成はタスクとして実行されます: API 境界で認可され、ai.generate ワークフローが実行し、冪等サブミッションストア経由で回復可能です。

bring-your-own-key モードはプロバイダーキーを AES-GCM エンベロープとして保存します(CREDENTIAL_ENCRYPTION_KEY、byok-key-vault.ts)。復号はサーバー実行パス内でのみ行われます。使用量と推定コストはリクエストごとに記録され、ワークスペース予算に供されます。


## 検証とトラブルシューティング

無効なエイリアスがインターフェースに存在しないこと、エンタイトルメントと予算の拒否がディスパッチ前に起きること、再試行されたサブミッションがタスクを再利用すること、保存された BYOK キーがクライアントに返らないことを確認します。実モデルによる受け入れは文書化されたプロバイダー smoke パスに留めてください。


## 次へ

[バックグラウンドジョブ](https://supastack.dev/ja/docs/web/jobs.md)