> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL を AI API に接続する

> VillageSQL の vsql_ai 拡張機能を使用して MySQL を AI API に接続する方法 — 拡張機能のインストール、API キーの設定、プロバイダーとモデルの選択。

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

VillageSQL の `vsql_ai` 拡張機能を使用すると、SQL クエリから AI 言語モデルを直接呼び出せます。最初の `ai_prompt()` を実行する前に、拡張機能をインストールし、API キーを用意する必要があります。このガイドでは、セットアップ、プロバイダーの選択肢、および本番環境に移行する前に重要となるセキュリティ上の考慮事項を説明します。

## 拡張機能のインストール

```sql theme={null}
INSTALL EXTENSION vsql_ai;
```

API キーを設定したら（後述）、テスト呼び出しを行います。

```sql theme={null}
SET @anthropic_key = 'sk-ant-your-key-here';
SELECT ai_prompt('anthropic', 'claude-haiku-4-5', @anthropic_key, 'Say hello') AS test;
```

## API キーの設定

`ai_prompt()` 関数と `ai_embedding()` 関数は、API キーをパラメータとして受け取ります。推奨されるパターンは、接続時に設定するセッション変数です。ログファイルに残る可能性のあるクエリに、キーのリテラルを埋め込まないでください。`'local'` プロバイダーの場合は空文字列を渡します。API キーは不要です。

```sql theme={null}
-- Set once per connection, use everywhere
SET @anthropic_key = 'sk-ant-your-key-here';
SET @openai_key    = 'sk-your-openai-key';
SET @google_key    = 'your-google-ai-key';

-- Then use the variable
SELECT ai_prompt('anthropic', 'claude-haiku-4-5', @anthropic_key, 'Hello') AS response;
```

**避けるべきこと:**

```sql theme={null}
-- Don't do this — key is visible in slow query logs and PROCESSLIST
SELECT ai_prompt('anthropic', 'claude-haiku-4-5', 'sk-ant-12345...', 'Hello');
```

セッション変数は、ファイルに書き出す SQL ではなく、アプリケーションの接続セットアップで設定してください。`SET @key = '...'` ステートメント自体は、キーを含めてそのまま `performance_schema.events_statements_history`（MySQL 8.4 ではデフォルトで有効）に記録され、有効にしている一般クエリログやスロークエリログにも記録されます。セッション変数を使用すると、キーを使用する*クエリ*からはキーが除外されますが、キーを設定するステートメントからは除外されません。これを避ける唯一の方法は、キーをリテラルの SQL テキストとして一切送信しないことです。プリペアドステートメントのパラメータとしてバインドするか、サーバーが解析する SQL テキストにリテラルを含めないクライアント側の置換メカニズムを使用してください。

## プロバイダーとモデルの選択

### Anthropic

最適な用途: 複雑な推論、長い文書、コード生成、および指示に従うタスク。

```sql theme={null}
-- Fast and cost-effective
SELECT ai_prompt('anthropic', 'claude-haiku-4-5', @anthropic_key, @prompt);

-- Balanced — speed and intelligence
SELECT ai_prompt('anthropic', 'claude-sonnet-5', @anthropic_key, @prompt);

-- Recommended default — complex agentic and enterprise work
SELECT ai_prompt('anthropic', 'claude-opus-5', @anthropic_key, @prompt);
```

**Claude モデル:**

* `claude-fable-5` — 最も高性能。高度な推論と長期的な作業向け
* `claude-opus-5` — 推奨デフォルト。複雑なエージェント型コーディングとエンタープライズ作業向け
* `claude-sonnet-5` — 速度と知能の最良の組み合わせ
* `claude-haiku-4-5` — 最速かつ最もコスト効率が高い

以前の世代も引き続きサポートされています: `claude-opus-4-8`、`claude-opus-4-7`、`claude-opus-4-6`、`claude-opus-4-5-20251101`、`claude-sonnet-4-6`、`claude-sonnet-4-5-20250929`。

Anthropic は `ai_embedding()` をサポートしていません。

### Google Gemini

最適な用途: 埋め込みの生成とマルチモーダルタスク。

```sql theme={null}
-- Prompting
SELECT ai_prompt('google', 'gemini-2.5-flash', @google_key, @prompt);

-- Embeddings (3072 dimensions)
SELECT ai_embedding('google', 'gemini-embedding-001', @google_key, @text);
```

### OpenAI

最適な用途: 広く採用されている `text-embedding-3` ファミリーによる埋め込みの生成。

```sql theme={null}
-- Prompting
SELECT ai_prompt('openai', 'gpt-4o-mini', @openai_key, @prompt);

-- Embeddings (1536 dimensions)
SELECT ai_embedding('openai', 'text-embedding-3-small', @openai_key, @text);

-- Embeddings (3072 dimensions — higher accuracy)
SELECT ai_embedding('openai', 'text-embedding-3-large', @openai_key, @text);
```

### ローカル（Ollama）

最適な用途: ローカル開発と、ネットワークの外に出せないプライベートなデータ。`127.0.0.1:11434` で実行中の [Ollama](https://ollama.com) が必要です。API キーは不要で、空文字列を渡します。

```sql theme={null}
-- Prompting
SELECT ai_prompt('local', 'llama3.2', '', @prompt);

-- Embeddings
SELECT ai_embedding('local', 'nomic-embed-text', '', @text);
```

Ollama でプルしたモデルであれば、どれでも使用できます。一般的なチャットモデル: `llama3.2`、`mistral`、`gemma2`。一般的な埋め込みモデル: `nomic-embed-text`、`mxbai-embed-large`。

### プロバイダーの比較

| プロバイダー | プロンプト | 埋め込み | 最適な用途 |
| :- | :- | :- | :- |
| `'anthropic'` | 対応 | 非対応 | 推論、指示、コード |
| `'google'` | 対応 | 対応 | バランス型。Gemini の埋め込み |
| `'openai'` | 対応 | 対応 | OpenAI エコシステム。text-embedding-3 |
| `'local'` | 対応 | 対応 | ローカルの Ollama。API キー不要。プライベートなデータ |

## タイムアウトとレート制限に関する考慮事項

AI API の呼び出しには 5〜30 秒かかります。MySQL はデフォルトではクエリの実行時間を制限しませんが（`max_execution_time` は `0`、つまり無制限）、アプリケーションやコネクションプールがこれを設定している場合、30 秒かかる AI 呼び出しは途中で打ち切られることがあります。AI クエリを実行するセッションでは、制限を明示的に引き上げるか確認してください。

```sql theme={null}
SET SESSION max_execution_time = 60000;  -- 60 seconds
```

多数の行に対するバッチ操作では、これが重要です。各行で `ai_prompt()` を呼び出す 1000 行の UPDATE は、30 分以上かかることがあります。

すべてのプロバイダーは、1 分あたりに実行できるリクエスト数にレート制限を設けています。レート制限に達すると、`ai_prompt()` は NULL を返します。一括操作では、50〜100 行のバッチで処理し、アプリケーションのループ内でバッチ間に一時停止を入れてください。バッチのパターンについては、[MySQL クエリから AI モデルを実行する](https://villagesql.com/docs/ja/guides/ai-prompts-in-mysql.md)を参照してください。

## よくある質問

#### セッション変数の代わりに MySQL のテーブルに API キーを保存できますか？

できますが、あるセキュリティリスクを別のリスクと交換することになります。テーブル方式ではキーを読み取るために SELECT が必要で、そのクエリもログに記録されます。アプリケーションフレームワークがプログラムで設定するセッション変数が、最もクリーンな選択肢です。

#### API 呼び出しが失敗するとどうなりますか？

関数は NULL を返します。テスト時には結果の NULL を確認してください。呼び出しの直後に `SHOW WARNINGS` を実行してください。`vsql_ai` は実際の失敗理由（無効なキー、不明なプロバイダー、サポートされていないモデルなど）を示す `Warning 3200` を発生させます。これは単なる NULL よりもはるかに診断に役立ちます。一般的な原因: 無効な API キー、ネットワークのタイムアウト、レート制限への到達、またはサポートされていないモデル名。

#### 同じクエリで異なるプロバイダーを使用できますか？

はい。`ai_prompt()` は通常の関数です。同じ SELECT 内で、異なるプロバイダーとモデルの組み合わせで呼び出せます。

#### モデル名は安定していますか？

プロバイダーは時間とともにモデル名を変更します。ここに記載した名前は、拡張機能で現在テスト済みのモデルと一致します。利用可能な最新のモデル識別子については、プロバイダーのドキュメントを確認してください。

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

| 問題 | 解決策 |
| :- | :- |
| `FUNCTION <database>.ai_prompt does not exist` | `INSTALL EXTENSION vsql_ai` を実行します |
| `ai_prompt()` が NULL を返す | API キーが有効か確認します。`max_execution_time` が十分に大きいか確認します。モデル名を検証します |
| クエリがタイムアウトする | `SET SESSION max_execution_time = 60000` を設定します |
| キーがスロークエリログに表示される | SQL の文字列リテラルではなく、アプリケーションコードで設定したセッション変数を使用します |

## 関連項目

* [MySQL クエリから AI モデルを実行する](https://villagesql.com/docs/ja/guides/ai-prompts-in-mysql.md) — 拡張機能の設定後に ai\_prompt() を使用する
* [MySQL でベクトル埋め込みを生成する](https://villagesql.com/docs/ja/guides/vector-embeddings.md) — セマンティック検索のために ai\_embedding() を使用する


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.