Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
A extensão vsql_ai do VillageSQL permite chamar modelos de linguagem de IA diretamente de consultas SQL. Antes de executar seu primeiro ai_prompt(), você precisa da extensão instalada e de uma chave de API pronta. Este guia cobre a configuração, as opções de provedor e as considerações de segurança que importam antes de ir para produção.

Instale a Extensão

Depois que uma chave de API estiver definida (veja abaixo), faça uma chamada de teste:

Definindo Sua Chave de API

As funções ai_prompt() e ai_embedding() recebem a chave de API como parâmetro. O padrão recomendado é uma variável de sessão definida no momento da conexão — nunca incorpore um literal de chave em uma consulta que possa acabar em um arquivo de log. Para o provedor 'local', passe uma string vazia — nenhuma chave de API é necessária.
O que evitar:
Defina a variável de sessão na configuração de conexão da sua aplicação, não em SQL que você grava em um arquivo. A própria instrução SET @key = '...' é capturada literalmente, com a chave incluída, em performance_schema.events_statements_history — ativa por padrão no MySQL 8.4 — assim como em qualquer log geral ou de consultas lentas que você habilitar. Uma variável de sessão mantém a chave fora da consulta que a usa, mas não fora da instrução que a define. A única forma de evitar isso é nunca enviar a chave como texto SQL literal: vincule-a como parâmetro de uma instrução preparada, ou use um mecanismo de substituição no lado do cliente que nunca coloque o literal no texto SQL que o servidor analisa.

Escolhendo um Provedor e um Modelo

Anthropic

Melhor para: raciocínio complexo, documentos longos, geração de código e tarefas de seguimento de instruções.
Modelos Claude:
  • claude-fable-5 — o mais capaz, para raciocínio exigente e trabalho de longo horizonte
  • claude-opus-5 — padrão recomendado; codificação agêntica complexa e trabalho corporativo
  • claude-sonnet-5 — a melhor combinação de velocidade e inteligência
  • claude-haiku-4-5 — o mais rápido e com melhor custo-benefício
As gerações anteriores continuam suportadas: 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. A Anthropic não suporta ai_embedding().

Google Gemini

Melhor para: geração de embeddings e tarefas multimodais.

OpenAI

Melhor para: geração de embeddings com a família text-embedding-3, amplamente adotada.

Local (Ollama)

Melhor para: desenvolvimento local e dados privados que não podem sair da sua rede. Requer o Ollama em execução em 127.0.0.1:11434. Nenhuma chave de API é necessária — passe uma string vazia.
Use qualquer modelo que você tenha baixado no Ollama. Modelos de chat comuns: llama3.2, mistral, gemma2. Modelos de embedding comuns: nomic-embed-text, mxbai-embed-large.

Comparação de provedores

Considerações sobre Timeout e Limite de Taxa

As chamadas a APIs de IA levam de 5 a 30 segundos. O MySQL não limita a duração das consultas por padrão (max_execution_time é 0, ilimitado), mas se a sua aplicação ou um pool de conexões o definir, uma chamada de IA de 30 segundos pode ser interrompida. Para sessões que executam consultas de IA, aumente ou confirme o limite explicitamente:
Para operações em lote sobre muitas linhas, isso importa — um UPDATE de 1000 linhas que chama ai_prompt() em cada linha pode levar mais de 30 minutos. Todos os provedores impõem limites de taxa sobre quantas requisições você pode fazer por minuto. Atingir um limite de taxa faz ai_prompt() retornar NULL. Para operações em massa, processe em lotes de 50 a 100 linhas e adicione uma pausa entre os lotes no loop da sua aplicação. Consulte Executando Modelos de IA a partir de Consultas MySQL para padrões de lote.

Perguntas Frequentes

Posso armazenar chaves de API em uma tabela do MySQL em vez de variáveis de sessão?

Pode, mas você está trocando um risco de segurança por outro. A abordagem com tabela exige um SELECT para ler a chave — essa consulta também aparece nos logs. Variáveis de sessão definidas programaticamente pelo framework da sua aplicação são a opção mais limpa.

O que acontece se a chamada à API falhar?

A função retorna NULL. Verifique se há NULL nos seus resultados durante os testes. Execute SHOW WARNINGS imediatamente após a chamada — a vsql_ai gera um Warning 3200 com o motivo real da falha (chave inválida, provedor desconhecido, modelo não suportado etc.), o que é muito mais diagnóstico do que um NULL puro. Causas comuns: chave de API inválida, timeout de rede, limite de taxa atingido ou um nome de modelo não suportado.

Posso usar provedores diferentes na mesma consulta?

Sim — ai_prompt() é uma função comum. Você pode chamá-la com combinações diferentes de provedor/modelo no mesmo SELECT.

Os nomes dos modelos são estáveis?

Os provedores mudam os nomes dos modelos ao longo do tempo. Os nomes listados aqui correspondem aos modelos testados atualmente pela extensão. Consulte a documentação do seu provedor para os identificadores de modelo mais recentes disponíveis.

Solução de Problemas

Veja também