自然文からクエリを組み立てる（AI アシスト）
「最新の投稿を、いいね数と投稿者の表示名つきで」のような文から、クエリの形を組み立てる機能です。 TypeSafe 社の AI モデル Jev が、取り込んだスキーマの中の候補から選び、GalleonQL がそれを クエリビルダー に入れます。
概要
- Jev はクエリを書くのではなく、スキーマにあるフィールドの中から選ぶだけです。候補に無いものは選べないので、 出来上がるクエリは必ずスキーマ上有効な形になります。
- Jev の答えは提案です。ルートのフィールド、入れるフィールド、引数の値を画面に並べ、あなたが確かめて 確定したものだけがビルダーに入ります。確率と「要確認」の印を見ながら、外す・足すをその場で行えます。
- 入れたものは add Query / add Child で入れたものと同じで、ビルダーでそのまま直せます。既にあるクエリは 置き換えず、後ろに足します。
- AI アシストは Pro の機能です。 Free では入力欄も設定の欄も出ず、自分の API キーがあっても使えません。 Pro のかたは、Pro に含まれる月ごとの枠（トークン換算で毎月 約 470 万トークン）をまず使います。枠を使い切った後は、 あなた自身の TypeSafe の API キーを保存していれば、そのキーで TypeSafe へ直接つないで続けて使えます（上限なし。 費用はキーの持ち主に請求されます。TypeSafe は 2026 年 10 月時点で招待制の早期提供です。下の「Pro の枠で使う」）。
前提
- スキーマの取り込み が済んでいること（候補はスキーマから作ります）。
- Pro プランであること（Free では使えません）。枠を使い切った後に自分のキーで続けるときは、TypeSafe の API キーが 要ります。キーは TypeSafe のダッシュボード（console.typesafe.ai/keys）で発行します。
設定する
1. API キーを保存する
- トップバーの 設定（⚙） を開き、左の 「AI アシスト」 のタブを選びます（Pro のときだけ出ます）。AI アシストの欄に出る「設定を開く」から開いたときは、このタブが選ばれた状態で開きます。
- 「AI アシスト（Jev）」の欄の「TypeSafe の API キー」にキーを貼り付け、「保存」を押します。 入力欄は伏せ字です。保存すると「保存済み（末尾 xxxx）」と、キーの末尾 4 文字だけが表示されます。
- 保存したキーを消すときは「削除」を押します。
キーはこのコンピュータの中にだけ保存されます。プロジェクトのエクスポート には含まれません。 自分のキーを使うときは、利用料はご自身の TypeSafe の課金になります（設定の欄にも常に 1 行出ています）。 Pro のかたは、キーを保存していてもまず Pro の枠を使い、枠を使い切った後に自分のキーで送ります。
2. 接続テストをする
「接続テスト」を押すと、TypeSafe へ実際に小さな問い合わせを送り、正しい答えが返ってきたことを 確かめてから「接続できました（N トークン）」と表示します。
接続テストに通ると、トップバーの URL 欄のすぐ下に自然文の入力欄が現れます（Pro の枠を使える版では、キーや 接続テストに関わらず最初から表示されます。Free では表示されません）。
3. 利用状況を確かめる
設定の同じ欄の「利用状況を見る」を押すと、利用状況のポップアップが開きます（設定の欄には利用状況そのものは 出ません。見方は下の「利用状況を見る」）。自分のキーで送った分は、ポップアップの「API キー」のタブに出ます。これは このコンピュータの GalleonQL から送った分です。同じキーを他のアプリでも使っている場合、アカウント全体とは合いません。 アカウント全体の利用量と利用料は、そのタブの「アカウント全体の利用量（TypeSafe のコンソール）」から確かめられます （GalleonQL は利用料を表示しません）。
Pro の枠で使う
Pro のかたは、Pro に含まれる枠で使えます。自分の TypeSafe キーを保存していても、まず Pro の枠を使います。 設定の「AI アシスト（Jev）」の欄に「Pro には、トークン換算で毎月 約 470万トークンの利用枠が含まれます。使い切った後は、 自分のキーがあればそのキーで続けて使えます」と出ているときは、この方法です。URL 欄の下の入力欄も、接続テストなしで 最初から現れます。
- 枠はトークン換算で毎月 約 470 万トークンです。入力トークンで数えます（中継サーバーの処理の分も、トークンに 換算して入力トークンに含めます）。
- 問い合わせは Trimix の中継サーバーを通って Jev に届きます。Pro であることは、問い合わせのたびに確かめます。
- 上限は月ごとです。右の欄に「今月の残り ○%」と出ます。起動した直後で、まだ中継サーバーから数を受け取って いないときは「今月の残り ---」と出ます（推測では表示しません。押すと利用状況を読みます）。
- 枠を使い切ったとき:
- 自分のキーを保存していれば、同じ問い合わせを自分のキーで続けて送ります。右の欄に「今月の枠を使い切りました・ 自分のキーで送っています」と出ます。この間の利用料はご自身の TypeSafe の課金になります（表示にマウスを置くと、 Pro の枠が戻る日付が出ます）。その日付（毎月 1 日・協定世界時）を過ぎると、また Pro の枠から使います。
- 自分のキーが無ければ「今月の枠を使い切りました（日付 に戻ります）」と出て、その日付（毎月 1 日・協定世界時） まで使えません。日付はお使いの地域の表記で出ます。
- Jev が混み合っているときは「Jev が混雑しています（時刻 に解除）」と出ます。その時刻のあとにもう一度お試しください。
- Pro の枠を使うかた全員の合計がその日の上限に達すると「本日の利用の上限に達しました（時刻 に戻ります）」と出ます。 その時刻（毎日 0 時・協定世界時）のあとにもう一度お試しください。あなたの今月の枠は減りません。
- Jev の混雑・1 日の上限・中継サーバーへの通信の失敗・中継サーバー側の不具合のときは、自分のキーを保存していても 自分のキーには切り替えません（あなたの課金で黙って送ることはしません）。
- Pro でなくなった場合は、入力欄と設定の欄が消え、AI アシストは使えなくなります（自分のキーを保存していても使えません）。 Pro のままで購入を確かめられなかったときは、自分のキーがあればそのキーで送り、無ければ「Pro の確認ができませんでした」と出ます。
利用状況を見る
次のどちらかで「Jev の利用状況」のポップアップが開きます。
- 右の欄の表示を押す。「今月の残り ○%」（起動した直後は「今月の残り ---」）のほか、自分のキーで送ったときの 「今回 ○ トークン」や「枠を使い切り・自分のキーで送信」も押せます。
- 設定の「AI アシスト（Jev）」の欄の「利用状況を見る」を押す（Pro のかたと、自分のキーを保存しているかたに出ます。 組み立てる前でも開けます）。
ポップアップには「Pro の枠」と「API キー」の 2 種類があります。Pro で自分のキーも保存しているかたには、 上にタブが 2 つ出ます。どちらか一方だけのかたには、その一方だけが出ます（タブは出ません）。
- 最初に開くタブは、Pro の枠を今月使い切っていれば「API キー」、そうでなければ「Pro の枠」です。自分のキーで送ったときの 右の欄の表示から開いたときは「API キー」で開きます。
- タブはクリックで切り替えます（Tab キーで選んで Enter / Space でも切り替えられます）。自分でタブを切り替えた後は、 記録を読み終えてもタブは変わりません。
開くたびに、最新の記録を 1 回読みます（開いている間は自動で読み直しません）。読んでいる間は「読み込み中…」とだけ出て、 数は出ません。どちらのタブも 1 か月分ずつ表示し、利用料は出しません。
Pro の枠のタブ（中継サーバーの記録。Pro の枠で送った分だけ）:
- 今月は「残り ○%」と、枠が戻る日付（毎月 1 日・協定世界時）を出します。使い切った月は「使い切りました」と出ます。
- 見出しの下のバーは、残りの枠を表します。満タンから始まり、使うほど短くなります（前の月も同じです）。
- 前の月は「使った割合 ○%」と、その月の期間（協定世界時）を出します。
- 表には、問い合わせの回数と、入力トークン（中継サーバーの処理の分を含む）と上限を出します。最後の問い合わせで上限を またいだ月も、入力トークンは上限と同じ数で表示します。今月まだ使っていなければ「今月はまだ使っていません」と出ます。
- 読めなかったときは理由と「もう一度」ボタンが出ます。Pro の購入を確かめられなかった場合は「Pro の確認ができませんでした」と出て、 前の月の記録も見られません。
API キーのタブ（このコンピュータの記録。自分のキーで送った分だけ）:
- このコンピュータの GalleonQL から自分のキーで送った分の、問い合わせの回数と入力トークンを出します（上限とバーはありません）。 今月まだ使っていなければ「今月はまだ使っていません」と出ます。
- 「アカウント全体の利用量（TypeSafe のコンソール）」から、アカウント全体の利用量と利用料を確かめられます。
どちらのタブも共通です。
- 前の月の記録があるときは、月の名前の左右の ‹ ›（またはキーボードの ← →）で切り替えられます。 使わなかった月は記録が無いので飛ばします。
- 下に、記録を読んだ時刻（「○ 時点」）を出します。
組み立ての流れ
1. 文を入れて組み立てる
URL 欄の下の入力欄（✨）に、欲しいデータを文で書き、Enter を押すか、送信ボタンの下の「組み立て」を 押します。日本語でも英語でも書けます。入力欄は、空のときは 1 行です（案内文が入りきらないときは右が「…」で切れ、 マウスを載せると全文が出ます）。Shift+Enter で改行でき、文を打つと入力欄は行数に合わせて広がります （8 行を超える分は欄の中でスクロールします）。問い合わせている間は「組み立て」ボタンのアイコンが回り、右の欄に 「Jev に問い合わせ中…」と出ます。
2. プロジェクトごとの初回確認
そのプロジェクトで初めて使うときだけ、「このプロジェクトのスキーマの一部を TypeSafe へ送ります」と、 送るもの・送らないものが表示されます。「送る」で続け、「やめる」なら何も送りません。
3. ルートを選ぶ
入力欄の下に、どのフィールドから始めるかの候補が 3 件、確率つきで出ます。1 位が選ばれた状態なので、 そのままでよければ Enter で確定します。
- ↑ / ↓ で選び直し、Enter で確定、Esc で閉じます。候補はクリックでも確定できます。
- Jev が「該当なし」と答えたときは「見つかりません」と出し、近い候補を 3 件並べます（選ばれた状態には しません）。
4. 提案一覧を確かめて確定する
ルートを確定すると、そのフィールドの直下に入れるものの提案一覧が出ます。
| 表示 | 意味 |
|---|---|
| チェックの付いたフィールド | Jev が「文が求めている」と答えたもの（確率 50% 以上） |
| 「要確認」の印 | Jev が迷ったもの（フィールドは確率 30〜70%、引数の値は確信度が低いもの） |
| 引数の値の選択欄 | 値が決まっている引数（列挙型）。Jev が選んだ値が選ばれています。「指定なし」もあります |
| 「変数（要入力）」 | 値を自分で入れる必須の引数（ID・日付・数値など）。GraphQL 変数として入ります |
| 「変数として足す」 | 値を自分で入れる任意の引数。チェックを付けると変数として入ります |
チェックを外す・付ける・値を選び直すをその場で行い、Enter（または「確定」）でビルダーに入れます。 変数を入れたときは、ビルダーが変数モードに切り替わり、値は変数の入力欄で入れます （クエリビルダー の手順 9「入力モードを切り替える（インライン／変数）」）。
確定すると、キー操作の先（フォーカス）がクエリパネルへ移ります（入れたフィールドの行、選べない行なら クエリパネル全体が枠で囲まれます）。続けて Enter を押しても組み立て直しはしません。もう一度組み立てるときは 入力欄をクリックしてから Enter を押します。確定のあとの表示は Esc で閉じます。
5. おすすめの枝を展開する
提案一覧と、確定したあとの表示には「おすすめの枝」（▸ author のようなボタン）が出ます。押すと、その フィールドを今のフィールドの下へ展開し、同じように提案一覧を出します。何度でも続けられます。提案一覧で枝を 押したときは、その時点の選択のまま確定してから展開します。
自分のキーで送ったときは、右の欄に、この組み立てで送った入力トークン（「今回 N トークン」）が出ます。押すと 利用状況のポップアップを「API キー」のタブで開きます。組み立てたクエリは自動では送信しません。確かめてから 「▶ 送信」を押してください。
送るもの・送らないもの
| 送るもの | 送らないもの |
|---|---|
| 入力した文 | 認証情報（トークン・パスワード） |
| 候補の型名・フィールド名・型 | ヘッダー |
| 候補の説明文（スキーマに書かれたもの） | 環境変数の値 |
| 列挙型（enum）の値 | URL |
| レスポンス |
送れる項目はアプリの中で決まっていて、それ以外のものは送れない作りになっています。
Pro の枠で使うときは、上の内容は Trimix の中継サーバーを通って TypeSafe に届きます。加えて、Pro の確認のために 購入の情報（Mac App Store 版は App Store の取引の署名付き情報、Windows / Linux 版はライセンスキー）を中継サーバーに 送ります。中継サーバーに残るのは、利用者を見分ける ID と使用量です。入力した文とスキーマの候補は保存しません。
費用と利用状況
- 自分のキーで使うとき、費用は TypeSafe からキーの持ち主に請求されます。GalleonQL の料金には含まれません。 Pro の枠で使うときは追加の費用はかかりません（月の上限があります）。Pro の枠を使い切った後に自分のキーで送った分は、 ご自身の TypeSafe の課金になります。
- GalleonQL は利用料を表示しません。利用料は TypeSafe のコンソール（利用状況のポップアップの「API キー」のタブの 「アカウント全体の利用量（TypeSafe のコンソール）」）で確かめてください。
- 1 回の組み立て（ルートと 1 つの節）は、デモのスキーマで 1,700 トークン前後、枝を 1 つ展開して 2,700 トークン 前後でした。大きなスキーマほど多くなります。
現時点でできないこと（制限事項）
- 組み立てられるのは Query だけです（Mutation・Subscription は対象外）。
- 送信は自動で行いません。
- ID・日付・数値・自由な文字列の引数の値は作りません。変数にして空欄のまま入れるので、自分で入れてください。
- union 型のフィールド（インラインフラグメントが必要なもの）は候補に出ません。
- Jev の答えは正しいとは限りません。提案は必ず確かめてから確定してください。
- 1 つの型にフィールドが非常に多いスキーマ（ルートが 254 件を超えるなど）では、候補を送れずエラーになります。
うまくいかないときは
| 症状 | 想定される原因 | 対処 |
|---|---|---|
| URL 欄の下に入力欄が出ない | キーを保存していない、または接続テストに通っていない | 設定の「AI アシスト（Jev）」でキーを保存し、「接続テスト」を押す |
| キーを入れていないのに入力欄が出ない | Pro ではない、または中継サーバーの設定が入っていない版 | Pro にするか、自分の TypeSafe キーを保存して接続テストをする |
| 入力欄が押せない（「スキーマを取り込むと使えます」） | スキーマを取り込んでいない | スキーマの取り込み を行う |
| 「キーが無効です」と出る | キーが間違っている・無効になった | 「設定を開く」からキーを保存し直し、接続テストをする |
| 「利用上限を超えました（429）」 | TypeSafe の利用上限 | 少し待ってから組み立て直す |
| 「TypeSafe が混雑しています（529）」 | TypeSafe 側の混雑 | 少し待ってから組み立て直す |
| 「今月の枠を使い切りました（日付 に戻ります）」 | Pro の枠を使い切った（自分のキーを保存していない） | 日付まで待つか、自分の TypeSafe キーを保存する（次の問い合わせから自分のキーで送ります。利用料はご自身の課金です） |
| 「枠を使い切り・自分のキーで送信」 | Pro の枠を使い切ったので、保存した自分のキーで送っている | 想定どおりです。枠が戻る日付（毎月 1 日・協定世界時）まで、利用料はご自身の TypeSafe の課金になります |
| 「Jev が混雑しています（時刻 に解除）」 | 中継サーバー全体が制限中（自分のキーには切り替えません） | 示された時刻のあとにもう一度試す |
| 「本日の利用の上限に達しました（時刻 に戻ります）」 | Pro の枠を使うかた全員の合計が、その日の上限に達した（自分のキーには切り替えません） | 示された時刻のあとにもう一度試す |
| 「Pro の確認ができませんでした」 | Pro の購入・ライセンスを確かめられなかった（失効・返金・ネットワーク）。自分のキーを保存していない | プランの確認 をして、しばらくしてからもう一度試す |
| 「前の問い合わせを処理中です…」 | 続けて問い合わせた | 少し待ってからもう一度試す |
| 「中継で問題が起きました（しばらくしてから試してください）」 | 中継サーバー側の不具合 | しばらくしてからもう一度試す |
| 利用状況のポップアップに「Pro の確認ができませんでした」と出る | Pro が失効した、または購入・ライセンスを確かめられなかった | プランの確認 をして、「もう一度」を押す |
| 「TypeSafe に接続できません」 | ネットワークに接続していない | 接続を確かめてから組み立て直す |
| 「中継サーバーに接続できません（ネットワークを確かめてください）」 | Pro の枠で使っていて、中継サーバーに届かない（ネットワークに接続していない） | 接続を確かめてから、組み立て直すか「もう一度」を押す |
| 「展開先のフィールドがビルダーにありません」 | 枝を展開する前に、親のフィールドを削除した・別のタブに切り替えた | もう一度ルートから組み立てる |
| Mutation のタブで組み立てたら新しいタブが開いた | Query と Mutation は 1 つのクエリに混ぜられない | 想定どおりです。新しいタブに Query として入ります |
関連ドキュメント
- 組み立てたあとの直し方: クエリビルダー
- 候補の元になるスキーマ: スキーマの取り込み
- 送信と結果の見方: クエリの送信とレスポンス
- マニュアルの索引: GalleonQL ユーザーマニュアル