Tessera
ログイン無料で始める
ドキュメント一覧

スキーマ生成AI

概要

Tesseraのスキーマ生成AIは、チャットでの自然言語のやり取りだけでコンテンツタイプ（スキーマ）の新規作成・変更案を生成します。汎用のAIチャットと違うのは、既存のスキーマ構成・フィールド一覧・（承認待ちがあればその内容も含めた）現在の状態を理解した上で提案する点です。「著者フィールドを必須にして」のような依頼に対し、他の既存フィールドを壊さずに差分だけを反映した提案を返します。

生成された提案がそのまま本番のスキーマに反映されることはありません。必ず一度ステージング（保留中の変更として保存）され、内容を人間が確認して承認して初めて反映されます。

クイックスタート

このチャットは1セッションにつき1つのコンテンツタイプのみを作成・編集します（管理画面のチャットUIにも同じ内容の注記が表示されます）。

  1. ログイン後、/schema-chatにアクセスします。
  2. 直接アクセスした場合は常に新規作成モードです。既存のコンテンツタイプを編集したい場合は、/entriesのスキーマ一覧から対象の「スキーマを編集」ボタンを使ってください（/schema-chat?mode=update&targetApiId=...という形でこのセッションの編集対象が固定されます）。
  3. チャット欄に自然言語で要求を入力します（例:「ブログ記事のコンテンツモデルを作りたい。著者と複数タグを持たせたい」）。
  4. AIの応答が提案として成立すると、右側のプレビュー欄に反映後のフィールド構成・差分が表示されます。
  5. 内容に問題なければ「この内容で生成」ボタンを押します。これで初めて承認待ち（pending）の変更提案としてステージングされます（チャットの応答を受け取っただけではまだ何も保存されません）。
  6. /entriesの承認待ちセクションで差分を確認し、承認してください。

新規作成モードでは、一度スコープ（apiId）が確定すると、そのセッション内では同じコンテンツタイプのみを編集し続けます（無関係な既存コンテンツタイプへの変更は提案されません）。

実例

新規コンテンツタイプの作成

「ブログ記事のコンテンツモデルを作りたい。著者と複数タグを持たせたい」と入力すると、AIはtitle(text)・body(richtext_markdown)・author(reference, cardinality: one)・tags(reference, cardinality: many)といったフィールド構成を提案します。単体型（会社概要のように常に1件しか存在しないコンテンツ）かどうか判断がつかない依頼の場合は、AIが提案せず先に確認の質問を返すことがあります。

既存フィールドの型変更提案

編集モードで「カテゴリをテキストではなく選択式にしたい」のように依頼すると、AIは対象フィールドのみを変更した全体構成を再提案します。既存コンテンツに影響する可能性がある変更（後述の影響分析）は、提案の生成前に自動でチェックされます。

影響分析が表示されるケース

編集モードでの提案が既存コンテンツに影響しうる場合（フィールド削除・型変更・unique制約の新規追加・selectの選択肢削減）、「この内容で生成」ボタンの上に影響件数が表示されます。例えば既に値を持つコンテンツがあるフィールドを削除しようとすると「フィールド『◯◯』の削除により、既に値を持つX件のコンテンツからこのフィールドの値が失われます」という形で件数付きの警告が出ます。この分析はLLMを使わず、決定論的なDBクエリのみで算出されます。

エラーケース

AIの自己修正が失敗した場合

HTTP 502

AIの出力が内部的な型検証（reference型のrelation欠落、select型のoptions欠落など）に通らなかった場合、Tesseraは自動的に最大2回まで自己修正を試みます（計3回まで試行）。それでも解決しなかった場合、以下の文言でエラーが返ります。

「AIが一部の既存フィールド構成を正しく再現できず、提案の生成に失敗しました。もう一度同じ内容で送信するか、依頼の表現を変えてお試しください。」

このケースでも実際にAI APIへのリクエストは発生しているため、後述のクレジットは消費されます。

承認待ち(pending)の提案と承認済みスキーマの違い

同じコンテンツタイプに対して既に承認待ちの変更提案がある状態でチャットを続けると、AIが参照する「現在のスキーマ」はその未承認の提案内容になります。この状態で、まだ承認されていないフィールドについて再度チャットで言及すると、画面上に次のような注記が表示されます。

「『◯◯』のフィールドは承認待ちの提案に含まれており、まだ実際のスキーマには反映されていません。」

この注記はAIの生成文とは独立してサーバー側が機械的に付与するもので、AI自身の説明文が万一「既にスキーマに存在します」のような確定的な表現をしてしまった場合でも、実際の状態を正しく伝えます。

削除提案時のデータ喪失に関する説明の正確性

未承認（pending）のフィールドの削除を提案する場合、AIは「既存データが失われる」という説明を行いません。一度も承認されていないフィールドにはどのコンテンツにもデータが実在し得ないためです。一方、既に承認済みで実際にコンテンツが値を持っているフィールドの削除を提案する場合は、上記「影響分析」の通り正しく件数付きでデータ喪失の可能性を警告します。この2つは意図的に異なる挙動であり、バグではありません。

レート制限超過

HTTP 429

/api/schema-ai/chatには、原価割れ防止のための利用回数上限があります（詳細は下表）。上限に達すると、実際にはAI APIを呼び出さずにHTTP 429エラーを返します（無駄なコストを発生させないため）。

コスト・利用上限

AIクレジットを消費するのは/api/schema-ai/chat（チャットでの応答生成）のみです。「この内容で生成」ボタン（/api/schema-ai/generate、提案のステージング）はAI APIを呼び出さないため、クレジットを消費せず、レート制限の対象にもなりません。

デフォルトモデルはClaude Sonnet 5（effort: medium）で、画面上に常時表示されます。ユーザー向けには「1リクエスト＝1クレジット」として抽象化して表示されます。

プラン1時間あたり1日あたり1ヶ月あたり
Free5回15回300回（込み枠を使い切ると当月はブロック）
Paid60回500回上限なし（15,000クレジット/月は込み枠。超過分はStripe経由の従量課金）

Freeプランの月間上限はハードキャップ（達すると翌月まで新規リクエスト不可）、Paidプランの込み枠は超過してもブロックされず、超過分だけ従量課金される設計です。

関連ドキュメント