> ## 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 的 vsql_ai 扩展

> vsql_ai 扩展从 SQL 调用 Claude、Gemini、OpenAI 和本地 Ollama 模型，在查询内部返回提示回答和嵌入向量。

大多数数据库 AI 工作都遵循同一种模式：读取行，发送给模型，等待，
再把答案写回去。`vsql_ai` 通过从 SQL 直接调用模型省去了中间环节。
两个函数就能覆盖这些工作，一个用于提示，一个用于嵌入。
提示函数可用于 Anthropic Claude、Google Gemini、OpenAI，或通过 Ollama
在本地运行的模型。嵌入函数可用于除 Anthropic 之外的所有这些提供商。

| | |
| - | - |
| **维护者** | VillageSQL |
| **源代码和完整文档** | [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) |
| **许可证** | GPL-2.0 |

## 安装

如果您使用安装脚本、Docker 镜像或发行版压缩包安装了 VillageSQL，
`vsql_ai.veb` 已经位于服务器的 `lib/veb/` 目录中。
用一条语句将它安装到服务器中：

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

确认它已存在：

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_ai';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_ai        |
+----------------+
```

要自行构建，请按照[存储库](https://github.com/villagesql/vsql-ai)中的
构建说明进行操作。

## 新增内容

| 函数 | 返回 | 作用 |
| - | - | - |
| `ai_prompt(provider, model, api_key, prompt)` | 文本 | 发送提示并返回模型的回复 |
| `ai_embedding(provider, model, api_key, text)` | 文本 | 以 JSON 数组形式返回嵌入向量 |

`provider` 为 `anthropic`、`google`、`openai` 或 `local`。本地模型通过
Ollama 运行，API 密钥留空即可。`ai_embedding` 支持 Google、OpenAI 和
本地模型。

## 示例

向本地模型提问：

```sql theme={null}
SELECT ai_prompt('local', 'llama3.2', '', 'Reply with exactly one word: the capital of France.') AS answer;
```

```
+--------+
| answer |
+--------+
| Paris. |
+--------+
```

模型用自己的措辞回答，因此您得到的回复会与这里的不同。

把文本转换成向量并检查它的宽度：

```sql theme={null}
SELECT JSON_LENGTH(ai_embedding('local', 'nomic-embed-text', '', 'Machine learning')) AS dimensions;
```

```
+------------+
| dimensions |
+------------+
|        768 |
+------------+
```

托管提供商使用相同的调用，并附上密钥：

```sql theme={null}
SET @api_key = '...';
SELECT ai_prompt('anthropic', 'claude-opus-5', @api_key, 'Hello!');
```

> [!NOTE]
>
> 在 VillageSQL 0.0.6 及更早版本上，结果带有 binary 字符集，
> 由此产生两个后果。JSON 函数或 `JSON` 列会拒绝它，因此上面的嵌入示例
> 在这些版本上会失败并报
> `ERROR 3144 (22032): Cannot create a JSON value from a string with CHARACTER
>     SET 'binary'.`。在 `JSON_OBJECT()` 或 `JSON_ARRAY()` 内部它会被接受，
> 但会被 base64 编码，因此 `SELECT JSON_OBJECT('v', ai_prompt(...))` 得到
> `{"v": "base64:type15:UGFyaXMu"}`。在这些版本上，请用
> `CONVERT(... USING utf8mb4)` 包装调用。在 0.0.7 及更高版本上不需要这样做，
> 上面的示例可以按原样运行。

> [!WARNING]
>
> 每次调用都会在模型回答期间阻塞其语句，并且每次调用都按提供商的收费
> 计费。对大表逐行调用既慢又昂贵。保存在变量中的密钥不会出现在调用模型
> 的语句里，但保存它的 `SET` 语句会连同密钥一起写入查询日志。

## 另请参阅

* [设置 AI API 密钥](https://villagesql.com/docs/en/guides/ai-api-setup.md) — 密钥放在哪里，以及如何让它不进入日志
* [MySQL 中的 AI 提示](https://villagesql.com/docs/en/guides/ai-prompts-in-mysql.md) — 在真实表上经得起考验的提示模式
* [生成向量嵌入](https://villagesql.com/docs/en/guides/vector-embeddings.md) — 存储向量并搜索它们
* [安装扩展](https://villagesql.com/docs/zh/extensions/install.md) — `INSTALL EXTENSION` 如何工作，以及服务器在哪里查找包
* [可用扩展](https://villagesql.com/docs/zh/extensions/catalog) — 完整目录
* [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) — 源代码、构建说明和已知限制


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