AIアシスタント

自然言語の指示からSQLを生成します。

場所： ワークスペース › ツール › AIアシスタント

ワークスペースのツールリストから「AIアシスタント」を開きます。画面下部のテキスト領域に要望を入力します。たとえば「先月の購入数が多い顧客を10人教えて」のように入力します。

アシスタントは対応するSQLを生成し、コードパネルに表示します。プロバイダの準備ができていれば（クラウドのプロバイダには自分のキーが必要で、Apple IntelligenceとOllamaには不要です）、応答は言語モデルが生成します。

キーワード： AI、人工知能、自然言語、OpenAI、Gemini、アシスタント

アシスタントのプロバイダを選びます。Apple Intelligenceにはキーが不要で、クラウドのプロバイダには必要です。

場所： AIアシスタント › 設定（歯車）

AIアシスタントのヘッダにある歯車アイコンをタップすると、設定パネルが開きます。そこでプロバイダを選びます。Apple Intelligenceはデバイス上で動作し、キーもアカウントも不要です。クラウドのプロバイダではAPIキーの入力を求められ、モデルも選べます。

パネルは選んだプロバイダに必要な項目に合わせて表示されます。キーを必要としないプロバイダでは、キーの行はありません。欠けているのではなく、必要ないのです。

キーを必要とするプロバイダで、まだキーを保存していない場合、アシスタントはデモモードで動作し、パターンの一致にもとづくサンプル応答を返します。サンプルのSQL文はMySQLのものなので、ほかのエンジンのセッションではデモモードはアシスタントの設定方法だけを案内します。

キーワード： APIキー、OpenAI、Gemini、設定、モデル、GPT、Apple Intelligence、キー不要、オンデバイス

デバイス上で動作するシステムのモデルです。キー不要、費用なしで、インターネットには何も送られません。

場所： Calíope › 設定 › AIアシスタント

Apple Intelligenceはシステムの言語モデルです。デバイス上で動作するので、キーもアカウントも不要で、費用もかからず、質問がインターネットに送られることもありません。

ピッカーに表示されるには2つの条件があります。対応するデバイスであること、そして「システム設定」でApple Intelligenceがオンになっていることです。どちらかが欠けていると、ピッカーには表示されません。淡色で表示されるのではなく、そもそも項目がなく、アシスタントはクラウドのプロバイダで引き続き動作します。

得意なのは短い要望です。エラーの説明、1つか2つのテーブルに対するクエリーの作成、構文の確認などです。大きなスキーマは苦手です。コンテキストウインドウが小さく、スキーマが収まらないときは、アシスタントが会話の中でそう伝え、どうすればよいかを提案します。

そこで役立つのが「スキーマをモデルに送信」スイッチです。同じパネルにあり、「設定」›「AIアシスタント」にもあります。オンにすると、使用中のデータベースのテーブル名、列名、外部キー名が送られます。行は決して送られません。オフにすると、スキーマは何も送られません。質問の中でテーブル名を挙げてください。

推奨事項：クエリーの対象が少数のテーブルなら、その名前を挙げてスイッチをオフにしてください。入力が1行増えるだけで、Apple Intelligenceではスキーマがあふれるのを防ぐことにもなります。

キーワード： Apple Intelligence、オンデバイス、キー不要、プライバシー、コンテキストウインドウ、スキーマ、収まらない

オープンなモデルのためのサーバで、指定した場所で動作します。キー不要で、クエリーごとの費用もかかりません。

場所： Calíope › 設定 › AIアシスタント

Ollamaは、オープンな言語モデルを自分のMacで動かすプログラムです。ollama.comからインストールし、ollama pull <name>でモデルを取得します（例：ollama pull qwen2.5-coder）。Calíopeはほかのプロバイダと同じようにOllamaとやり取りします。キーは不要で、クエリーごとの費用もかかりません。

アドレスに入力するもの。デフォルトのhttp://127.0.0.1:11434は、Ollamaが同じMacで動いているときに使えます。iPadやiPhoneからは、ネットワーク上のMacのアドレス（http://192.168.x.x:11434）を入力します。ここで忘れがちな手順があります。デフォルトではOllamaは自分自身からの接続しか受け付けません。ネットワークからの接続を受け付けるには、OLLAMA_HOST=0.0.0.0 ollama serveで起動してください。

送られるもの。質問と、「スキーマをモデルに送信」スイッチがオンなら使用中のデータベースのテーブル名、列名、外部キー名です。行は決して送られません。送り先はそのアドレスだけです。同じMac上ならMacの外には出ず、ネットワーク上ならそのMacまでで、それより先には行きません。

どのモデルを使うか。コード向けのモデルのほうが、はるかに良いSQLを返します。小さなモデルはSQLのブロックなしに文章で答えることがあり、その場合アシスタントは受け取ったテキストをそのまま表示し、エディタに送るものはありません。スキーマにない列名を作り出すこともあります。ローカルのモデルでは、待ち時間もコンピュータ次第です。タイムアウトになる場合は、「設定」で生成の上限を引き上げてください。

応答がない場合。アシスタントがアドレスを添えてそのことを伝えます。確認するのは2つで、この順番です。Ollamaが動いていること、そして入力したアドレスがOllamaのものであることです。

キーワード： Ollama、ローカル、キー不要、モデル、Llama、Qwen、ネットワーク、OLLAMA_HOST、アドレス

このMac上のAIクライアントが、書き込み権限のないユーザを通じて、データベースの一覧表示、テーブルの説明、読み出し専用のクエリーの実行を行えます。

場所： Calíope › 設定 › AIアシスタント

MCPサーバをオンにすると、このMacで動いているAIクライアント（Claude Desktop、Cursor、MCPを話すものなら何でも）が、チェックを付けた接続に対して、データベースの一覧表示、テーブルの説明、読み出し専用のクエリーの実行をCalíopeに依頼できます。

どこで動くか。Calíopeの中で、127.0.0.1で待ち受けます。つまりこのMacだけで、Calíopeが開いている間だけです。ネットワークにもインターネットにも何も公開されません。これは設定ではなく、そういう作りになっています。

何が見えるか。「設定」›「AIアシスタント」›「MCPサーバ」でチェックを付けた接続だけです。チェックを付けていないものはクライアントにとって存在せず、一覧にも表示されません。

何ができるか。読み出しだけで、それ以外は何もできません。1回の呼び出しで1つのSQL文、それも読み出しだけです。SELECT、書き込まないWITH、SHOW、EXPLAIN、DESCRIBE、VALUES、TABLE、ANALYZEのいずれかで、INSERT、UPDATE、DROP、SELECT … FOR UPDATEはサーバに触れる前に拒否されます。応答は200行までです。

見えないもの。この関門は、サーバに触れる前にCalíopeの中で確認する構文上の許可リストであり、読み出し専用のトランザクションではありません。副作用のある関数（pg_terminate_backend、setval、GET_LOCK、SLEEP）を呼ぶSELECTは通過します。そのため、公開する接続は書き込み権限も管理権限もないデータベースユーザのものにしてください。そうすれば、SQL文にできる最悪のことは、そのユーザにできることまでになります。

キー。キーがなければサーバは応答しません。キーはこのMacのキーチェーンに保存され、iCloudには送られず、設定のバックアップにも含まれません。漏れたと思ったら、「新しいキーを生成」で古いキーはすぐに無効になります。その場合は、クライアントに設定をもう一度ペーストする必要があります。

選んだポートがすでにほかのプログラムに使われている場合は、Calíopeがそれを伝え、サーバは起動しません。

キーワード： MCP、サーバ、クライアント、Claude Desktop、Cursor、読み出し専用、トークン、ポート、権限

オンにして、接続にチェックを付け、設定をコピーしてクライアントにペーストします。

5つの手順を、この順番で行います。

1. 「設定」›「AIアシスタント」›「MCPサーバ」で、スイッチをオンにします。
2. クライアントに見せたい接続にチェックを付けます。チェックを付けていないものはクライアントからは見えません。
3. 「設定をコピー」を押します。クライアントごとに1つ、計2つのブロックがクリップボードに入ります。ポートとキーはすでに入っています。
4. 必要なブロックをクライアントのファイルにペーストします。
- Cursor → ~/.cursor/mcp.json
- Claude Desktop → ~/Library/Application Support/Claude/claude_desktop_config.json
5. クライアントを再起動します。クライアントは起動時に設定を読み込みます。

Claude DesktopはHTTPではなく標準入出力でしか通信しないため、そのブロックではmcp-remoteを橋渡しに使っています。その設定でnpxがしているのはそれです。

クライアントが何かを見つけるにはCalíopeが開いている必要があります。閉じると、もう一度開くまでツールは応答しなくなります。

キーワード： MCP、設定、Cursor、Claude Desktop、JSON、クライアント

MCPでは行が送られます。送り先は自分のマシン上のクライアントで、その後どうするかはクライアント次第です。

Calíopeのアシスタントがモデルに送るのは、多くてもスキーマの名前だけです。MCPサーバは別物で、はっきり書いておく価値があります。ここでは行が送られます。クエリーへの応答とは、データ*そのもの*だからです。

送り先。この同じマシン上で動いている、設定したクライアントです。Calíopeはインターネットに何も送りません。

その後。クライアントが受け取ったものをどう扱うか（たとえば、回答を書くためにクラウドのモデルに送るなど）を決めるのは、Calíopeではなくそのクライアントとそのプライバシーポリシーです。データにとってそれが重要なら、接続にチェックを付ける前に判断してください。

止め方（影響の小さい順）：
- 接続のチェックを外す：クライアントにとってその接続は存在しなくなります。
- サーバをオフにする：すべて応答しなくなります。
- 新しいキーを生成する：誰かが古いキーを持っていても、すぐに使えなくなります。

記録されるもの。MCPで実行したものはすべて、自分で入力したものと同じように、接続と結果とともにクエリーログに残ります。拒否されたものはサーバに届かず、行も残りません。

キーワード： MCP、プライバシー、行、データ、クライアント、クラウド、クエリーログ

AIが生成したSQLをSQLエディタに直接送ります。

場所： AIアシスタント › エディタで開く

アシスタントがSQLのブロックを生成すると、コードの下に「エディタで開く」ボタンが表示されます。タップすると、SQLがSQLエディタに送られ、確認して実行できる状態になります。Macでは新しいタブで開き、iPad、iPhone、Apple Vision Proでは、エディタが前面に出て、それまでの内容がそのSQLに置き換わります。

アシスタントは何も実行しません。読み込んだものは、ほかのSQL文と同じようにエディタから実行します。接続に確認を求めるタグが付いていれば、書き込みの前に確認が求められます。接続が読み出し専用なら、サーバに届く前に拒否されます。

キーワード： 読み込む、エディタ、開く、生成されたSQL、挿入、エディタに送る

スイッチがオンになっている間、アシスタントは使用中のデータベースの構造を受け取ります。

場所： ワークスペース › ツール › AIアシスタント

「スキーマをモデルに送信」スイッチがオン（初期状態でオンです）で、データベースが選択されていると、Calíopeは使用中のスキーマのテーブル、列、外部キーの一覧を読み込み、要望と一緒にモデルに送ります。これにより、テーブルを手で説明しなくても、実際のテーブルに合ったSQLが返ってきます。データの行は1行も送られません。コンテキストのデータベースは、アシスタントのヘッダにあるセレクタで変更できます。セレクタはフィルタ欄付きで開くので、サーバにデータベースがたくさんあっても名前で見つけられます。

スイッチがオフのときは、スキーマは何も送られず、質問の中でテーブル名を挙げる必要があります。クエリーの対象が少数のテーブルなら、このほうが適しています。Apple Intelligenceでは、スキーマがモデルのウインドウからあふれるのを防ぐことにもなります。

サーバのアカウントにカタログを読む権限がない場合、アシスタントはコンテキストを読み込めなかったと警告します。この警告は読み込みが失敗したことを示すものです。スイッチをオフにしてもこの警告は出ません。その場合は誰も読み込みを求めていないので、何も読み込まれていないからです。

キーワード： スキーマ、コンテキスト、テーブル、information_schema、権限、スキーマのコンテキスト

モデルが1回の応答で生成できるテキストの量を調整します。

場所： Calíope › 設定 › AIアシスタント

AIモデルはトークンを単位に動作します。トークンはおよそ0.75語に相当するテキストの断片です。「SQLの最大長」の設定は、モデルが1回の応答で生成できるトークン数を決めます。影響するのは出力だけで、要望の長さや送られるスキーマの長さは制限しません。

選べるオプション（「設定」›「AIアシスタント」›「生成」）：

- コンパクト（800トークン）：単純なクエリーには十分です。1つか2つのテーブルに対するSELECT、基本的なフィルタ、単純なGROUP BYなどです。呼び出しごとの費用を抑え、待ち時間を短くします。ふだんのクエリーが短く単純な場合に使います。

- 標準（2,000トークン）：デフォルト値です。複数テーブルのJOIN、サブクエリー、中程度のCTEを含め、ほとんどのクエリーに適しています。

- 拡張（4,000トークン）：非常に複雑なクエリー向けです。何段にも連なるJOIN、多分岐のCTE、ストアドプロシージャ、長い分析クエリーなどです。ほかのオプションでSQLが途中で切れる場合に使います。

長さを増やすべきなのは？生成されたSQLが不完全に見える場合（たとえばFROM句が途中で切れている、JOINの閉じる部分が欠けているなど）は、モデルが書き終える前に上限に達したということです。拡張に切り替えると直ります。

減らすべきなのは？メンテナンスや簡単な診断のクエリーしか実行しないなら、コンパクトで十分です。プロバイダがトークン単位で課金する場合は費用が下がり、モデルが自分のマシンで動いている場合は待ち時間が短くなります。その場合、支払うのは時間だからです。

設定はすぐに反映されます。アプリを再起動したり、アシスタントを開き直したりする必要はありません。

キーワード： トークン、長さ、最大トークン数、切れたSQL、途中で切れる、費用、生成、最大長

AI APIの呼び出しをキャンセルするまでCalíopeが待つ時間を調整します。

場所： Calíope › 設定 › AIアシスタント

時間のかかるモデルがあります。推論モデル（OpenAIのo1、o3、o4、Gemini Ultraなど）や、自分のマシンで動いているモデルです。後者は、動かしているコンピュータの速度で応答します。複雑なクエリーでは、応答の生成に30秒以上かかることがあります。モデルが書き終える前にCalíopeが呼び出しをキャンセルすると、タイムアウトのエラーが表示されます。アプリの不具合のように見えますが、実際には時間が足りなかっただけです。

「設定」›「AIアシスタント」›「生成」には2つのスライダがあります。

- 「モデル一覧のタイムアウト」（5〜60秒、デフォルトは15秒）：選んだプロバイダが公開しているモデルの一覧を取得するときに、Calíopeが待つ時間です。

- 「SQL生成のタイムアウト」（10〜120秒、デフォルトは30秒）：モデルが生成したSQLを受け取るまで、Calíopeが待つ時間です。

生成のタイムアウトを増やすべきなのは？推論モデルや、メモリーの少ないMac上のローカルモデルを使っていて、複雑なクエリーの生成でエラーが出る場合は、値を60〜90秒に上げてください。これらのモデルは応答する前に考えるので、より多くの時間が必要です。

デフォルトのままでよいのは？gpt-4oやgemini-1.5-flashなら、ほとんどのクエリーで30秒あれば十分です。

変更はアプリを再起動しなくてもすぐに反映されます。

キーワード： タイムアウト、待機、遅い、o1、o3、o4、Gemini Ultra、エラー、キャンセル、推論、時間制限

マイクを使って、アシスタントへの要望をリアルタイムで文字にします。声がデバイスの外に出ることはありません。

場所： AIアシスタント › マイク

テキスト欄の横にあるマイクボタンをタップすると、音声入力が始まります。マイクの横のカプセルに表示されている言語で話してください。話すそばからテキストがリアルタイムで表示されます。録音中はアイコンが赤くなります。

もう一度ボタンをタップすると音声入力が止まり、書き起こされたテキストが欄に残ります。そのまま編集することも、↩で直接送ることもできます。

初回：システムが求めるアクセス権は1つだけで、マイクです。書き起こしがデバイスの外に出ることはないため、音声認識のアクセス権はもう必要ありません。拒否した場合は、Macでは「システム設定」›「プライバシーとセキュリティ」›「マイク」で、それ以外のデバイスでは「設定」›「Calíope」で元に戻せます。

言語：マイクの横に、聞き取っている言語のコード（EN、FR、IT…）を示すカプセルがあり、録音中は欄に言語名が略さずに表示されます。デフォルトではCalíopeで設定した言語に従い、システムに地域のバリエーションがあればそれを使います。たとえば、カナダのMacでアプリをフランス語で使っていれば、カナダのフランス語で音声入力します。別の言語を選ぶにはカプセルをタップします。モデルがまだデバイスにない言語は、選択肢に表示されるときにそのことが示されます。そうした言語を選ぶと、初めて音声入力するときにダウンロードされることを、欄の上の通知が知らせます。ダウンロードは1回だけで、それ以降はオフラインでも動作します。

声がデバイスの外に出ることはありません：書き起こしはすべてデバイス上で行われ、音声がサーバに送られることはないので、オフラインでも動作します。そのため、言語のモデルがない場合、Calíopeはインターネット経由で音声入力するのではなく、モデルがないことを伝えます。

開始時のエラー：マイクを押したときにエラーメッセージが表示される場合は、アクセス権が有効になっていること、ほかのアプリがマイクを占有していないことを確認してください。

キーワード： 音声、マイク、音声入力、書き起こし、話す、音声認識、発話

アシスタントとの会話の履歴全体をテキストファイルとして保存します。

場所： AIアシスタント › 書き出す（↑）

AIアシスタントのヘッダにある↑ボタン（矢印の付いた四角）をタップすると、表示中の会話を書き出せます。このボタンは、履歴に自分のメッセージが1件以上あるときだけ有効になります。

タップするとシステムの保存ダイアログが開きます。デフォルトのファイル名には現在の日時が入ります：caliope_ai_YYYYMMDD_HHmm.txt

書き出したファイルの内容：
- 書き出しの日時を記したヘッダ
- 使用中のデータベース、AIプロバイダ、使用したモデル
- 履歴のすべてのメッセージ（「[あなた]」または「[AIアシスタント]」の印付き）
- 生成されたSQLのブロック（ある場合）。--- SQL ---で区切られます

ファイルはUTF-8エンコーディングのプレーンテキスト（.txt）として保存され、どのテキストエディタや分析ツールでも開けます。

注：会話は履歴パネル（時計のアイコン）にも残るので、タブを閉じても失われません。書き出しは、会話をファイルとしてCalíopeの外に持ち出すためのものです。

キーワード： 書き出す、保存、会話、テキスト、履歴、TXT、ファイル、ダウンロード

AIが生成したSQLは確認が必要で、外部のサービスに送られます。

場所： AIアシスタント › SQLパネル

「AIによる生成」の表示

アシスタントが生成するSQLのブロックには、どれも下部に「AIによる生成・実行前に確認してください」と表示され、生成したプロバイダの名前も添えられます。実行する前に必ず確認してください。言語モデルは論理的な誤りを犯し、存在しないテーブル名を作り出します。

質問の送り先

選んだプロバイダによって異なり、プロバイダは5つあります。

- OpenAI：同社のサーバに送られます。キーは自分で用意します：platform.openai.com
- Google Gemini：同社のサーバに送られます。キーは自分で用意します：aistudio.google.com
- Anthropic Claude：同社のサーバに送られます。キーは自分で用意します：console.anthropic.com
- Apple Intelligence：どこにも送られません。モデルはシステムのもので、デバイス上で動作します。キーは不要です。
- Ollama：入力したアドレスにだけ送られます。自分のマシンか、ネットワーク上のマシンです。キーは不要です。

3つのクラウドのプロバイダでは、Calíopeはそのサービスのクライアントとして動作し、キーを自前のサーバに保存したり共有したりすることは決してありません。キーはデバイスのキーチェーンに保存されます。

送られるもの

質問を送ると、入力したテキストが、会話の直近3回分のやり取りと一緒に送られます。「スキーマをモデルに送信」スイッチがオンなら、使用中のデータベースのテーブル名、列名、外部キー名も送られます。接続に保護のための環境タグが付いている場合は、タグの名前とそのレベル（読み出し専用か、書き込みを確認するか）も送られ、モデルは読み出しだけを提案するか、何を書き込むかを明示します。

テーブルのデータ、パスワード、接続の資格情報は決して送られません。

→ プライバシーポリシーの全文

キーワード： 法的通知、AIによる生成、免責事項、APIキー、プライバシー、OpenAI、Gemini、送信されるデータ、確認、セキュリティ

アシスタントとの会話はすべて保存され、再開できます。

場所： AIアシスタント › 履歴（時計）

AIアシスタントのヘッダにある時計のアイコンをクリックすると、チャットの横に履歴パネルが開きます。会話は最初の質問を送った時点で保存されるので、回答に失敗したり接続を切り替えたりしても、質問が失われることはありません。

会話の再開。一覧の行をクリックすると、その会話がすべてのコンテキストとともに使用中の会話になり、続く質問は同じスレッドで続きます。最初から始めるには、ヘッダの「+」ボタンを使います。前のスレッドは履歴に残ります。

検索。上部の欄では、タイトルだけでなく、生成されたSQLを含むすべてのやり取りのテキストを検索します。

各行に表示されるもの。タイトルは最初の質問から作られます。その下に、日付、コンテキストだったデータベース、スレッドの質問の数が表示されます。

削除。行のコンテキストメニューで削除できます。履歴全体を削除するには、下部のゴミ箱のアイコンを使います。

保存場所。このデバイスの~/Library/Application Support/Caliope/ai_history.jsonです。最新の200件の会話が保持され、その上限に達するとパネルの下部にそのことが表示されます。幅の狭いウインドウでは、パネルは引き出しに折りたたまれ、横の帯から開けます。

キーワード： 履歴、会話、保存、再開、検索、時計、削除

オプション：会話を自分のプライベートなiCloudにアップロードして、すべてのデバイスで使えるようにします。

場所： AIアシスタント › 履歴 › iCloud（クラウド）

履歴はデフォルトではローカルです。同期は、履歴パネルの下部にあるクラウドのアイコンでオンにします。Calíopeはまず、すでにある会話をどうするか（既存の会話をアップロードするか、新しい会話だけを同期するか）を尋ねます。

アップロードされるもの。タイトル、日付、コンテキスト（接続、データベース、プロバイダ、モデル）、そしてやり取りの全文（質問、回答、生成されたSQL）です。送り先はCalíopeのサーバではなく、iCloudアカウントのプライベートなデータベースです。

資格情報。デバイスの外に出る前に、テキストはクエリーログと同じ伏せ字処理を通ります。IDENTIFIED BY '…'やSET PASSWORDは'***REDACTED***'になります。ローカルのファイルには元のテキストが残ります。

オフにすると、iCloudにある会話をこのデバイスに残すかどうかをCalíopeが尋ねます。ダウンロードすると、ローカルの会話と結合され、それぞれ最新の版が残ります。「オフにしてiCloudのコピーを削除」も選べます。これを選ぶと、すべてのデバイスでiCloudからコピーが消えます。選ばなければiCloudに残り、同期がオンのほかのデバイスは引き続きそれを読みます。

何かが失敗すると、アイコンが赤くなります。クリックすると理由（iCloudアカウントがない、制限がある、ネットワーク）が表示され、再試行するか同期をオフにできます。

削除。同期がオンのときに会話や履歴全体を削除すると、iCloudからも削除されます。

キーワード： iCloud、同期、クラウド、CloudKit、デバイス、プライバシー、伏せ字

回答、そのSQLだけ、または会話全体をコピーします。

場所： AIアシスタント › 回答をコピー

各吹き出しの下に「回答をコピー」ボタンがあります。テキストをコピーし、回答にSQLのブロックがあればSQLもコピーします。ボタンは2秒間チェックマークを表示して完了を知らせます。

SQLだけ。コードパネルのヘッダの、「エディタで開く」の横に「SQLをコピー」があります。

一部分だけ。吹き出しとSQLパネルのテキストは選択できます。一部をドラッグして選び、⌘Cでコピーします。

会話全体。吹き出しのコンテキストメニューでそのやり取りをコピーできます。また、履歴の行のコンテキストメニュー›「会話をコピー」で、日付とコンテキストのヘッダ付きの全文をコピーできます。書き出しボタンと同じ形式です。

キーワード： コピー、クリップボード、SQL、選択、全文、回答