> ## 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）

最适合：本地开发，以及不能离开您网络的私有数据。需要 [Ollama](https://ollama.com) 在 `127.0.0.1:11434` 上运行。不需要 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 分钟以上。

所有提供商都对每分钟的请求数量施加速率限制。触发速率限制会导致 `ai_prompt()` 返回 NULL。对于批量操作，请按每批 50–100 行处理，并在应用程序循环中在各批之间加入暂停。有关批处理模式，请参阅 [从 MySQL 查询运行 AI 模型](https://villagesql.com/docs/zh/guides/ai-prompts-in-mysql.md)。

## 常见问题

#### 我可以把 API 密钥存在 MySQL 表中而不是会话变量里吗？

可以，但这是用一种安全风险换另一种。使用表的方式需要一条 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/zh/guides/ai-prompts-in-mysql.md)——配置好扩展后使用 ai\_prompt()
* [在 MySQL 中生成向量嵌入](https://villagesql.com/docs/zh/guides/vector-embeddings.md)——使用 ai\_embedding() 进行语义搜索


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