VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
vsql_ai 扩展让您可以直接从 SQL 查询中调用 AI 语言模型。在运行第一个 ai_prompt() 之前,您需要先安装扩展并准备好 API 密钥。本指南介绍安装设置、提供商选项,以及投入生产之前需要考虑的安全事项。
安装扩展
设置 API 密钥
ai_prompt() 和 ai_embedding() 函数以参数形式接收 API 密钥。推荐的做法是在建立连接时设置一个会话变量——切勿在查询中嵌入密钥字面量,因为查询可能会进入日志文件。对于 'local' 提供商,传入一个空字符串即可——不需要 API 密钥。
SET @key = '...' 语句本身会被原样记录(包括密钥)到 performance_schema.events_statements_history 中——该功能在 MySQL 8.4 中默认开启——以及您启用的任何通用日志或慢查询日志中。会话变量能让密钥不出现在使用它的查询里,但无法让密钥不出现在设置它的语句里。唯一的避免方法是完全不把密钥作为 SQL 文本字面量发送:将其绑定为预处理语句的参数,或者使用客户端替换机制,确保字面量不会进入服务器解析的 SQL 文本。
选择提供商和模型
Anthropic
最适合:复杂推理、长文档、代码生成,以及遵循指令的任务。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
最适合:生成嵌入向量和多模态任务。OpenAI
最适合:使用广泛采用的text-embedding-3 系列生成嵌入向量。
本地(Ollama)
最适合:本地开发,以及不能离开您网络的私有数据。需要 Ollama 在127.0.0.1:11434 上运行。不需要 API 密钥——传入一个空字符串即可。
llama3.2、mistral、gemma2。常见的嵌入模型:nomic-embed-text、mxbai-embed-large。
提供商比较
超时和速率限制注意事项
AI API 调用需要 5–30 秒。MySQL 默认不限制查询时长(max_execution_time 为 0,即无限制),但如果您的应用程序或连接池设置了该值,一次 30 秒的 AI 调用可能会被中断。对于运行 AI 查询的会话,请显式提高或确认该限制:
ai_prompt() 的 1000 行 UPDATE 可能需要 30 分钟以上。
所有提供商都对每分钟的请求数量施加速率限制。触发速率限制会导致 ai_prompt() 返回 NULL。对于批量操作,请按每批 50–100 行处理,并在应用程序循环中在各批之间加入暂停。有关批处理模式,请参阅 从 MySQL 查询运行 AI 模型。
常见问题
我可以把 API 密钥存在 MySQL 表中而不是会话变量里吗?
可以,但这是用一种安全风险换另一种。使用表的方式需要一条 SELECT 来读取密钥——这条查询同样会出现在日志中。由应用程序框架以编程方式设置的会话变量是最干净的选择。如果 API 调用失败会怎样?
函数返回 NULL。测试时请检查结果中的 NULL。在调用之后立即运行SHOW WARNINGS——vsql_ai 会抛出 Warning 3200,其中带有真实的失败原因(密钥无效、提供商未知、模型不受支持等),这比一个单独的 NULL 更有诊断价值。常见原因:API 密钥无效、网络超时、触发速率限制,或模型名称不受支持。
我可以在同一条查询中使用不同的提供商吗?
可以——ai_prompt() 是一个普通函数。您可以在同一条 SELECT 中以不同的提供商/模型组合调用它。
模型名称是稳定的吗?
提供商会随时间更改模型名称。此处列出的名称与扩展当前测试过的模型一致。请查阅您的提供商文档以获取最新可用的模型标识符。故障排除
另请参阅
- 从 MySQL 查询运行 AI 模型——配置好扩展后使用 ai_prompt()
- 在 MySQL 中生成向量嵌入——使用 ai_embedding() 进行语义搜索